@p2pcommons/sdk-js

v0.9.2

Published

3 years ago

The SDK for the p2p commons

Downloads

0High
0Medium
0Low

chartgerink

the-real-dk

p2p dat communication

@p2pcommons/sdk-js

npm version license downloads total downloads yearly downloads monthly downloads weekly

NodeJS development kit (sdk-js) for the peer-to-peer commons (p2pcommons). 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.

:warning: 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 () => {
  // create a content module
  await p2p.init({ type: 'content' }) // ~/.p2pcommons/hash/index.json --> type: content
  // create a profile module
  await p2p.init({ type: 'profile' }) // ~/.p2pcommons/hash/index.json --> type: profile
})()

@p2pcommons/sdk-js

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
}

init

async init(data: object)

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

data object following the p2pcommons module spec. The only required field is type.

Returns an object with:

rawJSON: flattened indexJSON data
metadata: (version, lastModified, isWritable)

get

async get(key: string)

Retrieves raw indexJSON item and metadata from the local db.

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

Returns an object with:

rawJSON: flattened indexJSON data
metadata: (version, lastModified, isWritable)

set

async set(metadata: object)

Used to update an existing module.

metadata: object with updated or added values. The only required field is the url property, which is used to identify the module to update.

refreshDrive

async refreshDrive(key: string|buffer, opts: object)

Synchronize a hyperdrive with a module directory to ensure that the sdk is aware of the latest changes to files. Optionally accepts an opts object. These are passed to dft.

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 (flattened rawJSON data) together with their metadata.

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 (flattened rawJSON data) together with metadata saved in the local db.

listProfiles

async listProfiles()

Returns an array containing all the profile modules (flattened rawJSON data) together with metadata saved in the local db.

list

async list()

Returns an array containing all the modules (flattened rawJSON data) and metadata saved in the local db.

openFile

async openFile(key: string)

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

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

register

async register(contentKey: string or buffer, profileKey: string or buffer)

Register (add) new content into a profile. The new content is added to the profile's p2pcommons.contents. See p2pcommons specs on registration

contentKey: versioned or unversioned key to be registered (origin module)
profileKey: unversioned profile key (destination module)

deregister

async deregister(contentKey: string or buffer, profileKey: string or buffer)

Deregister (remove) content from a profile.

contentKey: versioned or unversioned key of content at the version that is registered
profileKey: unversioned profile key (destination module)

follow

async follow(localProfileKey: string, targetProfileKey: string)

Get a local profile and update its follows property adding a new profile (targetProfile)

localProfileKey: unversioned key of local profile
targetProfileKey: versioned or unversioned key of profile to follow

unfollow

async unfollow(localProfileKey: string, targetProfileKey: string)

Undo the follow operation.

localProfileKey: unversioned key of local profile
targetProfileKey: versioned or unversioned key of profile at the version that is followed

verify

async verify(versionedKey: string)

Verifies a module. See p2pcommons specs on verification

Returns a boolean indicating whether the module is verified.

clone

async clone(mKey: string or buffer, mVersion: number, opts: object)

Get a module from the local db or the swarm. If the module is not present on the local db and the swarm is enabled (disableSwarm === false) then it will query the swarm.

:warning: NOTE: versioned module directories are read-only.

mKey: module url
mVersion: module version. [OPTIONAL]
opts: options modifiers passed to getFromSwarm [OPTIONAL]
- download: a boolean indicating if module directory needs to be saved on disk. [DEFAULT=TRUE]
- latestFallback: a boolean indicating if the sdk should try fetching latest version from swarm if passed version is unavailable. [DEFAULT=TRUE]

Returns a cancelable promise. When fullfiled returns an object with multiple values:

rawJSON: the module index.json content (flattened)
metadata: an object with module's metadata
versionedKey: an string indicating the full module url obtained. E.g: hyper://${mKey}+${version}
dlInfo: an object containin download info and a function resume that can be used to force resuming a download.
dlHandle: it contains a download event emitter, you can listen to end event to know when the download has been completed. It's defined only if download === true. [DEPRECATED]

