Distributed single writer key/value store
npm install dwebtrie
Uses a rolling hash array mapped trie to index key/value data on top of a ddatabase.
Useful if you just want a straight forward single writer kv store or if you are looking for a building block for building more complex multiwriter databases on top.
const dwebtrie = require('dwebtrie')
const db = dwebtrie('./trie.db', {valueEncoding: 'json'})
db.put('hello', 'world', function () {
db.get('hello', console.log)
})
Create a new database. Options include:
{
feed: aDDatabase, // use this feed instead of loading storage
valueEncoding: 'json', // set value encoding
subtype: undefined, // set subtype in the header message at feed.get(0)
alwaysUpdate: true // perform an ifAvailable update prior to every head operation
}
If you set options.feed
then you can set storage
to null.
Lookup a key. Returns a result node if found or null
otherwise.
Options are passed through to ddatabase's get method.
Insert a value.
Options can include:
{
condition: function (oldNode, newNode, cb(err, bool)) { ... }
}
The optional condition
function provides atomic compare-and-swap semantics, allowing you to optionally abort a put based on the current and intended node values.
The condition callback should be used as follows:
cb(new Error(...))
: Abort with an error that will be forwarded through theput
.cb(null, false)
: Abort the put, but do not produce an error.cb(null, true)
: Proceed with the put.
Delete a key from the database.
Options can include:
{
condition: function (oldNode, cb(err, bool)) { ... }
}
The optional condition
function behaves the same as the one in put
, minus the newNode
parameter.
Insert/delete multiple values atomically. The batch objects should look like this:
{
type: 'put' | 'del',
key: 'key/we/are/updating',
value: optionalValue
}
Watch a prefix of the db and get notified when it changes.
When there is a change watcher.on('change')
is emitted.
Use watcher.destroy()
to stop watching.
Emitted when the db has loaded it's internal state.
You do not need to wait for this unless noted in the docs.
Returns the current version of the db (an incrementing integer).
Only available after ready
has been emitted.
Returns the db public key. You need to pass this to other instances you want to replicate with.
Only available after ready
has been emitted.
Returns the db discovery key. Can be used to find other db peers.
Only available after ready
has been emitted.
Returns a new db instance checked out at the version specified.
Same as checkout but just returns the latest version as a checkout.
Returns a ddatabase replication stream for the db. Pipe this together with another dwebtrie instance.
Replicate takes an isInitiator
boolean which is used to indicate if this replication stream is the passive/active replicator.
All options are forwarded to hypercores replicate method.
Returns a nanoiterator that iterates the latest values in the prefix specified.
Options include:
{
recursive: true,
random: false // does a random order iteration
}
If you set recursive: false
it will only iterate the immediate children (similar to readdir)
Additional options are passed through to ddatabase's get method.
Same as above but as a stream
Creates an iterator for the prefix with the specified options and buffers it into an array that is passed to the callback.
A writable stream you can write batch objects to, to update the db.
Returns a nanoiterator that iterates over the feed in causal order.
Options include:
{
gt: seq,
lt: seq,
gte: seq,
lte: seq,
reverse: false,
live: false // set to true to keep iterating forever
}
Same as above but as a stream
Returns a nanoiterator that iterates the diff between the current db and the version you specifiy. The objects returned look like this
{
key: 'node-key-that-is-updated',
left: <node>,
right: <node>
}
If a node is in the current db but not in the version you are diffing against
left
will be set to the current node and right
will be null and vice versa.
Options include:
{
skipLeftNull: false,
skipRightNull: false,
hidden: false, // set to true to diff the hidden keyspace
checkpoint: <checkpoint>
}
The order of messages emitted for a specific diff is predictable (ordered by key hash). It is possible to resume a diff at any position. To do so, call the .checkpoint
method on the diff iterator. It returns a serialized buffer of the current position within the diff. To resume, create a new diff between the same versions and pass the checkpoint buffer as an option.
Same as above but as a stream
MIT