fluencelabs/gitbook-docs
1
0
Fork 0
mirror of https://github.com/fluencelabs/gitbook-docs synced 2025-04-25 07:52:14 +00:00
Code Issues Projects Releases Wiki Activity

spellcheck fixes

Browse Source
This commit is contained in:
Pavel Murygin 2021-09-24 14:00:52 +03:00
parent 836b911495
commit 7d828fb228
5 changed files with 42 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
js-sdk/1_concepts.md
View File

@ -1,6 +1,8 @@
# Concepts
## Basic concepts
##
## Fluence peer in JS
`@fluencelabs/fluence` package export 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:
@ -12,29 +14,28 @@
Even though the js-based implementation closely resembles [node](https://github.com/fluencelabs/gitbook-docs/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.
`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 strongly 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](https://github.com/fluencelabs/gitbook-docs/js-sdk/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 built-ins implementation for _kad_ or _srv_ services. However _op_ service is fully implemented. For the full descriptions of implemented built-ins refer to [Api reference](https://github.com/fluencelabs/gitbook-docs/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
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:
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 environment. The compiler outputs code for the following entities:
1. Exported `func` declarations are turned into callable async functiokns
1. Exported `func` declarations are turned into callable async functions
2. Exported `service` declarations are turned into functions which register callback handler in a typed manner
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

17
js-sdk/2_basics.md
View File

@ -27,11 +27,11 @@ The first one is a service named `HelloWorld`. A Service interfaces functions ex
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 show you how to call this function from the typescript application.
Finally we have a functions wich demomnstrate how to work with the network. It asks the current time from the relay peer and return back the our peer.
Finally we have a functions which demonstrate how to work with the network. It asks the current time from the relay peer and return back the our peer.
## Installing dependencies
Initialze an empty npm package:
Initialize an empty npm package:
```bash
npm init
@ -147,17 +147,17 @@ async function main() {
main();
```
\(1\) Import list of possible relay nodes \(network enironment\)
\(1\) Import list of possible relay nodes \(network environment\)
\(2\) Aqua compiler provides functions which can be directly imported like any normal typescript function.
\(3\) A Fluence peer has to be started before running any application in Fluence Network. For the vast majority of use cases you should use `Fluence` facade to start and stop the peer. The `start` method accepts a parameters object which. The most common parameter is the address of the relay node the peer should connect to. In this example we are using the first node of the `krasnodar` network. If you do not specify the `connectTo` options will only be able to execute air on the local machine only. Please keep in mind that the init function is asyncrhounous
\(3\) A Fluence peer has to be started before running any application in Fluence Network. For the vast majority of use cases you should use `Fluence` facade to start and stop the peer. The `start` method accepts a parameters object which. The most common parameter is the address of the relay node the peer should connect to. In this example we are using the first node of the `krasnodar` network. If you do not specify the `connectTo` options will only be able to execute air on the local machine only. Please keep in mind that the init function is asynchronous
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 `HelloWorld` service which outputs it's parameter to the console
For every exported `service XXX` definition in aqua code, the compiler provides a `registerXXX` counterpart. These functions 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 `HelloWorld` service 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, 5\) we are calling exported aqua 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 typescript. In \(4, 5\) we are calling exported aqua function with no arguments. Note that every function is asynchronous.
\(6\) You should call `stop` when the peer is no longer needed. As a rule of thumb all the peers should be uninitilized before destroying the application.
\(6\) You should call `stop` when the peer is no longer needed. As a rule of thumb all the peers should be uninitialized before destroying the application.
Let's try running the example:
@ -167,7 +167,6 @@ 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
The next section will cover in-depth and advanced usage JS SDK
The code from this section is available in on \(github\)\[[https://github.com/fluencelabs/examples/tree/main/js-sdk-examples/hello-world](https://github.com/fluencelabs/examples/tree/main/js-sdk-examples/hello-world)\]

43
js-sdk/3_in_depth.md
View File

@ -8,19 +8,19 @@ In this section we will cover the JS SDK in-depth.
`@fluencelabs/fluence` exports a facade `Fluence` which provides all the needed functionality for the most uses cases. It defined 4 functions:
* `start`: Start the default peer.
* `stop`: Stops the default peer
* `getStatus`: Gets the status of the default peer. This includes connection
* `getPeer`: Gets the default Fluence Peer instance \(see below\)
- `start`: Start the default peer.
- `stop`: Stops the default peer
- `getStatus`: Gets the status of the default peer. This includes connection
- `getPeer`: Gets the default Fluence Peer instance \(see below\)
Under the hood `Fluence` facade calls the corresponding method on the default instance of FluencePeer. This instance is passed to the Aqua-compiler generated functions by default.
## FluencePeer class
The second export `@fluencelabs/fluence` package is `FluencePeer` class. It is useful in scenarios when the application need to run everal different peer at once. The overall workflow with the `FluencePeer` is the following:
The second export `@fluencelabs/fluence` package is `FluencePeer` class. It is useful in scenarios when the application need to run several different peer at once. The overall workflow with the `FluencePeer` is the following:
1. Create an instance of the peer
2. Startign the peer
2. Starting the peer
3. Using the peer in the application
4. Stopping the peer
@ -30,7 +30,7 @@ To create a new peer simple instantiate the `FluencePeer` class:
const peer = new FluencePeer();
```
The constructor simply creates a new object and does not initialize any workflow. The `start` 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:
The constructor simply creates a new object and does not initialize any workflow. The `start` 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 additional 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.star({
@ -38,7 +38,7 @@ await peer.star({
});
```
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](https://github.com/fluencelabs/gitbook-docs/tree/77344eb147c2ce17fe1c0f37013082fc85c1ffa3/js-sdk/js-sdk/6_reference/modules.md)
connects the first node of the Krasnodar 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](https://github.com/fluencelabs/gitbook-docs/tree/77344eb147c2ce17fe1c0f37013082fc85c1ffa3/js-sdk/js-sdk/6_reference/modules.md)
```typescript
await peer.stop();
@ -124,9 +124,9 @@ It is possible to combine usage of the default peer with another one. Pay close
## 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:
Aqua compiler emits TypeScript or JavaScript which in turn can be called from a js-based environment. The compiler outputs code for the following entities:
1. Exported `func` declarations are turned into callable async functioks
1. Exported `func` declarations are turned into callable async functions
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`
@ -134,7 +134,7 @@ Aqua compiler emits TypeScript or JavaScript which in turn can be called from a
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
- `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<void>`.
@ -183,9 +183,9 @@ export function registerServiceName(
): void;
```
* `peer` - the Fluence Peer instance where the handler should be registered. The peer can be ommited. In that case the default Fluence Peer 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.
- `peer` - the Fluence Peer instance where the handler should be registered. The peer can be omitted. In that case the default Fluence Peer 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 omitted.
- `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:
@ -270,17 +270,17 @@ export interface CalcDef {
`CallParams` will be described later in the section
### Type convertion
### Type conversion
Basic types convertion is pretty much straightforward:
Basic types conversion 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
- `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.
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 omitted.
The type convertion works the same way for `service` and `func` definitions. For example a `func` with a callback might look like this:
The type conversion works the same way for `service` and `func` definitions. For example a `func` with a callback might look like this:
```text
func callMeBack(callback: string, i32 -> ()):
@ -312,4 +312,3 @@ Tetraplets have the form of:
To learn more about tetraplets and application security see [Security](https://github.com/fluencelabs/gitbook-docs/tree/77344eb147c2ce17fe1c0f37013082fc85c1ffa3/js-sdk/knowledge_security.md)
To see full specification of `CallParms` type see [Api reference](https://github.com/fluencelabs/gitbook-docs/tree/77344eb147c2ce17fe1c0f37013082fc85c1ffa3/js-sdk/js-sdk/6_reference/modules.md)

3
js-sdk/4_run_in_browser-1.md
View File

@ -1,8 +1,7 @@
# Running app in browser
You can use the JS SDK with any framework \(or even without it\). The "flunce" part of the application is a collection of pure typesctipt\javascript functions which can be called withing any framework of your choosing.
You can use the JS SDK with any framework \(or even without it\). The "fluence" part of the application is a collection of pure typescript\javascript functions which can be called withing any framework of your choosing.
See the browser-example which demonstrate integrating Fluence with React: \(github\)\[[https://github.com/fluencelabs/examples/tree/main/js-sdk-examples/browser-example](https://github.com/fluencelabs/examples/tree/main/js-sdk-examples/browser-example)\]
Also take a look at FluentPad. It is an example application written in React: [https://github.com/fluencelabs/fluent-pad](https://github.com/fluencelabs/fluent-pad)

3
js-sdk/README.md
View File

@ -2,5 +2,4 @@
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 which can be used with any framework of your choice \(or even without frameworks\).