delete

async delete(key: string or buffer, deleteFiles: boolean)

Removes a module and all its versions from the local db and seed db. If it was open in memory, its closed. Only removes unversioned keys, it will throw an error (code: only_unversioned) if it receives a version with the key. This method would also call deregister if passed key belongs to a content module. It will deregister the content module only from writable (local) profiles.

Note: While this will stop the file from being seeded, that does not means that the content won't still be available on the network. This is due to the P2P file sharing dynamics.

If deleteFiles option is true, then the target folder and all its versions will be moved to the trash bin.

destroy

async destroy()

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

Validations

The SDK exports many validation methods as SDK.validations that throw ValidationErrors when validation fails

Full validations

async validate({ indexMetadata: object, dbMetadata: object, key: string, p2pcommonsDir: string })

Fully validates a module against the p2pcommons module specs

indexMetadata: metadata from index.json (=rawJSON)
dbMetadata: metadata from the database (=metadata)
key: versioned or unversioned Hyperdrive key
p2pcommonsDir: path to p2pcommons directory [OPTIONAL]

Partial validations

async validatePartial({ indexMetadata: object, dbMetadata: object, key: string, p2pcommonsDir: string} )

Validates all present data (not undefined or null) against the p2pcommons specs. Can be used for validating unfinished modules. If p2pcommons.main is present, but empty, it will not be validated.

The following only validate a specific part of the supplied metadata:

async validateTitle({ indexMetadata: object })

async validateDescription({ indexMetadata: object })

async validateUrl({ indexMetadata: object, key: string })

async validateLinks({ indexMetadata: object })

async validateP2Pcommons({ indexMetadata: object })

Validates the p2pcommons object structure (not its contents)

async validateType({ indexMetadata: object })

async validateSubtype({ indexMetadata: object })

async validateMain({ indexMetadata: object, key: string, p2pcommonsDir: string })

Also checks the existence of the specified main file

async validateAvatar({ indexMetadata: object })

async validateAuthors({ indexMetadata: object })

async validateParents({ indexMetadata: object, dbMetadata: object, key: string })

async validateFollows({ indexMetadata: object, key: string })

async validateContents({ indexMetadata: object })

Special validations

async validateOnRegister({ contentIndexMetadata: object, contentDbMetadata: object, contentKey: string, profileIndexMetadata: object, profileDbMetadata: object, profileKey: string, p2pcommonsDir: string })

Fully validates a content module and a profile module upon registration. Includes cross-validation of module types and presence of the author in the content's metadata.

async validateOnFollow({ followedIndexMetadata: object })

Validates whether the followed module is a profile. This validation is only relevant at time of updating follows and is not included in any of the other validations.

async validateParentsOnUpdate({ indexMetadata: object, p2pcommons: SDK })

Validates whether parents are registered. This validation is only relevant at time of updating parents and is not included in any of the other validations.

p2pcommons: active instance of the p2pcommons SDK

Events

The following events are emitted by the SDK:

download-started

download-started ({key})

Emitted usually after cloning a new module. It passes the key of the drive.

download-progress

download-progress ({key})

Event used to track download progress of a new module.

download-drive-completed

download-drive-completed ({key})

Emitted when a drive has finished downloading. Drive has not been synced yet.

download-resume

download-resume ({key})

Emitted at SDK restart if some module has not finished its download. This means that the download is resuming.

download-resume-completed

download-resume-completed ({key})

Emitted when a resume download has been completed and the drive is synced to the disk.

update-profile

update-profile (rawJSON)

Emitted when an external profile has been updated. This will automatically update the local db. You don't need to do anything special. The event also emits the updated profile with the same rawJSON format.

update-content

update-content (rawJSON)

Emitted when an external content module has been updated. This will automatically update the local db. You don't need to do anything special. The event also emits the updated content with the same rawJSON format.

warn

warn (msg)

Emitted on unusual ocassions when a soft error happens. Used for logging purposes mostly.

error

error (err)

Emitted on unexpected circumstances, this can be emitted by our local db if something goes wrong.