Corestore

Corestore manages many related Hypercores behind one storage root and one replication surface. It is the helper you usually share across Hyperbee, Hyperdrive, and Autobase instances. For upstream source and changelog context, see the Corestore repository.

Install

npm i corestore

Quickstart

import Corestore from 'corestore'

const store = new Corestore('./app-storage')
await store.ready()

const messages = store.get({
  name: 'messages',
  valueEncoding: 'json'
})

await messages.ready()
await messages.append({ text: 'hello from corestore' })

console.log(await messages.get(0))

await store.close()

API Reference

Constructor and lifecycle

new Corestore(storage, options = {})

src

Create a new Corestore instance.

• Throws: ERR_ASSERTION if primaryKey is set on a root store without unsafe: true.

await store.ready()

A promise that resolves once the storage seed is loaded and properties such as store.primaryKey are available.

await store.close()

Fully close this Corestore instance.

await store.suspend([options])

src

Suspend the underlying storage for the Corestore.

• Returns: Promise<void> — Resolves once the storage is suspended.

Since 7.12.0 this no longer flushes the database first. Earlier releases flushed on every suspend() unless the store was read-only; flush explicitly if you were relying on that.

await store.suspend()

await store.resume()

src

Resume a suspended Corestore.

• Returns: Promise<void> — Resolves once the storage is resumed.

await store.resume()

Store properties

store.storage

src

The backing storage adapter used for aliases, seeds, and Hypercore data files.

• Returns: object

store.primaryKey

src

The 32-byte primary key used to deterministically derive writable named cores and namespaced key pairs.

• Returns: Buffer

store.readOnly

src

true when the store was opened without write access.

• Returns: boolean

store.manifestVersion

src

The Hypercore manifest version used when Corestore creates new writable cores. Set it with the manifestVersion option, or override it for a single core with store.get().

• Returns: number

store.alwaysLatestBlock

src

true when every core this store loads asks for the latest block with each upgrade request. Set it with the alwaysLatestBlock option. Sessions and namespaces created from a store share its value.

• Returns: boolean

store.active

src

true when the store should automatically attach loaded cores to active replication streams.

• Returns: boolean

store.opened / store.closed

true once store.ready() has resolved / once store.close() has completed. Useful for guarding access to a store whose lifecycle you don't fully control.

• Returns: boolean

Loading cores and scoping sessions

store.get(key | { name: 'a-name', ...hypercoreOpts})

src

Loads a Hypercore, either by name (if the name option is provided), or from the provided key (if the first argument is a Buffer or String with hex/z32 key, or if the key options is set).

• Returns: Hypercore — A Hypercore session for the requested core.

allowLatestBlock is forwarded through to the returned Hypercore's own allowLatestBlock option. When you set it, even to false, it takes precedence over the store's alwaysLatestBlock.

When get() creates a new writable core, from name or keyPair, you can pass manifestVersion to override store.manifestVersion for that call. A core that already exists under that name keeps the manifest it was created with. Added in 7.12.6.

userData is an object of keys and values that get() writes to the core's local User Data store, as the Hypercore userData option does. Added in 7.14.0. weak is forwarded like the Hypercore weak option, so the session does not keep the core alive and does not stop store.purge(). Added in 7.15.0.

const core = store.get({ name: 'my-core' })

storeA.session()

src

Create a new Corestore session. Closing a session will close all cores made from this session.

• Returns: Corestore — A new Corestore session sharing the same storage.

const session = store.session()

store.namespace(name)

src

Create a new namespaced Corestore session. Namespacing is useful if you're going to be sharing a single Corestore instance between many applications or components, as it prevents name collisions.

• Returns: Corestore — A new namespaced Corestore session.

const ns1 = store.namespace('a')
const ns2 = ns1.namespace('b')
const core1 = ns1.get({ name: 'main' }) // These will load different Hypercores
const core2 = ns2.get({ name: 'main' })

Replication and discovery

store.replicate(optsOrStream)

src

Creates a replication stream that's capable of replicating all Hypercores that are managed by the Corestore, assuming the remote peer has the correct capabilities.

• Returns: Stream — The replication stream.

const swarm = new Hyperswarm()

// join the relevant topic
swarm.join(...)

// simply pass the connection stream to corestore
swarm.on('connection', (connection) => store.replicate(connection))

store.findingPeers()

src

