fluencelabs/examples
1
0
Fork 0
mirror of https://github.com/fluencelabs/examples synced 2024-12-04 19:20:17 +00:00
Code Issues Projects Releases Wiki Activity

feat: Update readme files for JS Client examples (#430)

Browse Source
This commit is contained in:
Pavel 2023-02-23 22:02:15 +04:00 committed by GitHub
parent 3678e46b66
commit 9e5e485e0a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 78 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
js-client-examples/browser-example/README.md
View File

@ -4,6 +4,12 @@ This sample project demonstrates how fluence network can be accessed from the br
## Getting started ## Getting started
Install dependencies:
```bash
npm i
```
Run aqua compiler in watch mode: Run aqua compiler in watch mode:
```bash ```bash
@ -18,130 +24,6 @@ npm start
The browser window with `localhost:3000` should open The browser window with `localhost:3000` should open
## How it works ## Learn more
The application can be split into two main building blocks: the runtime provided by the `@fluencelabs/fluence` package and the compiler for the `Aqua` language. The workflow is as follows:
1. You write aqua code
2. Aqua gets compiled into the typescript file
3. The typescript is build by the webpack (or any other tool of you choice) into js bunlde.
## Project structure
```
aqua (1)
┗ getting-started.aqua (3)
node_modules
public
src
┣ _aqua (2)
┃ ┗ getting-started.ts (4)
┣ App.scss
┣ App.tsx
┣ index.css
┣ index.tsx
┣ logo.svg
┗ react-app-env.d.ts
package-lock.json
package.json
tsconfig.json
```
The project structure is based on the create-react-app template with some minor differences:
* `aqua` (1) contains the Aqua source code files. The complier picks them up and generate corresponding typescript file. See `getting-started.aqua` (3) and `getting-started.ts` respectively
* `src/_aqua` (2) is where the generated target files are places. The target directory is conveniently placed inside the sources directory which makes it easy to import typescript functions from the application source code
## npm packages and scripts
The following npm packages are used:
* `@fluencelabs/fluence` - is the client for Fluence Network running inside the browser. See https://github.com/fluencelabs/fluence-js for additional information
* `@fluencelabs/fluence-network-environment` - is the maintained list of Fluence networks and nodes to connect to.
* `@fluencelabs/aqua` - is the command line interface for Aqua compiler. See https://github.com/fluencelabs/aqua for more information
* `@fluencelabs/aqua-lib` - Aqua language standard library
* `chokidar-cli` - A tool to watch for aqua file changes and compile them on the fly
The compilation of aqua code is implemented with these scripts:
```
scripts: {
...
"compile-aqua": "aqua -i ./aqua/ -o ./src/_aqua",
"watch-aqua": "chokidar \"**/*.aqua\" -c \"npm run compile-aqua\""
}
...
```
The interface is pretty straightforward: you just specify the input and output directories for the compiler.
## Aqua code
```
import "@fluencelabs/aqua-lib/builtin.aqua"
func getRelayTime(relayPeerId: PeerId) -> u64: (1)
on relayPeerId: (2)
ts <- Peer.timestamp_ms() (3)
<- ts (4)
```
The code above defines a function which retrieves the current timestamp from the relay node. The function works as following:
1. The function definition, specifying arguments and return value types
2. Shift the execution to the peer with id equal to `relayPeerId`
3. Calls built-in function on the current peer and stores the result into a variable
4. Returns the result
The function gets compiled into typescript and can be called from the application code (see next section)
## Application code
Let's take a look at how we can use Fluence from typecript.
First, we need to import the relevant packages:
```typescript
import { createClient, FluenceClient } from "@fluencelabs/fluence";
import { krasnodar } from "@fluencelabs/fluence-network-environment";
import { getRelayTime } from "./_aqua/getting-started";
```
Please notice that the function defined in Aqua has been compiled into typescript and can be directly imported. 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!
Next we initialize the client:
```typescript
const relayNode = krasnodar[0];
function App() {
const [client, setClient] = useState<FluenceClient | null>(null);
...
useEffect(() => {
createClient(relayNode)
.then((client) => setClient(client))
.catch((err) => console.log("Client initialization failed", err));
}, [client]);
```
Every peer running in the browser must connect to the network through a relay node. We use the first node of the krasnodar network there. In our example we store the client using React `useState` facilities. Feel free to store wherever you store other application state.
Executing Aqua is as easy as calling a function in typesctipt:
```typescript
const doGetRelayTime = async () => {
if (!client) {
return;
}
const time = await getRelayTime(client, relayNode.peerId);
setRelayTime(new Date(time));
};
```
To learn more, refer to the [documentation page](https://fluence.dev//docs/build/js-client/js-client)

21
js-client-examples/hello-world/README.md Normal file
View File

@ -0,0 +1,21 @@
# Getting Started with Fluence
This is a minimalistic Node.js application for Fluence using Fluence JS Client.
## Getting started
Install dependencies:
```bash
npm i
```
Run the Node.js application:
```bash
npm start
```
## Learn more
To learn more, refer to the [documentation page](https://fluence.dev//docs/build/js-client/js-client)

29
js-client-examples/node-example/README.md Normal file
View File

@ -0,0 +1,29 @@
# Getting Started with Fluence
This is a sample Node.js application using Fluence JS Client. It exposes a calculator service written in Typescript which can be accessed from Fluence Network using Aqua language
## Getting started
Install dependencies:
```bash
npm i
```
Start the Node.js application:
```bash
npm start
```
This should start listening to incoming particles from Fluence Network.
Try interacting with the application with some aqua:
```bash
./run_calculation.sh
```
## Learn more
To learn more, refer to the [documentation page](https://fluence.dev//docs/build/js-client/js-client)

10
quickstart/1-browser-to-browser/README.md Normal file
View File

@ -0,0 +1,10 @@
# Getting started
```bash
npm i
npm start
```
The browser window with `localhost:3000` should open
To learn more, refer to the [documentation page](https://fluence.dev//docs/build/quick-start/browser-to-browser/)

10
quickstart/3-browser-to-service/README.md Normal file
View File

@ -0,0 +1,10 @@
# Getting started
```bash
npm i
npm start
```
The browser window with `localhost:3000` should open
To learn more, refer to the [documentation page](https://fluence.dev//docs/build/quick-start/browser-to-service/)