Skip to content
Software Development Kit (SDK) for JavaScript environments.
JavaScript
Branch: master
Clone or download
Latest commit 66d2ec9 Nov 11, 2019

README.md

@p2pcommons/sdk-js

npm version Build Status

The base Software Development Kit in JavaScript (sdk-js) for a p2p communication infrastructure. More information on this infrastructure is available in this conceptual publication and this technical publication (note these might have been extended by now).

The specifications for sdk-js are available from @p2pcommons/specs.

⚠️ Work In Progress

Install

npm install @p2pcommons/sdk-js

Usage

This is an npm module that does not export any processes to your global environment. In other words, it is a module that you can use in your NodeJS packages, but does not provide any direct functionality outside of it.

Example

const P2PCommons = require('@p2pcommons/sdk-js')

const p2p = new P2PCommons()

;(async () => {
  // call this method first
  await p2p.ready()

  // create a content module
  await p2p.init({ type: 'content' }) // ~/.p2pcommons/hash/dat.json --> type: content
  // create a profile module
  await p2p.init({ type: 'profile' }) // ~/.p2pcommons/hash/dat.json --> type: profile
})()

API

const P2PCommons = require('@p2pcommons/sdk-js')

constructor

P2PCommons(opts)

Returns a new instance of the sdk.

  • opts can include the following:
{
  baseDir: // defaults to '~/.p2pcommons'
  persist: // Indicates if the drives should be persisted - defaults to true
  storage: // Accepts a storage function - defaults to undefined
  disableSwarm: // defaults to undefined
  swarm: // swarm options - defaults to undefined
}

ready

async ready()

After creating a new instance the next required step is call the ready method. This method will create (if needed) the db and open it.

Returns a promise. Call this method before any other for expected behavior.

init

async init(data: object)

Creates a new folder for 'content' or 'profile' according to the received data.type value.

Returns an object containing the metadata for the newly created module.

get

async get(hash: string)

Retrieves metadata item from the local db.

  • hash: represents the key (url) to be looked for. It is the buffer archive key .toString('hex')

set

async set(metadata: object)

Used to update a previously retrieved value.

  • metadata: it is an object with the updated values. The only required field is the url property, which is used as the object key.

filter

async filter(feature: string, criteria: string)

Handy method for querying content values from the local db.

Returns a promise which can resolve to an array of 0 or more values.

  • feature: indicates the filter property, e.g.: filter by title or description (currently supported filter types)
  • criteria: it is the filter value.

listContent

async listContent()

Returns an array containing all the content modules saved in the local db.

listProfiles

async listProfiles()

Returns an array containing all the profile modules saved in the local db.

list

async list()

Returns an array containing all the modules saved in the local db.

openFile

async openFile(key: string)

Used to obtain a file descriptor from the main file of a module.

  • type: indicates the module type to retrieve. Allowed values: profile, content.
  • key: represents the module key (url) to be looked for. It is the buffer archive key .toString('hex')

destroy

async destroy()

Closes the swarm instance (if created) and the local db.

Errors

The SDK exports some custom errors: SDK.errors

ValidationError

Indicates there is a difference between what is expected and what was received

InvalidKeyError

Some keys are read only. This error indicates the user is trying to modificate a read only property.

MissingParam

A more general error, used to indicate if something is missing.

You can’t perform that action at this time.