Model a tree structure on top off an append-only log.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Model a tree structure on top of an append-only log.

npm install append-tree

Build Status

The data structure stores a small index for every entry in the log, meaning no external indexing is required to model the tree. Also means that you can perform fast lookups on sparsely replicated logs.


var tree = require('append-tree')
var hypercore = require('hypercore')

var feed = hypercore('./my-tree')
var tr = tree(feed, {valueEncoding: 'utf-8'})

tr.put('/hello', 'world', function (err) {
  if (err) throw err

  tr.get('/hello', function (err, val) {
    if (err) throw err
    console.log(val) // <-- 'world'

    tr.list('/', function (err, list) {
      if (err) throw err
      console.log(list) // <-- ['hello']


var tr = tree(feed, [options])

Create a new append tree.

First option should be a hypercore feed (or any append-only log that supports .append() and .length).

Options include:

  valueEncoding: 'binary' | 'utf-8' | 'json' | anyAbstractEncoding
  offset: 0 // optional feed offset where the tree starts
  cache: true // use an LRU cache on tree entries
  cacheSize: 65536 // how many entries to use in the LRU cache

tr.put(name, value, [callback])

Insert a new node in the tree.

tr.del(name, [callback])

Delete a node from the tree.

tr.get(name, [options], callback)

Retrieve a value from the tree. Accepts the same options as hypercore's get method.

tr.list(name, [options], callback)

List all immediate children of a node. Similar to doing a readdir in a file system. Accepts the same options as hypercore's get method.

tr.path(name, [options], callback)

Will call the callback with a list of feed indexes needed to lookup the given name. Useful if you are replicating the tree and want to avoid roundtrips. Accepts the same options as hypercore's get method.

var stream = tr.history([options])

Create a history stream containing all the changes in the tree. Accepts the same options as hypercore's createReadStream method.

Each data event looks like this

  type: 'put' | 'del',
  version: 42, // version of the tree at this point in time
  name: '/foo',
  value: new Buffer('bar') // null if it is a del


Number describing the current version of the tree.

Populated initially after ready event. Will be -1 before.

tr.on('ready', cb)

Fired when the tree is ready and all properties have been populated.

var oldTree = tr.checkout(version, [options])

Checkout an old readonly version of the tree. .get, .list will return the same values as the tree did at the old version. Accepts the same options as the tree constructor.

var stream = tr.diff(checkout, [options])

Diff a tree against another checkout of the tree. Will emit the same data as the history stream but representing the diff from tr to checkout.

Accepts the same options as hypercore's createReadStream method.