mirror of
https://github.com/fluencelabs/gitbook-docs
synced 2025-04-25 07:52:14 +00:00
Add documentation about fluence-js v0.14.2 (#26)
This commit is contained in:
Pavel
GitHub
parent
d43bdccfd2
commit
da12c3cd48
@ -9,25 +9,34 @@ 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:
|
||||
|
||||
```
|
||||
service HelloWorld("hello-world"):
|
||||
hello(str: string)
|
||||
import Peer from "@fluencelabs/aqua-lib/builtin.aqua" -- (1)
|
||||
|
||||
func sayHello():
|
||||
service HelloWorld("hello-world"): -- (2)
|
||||
hello(str: string)
|
||||
getFortune() -> string
|
||||
|
||||
func sayHello(): -- (3)
|
||||
HelloWorld.hello("Hello, world!")
|
||||
|
||||
func getRelayTime() -> u64:
|
||||
on HOST_PEER:
|
||||
func tellFortune() -> string: -- (4)
|
||||
res <- HelloWorld.getFortune()
|
||||
<- res
|
||||
|
||||
func getRelayTime() -> u64: -- (5)
|
||||
on HOST_PEER_ID:
|
||||
ts <- Peer.timestamp_ms()
|
||||
<- ts
|
||||
```
|
||||
|
||||
We need to import definitions to call standard Peer operations (1)
|
||||
|
||||
This file has three 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.
|
||||
(2) 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 show you how to call this function from the typescript application.
|
||||
(3) and (4) are functions `sayHello` and `tellFortune` correspondingly. These functions very simple. The only thing the first one does is calling the `hello` method of `HelloWorld` service located on the current peer. Similarly `tellFortune` calls the `getFortune` method from the same service and returns the value to the caller. We will show you how to call these function from the typescript application.
|
||||
|
||||
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.
|
||||
Finally we have a function (5) 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
|
||||
|
||||
@ -123,25 +132,34 @@ import {
|
||||
registerHelloWorld,
|
||||
sayHello,
|
||||
getRelayTime,
|
||||
tellFortune,
|
||||
} from "./_aqua/hello-world"; // (2)
|
||||
|
||||
async function main() {
|
||||
await Fluence.start({ connectTo: krasnodar[0] }); // (3)
|
||||
|
||||
// (3)
|
||||
// (4)
|
||||
registerHelloWorld({
|
||||
hello: async (str) => {
|
||||
hello: (str) => {
|
||||
console.log(str);
|
||||
},
|
||||
getFortune: async () => {
|
||||
await new Promise((resolve) => {
|
||||
setTimeout(resolve, 1000);
|
||||
});
|
||||
return "Wealth awaits you very soon.";
|
||||
},
|
||||
});
|
||||
|
||||
await sayHello(); // (4)
|
||||
|
||||
const relayTime = await getRelayTime(); // (5)
|
||||
console.log(await tellFortune()); // (6)
|
||||
|
||||
const relayTime = await getRelayTime();
|
||||
|
||||
console.log("The relay time is: ", new Date(relayTime).toLocaleString());
|
||||
|
||||
await Fluence.stop(); // (6)
|
||||
await Fluence.stop(); // (7)
|
||||
}
|
||||
|
||||
main();
|
||||
@ -151,13 +169,13 @@ main();
|
||||
|
||||
(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 (4) we are registering handlers for `HelloWorld` service functions which outputs it's parameter to the console. Please note that the handlers can be implemented in both: synchronous and asynchronous way. The handler can be made asynchronous like any other function in javascript: either return a Promise or mark it with async keyword to take advantage of async-await pattern.
|
||||
|
||||
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 (5, 6) 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.
|
||||
(7) 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:
|
||||
|
||||
|
||||
@ -8,10 +8,10 @@ In this section we will cover the Fluence JS 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.
|
||||
|
||||
@ -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 to 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,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 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.
|
||||
- `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:
|
||||
|
||||
@ -259,12 +259,12 @@ 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<null>) => void;
|
||||
getResult: (callParams: CallParams<null>) => number;
|
||||
add: (n: number, callParams: CallParams<"n">) => void | Promise<void>;
|
||||
subtract: (n: number, callParams: CallParams<"n">) => void | Promise<void>;
|
||||
multiply: (n: number, callParams: CallParams<"n">) => void | Promise<void>;
|
||||
divide: (n: number, callParams: CallParams<"n">) => void | Promise<void>;
|
||||
reset: (callParams: CallParams<null>) => void | Promise<void>;
|
||||
getResult: (callParams: CallParams<null>) => number | Promise<number>;
|
||||
}
|
||||
```
|
||||
|
||||
@ -274,9 +274,9 @@ export interface CalcDef {
|
||||
|
||||
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 omitted.
|
||||
|
||||
@ -290,11 +290,49 @@ func callMeBack(callback: string, i32 -> ()):
|
||||
The type for `callback` argument will be:
|
||||
|
||||
```typescript
|
||||
callback: (arg0: string, arg1: number, callParams: CallParams<'arg0' | 'arg1'>) => void,
|
||||
callback: (arg0: string, arg1: number, callParams: CallParams<'arg0' | 'arg1'>) => void | Promise<void>,
|
||||
```
|
||||
|
||||
For the service definitions arguments are named (see calc example above)
|
||||
|
||||
### Using asynchronous code in callbacks
|
||||
|
||||
Typescript code generated by Aqua compiler has two scenarios where a user should specify a callback function. These are services and callback arguments of function in aqua. If you look at the return type of the generated function you will see a union of callback return type and the promise with this type, e.g `string | Promise<string>`. Fluence-js supports both sync and async version of callbacks and figures out which one is used under the hood. The callback be made asynchronous like any other function in javascript: either return a Promise or mark it with async keyword to take advantage of async-await pattern.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
func withCallback(callback: string -> ()):
|
||||
callback()
|
||||
|
||||
service MyService:
|
||||
callMe(string)
|
||||
```
|
||||
|
||||
Here we are returning a promise
|
||||
|
||||
```typescript
|
||||
registerMyService({
|
||||
callMe: (arg): Promise<void> => {
|
||||
return new Promise((resolve) => {
|
||||
setTimeout(() => {
|
||||
console.log("I'm running 3 seconds after call");
|
||||
resolve();
|
||||
}, 3000);
|
||||
});
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
And here we are using async-await pattern
|
||||
|
||||
```typescript
|
||||
await withCallback(async (arg) => {
|
||||
const data = await getStuffFromDatabase(arg);
|
||||
console.log("");
|
||||
});
|
||||
```
|
||||
|
||||
### 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.
|
||||
@ -309,6 +347,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 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 see full specification of `CallParams` type see [API reference](https://github.com/fluencelabs/gitbook-docs/tree/77344eb147c2ce17fe1c0f37013082fc85c1ffa3/js-sdk/js-sdk/6_reference/modules.md)
|
||||
|
||||
@ -2,22 +2,29 @@
|
||||
|
||||
Fluence JS versioning scheme is the following: `0.BREAKING.ENHANCING`
|
||||
|
||||
* `0` shows that Fluence JS does not meet its vision yet, so API can change quickly
|
||||
* `BREAKING` part is incremented for each breaking API change
|
||||
* `ENHANCING` part is incremented for every fix and update which is compatible on API level
|
||||
- `0` shows that Fluence JS does not meet its vision yet, so API can change quickly
|
||||
- `BREAKING` part is incremented for each breaking API change
|
||||
- `ENHANCING` part is incremented for every fix and update which is compatible on API level
|
||||
|
||||
## [0.13.0](https://github.com/fluencelabs/fluence-js/releases/tag/v0.13.0) – September 24, 2021
|
||||
## [0.14.2](https://github.com/fluencelabs/fluence-js/releases/tag/v0.14.2) – October 21, 2021
|
||||
|
||||
* `PeerStatus` is now exported from index file \([\#80](https://github.com/fluencelabs/fluence-js/pull/80)\)
|
||||
* `KeyPair`: method `fromBytes` is replaced with fromEd25519SK \([\#81](https://github.com/fluencelabs/fluence-js/pull/81)\)
|
||||
FluencePeer: add option to specify default TTL for all new particles \([\#91](https://github.com/fluencelabs/fluence-js/pull/91)\)
|
||||
|
||||
## [0.14.1](https://github.com/fluencelabs/fluence-js/releases/tag/v0.14.1) – October 20, 2021
|
||||
|
||||
Compiler support: fix issue with incorrect check for missing fields in service registration \([\#90](https://github.com/fluencelabs/fluence-js/pull/90)\)
|
||||
|
||||
## [0.14.0](https://github.com/fluencelabs/fluence-js/releases/tag/v0.14.0) – October 20, 2021
|
||||
|
||||
Compiler support: added support for asynchronous code in service definitions and callback parameters of functions. \([\#83](https://github.com/fluencelabs/fluence-js/pull/83)\)
|
||||
|
||||
## [0.12.1](https://github.com/fluencelabs/fluence-js/releases/tag/v0.12.1) – September 14, 2021
|
||||
|
||||
* `KeyPair`: add fromBytes, toEd25519PrivateKey \([\#78](https://github.com/fluencelabs/fluence-js/pull/78)\)
|
||||
- `KeyPair`: add fromBytes, toEd25519PrivateKey \([\#78](https://github.com/fluencelabs/fluence-js/pull/78)\)
|
||||
|
||||
## [0.12.0](https://github.com/fluencelabs/fluence-js/releases/tag/v0.13.0) – September 10, 2021
|
||||
|
||||
* The API to work with the default Fluence Peer has been put under the facade `Fluence`. Method `init` was renamed to `start` and `uninit` renamed to `stop`. `connectionStatus` migrated to `getStatus`.
|
||||
- The API to work with the default Fluence Peer has been put under the facade `Fluence`. Method `init` was renamed to `start` and `uninit` renamed to `stop`. `connectionStatus` migrated to `getStatus`.
|
||||
|
||||
To migrate from 0.11.0 to 0.12.0
|
||||
|
||||
@ -30,5 +37,4 @@ To migrate from 0.11.0 to 0.12.0
|
||||
|
||||
## [0.11.0](https://github.com/fluencelabs/fluence-js/releases/tag/v0.11.0) – September 08, 2021
|
||||
|
||||
* Update JS SDK api to the new version \([\#61](https://github.com/fluencelabs/fluence-js/pull/61)\)
|
||||
|
||||
- Update JS SDK api to the new version \([\#61](https://github.com/fluencelabs/fluence-js/pull/61)\)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user