IPFS Observed-Remove Set and Map

Eventually-consistent, conflict-free replicated data types (CRDT) implemented using IPFS and native Map and Set objects.

This module and the IPFS PubSub system are experimental. If you encounter an issue, fork the repository, write tests demonstrating the issue, and create a pull request.

const ipfsAPI = require('ipfs-http-client');
const { IpfsObservedRemoveSet } = require('ipfs-observed-remove');

// IPFS nodes with PubSub enabled
const ipfs1 = ipfsAPI('/ip4/127.0.0.1/tcp/5001'); 
const ipfs2 = ipfsAPI('/ip4/127.0.0.1/tcp/5002');

const topic = "CRDT_SET";

const alice = new IpfsObservedRemoveSet(ipfs1, topic);
const bob = new IpfsObservedRemoveSet(ipfs2, topic);

alice.on('add', (value) => {
  console.log(value); // logs foo, bar
});

alice.add('foo');
bob.add('bar');

// Later

alice.has('bar'); // true
bob.has('foo'); // true

const ipfsAPI = require('ipfs-http-client');
const { IpfsObservedRemoveMap } = require('ipfs-observed-remove');

// IPFS nodes with PubSub enabled
const ipfs1 = ipfsAPI('/ip4/127.0.0.1/tcp/5001'); 
const ipfs2 = ipfsAPI('/ip4/127.0.0.1/tcp/5002');

const topic = "CRDT_MAP";

const alice = new IpfsObservedRemoveMap(ipfs1, topic);
const bob = new IpfsObservedRemoveMap(ipfs2, topic);

alice.on('set', (key, value) => {
  console.log(key, value); // logs [a, 1], [b, 2]
});

alice.set('a', 1);
bob.add('b', 2);

// Later

alice.get('b'); // 2
bob.get('a'); // 1

Install

yarn add ipfs-observed-remove

Set API

Table of Contents

• constructor
  • Parameters
• ipfsSync
• dump
• getIpfsHash
• ipfsPeerCount
• shutdown
• IpfsObservedRemoveSet#readyPromise

constructor

Create an observed-remove CRDT.

Parameters

• ipfs Object? Object implementing the core IPFS API, most likely a js-ipfs or ipfs-http-client object.

• topic String? IPFS pubub topic to use in synchronizing the CRDT.

• entries Iterable<V> Iterable of initial values (optional, default [])

• options Object (optional, default {})

  • options.maxAge String Max age of insertion/deletion identifiers (optional, default 5000)
  • options.bufferPublishing String Interval by which to buffer 'publish' events (optional, default 20)

ipfsSync

Publish an IPFS hash of an array containing all of the object's insertions and deletions.

Returns Array<Array<any>>

dump

Return a sorted array containing all of the set's insertions and deletions.

getIpfsHash

Stores and returns an IPFS hash of the current insertions and deletions

Returns Promise<string>

ipfsPeerCount

Current number of IPFS pubsub peers.

Returns number

shutdown

Gracefully shutdown

Returns void

IpfsObservedRemoveSet#readyPromise

Resolves when IPFS topic subscriptions are confirmed.

Type: Promise<void>

Map API

Table of Contents

• constructor
  • Parameters
• ipfsSync
• dump
• getIpfsHash
• ipfsPeerCount
• shutdown
• IpfsObservedRemoveSet#readyPromise

constructor

Create an observed-remove CRDT.

Parameters

• ipfs Object? Object implementing the core IPFS API, most likely a js-ipfs or ipfs-http-client object.

• topic String? IPFS pubub topic to use in synchronizing the CRDT.

• entries Iterable<V> Iterable of initial values (optional, default [])

• options Object (optional, default {})

  • options.maxAge String Max age of insertion/deletion identifiers (optional, default 5000)
  • options.bufferPublishing String Interval by which to buffer 'publish' events (optional, default 20)
  • options.chunkPubSub boolean Chunk pubsub messages for values greater than 1 MB (optional, default false)

ipfsSync

Publish an IPFS hash of an array containing all of the object's insertions and deletions.

Returns Array<Array<any>>

dump

Return a sorted array containing all of the set's insertions and deletions.

getIpfsHash

Stores and returns an IPFS hash of the current insertions and deletions

Returns Promise<string>

ipfsPeerCount

Current number of IPFS pubsub peers.

Returns number

shutdown

Gracefully shutdown

Returns void

IpfsObservedRemoveSet#readyPromise

Resolves when IPFS topic subscriptions are confirmed.

Type: Promise<void>