BitTree

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

``
npm install @web4/bittree
`

Usage

` js
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 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:
}
`

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:

` js
{
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:

` js
{
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:

` js
{
left: ,
right:
}
`

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:
`js
{
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:
`js
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.