IPFS Observed Remove Map

Eventually-consistent, conflict-free replicated data type (CRDT) implemented using IPFS PubSub and extending the observed remove map module.

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-api');
const { IpfsOrMap } = require('ipfs-observed-remove-map');

// 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";

const map1 = new IpfsOrMap(ipfs1, topic);
const map2 = new IpfsOrMap(ipfs2, topic);

// Callback when values change
map1.on('set', (key, value) => {
  map1.get('A'); // Returns 1
});

map2.set('A', 1);

Install

yarn add ipfs-observed-remove-map

IPFS-based API

new IpfsOrMap(ipfs, ipfsTopic, uuid)

Create a new IPFS-based observed remove map.

Required ipfs is any Javascript object implementing the core IPFS API , most likely a js-ipfs or js-ipfs-api object.

Required ipfsTopic is a string representing the IPFS pubsub topic the client should subscribe to.

Optional uuid is some universally unique identifer string for this instance.

ipfsOrMap.setIpfsSyncTimeout()

Broadcasts the IPFS hash of the key-value pairs, triggering a 'hard' sync of all nodes.

ipfsOrMap.getIpfsHash()

Returns a promise which resolves to the IPFS hash string of the key-value pairs.

ipfsOrMap.waitForIpfsPeers()

Returns a promise which resolves when the ipfsTopic topic has peers. Useful for testing.

ipfsOrMap.ipfsPeerCount()

Returns a promise which resolves with the number of ipfsTopic topic peers.

Core observed-remove-map API

ipfsOrMap.add(key)

Add a key to the map with a value of null.

element is any serializable Javascript object. Changes to within this object will NOT be replicated.

ipfsOrMap.delete(key)

Remove a key and it's value from the map.

ipfsOrMap.set(key, value)

Sets the value at key. If key does not exist, it will be added first.

ipfsOrMap.get(key)

Returns the value associated with the given key.

ipfsOrMap.keys()

Returns an array with all keys.

ipfsOrMap.values()

Returns an array with all values.

ipfsOrMap.receive(op)

Receive an operation from a remote map. Must be called exactly once per remote operation.

ipfsOrMap.on('op', function (op) {})

Fires when an operation needs to be sent to connected Maps. Operations should be delivered in the order they are emitted and must be delivered exactly once. There may be multiple operation events for each call to a method.

op is the operation object that needs to be passed into otherOrMap.receive(op) for all other replicas.

ipfsOrMap.on('add', function (key) {})

Fires when a new key is added to the map by a remote operation. (will not fire when ipfsOrMap.add() is called locally.)

ipfsOrMap.on('delete', function (key, value) {})

Fires when a key is removed from the map by a remote operation. (will not fire when ipfsOrMap.delete() is called locally.)

ipfsOrMap.on('set', function (key, value) {})

Fires when the value associated with a key is changed by a remote operation. (will not fire when ipfsOrMap.set() is called locally.)