corestore 5.8.0 → 6.0.0-alpha.1

package/.github/workflows/test-node.yml

@@ -0,0 +1,24 @@
+name: Test on Node.js
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+jobs:
+  build:
+    strategy:
+      matrix:
+        node-version: [12.x, 14.x, 16.x]
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm install
+    - run: npm test

package/README.md

@@ -1,15 +1,13 @@
-# corestore
-[![Build Status](https://travis-ci.com/andrewosh/corestore.svg?token=WgJmQm3Kc6qzq1pzYrkx&branch=master)](https://travis-ci.com/andrewosh/corestore)
+# Corestore v6
+[![Test on Node.js](https://github.com/hypercore-skunkworks/neocorestore/actions/workflows/test-node.yml/badge.svg)](https://github.com/hypercore-skunkworks/neocorestore/actions/workflows/test-node.yml)
 
-This module is the canonical implementation of the "corestore" interface, which exposes a Hypercore factory and a set of associated functions for managing generated Hypercores.
+Corestore is a Hypercore factory that makes it easier to manage large collections of named Hypercores.
 
-A corestore is designed to efficiently store and replicate multiple sets of interlinked Hypercores, such as those used by [Hyperdrive](https://github.com/mafintosh/hyperdrive) and [mountable-hypertrie](https://github.com/andrewosh/hypertrie), removing the responsibility of managing custom storage/replication code from these higher-level modules.
-
-In order to do this, corestore provides:
-1. __Key derivation__ - all writable Hypercore keys are derived from a single master key.
-2. __Caching__ - Two separate caches are used for passively replicating cores (those requested by peers) and active cores (those requested by the owner of the corestore).
-3. __Storage bootstrapping__ - You can create a `default` Hypercore that will be loaded when a key is not specified, which is useful when you don't want to reload a previously-created Hypercore by key.
-4. __Namespacing__ - If you want to create multiple compound data structures backed by a single corestore, you can create namespaced corestores such that each data structure's `default` feed is separate.
+Corestore provides:
+1. __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 random-access-storage instance, where they will be keyed by their discovery keys.
+4. __Namespacing__ - You can share a single Corestore instance between multiple applications or components without worrying about naming collisions by creating "namespaces" (e.g. `corestore.namespace('my-app').get({ name: 'main' }) 
 
 ### Installation
 `npm i corestore --save`
@@ -18,102 +16,45 @@ In order to do this, corestore provides:
 A corestore instance can be constructed with a random-access-storage module, a function that returns a random-access-storage module given a path, or a string. If a string is specified, it will be assumed to be a path to a local storage directory:
 ```js
 const Corestore = require('corestore')
-const ram = require('random-access-memory')
-const store = new Corestore(ram)
-await store.ready()
-```
-
-Hypercores can be generated with both the `get` and `default` methods. If the first writable core is created with `default`, it will be used for storage bootstrapping. We can always reload this bootstrapping core off disk without your having to store its public key externally. Keys for other hypercores should either be stored externally, or referenced from within the default core:
-```js
-const core1 = store1.default()
-```
-_Note: You do not have to create a default feed before creating additional ones unless you'd like to bootstrap your corestore from disk the next time it's instantiated._
 
-Additional hypercores can be created by key, using the `get` method. In most scenarios, these additional keys can be extracted from the default (bootstrapping) core. If that's not the case, keys will have to be stored externally:
-```js
-const core2 = store1.get({ key: Buffer(...) })
-```
-All hypercores are indexed by their discovery keys, so that they can be dynamically injected into replication streams when requested.
-
-Two corestores can be replicated with the `replicate` function, which accepts hypercore's `replicate` options:
-```js
-const store1 = new Corestore(ram)
-const store2 = new Corestore(ram)
-await Promise.all([store1.ready(), store2.ready()]
-
-const core1 = store2.get()
-const core2 = store2.get({ key: core1.key })
-const stream = store1.replicate(true, { live: true })
-stream.pipe(store2.replicate(false, { live: true })).pipe(stream) // This will replicate all common cores.
+const store = new Corestore('./my-storage')
+const core1 = store.get({ name: 'core-1' })
+const core2 = store.get({ name: 'core-2' })
 ```
 
 ### API
-#### `const store = corestore(storage, [opts])`
-Create a new corestore instance. `storage` can be either a random-access-storage module, or a function that takes a path and returns a random-access-storage instance.
+#### `const store = new Corestore(storage)`
+Create a new Corestore instance.
 
-Opts is an optional object which can contain any Hypercore constructor options, plus the following:
-```js
-{
-  cacheSize: 1000 // The size of the LRU cache for passively-replicating cores.
-}
-```
+`storage` can be either a random-access-storage module, a string, or a function that takes a path and returns an random-access-storage instance.
 
-#### `store.default(opts)`
-Create a new default hypercore, which is used for bootstrapping the creation of subsequent hypercores. Options match those in `get`.
+#### `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 if the `key` options is set).
 
-#### `store.get(opts)`
-Create a new hypercore. Options can be one of the following:
-```js
-{
-  key: 0x1232..., // A Buffer representing a hypercore key
-  discoveryKey: 0x1232..., // A Buffer representing a hypercore discovery key (must have been previously created by key)
-  ...opts // All other options accepted by the hypercore constructor
-}
-```
-
-If `opts` is a Buffer, it will be interpreted as a hypercore key.
+If that Hypercore has previously been loaded, subsequent calls to `get` will return a new Hypercore session on the existing core.
 
-#### `store.on('feed', feed, options)`
+All other options besides `name` and `key` will be forwarded to the Hypercore constructor.
 
-Emitted everytime a feed is loaded internally (ie, the first time get(key) is called).
-Options will be the full options map passed to .get.
+#### `const stream = store.replicate(opts)`
+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.
 
-#### `store.replicate(isInitiator, [opts])`
-Create a replication stream that will replicate all cores currently in memory in the corestore instance.
+`opts` will be forwarded to Hypercore's `replicate` function.
 
-When piped to another corestore's replication stream, only those cores that are shared between the two corestores will be successfully replicated.
-
-#### `store.list()`
-Returns a Map of all cores currently cached in memory. For each core in memory, the map will contain the following entries:
-```
-{
-  discoveryKey => core,
-  ...
-}
-```
+Corestore 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 -- Corestore replication does not exchange Hypercore keys.
 
-#### `const namespacedStore = store.namespace('some-name')`
-Create a "namespaced" corestore that uses the same underlying storage as its parent, and mirrors the complete corestore API. 
+If the remote side dynamically adds a new Hypercore to the replication stream, Corestore will load and replicatethat core if possible.
 
-`namespacedStore.default` returns a different default core, using the namespace as part of key generation, which makes it easier to bootstrap multiple data structures from the same corestore. The general pattern is for all data structures to bootstrap themselves from their corestore's default feed:
-```js
-const store = new Corestore(ram)
-const drive1 = new Hyperdrive(store.namespace('drive1'))
-const drive2 = new Hyperdrive(store.namespace('drive2'))
-```
+#### `const store = store.namespace(name)`
+Create a new namespaced Corestore. Namespacing is useful if you're going to be sharing a single Corestore instance between many applications or components, as it prevents name collisions.
 
-Namespaces currently need to be saved separately outside of corestore (as a mapping from key to namespace), so that data structures remain writable across restarts. Extending the above code, this might look like:
+Namespaces can be chained:
 ```js
-async function getDrive (opts = {}) {
-  let namespace = opts.key ? await lookupNamespace(opts.key) : await createNamespace()
-  const namespacedCorestore = store.namespace(namespace)
-  const drive = new Hyperdrive(namespacedCorestore)
-  await saveNamespace(drive.key, namespace)
-}
+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' })
 ```
 
-#### `store.close(cb)`
-Close all hypercores previously generated by the corestore.
-
 ### License
 MIT
+