# hypercore-storage

> Storage engine for Hypercore

Latest version **3.3.1** (published 2026-09-14) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install hypercore-storage
pnpm add hypercore-storage
yarn add hypercore-storage
bun add hypercore-storage
```

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 3.3.1 |
| Published | 2026-09-14 |
| First published | 2024-10-14 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 13 |
| Unpacked size | 160 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 13 |
| Author | Holepunch |
| Maintainers | mafintosh, lejeunerenard |

## Links

- npm: https://www.npmjs.com/package/hypercore-storage
- Repository: https://github.com/holepunchto/hypercore-storage
- Homepage: https://github.com/holepunchto/hypercore-storage#readme
- Issues: https://github.com/holepunchto/hypercore-storage/issues
- npm.io page: https://npm.io/package/hypercore-storage

## Dependencies (13)

- [b4a](https://npm.io/package/b4a.md) ^1.6.7
- [xache](https://npm.io/package/xache.md) ^1.2.1
- [streamx](https://npm.io/package/streamx.md) ^2.21.1
- [bare-path](https://npm.io/package/bare-path.md) ^3.0.0
- [flat-tree](https://npm.io/package/flat-tree.md) ^1.12.1
- [scope-lock](https://npm.io/package/scope-lock.md) ^1.2.4
- [device-file](https://npm.io/package/device-file.md) ^2.1.2
- [hyperschema](https://npm.io/package/hyperschema.md) ^1.21.0
- [index-encoder](https://npm.io/package/index-encoder.md) ^3.3.2
- [rocksdb-native](https://npm.io/package/rocksdb-native.md) ^3.18.0
- [compact-encoding](https://npm.io/package/compact-encoding.md) ^3.1.0
- [hypercore-crypto](https://npm.io/package/hypercore-crypto.md) ^3.4.2
- [resolve-reject-promise](https://npm.io/package/resolve-reject-promise.md) ^1.0.0

## Recent versions

- 3.3.1 (latest) — 2026-09-14
- 3.3.0 — 2026-09-14
- 3.2.1 — 2026-08-12
- 3.2.0 — 2026-07-13
- 3.1.2 — 2026-06-18
- 3.1.1 — 2026-06-05
- 3.1.0 — 2026-06-03
- 3.0.2 — 2026-05-25
- 3.0.1 — 2026-05-23
- 3.0.0 — 2026-05-21
- 2.9.0 — 2026-05-05
- 2.8.0 — 2026-03-27
- 2.7.1 — 2026-03-11
- 2.7.0 — 2026-03-11
- 2.6.1 — 2026-03-10
- … 107 more at https://npm.io/package/hypercore-storage/versions

## README

# hypercore-storage

The storage engine for Hypercore. Built on RocksDB.

```
npm install hypercore-storage
```

## API

The following API is what Hypercore 11 binds to to do I/O.

```js
const Storage = require('hypercore-storage')
```

#### `store = new Storage(dbOrPath, opts = {})`

Make a new storage engine.

`opts` includes:

```
{
  treeCache: {    // Same options as `xache`
    maxSize: 8192 // Max number of tree nodes to cache
  },
  onresume: null  // Called with the discovery key when `resumeCore` is invoked,
                  // before the lookup, so it fires even if the core does not exist
}
```

#### `core = await store.createCore({ key, discoveyKey, manifest?, keyPair?, encryptionKey?, userData? })`

Create a new core, returns a storage instance for that core.

#### `core = await store.resumeCore(discoveryKey)`

Resume a previously make core. If it doesn't exist it returns `null`.

#### `atom = store.createAtom()`

Primitive for making atomic batches across ops. See below for `core.atomize` on how to use it.
When you wanna flush your changes to the underlying storage, use `await atom.flush()`.

Internally to "listen" for when that happens you can add an sync hook with `atom.onflush(fn)`

#### `bool = await store.hasCore(discoveryKey)`

Check if a core exists.

#### `stream = store.createCoreStream()`

List all cores. Stream data looks like this `{ discoveryKey, core }` where core contains the core header.

#### `await store.close()`

Close the storage instance.

#### `rx = core.read()`

Make a read batch on a core storage.

**NOTE:** a read batch DOES NOT flush until you call `rx.tryFlush()`.

#### `await rx.getAuth()`

Returns the auth data around a core.

#### `await rx.getHead()`

Returns the head of the merkle tree.

#### `await rx.getSessions()`

Returns an array of all named sessions.

#### `await rx.getDependency()`

Returns the core this has a dependency on.

#### `await rx.getHints()`

Returns the various storage/replication hints.

#### `await rx.getBlock(index)`

Returns a block stored.

#### `await rx.getTreeNode(index)`

Returns a tree node stored.

#### `await rx.getBitfieldPage(index)`

Return a bitfield page.

#### `await rx.getUserData(key)`

Return a user stored buffer. `key` is a string.

#### `rx.tryFlush()`

Flushes the read batch, non of the above promises will resolve until you call this.

#### `tx = core.write()`

Make a write batch on a core storage.

**NOTE:** all the apis below are sync as they just buffer mutations until you flush them.

#### `tx.setAuth(auth)`

Set the auth data around a core.

#### `tx.setHead(auth)`

Set the head of the merkle tree.

#### `tx.setSessions(sessions)`

Set an array of all named sessions.

#### `tx.setDependency(dep)`

Set the core this has a dependency on.

#### `tx.setHints(hints)`

Set the various storage/replication hints.

#### `tx.putBlock(index, buffer)`

Put a block at a specific index.

#### `tx.deleteBlock(index)`

Delete a block at a specific index.

#### `tx.deleteBlockRange(start, index)`

Delete blocks between two indexes.

#### `tx.putTreeNode(node)`

Put a tree node (at its described index).

#### `tx.deleteTreeNode(index)`

Delete a tree node at a specific index.

#### `tx.deleteTreeNodeRange(start, index)`

Delete blocks between two tree indexes.

#### `tx.putBitfieldPage(index, page)`

Put a bitfield page at its described index.

#### `tx.deleteBitfieldPage(index)`

Delete a bitfield page.

#### `tx.deleteBitfieldPageRange(start, end)`

Delete bitfield pages between two indexes.

#### `tx.putUserData(key, value)`

Put a user provided buffer at a user provided `key`. `key` is a string.

#### `tx.deleteUserData(key)`

Delete a user provided `key`. `key` is a string.

#### `await tx.flush()`

Flushes the write batch.

#### `stream = core.createBlockStream(opts)`

Create a stream of all blocks.

#### `stream = core.createTreeNodeStream(opts)`

Create a stream of all tree nodes.

#### `stream = core.createBitfieldStream(opts)`

Create a stream of all bitfield pages.

#### `stream = core.createUserDataStream(opts)`

Create a stream of all user data. `opts` is a query object with the following possible properties:

```
{
  gt: 'only return keys > than this', // Not currently supported
  gte: 'only return keys >= than this',
  lt: 'only return keys < than this',
  lte: 'only return keys <= than this', // Not currently supported
  reverse: false // reverse results. Not currently supported
}
```

#### `await core.close()`

Close the core storage engine.

#### `atom = core.createAtom()`

Same as `store.createAtom()` but here again for conveinience.

#### `core = core.atomize(atom)`

Atomize a core. Allows you to build up cross core atomic batches and operations.
An atomized core will not flush its changes until you call `atom.flush()`, but you can still read your writes.

#### `core = core.createSession(name, head)`

Create a named session on top of a core. A named session points back to the previous storage,
but is otherwise independent and stored on disk, like a branch in git if you will.

#### `core.dependencies`

Array containing the full list of dependencies for this core (ie tree of named sessions).

## License

Apache-2.0

---
_Source: https://npm.io/package/hypercore-storage · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._