A completion callback. Call it after the current peer-discovery pass finishes so pending update waits on loaded cores can unblock.

• Returns: Function — A done function to call once peer discovery has finished.

const done = store.findingPeers()
swarm.flush().then(done, done)

store.list(namespace)

src

Creates a discovery key stream of all cores within a namespace or all cores in general if no namespace is provided.

• Returns: Readable — A stream of discovery keys.

for await (const discoveryKey of store.list()) console.log(discoveryKey)

store.getAuth(discoveryKey)

src

The storage-layer auth metadata for that core, including manifest details when available.

• Returns: Promise<object\|null> — The auth record, or null if not stored.

const auth = await store.getAuth(discoveryKey)

Key derivation and maintenance

await store.createKeyPair(name, ns = this.ns)

src

Generate a key pair seeded with the Corestore's primary key using a name and a ns aka namespace. ns defaults to the current namespace.

• Returns: Promise<{publicKey: Buffer, secretKey: Buffer}> — The derived key pair.

const keyPair = await store.createKeyPair('signer')

store.audit(opts = {})

src

An audit report describing the state of the backing store and any detected inconsistencies.

• Returns: AsyncGenerator<object> — Yields a result per core as it is audited.

for await (const report of store.audit()) console.log(report)

await store.staticify(core, opts = {})

src

A reopened Hypercore whose manifest is converted into a static prologue-based manifest for the current data snapshot.

• Returns: Promise<Hypercore> — The new static Hypercore.
• Throws: if the core has no data to staticify.

const staticCore = await store.staticify(core)

// Give the static core a version 2 manifest that carries user data
const custom = await store.staticify(core, {
  manifest: { version: 2, userData: Buffer.from('mapped from somewhere') }
})

await store.purge(keys, [options])

src

Permanently delete cores from the store's storage, using core.purge() for each one. A core the store does not hold is skipped, and so is a core with an open session unless you pass force. Weak sessions do not count as open. Added in 7.15.0.

• Returns: Promise<Buffer[]> — The discovery keys of the cores that were purged, in the order of keys. Skipped cores are left out.

A purged name starts over the next time you call store.get({ name }): it opens an empty core with the same key, unless you pass a different manifestVersion.

const core = store.get({ name: 'drafts' })
await core.append('hello')

const key = core.key
await core.close() // purge skips cores with open sessions

const purged = await store.purge(key) // or an array of keys
console.log(purged.length) // 1

Watchers

store.watch((core) => {})

src

Register a callback called when new Hypercores are opened. core is the internal core for the opened Hypercore. It can be used to create weak references to a Hypercore like so:

• Returns: void

store.watch(function (core) {
  const weakCore = new Hypercore({ core, weak: true })
})

store.unwatch(callback)

src

Unregister a callback used with store.watch(callback) so it no longer fires.

• Returns: void

store.unwatch(onCore)

Group notifications (experimental)

store.notifyGroup(topic)

src

Get a handle for updates from all hypercores with the group topic set.

• Returns: GroupNotifyHandle — A handle that emits update when a core in the group changes.

const handle = store.notifyGroup(topic)
handle.on('update', () => console.log('group changed'))

handle.updates(opts = {})

src

Gets updates for the topic the handle is for.

• Returns: Readable — A stream of the keys of the cores that updated.

for await (const key of handle.updates()) {
  // ...
}

handle.destroy()

src

Destroys and unregisters the handle from its store.

handle.on('update', callback)

Calls the callback whenever a core with the topic for the handle updates.

store.on('group-active', (topic) => {})

src

The group-active event emits whenever an opened Hypercore in the store updates. The topic is the group topic the core belongs to.

Types

CorestoreOptions

Options for the {@link Corestore} constructor. Any other options are forwarded to the underlying hypercore-storage instance.

Errors

Coded errors this module can throw — catch them via err.code.

See also

• Work with many Hypercores using Corestore—the task-oriented guide that shows how to share one store across your app.
• Hypercore—the append-only log type Corestore opens and co-replicates.
• Hyperbee—commonly layered on top of named Hypercores from one store.
• Hyperdrive—usually keeps filesystem metadata and content stores inside one shared Corestore.
• Autobase—multi-writer views often coordinate their input cores through one Corestore.
• Hyperswarm—pass swarm connections to store.replicate() to co-replicate all managed cores over one stream.
• Upstream Corestore repository—source, releases, and implementation details.