See API docs at docs.pears.com

An append-only B-tree running on a Hypercore. Allows sorted iteration and more.

npm install hyperbee 

constHyperbee=require('hyperbee')constHypercore=require('hypercore')constcore=newHypercore('./storage')constdb=newHyperbee(core,{keyEncoding: 'utf-8',valueEncoding: 'binary'})// If you own the coreawaitdb.put('key1','value1')awaitdb.put('key2','value2')awaitdb.del('some-key')// If you want to insert/delete batched valuesconstbatch=db.batch()awaitbatch.put('key','value')awaitbatch.del('some-key')awaitbatch.flush()// Execute the batch// Query the coreconstentry=awaitdb.get('key')// => null or{key, value }// Read all entriesforawait(constentryofdb.createReadStream()){// ..}// Read a rangeforawait(constentryofdb.createReadStream({gte: 'a',lt: 'd'})){// Anything >=a and <d}// Get the last written entryforawait(constentryofdb.createHistoryStream({reverse: true,limit: 1})){// ..}

It works with sparse cores, only a small subset of the full core is downloaded to satisfy your queries.

Make a new Hyperbee instance. core should be a Hypercore.

options include:

{keyEncoding: 'binary',// "binary" (default), "utf-8", "ascii", "json", or an abstract-encodingvalueEncoding: 'binary'// Same options as keyEncoding like "json", etc}

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

Waits until internal state is loaded.

Use it once before reading synchronous properties like db.version, unless you called any of the other APIs.

Fully close this bee, including its core.

The underlying Hypercore backing this bee.

Number that indicates how many modifications were made, useful as a version identifier.

String containing the id (z-base-32 of the public key) identifying this bee.

Buffer containing the public key identifying this bee.

Buffer containing a key derived from db.key.

This discovery key does not allow you to verify the data, it's only to announce or look for peers that are sharing the same bee, without leaking the bee key.

Boolean indicating if we can put or delete data in this bee.

Boolean indicating if we can read from this bee. After closing the bee this will be false.

Insert a new key. Value can be optional.

If you're inserting a series of data atomically or want more performance then check the db.batch API.

options includes:

{cas(prev,next){returntrue}}

cas option is a function comparator to control whether the put succeeds.

By returning true it will insert the value, otherwise it won't.

It receives two args: prev is the current node entry, and next is the potential new node.

awaitdb.put('number','123',{ cas })console.log(awaitdb.get('number'))// =>{seq: 1, key: 'number', value: '123' }awaitdb.put('number','123',{ cas })console.log(awaitdb.get('number'))// =>{seq: 1, key: 'number', value: '123' }// Without cas this would have been{seq: 2, ... }, and the next{seq: 3 }awaitdb.put('number','456',{ cas })console.log(awaitdb.get('number'))// =>{seq: 2, key: 'number', value: '456' }functioncas(prev,next){// You can use same-data or same-object lib, depending on the value complexityreturnprev.value!==next.value}

Get a key's value. Returns null if key doesn't exists.

seq is the Hypercore index at which this key was inserted.

Delete a key.

options include:

{cas(prev,next){returntrue}}

cas option is a function comparator to control whether the del succeeds.

By returning true it will delete the value, otherwise it won't.

It only receives one arg: prev which is the current node entry.

// This won't get deletedawaitdb.del('number',{ cas })console.log(awaitdb.get('number'))// =>{seq: 1, key: 'number', value: 'value' }// Change the value so the next time we try to delete it then "cas" will return trueawaitdb.put('number','can-be-deleted')awaitdb.del('number',{ cas })console.log(awaitdb.get('number'))// => nullfunctioncas(prev){returnprev.value==='can-be-deleted'}

Get the key and value from a block number.

seq is the Hypercore index. Returns null if block doesn't exists.

See more about how replicate works at core.replicate.

Make a new atomic batch that is either fully processed or not processed at all.

If you have several inserts and deletions then a batch can be much faster.

Insert a key into a batch.

options are the same as db.put method.

Get a key, value out of a batch.

Delete a key into the batch.

options are the same as db.del method.

Commit the batch to the database, and releases any locks it has acquired.

Destroy a batch, and releases any locks it has acquired on the db.

Call this if you want to abort a batch without flushing it.

Make a read stream. Sort order is based on the binary value of the keys.

All entries in the stream are similar to the ones returned from db.get.

range should specify the range you want to read and looks like this:

{gt: 'only return keys > than this',gte: 'only return keys >= than this',lt: 'only return keys < than this',lte: 'only return keys <= than this'}

options include:

{ reverse: false// Set to true to get them in reverse order, limit: -1// Set to the max number of entries you want}

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

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 endreverse: false,// If true get from the newest to the oldestgte: seq,// Start with this seq (inclusive)gt: seq,// Start after this indexlte: seq,// Stop after this indexlt: seq,// Stop before this indexlimit: -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.

Efficiently create a stream of the shallow changes between two versions of the db.

options are the same as db.createReadStream, except for reverse.

Each entry is sorted by key and looks like this:

{left: Object,// The entry in the `db`right: Object// The entry in `otherVersion`}

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.

Returns a watcher which listens to changes on the given key.

entryWatcher.node contains the current entry in the same format as the result of bee.get(key), and will be updated as it changes.

By default, the node will have the bee's key- and value encoding, but you can overwrite it by setting the keyEncoding and valueEncoding options.

You can listen to entryWatcher.on('update') to be notified when the value of node has changed.

Call await watcher.close() to stop the watcher.

Listens to changes that are on the optional range.

range options are the same as db.createReadStream except for reverse.

By default, the yielded snapshots will have the bee's key- and value encoding, but you can overwrite them by setting the keyEncoding and valueEncoding options.

Usage example:

forawait(const[current,previous]ofwatcher){console.log(current.version)console.log(previous.version)}

Returns a new value after a change, current and previous are snapshots that are auto-closed before next value.

Don't close those snapshots yourself because they're used internally, let them be auto-closed.

Watchers on subs and checkouts are not supported. Instead, use the range option to limit scope.

await watcher.ready()

Waits until the watcher is loaded and detecting changes.

await watcher.close()

Stops the watcher. You could also stop it by using break in the loop.

Get a read-only snapshot of a previous version.

Shorthand for getting a checkout for the current version.

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

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

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:

constroot=newHyperbee(core)constsub=root.sub('a')// In root, this will have the key ('a' + separator + 'b')awaitsub.put('b','hello')// Returns =>{key: 'b', value: 'hello')awaitsub.get('b')

Returns the header contained in the first block. Throws if undecodable.

options are the same as the core.get method.

Returns true if the core contains a Hyperbee, false otherwise.

This requests the first block on the core, so it can throw depending on the options.

options are the same as the core.get method.