fluencelabs/gitbook-docs
1
0
Fork 0
mirror of https://github.com/fluencelabs/gitbook-docs synced 2025-04-24 23:42:15 +00:00
Code Issues Projects Releases Wiki Activity

Update documentation for JS SDK-related examples (#24)

Browse Source
This commit is contained in:
Pavel 2021-09-12 00:55:59 +03:00 committed by GitHub
parent 849d9bbd44
commit 93bd78fa83
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 162 additions and 404 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
SUMMARY.md
View File

@ -1,34 +1,32 @@
# 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/3_in_depth.md)
* [Running app in nodejs](js-sdk/5_run_in_node.md)
* [Running app in browser](js-sdk/4_run_in_browser-1.md)
* [Api reference](js-sdk/6-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)
- [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/5_run_in_node.md)
- [Running app in browser](js-sdk/4_run_in_browser-1.md)
- [Api reference](js-sdk/6-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)
- [Research, Papers And References](research-papers-and-references.md)

244
building-a-frontend-with-js-sdk.md
View File

@ -1,244 +0,0 @@
---
description: WIP -- Tread Carefully
---
# Building A Frontend with JS SDK
The JS SDK provides the means to connect to a Fluence peer-to-peer network from a javascript environment and is currently available for _node.js_ and modern browsers.
To create an application two building blocks are needed: the JS SDK and the Aqua compiler. Both packages are available as _npm_ packages. The JS SDK wraps the AIR interpreter and provides a connection to the network. There is la ow-level api for executing AIR scripts and registering for service call handlers. The Aqua compiler allows to write code in Aqua language and compile it to typescript code which can be directly used with the JS SDK.
### Basic usage
To demonstrate the development of a client application, we initiate a bare-bones _node.js_ package and review the steps needed to install the JS SDK and Aqua compiler.
#### 1. Install The _npm_ Package
For the purpose of the demo we will use a very minimal _npm_ package with typescript support:
```text
src
┗ index.ts (1)
package.json (2)
tsconfig.json
```
index.ts \(1\):
```typescript
async function main() {
console.log("Hello, world!");
}
main();
```
package.json \(2\):
```javascript
{
"name": "demo",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"exec": "node -r ts-node/register src/index.ts"
},
"author": "",
"license": "ISC",
"devDependencies": {
"ts-node": "^9.1.1",
"typescript": "^4.2.4"
}
}
```
Let's test if it works:
```bash
$ npm install
$ npm run exec
```
The following should be printed
```bash
$ npm run exec
> demo@1.0.0 exec C:\work\demo
> node -r ts-node/register src/index.ts
Hello, world!
$ C:\work\demo>
```
#### 2. Setting JS SDK and connecting to Fluence network
Install the dependencies, you will need these two packages.
```bash
npm install @fluencelabs/fluence @fluencelabs/fluence-network-environment
```
The first one is the SDK itself and the second is a maintained list of Fluence networks and nodes to connect to.
All of the communication with the Fluence network is done by using `FluenceClient`. You can create one with `createClient` function. The client encapsulates air interpreter and connects to the network through the relay. Currently any node in the network can be used a relay.
```typescript
import { createClient } from "@fluencelabs/fluence";
import { testNet } from "@fluencelabs/fluence-network-environment";
async function main() {
const client = await createClient(testNet[1]);
console.log("Is client connected: ", client.isConnected);
await client.disconnect();
}
main();
```
Let's try it out:
```bash
$ npm run exec
> demo@1.0.0 exec C:\work\demo
> node -r ts-node/register src/index.ts
Is client connected: true
$
```
**Note**: typically you should have a single instance`FluenceClient` per application since it represents it's identity in the network. You are free to store the instance anywhere you like.
#### 3. Setting up aqua compiler
Aqua is the proffered language for the Fluence network. It can be used with javascript-based environments via _npm_ package.
**Warning: the package requires java to be installed \(it will call "java -jar ... "\)**
```bash
npm install --save-dev @fluencelabs/aqua-cli
```
We will also need the standard library for the language
```text
npm install --save-dev @fluencelabs/aqua-lib
```
Let's add our first aqua file:
```text
aqua (1)
┗ demo.aqua (2)
node_modules
src
┣ compiled (3)
┗ index.ts
package-lock.json
package.json
tsconfig.json
```
Add two directories, one for aqua sources \(1\) and another for the typescript output \(3\)
Create a new text file called `demo.aqua` \(2\):
```text
import "@fluencelabs/aqua-lib/builtin.aqua"
func demo(nodePeerId: PeerId) -> []string:
on nodePeerId:
res <- Peer.identify()
<- res.external_addresses
```
This script will gather the list of external addresses from some node in the network. For more information about the aqua language refer to the aqua documentation.
The aqua code can now be compiled by using the compiler CLI. We suggest adding a script to the package.json file like so:
```javascript
...
"scripts": {
"exec": "node -r ts-node/register src/index.ts",
"compile-aqua": "aqua-cli -i ./aqua/ -o ./src/compiled"
},
...
```
Run the compiler:
```bash
npm run compile-aqua
```
A typescript file should be generated like so:
```text
aqua
┗ demo.aqua
node_modules
src
┣ compiled
┃ ┗ demo.ts <--
┗ index.ts
package-lock.json
package.json
tsconfig.json
```
#### 4. Consuming the compiled code
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. Note that all the type information and therefore type checking and code completion facilities are there!
Let's do it!
```typescript
import { createClient } from "@fluencelabs/fluence";
import { testNet } from "@fluencelabs/fluence-network-environment";
import { demo } from "./compiled/demo"; // import the generated file
async function main() {
const client = await createClient(testNet[1]);
console.log("Is client connected: ", client.isConnected);
const otherNode = testNet[2].peerId;
const addresses = await demo(client, otherNode); // call it like a normal function in typescript
console.log(`Node ${otherNode} is connected to: ${addresses}`);
await client.disconnect();
}
main();
```
if everything is fine you have similar result:
```text
$ npm run exec
> demo@1.0.0 exec C:\work\demo
> node -r ts-node/register src/index.ts
Is client connected: true
Node 12D3KooWHk9BjDQBUqnavciRPhAYFvqKBe4ZiPPvde7vDaqgn5er is connected to: /ip4/138.197.189.50/tcp/7001,/ip4/138.197.189.50/tcp/9001/ws
$
```
### Advanced usage
Fluence JS SDK gives options to register own handlers for aqua vm service calls
**TBD**
### References
* For the list of compiler options see: [https://github.com/fluencelabs/aqua](https://github.com/fluencelabs/aqua)
* **Repository with additional examples:** [**https://github.com/fluencelabs/aqua-playground**](https://github.com/fluencelabs/aqua-playground)\*\*\*\*
**Building A Frontend with JS SDK**

11
js-sdk/1_concepts.md
View File

@ -2,7 +2,7 @@
## 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:
`@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:
1. Connectivity with one or many Fluence Node which allows sending particles to and receiving from other Peers
2. The Peer Id identifying the node in the network
@ -31,10 +31,9 @@ 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

57
js-sdk/2_basics.md
View File

@ -14,9 +14,20 @@ service HelloWorld("hello-world"):
func sayHello():
HelloWorld.hello("Hello, world!")
func getRelayTime() -> u64:
on HOST_PEER:
ts <- Peer.timestamp_ms()
<- ts
```
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.
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.
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.
## Installing dependencies
@ -36,10 +47,14 @@ The first one is the SDK itself and the second is a maintained list of Fluence n
Aqua compiler cli has to be installed, but is not needed at runtime.
**Warning: the package requires java to be installed \(it will call "java -jar ... "\)**
```bash
npm install --save-dev @fluencelabs/aqua
```
Aqua comes with the standard library which can accessed from "@fluencelabs/aqua-lib" package. All the aqua packages are only needed at compiler time, so we install it as a development dependency
```bash
npm install --save-dev @fluencelabs/aqua-cli
npm install --save-dev @fluencelabs/aqua-lib
```
Also we might want to have aqua source files automatically recompiled on every save. We will take advantage of chokidar for that:
@ -76,7 +91,7 @@ The overall project structure looks like this:
The Aqua compiler can be run with `npm`:
```bash
npx aqua-cli -i ./aqua/ -o ./src/_aqua
npx aqua -i ./aqua/ -o ./src/_aqua
```
We recommend to store this logic inside a script in `packages.json` file:
@ -86,7 +101,7 @@ We recommend to store this logic inside a script in `packages.json` file:
...
"scripts": {
...
"compile-aqua": "aqua-cli -i ./aqua/ -o ./src/_aqua", // (1)
"compile-aqua": "aqua -i ./aqua/ -o ./src/_aqua", // (1)
"watch-aqua": "chokidar \"**/*.aqua\" -c \"npm run compile-aqua\"" // (2)
},
...
@ -102,14 +117,19 @@ Using the code generated by the compiler is as easy as calling a function. The c
Let's see how use generated code in our application. `index.ts`:
```typescript
import { FluencePeer } from "@fluencelabs/fluence";
import { registerHelloWorld, sayHello } from "./_aqua/hello-world"; // (1)
import { Fluence } from "@fluencelabs/fluence";
import { krasnodar } from "@fluencelabs/fluence-network-environment"; // (1)
import {
registerHelloWorld,
sayHello,
getRelayTime,
} from "./_aqua/hello-world"; // (2)
async function main() {
await FluencePeer.default.init(); // (2)
await Fluence.start({ connectTo: krasnodar[0] }); // (3)
// (3)
registerHelloWorld({
// (3)
hello: async (str) => {
console.log(str);
},
@ -117,21 +137,27 @@ async function main() {
await sayHello(); // (4)
await FluencePeer.default.uninit(); // (5)
const relayTime = await getRelayTime(); // (5)
console.log("The relay time is: ", new Date(relayTime).toLocaleString());
await Fluence.stop(); // (6)
}
main();
```
\(1\) Aqua compiler provides functions which can be directly imported like any normal typescript function.
\(1\) Import list of possible relay nodes (network enironment)
\(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\) Aqua compiler provides functions which can be directly imported like any normal typescript function.
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
\(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
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 `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
\(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.
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.
\(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.
Let's try running the example:
@ -143,3 +169,4 @@ If everything has been done correctly yuo should see `Hello, world!` in the cons
The next secion 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]

114
js-sdk/3_in_depth.md
View File

@ -6,14 +6,28 @@
In this section we will cover the JS SDK in-depth.
## Fluence
`@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)
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 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 everal different peer at once. The overall workflow with the `FluencePeer` is the following:
1. Create an instance of the peer
2. Initializing the peer
2. Startign the peer
3. Using the peer in the application
4. Uninitializing the peer
4. Stopping the peer
To create a new peer simple instantiate the `FluencePeer` class:
@ -21,61 +35,23 @@ 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 `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:
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:
```typescript
await peer.init({
await peer.star({
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](https://github.com/fluencelabs/gitbook-docs/tree/77344eb147c2ce17fe1c0f37013082fc85c1ffa3/js-sdk/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();
await peer.stop();
```
## 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
```
The peer by itself does not do any useful work. You should take advantage of functions generated by the Aqua compiler.
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:
@ -91,10 +67,10 @@ async function main() {
const peer2 = new FluencePeer();
// Don't forget to initialize peers
await peer1.init({
await peer1.start({
connectTo: relay,
});
await peer2.init({
await peer2.start({
connectTo: relay,
});
@ -124,8 +100,8 @@ async function main() {
await someCallableFunction(peer1, arg1, arg2, arg3);
await peer1.uninit();
await peer2.uninit();
await peer1.stop();
await peer2.stop();
}
// ... more application logic
@ -163,7 +139,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>`.
@ -193,6 +169,11 @@ export async function callMeBack(
### Service definitions
```
service ServiceName:
-- service interface
```
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
@ -200,48 +181,48 @@ export interface ServiceNameDef {
//... service function definitions
}
export function registerStringExtra(
export function registerServiceName(
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.
- `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.
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(
export function registerServiceName(
//
service: ServiceNameDef
): void;
// (2)
export function registerStringExtra(
export function registerServiceName(
serviceId: string,
service: ServiceNameDef
): void;
// (3)
export function registerStringExtra(
export function registerServiceName(
peer: FluencePeer,
service: ServiceNameDef
): void;
// (4)
export function registerStringExtra(
export function registerServiceName(
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
1. Uses default Fluence Peer and the default id taken from aqua definition
2. Uses default Fluence Peer 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.
@ -249,20 +230,20 @@ If the default id **is not defined** in aqua code the overloads will exclude one
```typescript
// (1)
export function registerStringExtra(
export function registerServiceName(
serviceId: string,
service: ServiceNameDef
): void;
// (2)
export function registerStringExtra(
export function registerServiceName(
peer: FluencePeer,
serviceId: string,
service: ServiceNameDef
): void;
```
1. Uses `FluencePeer.default` and specifies the service id explicitly
1. Uses default Fluence Peer and specifies the service id explicitly
2. Specifying both peer and the service id.
### Service interface
@ -298,9 +279,9 @@ export interface CalcDef {
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
- `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.
@ -336,4 +317,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)

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

@ -1,4 +1,7 @@
# Running app in browser
You can use the JS SDK with any framework \(or even without it\). Just follow the steps from the previous sections. FluentPad is an example application written in React: [https://github.com/fluencelabs/fluent-pad](https://github.com/fluencelabs/fluent-pad)
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.
See the browser-example which demonstrate integrating Fluence with React: (github)[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)

25
quick-start.md
View File

@ -6,10 +6,10 @@ Fluence provides a [docker-based development environment](https://github.com/flu
Fluence's devcontainer is a ready to use dockerized development environment with VSCode integration containing the following tools:
* [`aqua-cli`](https://www.npmjs.com/package/@fluencelabs/aqua-cli) to compile [Aqua](https://doc.fluence.dev/aqua-book/) to AIR or Typescript
* [`fldist`](https://www.npmjs.com/package/@fluencelabs/fldist) to manage services and optionally execute compiled Aqua from the command line
* [`marine`](https://crates.io/crates/marine) to compile services developed in Rust to the wasm32-wasi target
* [`mrepl`](https://crates.io/crates/mrepl) to run, test and debug Wasm services locally
- [`aqua`](https://www.npmjs.com/package/@fluencelabs/aqua) to compile [Aqua](https://doc.fluence.dev/aqua-book/) to AIR or Typescript
- [`fldist`](https://www.npmjs.com/package/@fluencelabs/fldist) to manage services and optionally execute compiled Aqua from the command line
- [`marine`](https://crates.io/crates/marine) to compile services developed in Rust to the wasm32-wasi target
- [`mrepl`](https://crates.io/crates/mrepl) to run, test and debug Wasm services locally
### How to install
@ -17,21 +17,21 @@ Docker and optionally VSCode need to be available on your system. For Docker ins
With Docker and VSCode in place:
* Install Remote-Containers extension in VSCode
- Install Remote-Containers extension in VSCode
![Install Remote - Containers in VSCode](.gitbook/assets/image%20%2813%29.png)
* Run Remote-Containers: Clone Repository in Container Volume... through command palette \(F1 or Cmd-Shift-P\)
- Run Remote-Containers: Clone Repository in Container Volume... through command palette \(F1 or Cmd-Shift-P\)
![Select Remote Container Clone Repository](.gitbook/assets/image%20%2814%29.png)
* Enter `fluencelabs/devcontainer`
- Enter `fluencelabs/devcontainer`
![Select \`fluencelabs/devcontainer\`](.gitbook/assets/image%20%2815%29.png)
![Select `fluencelabs/devcontainer`](.gitbook/assets/image%20%2815%29.png)
* When asked for branch, press enter \(main\)
* When asked for volume, press enter \(unique\)
* open Terminal within VSCode \(ctrl-\`\)
- When asked for branch, press enter \(main\)
- When asked for volume, press enter \(unique\)
- open Terminal within VSCode \(ctrl-\`\)
![Installed And Ready Devcontainer in VSCode](.gitbook/assets/image%20%2812%29.png)
@ -51,7 +51,4 @@ We recommend you follow the above outlined sequence of tutorial sections startin
![Start With The Aqua Tutorial in VSCode](.gitbook/assets/image%20%2820%29.png)
If you encounter any problems or have suggestions, please open an issue or submit a PR. You can also reach out in [Discord](https://fluence.chat) or [Telegram](https://t.me/fluence_project). For more detailed reference resources, see the [Fluence documentation](https://doc.fluence.dev/docs/) and [Aqua book](https://doc.fluence.dev/aqua-book/).

23
quick-start/README.md
View File

@ -12,10 +12,10 @@ For your development convenience, Fluence provides a [docker-based development e
Fluence's devcontainer is a ready to use dockerized development environment with VSCode integration containing the following tools:
* [`aqua`](https://www.npmjs.com/package/@fluencelabs/aqua-cli) to compile [Aqua](https://doc.fluence.dev/aqua-book/) to AIR or wrapped in Typescript
* [`fldist`](https://www.npmjs.com/package/@fluencelabs/fldist) to manage services and optionally execute compiled Aqua from the command line
* [`marine`](https://crates.io/crates/marine) to compile services developed in Rust to the wasm32-wasi target
* [`mrepl`](https://crates.io/crates/mrepl) to run, test and debug WebAssembly \(Wasm\) services locally
- [`aqua`](https://www.npmjs.com/package/@fluencelabs/aqua) to compile [Aqua](https://doc.fluence.dev/aqua-book/) to AIR or wrapped in Typescript
- [`fldist`](https://www.npmjs.com/package/@fluencelabs/fldist) to manage services and optionally execute compiled Aqua from the command line
- [`marine`](https://crates.io/crates/marine) to compile services developed in Rust to the wasm32-wasi target
- [`mrepl`](https://crates.io/crates/mrepl) to run, test and debug WebAssembly \(Wasm\) services locally
### How to install
@ -23,21 +23,21 @@ Docker and optionally VSCode need to be available on your system. For Docker ins
With Docker and VSCode in place:
* Install Remote-Containers extension in VSCode
- Install Remote-Containers extension in VSCode
![Install Remote - Containers in VSCode](../.gitbook/assets/image%20%2813%29.png)
* `Run Remote-Containers: Clone Repository in Container Volume...` via the command palette \(F1 or Cmd-Shift-P\)
- `Run Remote-Containers: Clone Repository in Container Volume...` via the command palette \(F1 or Cmd-Shift-P\)
![Select Remote Container Clone Repository](../.gitbook/assets/image%20%2814%29.png)
* Enter `fluencelabs/devcontainer`
- Enter `fluencelabs/devcontainer`
![Select \`fluencelabs/devcontainer\`](../.gitbook/assets/image%20%2815%29.png)
![Select `fluencelabs/devcontainer`](../.gitbook/assets/image%20%2815%29.png)
* When asked for branch, press enter \(main\)
* When asked for volume, press enter \(unique\)
* Open Terminal in VSCode \(ctrl-\`\)
- When asked for branch, press enter \(main\)
- When asked for volume, press enter \(unique\)
- Open Terminal in VSCode \(ctrl-\`\)
![Installed And Ready Devcontainer in VSCode](../.gitbook/assets/image%20%2818%29%20%281%29.png)
@ -48,4 +48,3 @@ Congratulations, you now have a fully functional Fluence development environment
If you encounter any problems or have suggestions, please open an issue or submit a PR. You can also reach out in [Discord](https://fluence.chat) or [Telegram](https://t.me/fluence_project). For more detailed reference resources, see the [Fluence documentation](https://doc.fluence.dev/docs/) and [Aqua book](https://doc.fluence.dev/aqua-book/).
All right, now we are ready to proceed to the first application on Fluence.

25
tutorials_tutorials/building-a-frontend-with-js-sdk.md
View File

@ -110,16 +110,16 @@ $
**Note**: typically you should have a single instance`FluenceClient` per application since it represents it's identity in the network. You are free to store the instance anywhere you like.
#### 3. Setting Up The Aqua Compiler
#### 3. Setting Up The Aqua Compiler
Aqua is the proffered language for the Fluence network. It can be used with javascript-based environments via npm package.
{% hint style="warning" %}
**The package requires java to be installed as it calls "java -jar ... "**
**The package requires java to be installed as it calls "java -jar ... "**
{% endhint %}
```bash
npm install --save-dev @fluencelabs/aqua-cli
npm install --save-dev @fluencelabs/aqua
```
We will also need the standard library for the language
@ -136,9 +136,9 @@ aqua (1)
node_modules
src
┣ compiled (3)
┗ index.ts
┗ index.ts
package-lock.json
package.json
package.json
tsconfig.json
```
@ -163,7 +163,7 @@ The aqua code can now be compiled by using the compiler CLI. We suggest adding a
...
"scripts": {
"exec": "node -r ts-node/register src/index.ts",
"compile-aqua": "aqua-cli -i ./aqua/ -o ./src/compiled"
"compile-aqua": "aqua -i ./aqua/ -o ./src/compiled"
},
...
```
@ -177,15 +177,15 @@ npm run compile-aqua
A typescript file should be generated like so:
```text
aqua
┗ demo.aqua
aqua
┗ demo.aqua
node_modules
src
┣ compiled
┃ ┗ demo.ts <--
┗ index.ts
┗ index.ts
package-lock.json
package.json
package.json
tsconfig.json
```
@ -237,6 +237,5 @@ Fluence JS SDK gives options to register own handlers for aqua vm service calls
### References
* For the list of compiler options see: [https://github.com/fluencelabs/aqua](https://github.com/fluencelabs/aqua)
* Repository with additional examples: [**https://github.com/fluencelabs/aqua-playground**](https://github.com/fluencelabs/aqua-playground)\*\*\*\*
- For the list of compiler options see: [https://github.com/fluencelabs/aqua](https://github.com/fluencelabs/aqua)
- Repository with additional examples: [**https://github.com/fluencelabs/aqua-playground**](https://github.com/fluencelabs/aqua-playground)\*\*\*\*