@web4/bittree v1.0.0

BitTree

An append-only Btree running on a Unichain. Allows sorted iteration and more.

npm install @web4/bittree

Usage

const Bittree = require('@web4/bittree')
const db = new Bittree(feed, {
  keyEncoding: 'utf-8', // can be set to undefined (binary), utf-8, ascii or and abstract-encoding
  valueEncoding: 'binary' // same options as above
})

// if you own the feed
await db.put('key', 'value')
await db.del('some-key')

// if you want to insert/delete batched values
const batch = db.batch()

await batch.put('key', 'value')
await batch.del('some-key')
await batch.flush() // execute the batch

// if you want to query the feed
const node = await db.get('key') // null or { key, value }

// if you want to read a range
const rs = db.createReadStream({ gt: 'a', lt: 'd' }) // anything >a and <d
const rs = db.createReadStream({ gte: 'a', lte: 'd' }) // anything >=a and <=d

// get the last written entry
const rs = db.createHistoryStream({ reverse: true, limit: 1 })

Some of the internals are still being tweaked, but overall the API and feature set is pretty stable, if you want to try it out.

All of the above methods work with sparse feeds, meaning only a small subset of the full feed is downloaded to satisfy your queries.

API

const db = new Bittree(feed, [options])

Make a new Bittree instance. feed should be a Unichain.

Options include:

{
  keyEncoding: 'utf-8' | 'binary' | 'ascii', // or some abstract encoding
  valueEncoding: <same as above>
}

Note that currently read/diff streams sort based on the encoded value of the keys.

await db.put(key, [value])

Insert a new key. Value can be optional. If you are inserting a series of data atomically, or you just have a batch of inserts/deletions available using a batch can be much faster than simply using a series of puts/dels on the db.

{ seq, key, value } = await db.get(key)

Get a key, value. If the key does not exist, null is returned. seq is the unichain version at which this key was inserted.

await db.del(key)

Delete a key

batch = db.batch()

Make a new batch.

await batch.put(key, [value])

Insert a key into a batch.

{ seq, key, value } = await batch.get(key)

Get a key, value out of a batch.

await batch.del(key)

Delete a key into the batch.

await batch.flush()

Commit the batch to the database.

batch.destroy()

Destroy a batch and releases any locks it has aquired on the db. Call this if you want to abort a batch without flushing it.

stream = db.createReadStream([options])

Make a read stream. All entries in the stream are similar to the ones returned from .get and the sort order is based on the binary value of the keys.

Options include:

{
  gt: 'only return keys > than this',
  gte: 'only return keys >= than this',
  lt: 'only return keys < than this',
  lte: 'only return keys <= than this',
  reverse: false // set to true to get them in reverse order,
  limit: -1 // set to the max number of entries you want
}

const { seq, key, value } = await db.peek([options])

Similar to doing a read stream and returning the first value, but a bit faster than that.

stream = db.createHistoryStream([options])

Create a stream of all entries ever inserted or deleted from the db. Each entry has an additional type property indicating if it was a put or del operation.

Options include:

{
  live: false, // if true the stream will wait for new data and never end
  reverse: false, // if true get from the newest to the oldest
  gte: seq, // start with this seq (inclusive)
  gt: seq, // start after this index
  lte: seq, // stop after this index
  lt: seq, // stop before this index
  limit: -1 // set to the max number of entries you want
}

If any of the gte, gt, lte, lt arguments are < 0 then they'll implicitly be added with the version before starting so doing { gte: -1 } makes a stream starting at the last index.

stream = db.createDiffStream(otherVersion, [options])

Efficiently create a stream of the shallow changes between two versions of the db. Each entry is sorted by key and looks like this:

{
  left: <the entry in the db>,
  right: <the entry in the other version>
}

If an entry exists in db but not in the other version, then left is set and right will be null, and vice versa.

If the entries are causally equal (i.e. the have the same seq), they are not returned, only the diff.

Currently accepts the same options as the read stream except for reverse.

dbCheckout = db.checkout(version)

Get a readonly db checkout of a previous version.

dbCheckout = db.snapshot()

Shorthand for getting a checkout for the current version.

const sub = db.sub('sub-prefix', opts = {})

Create a sub-database where all entries will be prefixed by a given value.

This makes it easy to create namespaces within a single Bittree.

Options include:

{
  sep: Buffer.alloc(1), // A namespace separator
  valueEncoding, // optional sub valueEncoding (defaults to the parents)
  keyEncoding // optional sub keyEncoding (defaults to the parents)
}

For example:

const rootDb = new Bittree(chain)
const subDb = rootDb.sub('a')

// In rootDb, this will have the key ('a' + separator + 'b')
await subDb.put('b', 'hello')

// Returns { key: 'b', value: 'hello')
await subDb.get('b')

db.version

Current version.

await db.ready()

Makes sure internal state is loaded. Call this once before checking the version if you haven't called any of the other APIs.