fluencelabs/fluence-js
1
0
Fork 0
mirror of https://github.com/fluencelabs/fluence-js.git synced 2024-12-05 02:10:18 +00:00
Code Issues Projects Releases Wiki Activity
JS/TS Peer for the Fluence p2p network
278 Commits 32 Branches 260 Tags 71 MiB
TypeScript 92.9%
JavaScript 6.5%
HTML 0.4%
CSS 0.2%
d9b2c00c79
Go to file
fluencebot d9b2c00c79
chore: release master (#317) 
* chore: release master

* chore: Regenerate pnpm lock file
2023-06-29 13:03:49 -06:00
.github chore: release master (#317) 2023-06-29 13:03:49 -06:00
packages chore: release master (#317) 2023-06-29 13:03:49 -06:00
.editorconfig Turn on noImplicitAny and strictNullChecks (#153) 2022-05-12 17:14:16 +03:00
.gitignore chore(deps): bump fluence-js to 0.27.0, avm: 0.31.11 (#199) 2022-11-01 20:00:17 +04:00
.npmrc feat!: Standalone web JS Client (#243) 2023-02-13 21:41:35 +07:00
.prettierignore feat: support signatures [fixes DXJ-389] (#310) 2023-06-20 13:52:41 -06:00
.prettierrc.cjs feat!: Standalone web JS Client (#243) 2023-02-13 21:41:35 +07:00
ci.cjs chore: Temporary workaround for e2e version set (#294) 2023-03-31 11:31:39 +03:00
CONTRIBUTING.md feat(docs): README edited to represent the current JS Client API (#256) 2023-02-16 17:45:37 +03:00
DEVELOPING.md feat(docs): README edited to represent the current JS Client API (#256) 2023-02-16 17:45:37 +03:00
LICENSE feat(docs): README edited to represent the current JS Client API (#256) 2023-02-16 17:45:37 +03:00
package.json feat: Cleaning up technical debts (#295) 2023-04-03 20:52:40 +03:00
pnpm-lock.yaml chore: release master (#317) 2023-06-29 13:03:49 -06:00
pnpm-workspace.yaml chore: Add release-please (#240) 2023-02-15 16:45:04 +02:00
README.md feat(logs): Use debug.js library for logging [DXJ-327] (#285) 2023-03-10 23:03:34 +03:00
tsconfig.json fix: nodenext moduleResolution for js peer (#271) 2023-02-22 13:46:14 +03:00

README.md

Fluence JS Client

npm npm

This is the Javascript client for the Fluence network. The main role of the JS client is to connect to the Fluence Network and allow you to integrate Aqua code into your application.

Installation

Adding the Fluence JS client for your web application is very easy.

Browser-based Apps

  1. Add a script tag with the JS Client bundle to your index.html. The easiest way to do this is using a CDN (like JSDELIVR or UNPKG). The script is large, thus we highly recommend to use the async attribute.

    Here is an example using the JSDELIVR CDN:

    <head>
    <title>Cool App</title>
    <script
        src="https://cdn.jsdelivr.net/npm/@fluencelabs/js-client.web.standalone@0.13.3/dist/js-client.min.js"
        async
    ></script>
</head>

    If you cannot or don't want to use a CDN, feel free to get the script directly from the npm package and host it yourself. You can find the script in the /dist directory of the package. (Note: this option means that developers understand what they are doing and know how to serve this file from their own web server.)

  2. Install the following packages:

    npm i @fluencelabs/js-client.api @fluencelabs/fluence-network-environment

  3. Add the following lines at the beginning of your code:

    import { Fluence } from "@fluencelabs/js-client.api";
import { randomKras } from '@fluencelabs/fluence-network-environment';

Fluence.connect(randomKras());

Node.js Apps

Prerequisites:

The Fluence JS Client only supports the ESM format. This implies that a few preliminary steps are required if your project is not already using ESM:

  • Add "type": "module" to your package.json.
  • Replace "main": "index.js" with "exports": "./index.js" in your package.json.
  • Remove 'use strict'; from all JavaScript files.
  • Replace all require()/module.export with import/export.
  • Use only full relative file paths for imports: import x from '.'; → import x from './index.js';.

If you are using TypeScript:

  • Make sure you are using TypeScript 4.7 or later.
  • Add "module": "ESNext", "target": "ESNext", "moduleResolution": "nodenext" to your tsconfig.json.
  • Use only full relative file paths for imports: import x from '.'; → import x from './index.js';.
  • Remove namespace usage and use export instead.
  • You must use a .js extension in relative imports even though you're importing .ts files.

Installation:

  1. Install the following packages:

    npm i @fluencelabs/js-client.api"@fluencelabs/js-client.node @fluencelabs/fluence-network-environment

  2. Add the following lines at the beginning of your code:

    import '@fluencelabs/js-client.node';
import { Fluence } from "@fluencelabs/js-client.api";
import { randomKras } from '@fluencelabs/fluence-network-environment';

Fluence.connect(randomKras());

Usage in an Application

Once you've added the client, you can compile Aqua and run it in your application. To compile Aqua, use Fluence CLI.

  1. Install the package:

    npm i -D "@fluencelabs/fluence-cli"

  2. Add a directory in your project for Aqua code, e.g., _aqua.

  3. Put *.aqua files in that directory.

  4. Add a directory for compiled Aqua files inside your sources. For example, if your app source is located in the src directory, you can create src/_aqua.

  5. To compile Aqua code once, run npx fluence aqua -i ./_aqua -o ./src/_aqua/. To watch the changes and to recompile on the fly, add the -w flag: npx fluence aqua -w -i ./_aqua -o ./src/_aqua/.

    Hint: it might be a good idea to add these scripts to your package.json file. For example, you project structure could look like this:

     ┣ _aqua
 ┃ ┗ demo.aqua
 ┣ src
 ┃ ┣ _aqua
 ┃ ┃ ┗ demo.ts
 ┃ ┗ index.ts
 ┣ package-lock.json
 ┣ package.json
 ┗ tsconfig.json

    Then, your package.json file should include the following lines:

    {
  ...
  "scripts": {
    ...
    "aqua:compile": "fluence aqua -i ./aqua/ -o ./src/_aqua",
    "aqua:watch": "fluence aqua -w -i ./aqua/ -o ./src/_aqua"
  },
  ...
}

  6. Now you can import and call Aqua code from your application like this:

    import { getRelayTime } from "./_aqua/demo";

async function buttonClick() {
  const time = await getRelayTime();
  alert("relay time: " + time);
}

Debug

JS Client uses the debug library under the hood for logging. The log namespaces are structured on a per-component basis, following this structure:

fluence:<component>:trace
fluence:<component>:debug
fluence:<component>:error

Marine JS logs have a slightly different structure:

fluence:marine:<service id>:trace
fluence:marine:<service id>:debug
fluence:marine:<service id>:info
fluence:marine:<service id>:warn
fluence:marine:<service id>:error

Each level corresponds to a logging level in Marine JS.

Star (*) character can be used as a wildcard to enable logs for multiple components at once. For example, DEBUG=fluence:* will enable logs for all components. To exclude a component, use a minus sign before the component name. For example, DEBUG=fluence:*,-fluence:particle:*

Index of components:

  • particle: everything related to particle processing queue
  • aqua: infrastructure of aqua compiler support
  • connection: connection layer
  • marine: Marine JS logs

Enabling logs in Node.js

enable logs, pass the environment variable DEBUG with the corresponding log level. For example:

DEBUG=fluence:* node --loader ts-node/esm ./src/index.ts

Enabling logs in the browser

To enable logs, set the localStorage.debug variable. For example:

localStorage.debug = 'fluence:*'

NOTE

In Chromium-based web browsers (e.g. Brave, Chrome, and Electron), the JavaScript console will—by default—only show messages logged by debug if the "Verbose" log level is enabled.

Development

To hack on the Fluence JS Client itself, please refer to the development page.

Documentation

The starting point for all documentation related to Fluence is fluence.dev. We also have an active YouTube channel.

Support

Please, file an issue if you find a bug. You can also contact us at Discord or Telegram. We will do our best to resolve the issue ASAP.

Contributing

Any interested person is welcome to contribute to the project. Please, make sure you read and follow some basic rules.

License

All software code is copyright (c) Fluence Labs, Inc. under the Apache-2.0 license.