{"id":48166,"library":"hypercore-storage","title":"hypercore-storage","description":"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.","status":"active","version":"3.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/holepunchto/hypercore-storage","tags":["javascript"],"install":[{"cmd":"npm install hypercore-storage","lang":"bash","label":"npm"},{"cmd":"yarn add hypercore-storage","lang":"bash","label":"yarn"},{"cmd":"pnpm add hypercore-storage","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Underlying key-value store for persistent storage.","package":"rocksdb","optional":false}],"imports":[{"note":"Package is ESM-only since v3 (or uses export default). For CJS, use dynamic import or upgrade to Node 14+ with module resolution.","wrong":"const Storage = require('hypercore-storage')","symbol":"default export (class Storage)","correct":"import Storage from 'hypercore-storage'"},{"note":"TypeScript users should use import type for type-only imports to avoid bundling issues.","wrong":"import Storage from 'hypercore-storage' (when only needing types)","symbol":"Storage (for types)","correct":"import type { Storage } from 'hypercore-storage'"},{"note":"CoreReadStream is a named export, not default. Ensure you use destructuring.","wrong":"import CoreReadStream from 'hypercore-storage' (wrong named export)","symbol":"CoreReadStream","correct":"import { CoreReadStream } from 'hypercore-storage'"}],"quickstart":{"code":"import Storage from 'hypercore-storage'\nconst store = new Storage('./my-db')\n\nasync function example() {\n  // Create a core\n  const core = await store.createCore({ key: Buffer.alloc(32), discoveryKey: Buffer.alloc(32) })\n\n  // Write a block\n  const tx = core.write()\n  tx.putBlock(0, Buffer.from('hello'))\n  await tx.flush()\n\n  // Read the block back\n  const rx = core.read()\n  const block = await rx.getBlock(0)\n  console.log(block.toString()) // 'hello'\n  rx.tryFlush()\n\n  await store.close()\n}\nexample().catch(console.error)","lang":"typescript","description":"Creates a hypercore storage instance, writes a block, reads it back, and closes the store."},"warnings":[{"fix":"Always call rx.tryFlush() after your read operations, or use an alternative pattern that flushes automatically.","message":"Read batch does not resolve until rx.tryFlush() is called. Forgetting to call tryFlush() causes promises to hang indefinitely.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use import syntax or switch to dynamic import. For Node.js <14, consider using a transpiler or downgrading to v2.","message":"The module is ESM-only from v3 onwards. Using require() throws a runtime error.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Check the return value before using it: const core = await store.resumeCore(dk); if (!core) throw new Error('Core not found');","message":"core.resumeCore(discoveryKey) can return null if the core does not exist. Code must handle null.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always await tx.flush() and handle errors. Do not assume the write succeeded until flush completes.","message":"Write batch methods (putBlock, etc.) are synchronous and only buffer changes. The flush() call is async and can throw if there are errors.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'11':63 '3.1.1':55 'atom':40 'batch':41 'bitfield':30 'block':27 'built':9 'cadenc':78 'compar':73 'core':25,46 'creat':22 'current':51 'data':36,49 'defin':35 'design':58 'effici':70 'engin':6 'flexibl':68 'hypercor':2,8,20,62,83 'hypercore-storag':1 'i/o':18 'includ':21 'irregular':80 'javascript':85 'layer':72 'level':17 'list':47 'low':16 'low-level':15 'node':29 'older':75 'oper':42 'packag':13 'page':31 'provid':14,65 'reading/writing':26 'releas':77 'resum':24 'rocksdb':11 'stabl':52 'storag':3,5,71 'stream':44 'tie':81 'travers':50 'tree':28 'updat':84 'use':60 'user':34 'user-defin':33 'version':53,76 'well':38","created_at":"2026-06-07T16:55:14.758370+00:00","updated_at":"2026-06-07T16:55:14.758370+00:00","problems":[{"fix":"Change to import Storage from 'hypercore-storage' (ESM) or use dynamic import: const { default: Storage } = await import('hypercore-storage')","cause":"Using CommonJS require() on an ESM-only package.","error":"TypeError: require(...) is not a function"},{"fix":"Create a new read batch for every set of read operations: const rx = core.read(); const block = await rx.getBlock(0); rx.tryFlush();","cause":"Calling a read method after the read batch has already been flushed.","error":"Error: expect read batch to be flushed"},{"fix":"Ensure the core exists: const core = await store.resumeCore(dk); if (core) { const tx = core.write(); ... }","cause":"Trying to call write() on a core that is not fully initialized (e.g., resumeCore returned null).","error":"TypeError: core.write is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/holepunchto/hypercore-storage#readme","github":"https://github.com/holepunchto/hypercore-storage","docs":null,"changelog":null,"pypi":null,"npm":"hypercore-storage","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}