hyperdb: P2P Indexable Database

Common errors

• Error: Collection '@example/members' not found

  cause The specified collection or index was not registered in the database definition, or the definition file was not correctly loaded at runtime.
  fix Verify that your builder script correctly registers the collection using `exampleDB.collections.register()`, runs `HyperDBBuilder.toDisk(dbBuilder)`, and that your runtime code correctly imports the generated definition via `import def from './spec/hyperdb/index.js'`.

• Error: Cannot insert, database is read-only

  cause The Hyperdb instance was initialized with `writable: false` (for `.bee`) or `readOnly: true` (for `.rocks`), preventing write operations.
  fix When initializing, ensure you explicitly set `{ writable: true }` in the options for `Hyperdb.rocks()` or `Hyperdb.bee()` if you intend to perform write operations.

• TypeError: (0, _hyperdb.default) is not a constructor

  cause This typically indicates a CommonJS `require` call in an ES module environment, or an incorrect named/default import for a module that exports a default.
  fix Ensure your runtime files are treated as ES modules (e.g., use `.mjs` extension or `"type": "module"` in `package.json`) and use `import HyperDB from 'hyperdb'`. If working with the builder, use `import HyperDBBuilder from 'hyperdb/builder'` or `const HyperDBBuilder = require('hyperdb/builder')` depending on your builder script's module type.

• No such file or directory: './spec/hyperdb/index.js'

  cause The generated database definition file could not be found at the specified path, often because the builder script was not run or produced output elsewhere.
  fix First, run your `build.js` (or equivalent) script to generate the definition files. Second, confirm that the `import def from './spec/hyperdb/index.js'` path in your runtime code correctly points to the location where the definition was generated, relative to the script's execution context.

Warnings

• gotcha When using `Hyperdb.bee` for P2P databases, the `autoUpdate` option defaults to `false`. This means the database will not automatically sync with updates from the underlying Hyperbee. You must manually call `db.update()` or set `autoUpdate: true` during initialization to ensure data consistency.
  Fix: Pass `{ autoUpdate: true }` in the options when initializing `Hyperdb.bee()` for automatic synchronization, or call `await db.update()` periodically to manually fetch new data.
• gotcha All write operations (e.g., `insert`, `delete`, `update`) are buffered and require an explicit `await db.flush()` call to be committed and persisted to the underlying storage. Forgetting to flush will result in data not being saved.
  Fix: Always call `await db.flush()` after a series of write operations to ensure changes are written to disk or replicated.
• breaking Hyperdb utilizes a mandatory builder step (using `hyperdb/builder` and `hyperschema`) to generate database definitions. Without correctly defined schemas, collections, and indexes, runtime operations will fail with 'collection not found' errors. This introduces a build-time dependency that must be managed.
  Fix: Ensure a `build.js` (or similar) script is executed to generate the database definition files (e.g., `./spec/hyperdb/index.js`) before attempting to initialize or use `HyperDB` at runtime.
• gotcha The documentation and examples show a mix of CommonJS (`require`) for builder scripts and ES Modules (`import`) for runtime usage. Mixing these in the same project or misusing them can lead to module resolution errors.
  Fix: For runtime code, use ES module `import HyperDB from 'hyperdb'`. For builder scripts (if kept as CJS), use `const HyperDBBuilder = require('hyperdb/builder')`. If using TypeScript, ensure your `tsconfig.json`'s `module` and `moduleResolution` settings align with your target Node.js environment and how you intend to run the code.
• gotcha Queries executed via `db.find()` operate on a snapshot of the database state at the moment the query is initiated. Any inserts or deletes that occur while a query stream is active will not be reflected in that particular query's results.
  Fix: If real-time reflection of changes is required, re-run the query after modifications have been flushed. For P2P scenarios with `autoUpdate: true`, consider using event listeners if the underlying Hyperbee provides them, or implement a polling mechanism with fresh queries.

Install

• npm install hyperdb npm
• yarn add hyperdb yarn
• pnpm add hyperdb pnpm

Imports

• HyperDB
  wrong:

  const HyperDB = require('hyperdb')

  correct:

  import HyperDB from 'hyperdb'

  Primary runtime import for database instantiation. The library uses ESM for its main entry point in recent versions (>=6.x), so `import` is preferred over `require`.
• HyperDBBuilder
  wrong:

  const HyperDBBuilder = require('hyperdb/builder')

  correct:

  import HyperDBBuilder from 'hyperdb/builder'

  Used in the database definition build script. While the README shows `require`, it is also available via ESM import. For clarity in builder scripts which might be CommonJS, `require` is also common.
• definition
  wrong:

  import def from './spec/hyperdb'

  correct:

  import def from './spec/hyperdb/index.js'

  The generated database definition is an ES module. Node.js requires the `.js` extension for local ES module imports unless a custom module resolution is configured.

Quickstart

Demonstrates initializing a local Hyperdb instance (using RocksDB), inserting data into a defined collection, querying by exact match and using an index, and properly closing the database. It assumes database schemas and collections have already been defined and built into './spec/hyperdb/index.js'.

// This quickstart assumes you have already run a builder script (like the one in the README)
// to generate your database definition files in './spec/hyperdb/index.js'.

import HyperDB from 'hyperdb';
import def from './spec/hyperdb/index.js'; // The generated database definition

async function run() {
  // Choose your engine: .rocks for local-only, .bee for P2P
  // For this example, we'll use RocksDB locally.
  // Replace './my-local-db' with a suitable path for your database files.
  const db = HyperDB.rocks('./my-local-db', def, { writable: true });

  await db.ready(); // Ensure the database is initialized and ready for operations

  // Add some entries
  console.log('Inserting members...');
  await db.insert('@example/members', { name: 'Alice', age: 30 });
  await db.insert('@example/members', { name: 'Bob', age: 25 });
  await db.insert('@example/members', { name: 'Charlie', age: 30 });
  await db.flush(); // Commit changes to the database

  console.log('Querying for Alice by name...');
  const alice = await db.get('@example/members', { name: 'Alice' });
  console.log('Found Alice:', alice);

  console.log('Querying for members with names starting C or later (via index)...');
  // The example index 'members-by-name' has a 'mapNameToLowerCase' helper.
  const olderMembersStream = db.find('@example/members-by-name', { gte: { key: 'c' } });
  const olderMembers = await olderMembersStream.toArray();
  console.log('Members with names starting C or later:', olderMembers.map(m => m.name));

  console.log('Getting one specific member by name using findOne...');
  const bob = await db.findOne('@example/members', { name: 'Bob' });
  console.log('Found Bob:', bob);

  await db.close(); // Close the database connection to release resources
  console.log('Database closed.');
}

run().catch(console.error);