From b227e1059ba4d73b0105e17c6e8285572553892a Mon Sep 17 00:00:00 2001 From: boneyard93501 Date: Fri, 10 Sep 2021 07:49:25 +0000 Subject: [PATCH] GitBook: [2.0.0] 13 pages and 24 assets modified --- ...) (3) (3) (3) (3) (3) (3) (3) (3) (1).png} | Bin ...) (3) (3) (3) (3) (3) (3) (3) (3) (2).png} | Bin ...) (3) (3) (3) (3) (3) (3) (3) (3) (3).png} | Bin .../{image (12).png => image (18) (1).png} | Bin .../{image (17).png => image (19) (1).png} | Bin .../{image (41).png => image (24) (1).png} | Bin .../{image (32).png => image (27) (1).png} | Bin .../{image (40).png => image (28) (1).png} | Bin .../{image (30).png => image (31) (1).png} | Bin .../{image (42).png => image (34) (1).png} | Bin .../{image (53).png => image (38) (1).png} | Bin .../{image (52).png => image (39) (1).png} | Bin SUMMARY.md | 63 ++-- js-sdk/1_concepts.md | 19 +- js-sdk/2_basics.md | 32 +- js-sdk/3_in_depth.md | 335 +----------------- js-sdk/{readme.md => README.md} | 5 +- js-sdk/api-reference.md | 2 + js-sdk/changelog.md | 5 +- js-sdk/running-app-in-browser.md | 2 + js-sdk/running-app-in-nodejs.md | 2 + quick-start/3.-browser-to-service.md | 2 +- quick-start/README.md | 2 +- tutorials_tutorials/recipes_setting_up.md | 10 +- 24 files changed, 84 insertions(+), 395 deletions(-) rename .gitbook/assets/{air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (1).png => air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (1).png} (100%) rename .gitbook/assets/{air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (2).png => air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (2).png} (100%) rename .gitbook/assets/{air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3).png => air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3).png} (100%) rename .gitbook/assets/{image (12).png => image (18) (1).png} (100%) rename .gitbook/assets/{image (17).png => image (19) (1).png} (100%) rename .gitbook/assets/{image (41).png => image (24) (1).png} (100%) rename .gitbook/assets/{image (32).png => image (27) (1).png} (100%) rename .gitbook/assets/{image (40).png => image (28) (1).png} (100%) rename .gitbook/assets/{image (30).png => image (31) (1).png} (100%) rename .gitbook/assets/{image (42).png => image (34) (1).png} (100%) rename .gitbook/assets/{image (53).png => image (38) (1).png} (100%) rename .gitbook/assets/{image (52).png => image (39) (1).png} (100%) rename js-sdk/{readme.md => README.md} (80%) create mode 100644 js-sdk/api-reference.md create mode 100644 js-sdk/running-app-in-browser.md create mode 100644 js-sdk/running-app-in-nodejs.md diff --git a/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (1).png b/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (1).png similarity index 100% rename from .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (1).png rename to .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (1).png diff --git a/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (2).png b/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (2).png similarity index 100% rename from .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (2).png rename to .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (2).png diff --git a/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3).png b/.gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3).png similarity index 100% rename from .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3).png rename to .gitbook/assets/air_null_6 (1) (2) (2) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3) (3).png diff --git a/.gitbook/assets/image (12).png b/.gitbook/assets/image (18) (1).png similarity index 100% rename from .gitbook/assets/image (12).png rename to .gitbook/assets/image (18) (1).png diff --git a/.gitbook/assets/image (17).png b/.gitbook/assets/image (19) (1).png similarity index 100% rename from .gitbook/assets/image (17).png rename to .gitbook/assets/image (19) (1).png diff --git a/.gitbook/assets/image (41).png b/.gitbook/assets/image (24) (1).png similarity index 100% rename from .gitbook/assets/image (41).png rename to .gitbook/assets/image (24) (1).png diff --git a/.gitbook/assets/image (32).png b/.gitbook/assets/image (27) (1).png similarity index 100% rename from .gitbook/assets/image (32).png rename to .gitbook/assets/image (27) (1).png diff --git a/.gitbook/assets/image (40).png b/.gitbook/assets/image (28) (1).png similarity index 100% rename from .gitbook/assets/image (40).png rename to .gitbook/assets/image (28) (1).png diff --git a/.gitbook/assets/image (30).png b/.gitbook/assets/image (31) (1).png similarity index 100% rename from .gitbook/assets/image (30).png rename to .gitbook/assets/image (31) (1).png diff --git a/.gitbook/assets/image (42).png b/.gitbook/assets/image (34) (1).png similarity index 100% rename from .gitbook/assets/image (42).png rename to .gitbook/assets/image (34) (1).png diff --git a/.gitbook/assets/image (53).png b/.gitbook/assets/image (38) (1).png similarity index 100% rename from .gitbook/assets/image (53).png rename to .gitbook/assets/image (38) (1).png diff --git a/.gitbook/assets/image (52).png b/.gitbook/assets/image (39) (1).png similarity index 100% rename from .gitbook/assets/image (52).png rename to .gitbook/assets/image (39) (1).png diff --git a/SUMMARY.md b/SUMMARY.md index f76867e..8acbf2f 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,33 +1,34 @@ # Table of contents -- [Introduction](README.md) -- [Thinking In Aquamarine](p2p.md) -- [Concepts](concepts.md) -- [Quick Start](quick-start/README.md) - - [1. Browser-to-Browser](quick-start/1.-browser-to-browser-1.md) - - [2. Hosted Services](quick-start/2.-hosted-services.md) - - [3. Browser-to-Service](quick-start/3.-browser-to-service.md) -- [Aquamarine](knowledge_aquamarine/README.md) - - [Aqua](knowledge_aquamarine/hll.md) - - [Marine](knowledge_aquamarine/marine/README.md) - - [Marine CLI](knowledge_aquamarine/marine/marine-cli.md) - - [Marine REPL](knowledge_aquamarine/marine/marine-repl.md) - - [Marine Rust SDK](knowledge_aquamarine/marine/marine-rs-sdk.md) -- [Tools](knowledge_tools.md) -- [Node](node.md) -- [JS SDK](js-sdk/readme.md) - - [Concepts](js-sdk/1_concepts.md) - - [Basics](js-sdk/2_basics.md) - - [In-depth](js-sdk/in-depth.md) - - [Running app in nodejs](js-sdk/4_run_in_node.md) - - [Running app in browser](js-sdk/5_run_in_browser.md) - - [Api reference](js-sdk/6_reference/modules.md) - - [Changelog](js-sdk/changelog.md) -- [Security](knowledge_security.md) -- [Tutorials](tutorials_tutorials/README.md) - - [Setting Up Your Environment](tutorials_tutorials/recipes_setting_up.md) - - [Deploy A Local Fluence Node](tutorials_tutorials/tutorial_run_local_node.md) - - [cUrl As A Service](tutorials_tutorials/curl-as-a-service.md) - - [Add Your Own Builtins](tutorials_tutorials/add-your-own-builtin.md) - - [Building a Frontend with JS-SDK](tutorials_tutorials/building-a-frontend-with-js-sdk.md) -- [Research, Papers And References](research-papers-and-references.md) +* [Introduction](README.md) +* [Thinking In Aquamarine](p2p.md) +* [Concepts](concepts.md) +* [Quick Start](quick-start/README.md) + * [1. Browser-to-Browser](quick-start/1.-browser-to-browser-1.md) + * [2. Hosted Services](quick-start/2.-hosted-services.md) + * [3. Browser-to-Service](quick-start/3.-browser-to-service.md) +* [Aquamarine](knowledge_aquamarine/README.md) + * [Aqua](knowledge_aquamarine/hll.md) + * [Marine](knowledge_aquamarine/marine/README.md) + * [Marine CLI](knowledge_aquamarine/marine/marine-cli.md) + * [Marine REPL](knowledge_aquamarine/marine/marine-repl.md) + * [Marine Rust SDK](knowledge_aquamarine/marine/marine-rs-sdk.md) +* [Tools](knowledge_tools.md) +* [Node](node.md) +* [JS SDK](js-sdk/README.md) + * [Concepts](js-sdk/1_concepts.md) + * [Basics](js-sdk/2_basics.md) + * [In-depth](js-sdk/3_in_depth.md) + * [Running app in nodejs](js-sdk/running-app-in-nodejs.md) + * [Running app in browser](js-sdk/running-app-in-browser.md) + * [Api reference](js-sdk/api-reference.md) + * [Changelog](js-sdk/changelog.md) +* [Security](knowledge_security.md) +* [Tutorials](tutorials_tutorials/README.md) + * [Setting Up Your Environment](tutorials_tutorials/recipes_setting_up.md) + * [Deploy A Local Fluence Node](tutorials_tutorials/tutorial_run_local_node.md) + * [cUrl As A Service](tutorials_tutorials/curl-as-a-service.md) + * [Add Your Own Builtins](tutorials_tutorials/add-your-own-builtin.md) + * [Building a Frontend with JS-SDK](tutorials_tutorials/building-a-frontend-with-js-sdk.md) +* [Research, Papers And References](research-papers-and-references.md) + diff --git a/js-sdk/1_concepts.md b/js-sdk/1_concepts.md index fab4cda..a240cc5 100644 --- a/js-sdk/1_concepts.md +++ b/js-sdk/1_concepts.md @@ -1,4 +1,6 @@ -# Basic concepts +# Concepts + +## Basic concepts The main export of the `@fluencelabs/fluence` package is the `FluencePeer` class. This class implements the Fluence protocol for javascript-based environments. It provides all the necessary features to communicate with Fluence network namely: @@ -8,17 +10,17 @@ The main export of the `@fluencelabs/fluence` package is the `FluencePeer` class 4. A set of builtin functions required by Fluence protocol 5. Support for the typescript code which is generated by Aqua compiler -Even though the js-based implementation closely resembles [node](node.md) there are some considerable differences to the latter. +Even though the js-based implementation closely resembles [node](https://github.com/fluencelabs/gitbook-docs/tree/90111033a58bc906a27b1b2bcec982d92739b6f7/js-sdk/node.md) there are some considerable differences to the latter. `FluencePeer` does not host services composed of wasm modules. Instead it allows to register service call handlers directly in javascript. The Aqua language compiler creates a typed helpers for that task. Using Aqua compiler is strontly advised when working with JS SDK. Due to the limitations of browser-based environment `FluencePeer` cannot be discovered by it's Peer Id on it's own. To overcome this `FluencePeer` must use an existing node which will act as a `relay`. When a peer is connected through a relay it is considered to be `client`. The `FluencePeer` routes all it's particle through it's relay thus taking advantage of the peer discovery implemented on the node. A particle sent to the connected client must be routed through it's relay. -The js-based peer does not implement the full set of builtin functions due the limitations described previously. E.g there is no builtins implementation for _kad_ or _srv_ services. However _op_ service is fully implemented. For the full descriptions of implemented builtins refer to [Api reference](js-sdk/6_reference/modules.md) +The js-based peer does not implement the full set of builtin functions due the limitations described previously. E.g there is no builtins implementation for _kad_ or _srv_ services. However _op_ service is fully implemented. For the full descriptions of implemented builtins refer to [Api reference](https://github.com/fluencelabs/gitbook-docs/tree/90111033a58bc906a27b1b2bcec982d92739b6f7/js-sdk/js-sdk/6_reference/modules.md) In contrast with the node implementation `FluencePeer` can initiate new particles execution. Aqua compiler generates executable functions from `func` definitions in aqua code. -# Creating applications with Aqua language +## Creating applications with Aqua language The official way to write applications for Fluence is using Aqua programming language. Aqua compiler emits TypeScript or JavaScript which in turn can be called from a js-based environemt. The compiler outputs code for the following entities: @@ -29,9 +31,10 @@ To learn more about Aqua see [aqua book](https://doc.fluence.dev/aqua-book/) The building block of the application are: -- Aqua code for peer-to-peer communication -- Compiler cli package for aqua to (java)typescript compilation -- Initialization of the `FluencePeer` -- Application specific code (java)typescript in the framework of your choice +* Aqua code for peer-to-peer communication +* Compiler cli package for aqua to \(java\)typescript compilation +* Initialization of the `FluencePeer` +* Application specific code \(java\)typescript in the framework of your choice In the next section we see it in action + diff --git a/js-sdk/2_basics.md b/js-sdk/2_basics.md index 05491a9..2dc6628 100644 --- a/js-sdk/2_basics.md +++ b/js-sdk/2_basics.md @@ -1,12 +1,14 @@ -# Intro +# Basics + +## Intro In this section we will show you how JS SDK can be used to create a hello world application with Fluence stack. -# Aqua code +## Aqua code Let's start with the aqua code first: -``` +```text service HelloWorld("hello-world"): hello(str: string) @@ -16,7 +18,7 @@ func sayHello(): This file has two definitions. The first one is a service named `HelloWorld`. A Service interfaces functions executable on a peer. We will register a handler for this interface in our typescript application. The second definition is the function `sayHello`. The only thing the function is doing is calling the `hello` method of `HelloWorld` service located on the current peer. We will shouw you how to call this function from the typescript application. -# Installing dependencies +## Installing dependencies Initialze an empty npm package: @@ -48,12 +50,12 @@ npm install --save-dev @fluencelabs/chokidar-cli And last, but no least we will need TypeScript -``` +```text npm install --save-dev typescript npx tsc --init ``` -# Setting up aqua compiler +## Setting up aqua compiler Let's put aqua described earlier into `aqua/hello-world.aqua` file. You probably want to keep the generated TypeScript in the same directory with other typescript files, usually `src`. Let's create the `src/_aqua` directory for that. @@ -79,7 +81,7 @@ npx aqua-cli -i ./aqua/ -o ./src/_aqua We recommend to store this logic inside a script in `packages.json` file: -```json +```javascript { ... "scripts": { @@ -91,10 +93,9 @@ We recommend to store this logic inside a script in `packages.json` file: } ``` -`compile-aqua` (1) runs the compilation once, producing `src/_aqua/hello-world.ts` in our case -`watch-aqua` (2) starts watching for any changes in .aqua files recompiling them on the fly +`compile-aqua` \(1\) runs the compilation once, producing `src/_aqua/hello-world.ts` in our case `watch-aqua` \(2\) starts watching for any changes in .aqua files recompiling them on the fly -# Using the compiled code in our application +## Using the compiled code in our application Using the code generated by the compiler is as easy as calling a function. The compiler generates all the boilerplate needed to send a particle into the network and wraps it into a single call. It also generate a function for service callback registration. Note that all the type information and therefore type checking and code completion facilities are there! @@ -122,15 +123,15 @@ async function main() { main(); ``` -(1) Aqua compiler provides functions which can be directly imported like any normal typescript function. +\(1\) Aqua compiler provides functions which can be directly imported like any normal typescript function. -(2) `FluencePeer` has to be initialized before running any application in Fluence Network. A peer represents the identity in the network, so most of the time you will only need a single peer per application. JS SDK provides a default instance which is accesible via `default` propery of the class. `init` method accepts a parameters object which will be covered in the next section. By default the peer is not get connected to the network and will only be able to execute air on the local machine only. Please keep in mind that the init function is asyncrhounous +\(2\) `FluencePeer` has to be initialized before running any application in Fluence Network. A peer represents the identity in the network, so most of the time you will only need a single peer per application. JS SDK provides a default instance which is accesible via `default` propery of the class. `init` method accepts a parameters object which will be covered in the next section. By default the peer is not get connected to the network and will only be able to execute air on the local machine only. Please keep in mind that the init function is asyncrhounous -For every exported `service XXX` definition in aqua code, the compiler provides a `registerXXX` counterpart. These funtions provide a type-safe way of registering callback handlers for the services. The callbacks are executed when the appropriate service is called in aqua on the current peer. The handlers take form of the object where keys are the name of functions and the values are async functions used as the corresponding callbacks. For example in (3) we are registering handler for `hello` function which outputs it's parameter to the console +For every exported `service XXX` definition in aqua code, the compiler provides a `registerXXX` counterpart. These funtions provide a type-safe way of registering callback handlers for the services. The callbacks are executed when the appropriate service is called in aqua on the current peer. The handlers take form of the object where keys are the name of functions and the values are async functions used as the corresponding callbacks. For example in \(3\) we are registering handler for `hello` function which outputs it's parameter to the console -For every exported `func XXX` definition in aqua code, the compiler provides an async function which can be directly called from typescripyt. In (4) we are calling the `sayHello` function with no arguments. Note that every function is asyncrhonous. +For every exported `func XXX` definition in aqua code, the compiler provides an async function which can be directly called from typescripyt. In \(4\) we are calling the `sayHello` function with no arguments. Note that every function is asyncrhonous. -(5) You should call `uninit` method of `FluencePeer` when it is no longer needed. As a rule of thumb all the peers should be uninitilized before destroying the application. +\(5\) You should call `uninit` method of `FluencePeer` when it is no longer needed. As a rule of thumb all the peers should be uninitilized before destroying the application. Let's try running the example: @@ -141,3 +142,4 @@ node -r ts-node/register src/index.ts If everything has been done correctly yuo should see `Hello, world!` in the console. The next secion will cover in-depth and advanced usage JS SDK + diff --git a/js-sdk/3_in_depth.md b/js-sdk/3_in_depth.md index 6d3ed54..4f5533d 100644 --- a/js-sdk/3_in_depth.md +++ b/js-sdk/3_in_depth.md @@ -1,335 +1,2 @@ -# Intro +# In-depth -In this section we will cover the JS SDK in-depth. - -# FluencePeer class - -The overall workflow with the `FluencePeer` is the following: - -1. Create an instance of the peer -2. Initializing the peer -3. Using the peer in the application -4. Uninitializing the peer - -To create a new peer simple instantiate the `FluencePeer` class: - -```typescript -const peer = new FluencePeer(); -``` - -The constructor simply creates a new object and does not initialize any workflow. The `init` function starts the Aqua VM, initializes the default call service handlers and (optionally) connect to the Fluence network. The function takes an optional object specifying additonal peer configuration. On option you will be using a lot is `connectTo`. It tells the peer to connect to a relay. For example: - -```typescript -await peer.init({ - connectTo: krasnodar[0], -}); -``` - -connects the first node of the Kranodar network. You can find the officially maintained list networks in the `@fluencelabs/fluence-network-environment` package. The full list of supported options is described in the [API reference](js-sdk/6_reference/modules.md) - -Most of the time a single peer is enough for the whole application. For these use cases`FluncePeer` class contains the default instance which can be accessed with the corresponding property: - -```typescript -await FluencePeer.default.init(); -``` - -The peer by itself does not do any useful work. You should take advantage of functions generated by the Aqua compiler. You can use them both with a single peer or in muliple peers scenario. If you are using the default peer for your application you don't need to explicitly pass it: the compiled functions will use the `default` instance in that case (see "Using multiple peers in one applicaton") - -To uninitialize the peer simply call `uninit` method. It will disconnect from the network and stop the Aqua vm, - -```typescript -await peer.unint(); -``` - -# Using multiple peers in one applicaton - -In most cases using a single peer is enough. However sometimes you might need to run multiple peers inside the same JS environment. When using a single peer you should initialize the `FluencePeer.default` and call Aqua compiler-generated functions without passing any peer. For example: - -```typescript -import { FluencePeer } from "@fluencelabs/fluence"; -import { - registerSomeService, - someCallableFunction, -} from "./_aqua/someFunction"; - -async function main() { - await FluencePeer.default.init({ - connectTo: relay, - }); - - // ... more application logic - - registerSomeService({ - handler: async (str) => { - console.log(str); - }, - }); - - await someCallableFunction(arg1, arg2, arg3); - - await FluencePeer.default.uninit(); -} - -// ... more application logic -``` - -If your application needs several peers, you should create a separate `FluncePeer` instance for each of them. The generated functions accept the peer as the first argument. For example: - -```typescript -import { FluencePeer } from "@fluencelabs/fluence"; -import { - registerSomeService, - someCallableFunction, -} from "./_aqua/someFunction"; - -async function main() { - const peer1 = new FluencePeer(); - const peer2 = new FluencePeer(); - - // Don't forget to initialize peers - await peer1.init({ - connectTo: relay, - }); - await peer2.init({ - connectTo: relay, - }); - - // ... more application logic - - // Pass the peer as the first agument - // || - // \/ - registerSomeService(peer1, { - handler: async (str) => { - console.log("Called service on peer 1: " str); - }, - }); - - // Pass the peer as the first agument - // || - // \/ - registerSomeService(peer2, { - handler: async (str) => { - console.log("Called service on peer 2: " str); - }, - }); - - // Pass the peer as the first agument - // || - // \/ - await someCallableFunction(peer1, arg1, arg2, arg3); - - - await peer1.uninit(); - await peer2.uninit(); -} - -// ... more application logic -``` - -It is possible to combine usage of the default peer with another one. Pay close attention to which peer you are calling the functions against. - -```typescript - // Registering handler for the default peer - registerSomeService({ - handler: async (str) => { - console.log("Called agains the default peer: " str); - }, - }); - - // Pay close attention to this - // || - // \/ - registerSomeService(someOthePeer, { - handler: async (str) => { - console.log("Called against the peer named someOtherPeer: " str); - }, - }); -``` - -# Understanding the Aqua compiler output - -Aqua compiler emits TypeScript or JavaScript which in turn can be called from a js-based environemt. The compiler outputs code for the following entities: - -1. Exported `func` declarations are turned into callable async functioks -2. Exported `service` declarations are turned into functions which register callback handler in a typed manner -3. For every exported `service` the compiler generated it's interface under the name `{serviceName}Def` - -## Function definitions - -For every exported function definition in aqua the compiler generated two overloads. One accepting the `FluencePeer` instance as the first argument, and one without it. Otherwise arguments are the same and correspond to the arguments of aqua functions. The last argument is always an optional config object with the following properties: - -- `ttl`: Optional parameter which specify TTL (time to live) of particle with execution logic for the function - -The return type is always a promise of the aqua function return type. If the function does not return anything, the return type will be `Promise`. - -Consider the following example: - -``` -func myFunc(arg0: string, arg1: string): - -- implementation - -``` - -The compiler will generate the following overloads: - -```typescript -export async function myFunc( - arg0: string, - arg1: string, - config?: { ttl?: number } -): Promise; - -export async function callMeBack( - peer: FluencePeer, - arg0: string, - arg1: string, - config?: { ttl?: number } -): Promise; -``` - -## Service definitions - -For every exported `service` declaration the compiler will generate two entities: service interface under the name `{serviceName}Def` and a function named `register{serviceName}` with several overloads. First let's describe the most complete one using the following example: - -```typescript -export interface ServiceNameDef { - //... service function definitions -} - -export function registerStringExtra( - peer: FluencePeer, - serviceId: string, - service: ServiceNameDef -): void; -``` - -- `peer` - the Fluence Peer instance where the handler should be registered. The peer can be ommited. In that case the `FluencePeer.default` will be used instead -- `serviceId` - the name of the service id. If the service was defined with the default service id in aqua code, this argument can be ommited. -- `service` - the handler for the service. - -Depending on whether or not the services was defined with the default id the number of overloads will be different. In the case it **is defined**, there would be four overloads: - -```typescript -// (1) -export function registerStringExtra( - // - service: ServiceNameDef -): void; - -// (2) -export function registerStringExtra( - serviceId: string, - service: ServiceNameDef -): void; - -// (3) -export function registerStringExtra( - peer: FluencePeer, - service: ServiceNameDef -): void; - -// (4) -export function registerStringExtra( - peer: FluencePeer, - serviceId: string, - service: ServiceNameDef -): void; -``` - -1. Uses `FluencePeer.default` and the default id taken from aqua definition -2. Uses `FluencePeer.default` and specifies the service id explicitly -3. The default id is taken from aqua definition. The peer is specified explicitly -4. Specifying both peer and the service id. - -If the default id **is not defined** in aqua code the overloads will exclude ones without service id: - -```typescript -// (1) -export function registerStringExtra( - serviceId: string, - service: ServiceNameDef -): void; - -// (2) -export function registerStringExtra( - peer: FluencePeer, - serviceId: string, - service: ServiceNameDef -): void; -``` - -1. Uses `FluencePeer.default` and specifies the service id explicitly -2. Specifying both peer and the service id. - -## Service interface - -The service interface type follows closely the definition in aqua code. It has the form of the object which keys correspond to the names of service members and the values are functions of the type translated from aqua definition (see Type convertion). For example, for the following aqua definition: - -``` -service Calc("calc"): - add(n: f32) - subtract(n: f32) - multiply(n: f32) - divide(n: f32) - reset() - getResult() -> f32 -``` - -The typescript interface will be: - -```typescript -export interface CalcDef { - add: (n: number, callParams: CallParams<"n">) => void; - subtract: (n: number, callParams: CallParams<"n">) => void; - multiply: (n: number, callParams: CallParams<"n">) => void; - divide: (n: number, callParams: CallParams<"n">) => void; - reset: (callParams: CallParams) => void; - getResult: (callParams: CallParams) => number; -} -``` - -`CallParams` will be described later in the section - -## Type convertion - -Basic types convertion is pretty much straightforward: - -- `string` is converted to `string` in typescript -- `bool` is converted to `boolean` in typescript -- All number types (`u8`, `u16`, `u32`, `u64`, `s8`, `s16`, `s32`, `s64`, `f32`, `f64`) are converted to `number` in typescript - -Arrow types translate to functions in typescript which have their arguments translated to typescript types. In addition to arguments defined in aqua, typescript counterparts have an additional argument for call params. For the majority of use cases this parameter is not needed and can be ommited. - -The type convertion works the same way for `service` and `func` definitions. For example a `func` with a callback might look like this: - -``` -func callMeBack(callback: string, i32 -> ()): - callback("hello, world", 42) -``` - -The type for `callback` argument will be: - -```typescript -callback: (arg0: string, arg1: number, callParams: CallParams<'arg0' | 'arg1'>) => void, -``` - -For the service definitions arguments are named (see calc example above) - -## Call params and tetraplets - -Each service call is accompanied by additional information specific to Fluence Protocol. Including `initPeerId` - the peer which initiated the particle execution, particle signature and most importantly security tetraplets. All this data is contained inside the last `callParams` argument in every generated function definition. These data is passed to the handler on each function call can be used in the application. - -Tetraplets have the form of: - -```typescript -{ - argName0: SecurityTetraplet[], - argName1: SecurityTetraplet[], - // ... -} -``` - -To learn more about tetraplets and application security see [Security](knowledge_security.md) - -To see full specification of `CallParms` type see [Api reference](js-sdk/6_reference/modules.md) diff --git a/js-sdk/readme.md b/js-sdk/README.md similarity index 80% rename from js-sdk/readme.md rename to js-sdk/README.md index a6562d5..5eb3bf0 100644 --- a/js-sdk/readme.md +++ b/js-sdk/README.md @@ -1,3 +1,6 @@ +# JS SDK + JS SDK provides the implementation of the Fluence Protocol which can be hosted in js-based environment. Currently node.js 14+ and majority of the modern browsers are tested. -The JS SDK is just a library wich can be used with any framework of your choice (or even without frameworks). +The JS SDK is just a library wich can be used with any framework of your choice \(or even without frameworks\). + diff --git a/js-sdk/api-reference.md b/js-sdk/api-reference.md new file mode 100644 index 0000000..b2b72ad --- /dev/null +++ b/js-sdk/api-reference.md @@ -0,0 +1,2 @@ +# Api reference + diff --git a/js-sdk/changelog.md b/js-sdk/changelog.md index 713ac03..89849fc 100644 --- a/js-sdk/changelog.md +++ b/js-sdk/changelog.md @@ -1 +1,4 @@ -Similar to what we have in aqua book \ No newline at end of file +# Changelog + +Similar to what we have in aqua book + diff --git a/js-sdk/running-app-in-browser.md b/js-sdk/running-app-in-browser.md new file mode 100644 index 0000000..4bb67a8 --- /dev/null +++ b/js-sdk/running-app-in-browser.md @@ -0,0 +1,2 @@ +# Running app in browser + diff --git a/js-sdk/running-app-in-nodejs.md b/js-sdk/running-app-in-nodejs.md new file mode 100644 index 0000000..1367383 --- /dev/null +++ b/js-sdk/running-app-in-nodejs.md @@ -0,0 +1,2 @@ +# Running app in nodejs + diff --git a/quick-start/3.-browser-to-service.md b/quick-start/3.-browser-to-service.md index 9711bdb..0bf6331 100644 --- a/quick-start/3.-browser-to-service.md +++ b/quick-start/3.-browser-to-service.md @@ -16,7 +16,7 @@ npm start Which will open a new browser tab at `http://localhost:3000` . Following the instructions, we connect to any one of the displayed relay ids, open another browser tab also at `http://localhost:3000`, select a relay and copy and paste the client peer id and relay id into corresponding fields in the first tab and press the `say hello` button. -![Browser To Service Implementation](../.gitbook/assets/image%20%2853%29.png) +![Browser To Service Implementation](../.gitbook/assets/image%20%2838%29%20%281%29.png) The result looks familiar, so what's different? Let's have a look at the Aqua file. Navigate to the `aqua/getting_started.aqua` file in your IDE: diff --git a/quick-start/README.md b/quick-start/README.md index 56e3201..ecc87f1 100644 --- a/quick-start/README.md +++ b/quick-start/README.md @@ -39,7 +39,7 @@ With Docker and VSCode in place: * When asked for volume, press enter \(unique\) * Open Terminal in VSCode \(ctrl-\`\) -![Installed And Ready Devcontainer in VSCode](../.gitbook/assets/image%20%2812%29.png) +![Installed And Ready Devcontainer in VSCode](../.gitbook/assets/image%20%2818%29.png) Congratulations, you now have a fully functional Fluence development environment. For a variety of container management options, click on the `Dev Container: Fluence` button in the lower left of your tool bar: diff --git a/tutorials_tutorials/recipes_setting_up.md b/tutorials_tutorials/recipes_setting_up.md index 87e4013..fb16503 100644 --- a/tutorials_tutorials/recipes_setting_up.md +++ b/tutorials_tutorials/recipes_setting_up.md @@ -1,6 +1,10 @@ # Setting Up Your Environment -In order to develop within the Fluence solution, [Rust](https://www.rust-lang.org/tools/install) and small number of tools are required. +In order to develop within the Fluence solution, [Node](https://nodejs.org/en/), [Rust](https://www.rust-lang.org/tools/install) and small number of tools are required. + +### NodeJs + +Download the \[installer\]\([https://nodejs.org/en/download/](https://nodejs.org/en/download/)\) for your platform and follow the instructions. ### Rust @@ -31,7 +35,7 @@ There are a number of good Rust installation and IDE integration tutorials avail The Aqua compiler and standard library and be installed via npm: ```text -npm -g install @fluencelabs/aqua-cli +npm -g install @fluencelabs/aqua npm -g install @fluencelabs/aqua-lib ``` @@ -61,7 +65,7 @@ cargo +nightly install mrepl In addition, Fluence provides the `fldist` tool for the lifecycle management of services. From deploying services to the network to executing compiled Aqua scripts from the command line , `fldist` does it: ```bash -npm install -g @fluencelabs/fldist +npm -g install @fluencelabs/fldist ``` ### Fluence SDK