Hyperbee

Save a note under note:welcome and retrieve it after restarting the app. Base scaffolds include Hyperbee storage.

How it works

Hyperbee adds sorted keys and values to a Hypercore. Use it for settings, note records or indexes that must survive app restarts.

The example uses UTF-8 keys and JSON values. It writes one note, retrieves it and scans the note: key range.

Replicas can read the writer's dataset; replication alone does not authorize a second writer. Choose a collaborative layer when several devices must edit.

Run an example

Use Node 22.17+ and npm for installation. Start in a new directory for this example so its ./data storage cannot collide with another example. Save each file below with the exact filename shown, then run the commands in order.

mkdir hyperbee-demo
cd hyperbee-demo
npm init -y
npm install hypercore@'^11.37.2' hyperbee@'^2.27.3'

Save as example.mjs:

import Hypercore from 'hypercore'
import Hyperbee from 'hyperbee'
const db = new Hyperbee(new Hypercore('./data'), {
  keyEncoding: 'utf-8', valueEncoding: 'json'
})
try {
  await db.ready()
  await db.put('note:welcome', { text: 'Hello offline' })
  console.log((await db.get('note:welcome')).value.text)
  for await (const entry of db.createReadStream({ gte: 'note:', lt: 'note;' })) {
    console.log(entry.key)
  }
} finally {
  await db.close()
}

Run from this example directory:

node example.mjs

Expected result

Hello offline note:welcome

API essentials

• put(key, value), get(key), del(key): write, look up and remove records. get() returns an entry containing key and value, or null.
• createReadStream(range): iterate an ordered range rather than loading every record.
• batch() and batch.flush(): group writes. close() releases the database and its core.

Troubleshooting and limits

• Access entry.value, not the entry object itself, when reading your JSON payload.
• Reuse the same encodings whenever reopening the store.
• A remote key with no available data can wait on replication. Connect first and give reads a bounded waiting policy.

Next steps