2021-01-29 13:48:27 +00:00
# Fluence JS SDK
2020-12-28 14:39:06 +00:00
2021-01-29 13:48:27 +00:00
[![npm ](https://img.shields.io/npm/v/@fluencelabs/fluence )](https://www.npmjs.com/package/@fluencelabs/fluence)
2020-12-28 14:39:06 +00:00
2021-01-29 13:48:27 +00:00
Official SDK for building web-based applications for Fluence
2020-05-14 12:20:39 +00:00
2021-01-29 13:48:27 +00:00
## About Fluence
2020-05-14 12:20:39 +00:00
2021-01-29 13:48:27 +00:00
Fluence is an open application platform where apps can build on each other, share data and users
| Layer | Tech | Scale | State | Based on |
| :-------------------: | :-------------------------------------------------------------------------------------------------------------------------------: | :------------------------------: | :-------------------------------: | :-----------------------------------------------------------------------------------------------------------: |
| Execution | [FCE ](https://github.com/fluencelabs/fce ) | Single peer | Disk, network, external processes | Wasm, [IT ](https://github.com/fluencelabs/interface-types ), [Wasmer\* ](https://github.com/fluencelabs/wasmer ) |
| Composition | [Aquamarine ](https://github.com/fluencelabs/aquamarine ) | Involved peers | Results and signatures | ⇅, π-calculus |
| Topology | [TrustGraph ](https://github.com/fluencelabs/fluence/tree/master/trust-graph ), [DHT\* ](https://github.com/fluencelabs/rust-libp2p ) | Distributed with Kademlia\* algo | Actual state of the network | [libp2p ](https://github.com/libp2p/rust-libp2p ) |
| Security & Accounting | Blockchain | Whole network | Licenses & payments | substrate? |
< img alt = "aquamarine scheme" align = "center" src = "doc/stack.png" / >
## Installation
With npm
```bash
npm install @fluencelabs/fluence
```
With yarn
2020-05-14 12:20:39 +00:00
```bash
2021-01-29 13:48:27 +00:00
yarn add @fluencelabs/fluence
```
## Getting started
Pick a node to connect to the Fluence network. The easiest way to do so is by using [fluence-network-environment ](https://github.com/fluencelabs/fluence-network-environment ) package
```typescript
import { dev } from '@fluencelabs/fluence-network-environment';
export const relayNode = dev[0];
```
Initialize client
```typescript
import { createClient, FluenceClient } from '@fluencelabs/fluence';
const client = await createClient(relayNode);
2020-05-14 12:20:39 +00:00
```
2021-01-29 13:57:41 +00:00
Respond to service function calls
2020-05-14 12:20:39 +00:00
2021-01-29 13:48:27 +00:00
```typescript
subscribeToEvent(client, 'helloService', 'helloFunction', (args) => {
const [networkInfo] = args;
console.log(networkInfo);
});
```
2020-05-14 12:20:39 +00:00
2021-01-29 13:48:27 +00:00
Make a particle
2020-05-14 12:20:39 +00:00
```typescript
2021-01-29 13:57:41 +00:00
const particle = new Particle(
`
2021-01-29 13:48:27 +00:00
(seq
2021-02-25 12:33:37 +00:00
(call myRelay ("peer" "identify") [] result)
2021-01-29 13:48:27 +00:00
(call %init_peer_id% ("helloService" "helloFunction") [result])
)`,
{
myRelay: client.relayPeerId,
},
);
2020-05-14 12:20:39 +00:00
```
2021-01-29 13:48:27 +00:00
Send it to the network
2020-05-14 12:20:39 +00:00
```typescript
2021-01-29 13:48:27 +00:00
await sendParticle(client, particle);
2020-05-14 12:20:39 +00:00
```
2021-01-29 13:48:27 +00:00
Observe the result in browser console
```json
{
2021-01-29 13:57:41 +00:00
"external_addresses": ["/ip4/1.2.3.4/tcp/7777", "/dns4/dev.fluence.dev/tcp/19002"]
2021-01-29 13:48:27 +00:00
}
```
## Documentation
SDK Reference: [readme.io ](https://fluence-labs.readme.io/docs/js-sdk )
2021-01-29 13:57:41 +00:00
Detailed guide on building applications: [readme.io ](https://fluence-labs.readme.io/docs/build-an-app )
2021-01-29 13:48:27 +00:00
Sample applications:
2021-01-29 13:57:41 +00:00
- [FluentPad ](https://github.com/fluencelabs/fluent-pad ): a collaborative text editor with users online status synchronization
- [Other demos ](https://github.com/fluencelabs/aqua-demo ): (Chat app, Social feed app, Blog platform app)
2021-01-29 13:48:27 +00:00
2021-01-29 13:57:41 +00:00
About [Fluence ](https://fluence.network/ )
2021-01-29 13:48:27 +00:00
## Developing
### Setting up Dev
Install node packages
```bash
npm install
```
### Running tests
2021-02-25 12:33:37 +00:00
Tests are split into unit and integration categories. By default integration tests require a locally running Fluence node with 4310 port open for ws connections. The dependency can be started with docker
2021-01-29 13:48:27 +00:00
```bash
2021-02-25 12:33:37 +00:00
docker run --rm -e RUST_LOG="info" -p 1210:1210 -p 4310:4310 fluencelabs/fluence:freeze -t 1210 -w 4310 -k gKdiCSUr1TFGFEgu2t8Ch1XEUsrN5A2UfBLjSZvfci9SPR3NvZpACfcpPGC3eY4zma1pk7UvYv5zb1VjvPHwCjj
```
To run all tests in interactive mode
```bash
npm run test
```
To run only unit tests
```bash
npm run test:unit
```
To run only integration tests
```bash
npm run test:unit
```
To run all tests
```bash
npm run test:all
2021-01-29 13:48:27 +00:00
```
## Contributing
2021-01-29 13:57:41 +00:00
While the project is still in the early stages of development, you are welcome to track progress and contribute. As the project is undergoing rapid changes, interested contributors should contact the team before embarking on larger pieces of work. All contributors should consult with and agree to our [basic contributing rules ](CONTRIBUTING.md ).
2021-01-29 13:48:27 +00:00
## License
2021-01-29 13:57:41 +00:00
[Apache 2.0 ](LICENSE )