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.

const Storage = require('hypercore-storage')

store = new Storage(dbOrPath)

Make a new storage engine.

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