Home > Engineering > Third Party Software > P2P building blocks > Hyperbee

Hyperbee

Hyperbee is an append-only B-tree — a sorted key/value store running on a single Hypercore. It gives sorted iteration, range queries, atomic batches, and history/diff streams, plus cheap sub-namespaces. It is the index and metadata layer of the family: Hyperdrive uses a Hyperbee for its file metadata, and it is the common materialised-view type for Autobase.


Core API

See the README for exhaustive detail.

Create

const db = new Hyperbee(core, [options])
core is a Hypercore. options includes keyEncoding and valueEncoding ('binary' 'utf-8' 'ascii' 'json' an abstract-encoding; default binary).
const db = new Hyperbee(core, { keyEncoding: 'utf-8', valueEncoding: 'json' })
await db.put('a', { hello: 'world' })
const { value } = await db.get('a')

Read & write

Streams

Sub-databases, versions, batches


Gotchas

sub() is byte-prefix namespacing, not isolation. Sibling sub-DBs share the one underlying core and the one version counter, and a createDiffStream reflects changes across all of them. Good for organising keys; not an access-control boundary.

db.version is Hyperbee’s own counter, and it is the point-in-time handle you pass to checkout() / createDiffStream(). Don’t conflate it with the underlying core’s length.

Long-lived read streams hold a checkout implicitly, which pins storage — close them when done.


Version

hyperbee@2 — a stable API; the docs mark it “Status: stable”, documented against 2.27.3, which is still the current release (no release since January 2026). Check the npm registry before pinning.

hyperbee2: the next major, in progress

A successor is in development as a separate package, hyperbee2: “Next major version for hyperbee. Will be merged in there and released a new major when fully done.” It is very active (2.21.4 in November 2026), and Autobee is built on it. Its API differs from Hyperbee’s:

The docs do not cover hyperbee2 yet. When and under what version the merge ships is not stated upstream.

See Also