Registry / storage / hypercore-storage

hypercore-storage

JSON →
library3.1.1jsnpmunverified

The storage engine for Hypercore, built on RocksDB. This package provides low-level I/O for Hypercore, including creating and resuming cores, reading/writing blocks, tree nodes, bitfield pages, and user-defined data, as well as atomic batch operations and streams for core listing and data traversal. Current stable version is 3.1.1. It is designed for use with Hypercore 11 and provides a more flexible and efficient storage layer compared to older versions. Release cadence is irregular, tied to Hypercore updates.

npm install hypercore-storage
INSTALL
IMPORT
SIG · HYPERCORE-STORAGE
H
hypercore-storage
storagejavascriptv3.1.1
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

default export (class Storage)
import Storage from 'hypercore-storage'
const Storage = require('hypercore-storage')
Package is ESM-only since v3 (or uses export default). For CJS, use dynamic import or upgrade to Node 14+ with module resolution.
Storage (for types)
import type { Storage } from 'hypercore-storage'
import Storage from 'hypercore-storage' (when only needing types)
TypeScript users should use import type for type-only imports to avoid bundling issues.
CoreReadStream
import { CoreReadStream } from 'hypercore-storage'
import CoreReadStream from 'hypercore-storage' (wrong named export)
CoreReadStream is a named export, not default. Ensure you use destructuring.

Creates a hypercore storage instance, writes a block, reads it back, and closes the store.

import Storage from 'hypercore-storage' const store = new Storage('./my-db') async function example() { // Create a core const core = await store.createCore({ key: Buffer.alloc(32), discoveryKey: Buffer.alloc(32) }) // Write a block const tx = core.write() tx.putBlock(0, Buffer.from('hello')) await tx.flush() // Read the block back const rx = core.read() const block = await rx.getBlock(0) console.log(block.toString()) // 'hello' rx.tryFlush() await store.close() } example().catch(console.error)
Debug
Known issues
breakingRead batch does not resolve until rx.tryFlush() is called. Forgetting to call tryFlush() causes promises to hang indefinitely.
fix
Always call rx.tryFlush() after your read operations, or use an alternative pattern that flushes automatically.
affects: >=3.0.0
breakingThe module is ESM-only from v3 onwards. Using require() throws a runtime error.
fix
Use import syntax or switch to dynamic import. For Node.js <14, consider using a transpiler or downgrading to v2.
affects: >=3.0.0
gotchacore.resumeCore(discoveryKey) can return null if the core does not exist. Code must handle null.
fix
Check the return value before using it: const core = await store.resumeCore(dk); if (!core) throw new Error('Core not found');
affects: >=3.0.0
gotchaWrite batch methods (putBlock, etc.) are synchronous and only buffer changes. The flush() call is async and can throw if there are errors.
fix
Always await tx.flush() and handle errors. Do not assume the write succeeded until flush completes.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: require(...) is not a function
Using CommonJS require() on an ESM-only package.
fix
Change to import Storage from 'hypercore-storage' (ESM) or use dynamic import: const { default: Storage } = await import('hypercore-storage')
Error: expect read batch to be flushed
Calling a read method after the read batch has already been flushed.
fix
Create a new read batch for every set of read operations: const rx = core.read(); const block = await rx.getBlock(0); rx.tryFlush();
TypeError: core.write is not a function
Trying to call write() on a core that is not fully initialized (e.g., resumeCore returned null).
fix
Ensure the core exists: const core = await store.resumeCore(dk); if (core) { const tx = core.write(); ... }
Upgrade
Version history
3.1.1latest on npm
Audit
Dependencies
rocksdbrequiredUnderlying key-value store for persistent storage.
Agent activity
16 hits · last 30 days
node
14
Resources
hypercore-storage — npm install hypercore-storage · libregistry