# hypertrie

> Distributed single writer key/value store

Latest version **5.1.3** (published 2022-02-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install hypertrie
pnpm add hypertrie
yarn add hypertrie
bun add hypertrie
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.1.3 |
| Published | 2022-02-23 |
| First published | 2018-06-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 15 |
| Unpacked size | 129.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 323 |
| Author | Mathias Buus |
| Maintainers | mafintosh |

## Links

- npm: https://www.npmjs.com/package/hypertrie
- Repository: https://github.com/mafintosh/hypertrie
- Homepage: https://github.com/mafintosh/hypertrie#readme
- Issues: https://github.com/mafintosh/hypertrie/issues
- npm.io page: https://npm.io/package/hypertrie

## Dependencies (15)

- [codecs](https://npm.io/package/codecs.md) ^2.0.0
- [thunky](https://npm.io/package/thunky.md) ^1.0.2
- [varint](https://npm.io/package/varint.md) ^5.0.0
- [inherits](https://npm.io/package/inherits.md) ^2.0.3
- [mutexify](https://npm.io/package/mutexify.md) ^1.2.0
- [array-lru](https://npm.io/package/array-lru.md) ^1.1.1
- [hypercore](https://npm.io/package/hypercore.md) ^9.4.1
- [is-options](https://npm.io/package/is-options.md) ^1.0.1
- [nanoiterator](https://npm.io/package/nanoiterator.md) ^1.2.0
- [unordered-set](https://npm.io/package/unordered-set.md) ^2.0.1
- [bulk-write-stream](https://npm.io/package/bulk-write-stream.md) ^1.1.4
- [hypercore-protocol](https://npm.io/package/hypercore-protocol.md) ^8.0.0
- [siphash24-universal](https://npm.io/package/siphash24-universal.md) ^1.0.0
- [inspect-custom-symbol](https://npm.io/package/inspect-custom-symbol.md) ^1.1.0
- [protocol-buffers-encodings](https://npm.io/package/protocol-buffers-encodings.md) ^1.1.0

## Recent versions

- 5.1.3 (latest) — 2022-02-23
- 5.1.2 — 2021-09-13
- 5.1.1 — 2020-09-08
- 5.1.0 — 2020-09-07
- 5.0.5 — 2020-07-15
- 5.0.4 — 2020-06-30
- 5.0.3 — 2020-06-29
- 5.0.2 — 2020-06-10
- 5.0.1 — 2020-05-13
- 5.0.0 — 2020-05-13
- 4.8.0 — 2020-05-10
- 4.7.1 — 2020-04-01
- 4.7.0 — 2020-03-10
- 4.6.1 — 2020-03-05
- 4.6.0 — 2020-03-05
- … 30 more at https://npm.io/package/hypertrie/versions

## README

# hypertrie

Distributed single writer key/value store

```
npm install hypertrie
```

[![Build Status](https://travis-ci.org/mafintosh/hypertrie.svg?branch=master)](https://travis-ci.org/mafintosh/hypertrie)

Uses a rolling hash array mapped trie to index key/value data on top of a [hypercore](https://github.com/mafintosh/hypercore).

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.

## Usage

```js
const hypertrie = require('hypertrie')
const db = hypertrie('./trie.db', {valueEncoding: 'json'})

db.put('hello', 'world', function () {
  db.get('hello', console.log)
})
```

## API

#### `db = hypertrie(storage, [key], [options])`

Create a new database. Options include:

```
{
  feed: aHypercore, // 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.

#### `db.get(key, [options], callback)`

Lookup a key. Returns a result node if found or `null` otherwise.
Options are passed through to hypercore's get method.

#### `db.put(key, value, [options], [callback])`

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:
1. `cb(new Error(...))`: Abort with an error that will be forwarded through the `put`.
2. `cb(null, false)`: Abort the put, but do not produce an error.
3. `cb(null, true)`: Proceed with the put.

#### `db.del(key, [options], [callback])`

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.

#### `db.batch(batch, [callback])`

Insert/delete multiple values atomically.
The batch objects should look like this:

```js
{
  type: 'put' | 'del',
  key: 'key/we/are/updating',
  value: optionalValue
}
```

#### `const watcher = db.watch(prefix, [onchange])`

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.

#### `db.on('ready')`

Emitted when the db has loaded it's internal state.

You do not need to wait for this unless noted in the docs.

#### `db.version`

Returns the current version of the db (an incrementing integer).

Only available after `ready` has been emitted.

#### `db.key`

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.

#### `db.discoveryKey`

Returns the db discovery key. Can be used to find other db peers.

Only available after `ready` has been emitted.

#### `checkoutDb = db.checkout(version)`

Returns a new db instance checked out at the version specified.

#### `checkoutDb = db.snapshot()`

Same as checkout but just returns the latest version as a checkout.

#### `stream = db.replicate(isInitiator, [options])`

Returns a hypercore replication stream for the db. Pipe this together with another hypertrie 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.

#### `ite = db.iterator(prefix, [options])`

Returns a [nanoiterator](https://github.com/mafintosh/nanoiterator) that iterates
the latest values in the prefix specified.

Options include:

```js
{
  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 hypercore's get method.

#### `stream = db.createReadStream(prefix, [options])`

Same as above but as a stream

#### `db.list(prefix, [options], callback)`

Creates an iterator for the prefix with the specified options and buffers it into an array that is passed to the callback.

#### `stream = db.createWriteStream()`

A writable stream you can write batch objects to, to update the db.

#### `ite = db.history([options])`

Returns a [nanoiterator](https://github.com/mafintosh/nanoiterator) that iterates over the feed in causal order.

Options include:

```js
{
  gt: seq,
  lt: seq,
  gte: seq,
  lte: seq,
  reverse: false,
  live: false // set to true to keep iterating forever
}
```

#### `stream = db.createHistoryStream([options])`

Same as above but as a stream

#### `ite = db.diff(version, [prefix], [options])`

Returns a [nanoiterator](https://github.com/mafintosh/nanoiterator) that iterates the diff between the current db and the version you specifiy. The objects returned look like this

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

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

#### `stream = db.createDiffStream(version, [prefix])`

Same as above but as a stream

## License

MIT

---
_Source: https://npm.io/package/hypertrie · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._