Libraries

import declaration allows to use functions, services and data types defined in another module on the file system. While it's a very simple mechanic, together with NPM flexibility it enables full-blown package management in Aqua.

As Aqua is itself compiled to TypeScript, there are usually two kinds of libraries:

  • With TypeScript API. Such libraries contain TS precompiled from Aqua, use them when you just want to call functions from TypeScript.

  • With Aqua API. You want to use them when writing your own Aqua scripts.

Available Aqua Libraries

To use library precompiled to TypeScript/JS, add -ts suffix, for example: @fluencelabs/aqua-dht => @fluencelabs/aqua-dht-ts

How To Use Aqua Libraries

To use a library, you need to download it by adding the library to dependencies in package.json and then running npm install.

If you're not familiar with NPM, package.json is a project definition file. You can specify dependencies to be downloaded from npmjs.org and define custom commands (scripts), which can be executed from the command line, e.g. npm run compile-aqua.

To create an NPM project, run npm initin a directory of your choice and follow the instructions.

Here's an example of adding aqua-lib to package.json dependencies:

{
"name": "my-awesome-project",
"version": "0.0.1",
"dependencies": {
"@fluencelabs/aqua-lib": "0.1.10"
}
}

After running npm i, you will have @fluencelabs/aqua-lib in node_modules

In Aqua

After the library is downloaded, you can import it in your .aqua script as documented in Imports And Exports:

import "@fluencelabs/aqua-lib/builtin.aqua"

Check out corresponding subpages for the API of available libraries.

In TypeScript and JavaScript

For this example, we'll use @fluencelabs/aqua-dht-ts

(note the -ts suffix, we're using the library with TS/JS API)

To execute Aqua functions, you need to be connected to the Fluence network. The easiest way is to add JS SDK to dependencies:

"dependencies": {
"@fluencelabs/aqua-dht-ts": "0.1.0",
"@fluencelabs/fluence": "0.9.53",
"@fluencelabs/fluence-network-environment": "1.0.10"
}

After executing npm install, the libraries are downloaded for immediate use in TS/JS code:

import { initTopicAndSubscribe, findSubscribers } from "@fluencelabs/aqua-dht-ts";
import { createClient } from "@fluencelabs/fluence";
import { krasnodar } from "@fluencelabs/fluence-network-environment";
async function main() {
// connect to the Fluence network
const client = await createClient(krasnodar[1]);
let topic = "myTopic";
let value = "myValue";
// create topic (if not exists) and subscribe on it
await initTopicAndSubscribe(client, client.relayPeerId!, topic, value, client.relayPeerId!, null);
// find other peers subscribed to that topic
let subscribers = await findSubscribers(client, client.relayPeerId!, topic);
console.log("found subscribers:", subscribers);
}