@elastosfoundation/hive-js-sdk

Elastos Hive JS SDK

Elastos Hive is an essential service infrastructure as a decentralized network of Hive nodes presenting data storage capabilities to dApps. And the JS SDK provides a group of APIs for Elastos dApps to easily access and store application data to remote Vault services on Hive nodes with the following features:

• Subscribe/unsubscribe to vault or backup vault
• Scripting execution
• Upload/Download files
• Structured data object access and store onto MongoDB (Not supported yet)
• Key/Values (Not supported yet);

Elastos Hive will keep the promise that users remain in full control of their own data and committing the practice on it.

SDK integration with NodeJS

To add the Hive JS SDK dependency to your project, run the following command from your source folder:

npm i --save @elastosfoundation/hive-js-sdk

Build from source

Preparing with the developer tool git, and then run the following commands to clone the source:

git clone https://github.com/elastos/Elastos.NET.Hive.JS.SDK
cd Elastos.NET.Hive.JS.SDK
npm install
npm run types
npm run build

Test configuration

Before running tests, the local user directory must be defined with the following command:

export HIVE_USER_DIR=/path/to/user/dir

Then, modify the "provider" field tests/src/res/custom.json to point to your own local hive node.

Run NodeJS tests

From the source folder, build the project, then run the following commands:

cd tests
npm run clean
npm install
npm run test:node

Run Browser tests

From the source folder, build the project, then run the following commands:

cd tests
npm run clean
npm install
npm run test:browser

Writing tests

The test context is based on the TestData class located in /tests/src/config/testdata.ts. The creation of this class will create the test context and set the user directory. The class should be created before each test using the following code:

testData = await TestData.getInstance("TEST SUITE NAME", CONFIGURATION, "OPTIONAL USER DIRECTORY");

Example:

testData = await TestData.getInstance("My service tests", ClientConfig.LOCAL);

Note: The optional third parameter of the TestData.getInstance method is the user directory which defaults to the path defined by the HIVE_USER_DIR environment variable (See Test configuration. You may also specify a custom folder, but it's recommended to only use this parameter on a local workstation for validation.

Test example

import {
  VaultSubscriptionService,
  PricingPlan,
} from "@elastosfoundation/hive-js-sdk";
import { ClientConfig } from "../config/clientconfig";
import { TestData } from "../config/testdata";

describe("pricing plans", () => {
  let testData: TestData;
  let vaultSubscriptionService: VaultSubscriptionService;

  beforeEach(async () => {
    testData = await TestData.getInstance(
      "pricingplans.test",
      ClientConfig.TESTNET
    );
    vaultsubscriptionService = new VaultSubscriptionService(
      testData.getAppContext(),
      testData.getProviderAddress()
    );
  });

  test("get vault pricing plans", async () => {
    let plans: PricingPlan[] =
      await vaultsubscriptionService.getPricingPlanList();
    expect(plans).not.toBeNull();
    expect(plans.length).toBeGreaterThan(0);
  });
});

Usage

In order to subscribe to a vault (create) a user needs to implement AppContextProvider

export class ApiServiceContextProvider implements AppContextProvider {
    getLocalDataDir = () : string => {
        ...
    };

    getAppInstanceDocument = async () : Promise<DIDDocument> => {
       ...
    };

    getAuthorization = async (authenticationChallengeJWtCode: string): Promise<string> => {
      ...
    }
}

let vaultSubscriptionService : VaultSubscription = new VaultSubscription(appContext, "[hiveNode address]");
let vaultInfo = await vaultSubscriptionService.subscribe();

The same mechanics is used by VaultService, which provides all services to interact with hive vault

let vaultServices = new Vault(appContext, "[hiveNode address]");
let scriptingService = vaultServices.getScriptingService();
let filesService = vaultServices.getFilesService();
let databaseService = vaultServices.getDatabaseService();
...