Hyperdb is a JavaScript library providing a database layer designed for both peer-to-peer (P2P) and local-only data storage, leveraging the Holepunch (formerly Hypercore Protocol) ecosystem. As of version 6.6.0, it offers a schema-driven approach to defining data structures, collections, and indexes using the `Hyperschema` and `hyperdb/builder` tools. It differentiates itself by allowing developers to choose between a P2P backend (Hyperbee) for distributed, eventually consistent data, or a local, embedded database backend (RocksDB) for high-performance, single-instance storage. The project appears to be actively maintained, aligning with the broader Holepunch initiative, though a strict release cadence isn't published. Key features include declarative schema and index definitions, streaming queries, and both synchronous (`await db.get`) and asynchronous (`db.find().toArray()`) data access patterns.
npm install hyperdbVerified import paths — ran on the pinned version, not inferred.
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'.
Pass `{ autoUpdate: true }` in the options when initializing `Hyperdb.bee()` for automatic synchronization, or call `await db.update()` periodically to manually fetch new data.Always call `await db.flush()` after a series of write operations to ensure changes are written to disk or replicated.
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.
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.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.
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'`.
When initializing, ensure you explicitly set `{ writable: true }` in the options for `Hyperdb.rocks()` or `Hyperdb.bee()` if you intend to perform write operations.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.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.