ipfs-log

ipfs-log

An append-only log on IPFS.

ipfs-log is a partially ordered linked list of IPFS hashes where each entry in the log points to all known heads (a head is a node that is not referenced by other nodes in the log).

Use cases

• Track a version of a file
• Create a feed of IPFS hashes
• Messaging
• CRDTs

Originally created for, and currently used in, orbit-db - a KV-store and Event Log on IPFS

Install

npm install ipfs-log

Usage

See ./examples for more.

const Log = require('ipfs-log');

Log.create(ipfs, 'A')
  .then((log) => {
    log.add('one').then((node) => {
      console.log('Node:', node.hash, node.payload);
    });
  })
  .catch((err) => console.error(err));

API

const Log = require('ipfs-log');

Class methods

All class methods take an ipfs-api instance as the first parameter. See https://github.com/ipfs/js-ipfs-api for documentation.

const ipfs = require('ipfs-api')();

create(ipfs, id, [items])

Create a log. Returns a Promise that resolves to a Log instance.

Log.create(ipfs, 'id').then((log) => console.log(log));

See Instance methods on how to use the log instance

getIpfsHash(ipfs, log)

Get the IPFS hash of this log. Returns a Promise that resolves to an IPFS hash.

Log.getIpfsHash(ipfs, log).then((hash) => console.log(hash));

fromIpfsHash(ipfs, hash)

Create a log from an IPFS hash. Returns a Promise that resolves to a Log instance.

Log.fromIpfsHash(ipfs, hash).then((log) => console.log(log));

fromSnapshot(ipfs, snapshot)

Create a log from a log snapshot. Returns a Promise that resolves a Log instance.

Log.create(ipfs, 'id').then((log) => {
  // Add items to the log    
});

const snapshot = log.snapshot;

Log.fromSnapshot(ipfs, snapshot).then((log) => console.log(log));

Instance methods

add(data)

Add a log entry. Returns the added node.

log.add({ some: 'data' });
log.add('text');
// log1.items ==> [{ some: 'data' },  'text']

join(other)

Joins the log with other log. Fetches history up to 256 items, ie. items that are not in this log but referred to in items in other.

// log1.items ==> ['A', 'B']
// log2.items ==> ['C', 'D']

log1.join(log2);
// log1.items ==> ['A', 'B', 'C', 'D']

clear()

Empties the log.

items

Returns all items in the log.

const items = log.items;
// items ==> ['A', 'B', 'C']

snapshot

Returns items in the current batch. Current batch are the items in the log that have been added after the latest sync with another log.

const snapshot = log.snapshot;
// snapshot ==> { id: 'log id', items: ['A', 'B', 'C']}

Tests

npm install
npm test

TODO

• Node.js Stream API
• Support for encrypting the hashes
• Support for payload encryption