Corechannels

Corechannels is a fork of Corestore, a Hypercore factory that makes it easier to manage large collections of named Hypercores. The key difference is that named cores are publicly derivable by default.

Corechannels provides:

1. Hierarchical Key Derivation - All writable Hypercore keys are derived from a single master key and a user-provided name.
2. Session Handling - If a single Hypercore is loaded multiple times through the get method, the underlying resources will only be opened once (using Hypercore 10's new session feature). Once all sessions are closed, the resources will be released.
3. Storage Management - Hypercores can be stored in any hypercore-storage instance, where they will be keyed by their discovery keys.
4. Namespacing - You can share a single Corechannels instance between multiple applications or components without worrying about naming collisions by creating "namespaces" (e.g. corechannels.namespace('my-app').get({ name: 'main' }))

Installation

npm install corechannels

Usage

A corechannels instance can be constructed with a hypercore-storage instance, or a string. If a string is specified, it will be assumed to be a path to a local storage directory:

const Corechannels = require('corechannels')
const store = new Corechannels('./my-storage')
const core1 = store.get({ name: '~private-channel' })
const core2 = store.get({ name: 'public-channel' })
const core3 = store.get({ name: '@publicKey/public-channel' }) // publicKey public channel
const core4 = store.get({ name: '@publicKey/~mail' }) // writable channel to publicKey
const core5 = store.get({ name: 'mail@publicKey' }) // read channel from publicKey

API

const store = new Corechannels(storage, options = {})

Create a new Corechannels instance.

storage can be either a hypercore-storage instance or a string.

Options:

{
  primaryKey: null, // The primary key to use as the master key for key derivation.
  writable: true,
}

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

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).

If that Hypercore has previously been loaded, subsequent calls to get will return a new Hypercore session on the existing core.

All other options besides name and key will be forwarded to the Hypercore constructor.

const stream = store.replicate(optsOrStream)

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

opts will be forwarded to Hypercore's replicate function.

Channelstore replicates in an "all-to-all" fashion, meaning that when replication begins, it will attempt to replicate every Hypercore that's currently loaded and in memory. These attempts will fail if the remote side doesn't have a Hypercore's capability -- Channelstore replication does not exchange Hypercore keys.

If the remote side dynamically adds a new Hypercore to the replication stream, ChannelStore will load and replicate that core if possible.

Using Hyperswarm you can easily replicate channelstores

const swarm = new Hyperswarm()

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

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

const storeB = storeA.session()

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

const store = store.namespace(name)

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

Namespaces can be chained:

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' })

const stream = store.list(namespace)

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

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

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:

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

store.unwatch(callback)

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

await store.suspend()

Suspend the underlying storage for the Channelstore.

await store.resume()

Resume a suspended Channelstore.

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

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

This is useful for creating deterministic key pairs that are unique to a peer.

await store.close()

Fully close this Corestore instance.

License

MIT