fluencelabs/gitbook-docs
1
0
Fork 0
mirror of https://github.com/fluencelabs/gitbook-docs synced 2025-06-09 13:01:30 +00:00
Code Issues Projects Releases Wiki Activity

GitBook: [#212] Fluence JS, In-depth: change Api to API

Browse Source
This commit is contained in:
Pavel Murygin 2021-10-20 19:29:27 +00:00 committed by gitbook-bot
parent 1f9d58391c
commit d43bdccfd2
No known key found for this signature in database
GPG Key ID: 07D2180C7B12D0FF
3 changed files with 26 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
fluence-js/2_basics.md
View File

@ -8,7 +8,7 @@ In this section we will show you how Fluence JS can be used to create a hello wo
Let's start with the aqua code first:
```text
```
service HelloWorld("hello-world"):
hello(str: string)
@ -65,7 +65,7 @@ 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
```
@ -76,7 +76,7 @@ Let's put aqua described earlier into `aqua/hello-world.aqua` file. You probably
The overall project structure looks like this:
```text
```
┣ aqua
┃ ┗ hello-world.aqua
┣ src
@ -108,7 +108,7 @@ 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 typescript application
@ -147,17 +147,17 @@ async function main() {
main();
```
\(1\) Import list of possible relay nodes \(network environment\)
(1) Import list of possible relay nodes (network environment)
\(2\) Aqua compiler provides functions which can be directly imported like any normal typescript function.
(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 asynchronous
(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 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 `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 typescript. In \(4, 5\) we are calling exported aqua function with no arguments. Note that every function is asynchronous.
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 uninitialized 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:
@ -169,5 +169,4 @@ If everything has been done correctly yuo should see `Hello, world!` in the cons
The next section will cover in-depth and advanced usage of Fluence JS
The code from this section is available in on [github](https://github.com/fluencelabs/examples/tree/main/js-sdk-examples/hello-world)
The code from this section is available in on [github](https://github.com/fluencelabs/examples/tree/main/fluence-js-examples/hello-world)

27
fluence-js/3_in_depth.md
View File

@ -11,7 +11,7 @@ In this section we will cover the Fluence JS in-depth.
* `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\)
* `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.
@ -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 additional 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 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)
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();
@ -134,13 +134,13 @@ 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>`.
Consider the following example:
```text
```
func myFunc(arg0: string, arg1: string):
-- implementation
```
@ -164,7 +164,7 @@ export async function callMeBack(
### Service definitions
```text
```
service ServiceName:
-- service interface
```
@ -243,9 +243,9 @@ export function registerServiceName(
### 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:
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:
```text
```
service Calc("calc"):
add(n: f32)
subtract(n: f32)
@ -276,13 +276,13 @@ 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
* 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 omitted.
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 -> ()):
callback("hello, world", 42)
```
@ -293,7 +293,7 @@ The type for `callback` argument will be:
callback: (arg0: string, arg1: number, callParams: CallParams<'arg0' | 'arg1'>) => void,
```
For the service definitions arguments are named \(see calc example above\)
For the service definitions arguments are named (see calc example above)
### Call params and tetraplets
@ -309,7 +309,6 @@ 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)
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)

5
fluence-js/4_run_in_browser-1.md
View File

@ -1,8 +1,7 @@
# Running app in browser
You can use the Fluence JS 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.
You can use the Fluence JS 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)
See the browser-example which demonstrate integrating Fluence with React: [github](https://github.com/fluencelabs/examples/tree/main/fluence-js-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)