|
1 |
| -# Corestore v6 |
2 |
| - |
3 |
| -Corestore is a Hypercore factory that makes it easier to manage large collections of named Hypercores. |
4 |
| - |
5 |
| -Corestore provides: |
6 |
| -1. __Key Derivation__ - All writable Hypercore keys are derived from a single master key and a user-provided name. |
7 |
| -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. |
8 |
| -3. __Storage Management__ - Hypercores can be stored in any random-access-storage instance, where they will be keyed by their discovery keys. |
9 |
| -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' }) |
10 |
| - |
11 |
| -### Installation |
12 |
| -`npm install corestore@next` |
13 |
| - |
14 |
| -### Usage |
15 |
| -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: |
16 |
| -```js |
17 |
| -const Corestore = require('corestore') |
18 |
| - |
19 |
| -const store = new Corestore('./my-storage') |
20 |
| -const core1 = store.get({ name: 'core-1' }) |
21 |
| -const core2 = store.get({ name: 'core-2' }) |
22 |
| -``` |
23 |
| - |
24 |
| -### API |
25 |
| -#### `const store = new Corestore(storage)` |
26 |
| -Create a new Corestore instance. |
27 |
| - |
28 |
| -`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. |
29 |
| - |
30 |
| -#### `const core = store.get(key | { name: 'a-name', ...hypercoreOpts})` |
31 |
| -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). |
32 |
| - |
33 |
| -If that Hypercore has previously been loaded, subsequent calls to `get` will return a new Hypercore session on the existing core. |
34 |
| - |
35 |
| -All other options besides `name` and `key` will be forwarded to the Hypercore constructor. |
36 |
| - |
37 |
| -#### `const stream = store.replicate(opts)` |
38 |
| -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. |
39 |
| - |
40 |
| -`opts` will be forwarded to Hypercore's `replicate` function. |
41 |
| - |
42 |
| -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. |
43 |
| - |
44 |
| -If the remote side dynamically adds a new Hypercore to the replication stream, Corestore will load and replicatethat core if possible. |
45 |
| - |
46 |
| -#### `const store = store.namespace(name)` |
47 |
| -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. |
48 |
| - |
49 |
| -Namespaces can be chained: |
50 |
| -```js |
51 |
| -const ns1 = store.namespace('a') |
52 |
| -const ns2 = ns1.namespace('b') |
53 |
| -const core1 = ns1.get({ name: 'main' }) // These will load different Hypercores |
54 |
| -const core2 = ns2.get({ name: 'main' }) |
55 |
| -``` |
56 |
| - |
57 |
| -### License |
58 |
| -MIT |
59 |
| - |
| 1 | +Development has moved to https://github.com/hypercore-protocol/corestore |
0 commit comments