@ethersphere/bee-js

Bee-js

Client library for connecting to Bee decentralised storage

Warning: This project is in beta state. There might (and most probably will) be changes in the future to its API and working. Also, no guarantees can be made about its stability, efficiency, and security at this stage.

Table of Contents

• Install
  • npm
  • Use in Node.js
  • Use in a browser with browserify, webpack or any other bundler
  • Use in a browser Using a script tag
• Usage
• API
• Contribute
  • Setup
  • Test
• License

Install

npm

> npm install @ethersphere/bee-js --save

Use in Node.js

We require Node.js's version of at least 12.x

var BeeJs = require("@ethersphere/bee-js");

Use in a browser with browserify, webpack or any other bundler

var BeeJs = require("@ethersphere/bee-js");

Use in a browser Using a script tag

Loading this module through a script tag will make the BeeJs object available in the global namespace.

<script src="https://unpkg.com/@ethersphere/bee-js/dist/index.browser.min.js"></script>

Usage

import { Bee } from "@ethersphere/bee-js"

bee = new Bee("http://localhost:1633")

const fileHash = await bee.uploadData("Bee is awesome!")
const data = await bee.downloadData(fileHash)

console.log(data.text()) // prints 'Bee is awesome!'

Documentation

You can find the full documentation here. The API reference documentation can be found here.

You can generate API docs locally with:

npm run docs

The generated docs can be viewed in browser by opening ./docs/index.html

Contribute

There are some ways you can make this module better:

• Consult our open issues and take on one of them
• Help our tests reach 100% coverage!
• Join us in our Mattermost chat if you have questions or want to give feedback

Setup

Install project dependencies with

npm i

Test

The tests run in both context: node and dom with Jest.

To run the integration tests, you need to have a Bee cluster running locally. To create a cluster, please consult the readme of @ethersphere/bee-local.

By default, tests are run against local bee node 0 - http://bee-0.localhost. You can change it by setting environment variable BEE_API_URL. In order to run tests which require one more node, you need to define BEE_PEER_API_URL as well. Its default value http://bee-1.localhost

In Visual Studio environment, the tests have been set up to run against your local bee node on http://localhost:1633 To run Jest tests, choose the vscode-jest-tests CI job under the Run tab. You can run your own local Bee client for test purposes with the help of test/bee.sh. If you pass --ephemeral flag, the container automatically will be removed at the end of the run.

There are also browser tests by Puppeteer, which also provide integrity testing.

npm run test:browser

The test HTML file which Puppeteer uses is the test/testpage/testpage.html. To open and manually test BeeJS with developer console, it is necessary to build the library first with npm run compile:browser (running the browser tests npm run test:browser also builds the library).

Compile code

In order to compile NodeJS code run

npm run compile:node

or for Browsers

npm run compile:browser

Maintainers

• nugaon
• agazso

License

BSD-3-Clause

Changelog

0.8.0 (2021-04-19)

☁️ High-level feed's API

We understand that the current Feed's API is rather a low level and to use it for simple tasks might be overwhelming. We designed high-level API, that works for JSON data (arrays, objects, etc.) in a very convenient way. See the example bellow:

await bee.setJsonFeed(
  'some cool arbitraty topic',
  { some: ['cool', { json: 'compatible' }, 'object']},
  { signer: '0x634fb5a872396d9693e5c9f9d7233cfa93f395c093371017ff44aa9ae6564cdd' }
)
const data = await bee.getJsonFeed(
  'some cool arbitraty topic',
  { signer: '0x634fb5a872396d9693e5c9f9d7233cfa93f395c093371017ff44aa9ae6564cdd' }
)
console.log(data)
// Prints: { some: ['cool', { json: 'compatible' }, 'object']}

⚠️ BigInt breaking change

JavaScript has limitations on how it can safely represent big numbers before floating errors come into the picture. Since the BZZ token has 16 decimal places we are able to safely represent only 0.9 BZZ which is not much. Because of this, we had to switch from using number to bigint type on money-related APIs that concerns balances, chequebook, and settlements.

⚙️ Internal refactors

As part of our internal code improvements, we have renamed all verify* functions into assert*. This mainly impacts BeeJS.Utils.Bytes namespace where for example verifyBytes was renamed to assertBytes. As part of this change also the order of parameters was changed and some return types as well. If you use TypeScript the changes should be caught by our typings, if you are using JavaScript please verify you are not using these functions or refactor your code appropriately.

---

⚠ BREAKING CHANGES

• verify to assert (#255) (725292b)
• use bigint for bzz amounts (#259) (9da31c2)

Features

• enable setting default headers (#271) (21d63e3)
• expose pinning functions (#262) (8a4274e)
• high-level json feed api (#246) (4b22563)

Bug Fixes

• check typings for test folder (#264) (b924e89)
• use bigint for bzz amounts (#259) (9da31c2)

Code Refactoring

• verify to assert (#255) (725292b)