npm package: @omegajs/keeper
Description: A factory module for Scroll that streamlines the process of managing and organizing collections of scrolls.
Latest version: 1.0.0

# Keeper [Scroll Storage Factory]
## @omegajs/keeper

### [See the full API docs at docs.l1fe.tech](https://docs.l1fe.tech/omega/components/keeper)

A factory module for Scroll that streamlines the process of managing and organizing collections of scrolls.

Keeper provides:
1. __Key Derivation__ - All writable Scroll keys are derived from a single master key and a user-provided name.
2. __Session Handling__ - If a single Scroll is loaded multiple times through the `get` method, the underlying resources will only be opened once (using Scroll 10's new session feature). Once all sessions are closed, the resources will be released.
3. __Storage Management__ - ≈ 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 Keeper instance between multiple applications or components without worrying about naming collisions by creating "namespaces" (e.g. `keeper.namespace('my-app').get({ name: 'main' })`)

## Install Via L1FE's NPM
```
npm config set registry https://npm.l1fe.tech
npm install @omegajs/keeper
```

## Install Via L1FE's Git Repository
```
git clone https://lab.l1fe.tech/omega/keeper.git
cd keeper
npm install
```

### Usage
A `keeper` 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 Keeper = require('@omegajs/keeper')

const vault = new Keeper('./my-keeper')
const scroll1 = vault.get({ name: 'scroll-1' })
const scroll2 = vault.get({ name: 'scroll-2' })
```

### API
#### `const vault = new Keeper(storage)`
Create a new Keeper instance.

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

#### `const scroll = vault.get(key | { name: 'a-name', exclusive, ...scrollOpts})`
Loads a Scroll, 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 Scroll has previously been loaded, subsequent calls to `get` will return a new Scroll session on the existing scroll.

If you set the `exclusive` option and you are opening a writable session it will wait for all other exclusive writable to close before
opening the Scroll effectively meaning any op on the scroll will wait until its exclusive.

All other options besides `name` and `key` and `exclusive` will be forwarded to the Scroll constructor.

#### `const stream = vault.replicate(optsOrStream)`
Creates a replication stream that's capable of replicating all Scrolls that are managed by the Keeper, assuming the remote peer has the correct capabilities.

`opts` will be forwarded to a Scroll's `replicate` function.

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

If the remote side dynamically adds a new Scroll to the replication stream, Keeper will load and replicate that scroll if possible.

Using [Flock](https://lab.l1fe.tech/omega/flock) you can easily replicate keepers

``` js
const flock = new Flock()

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

// simply pass the connection stream to keeper
flock.on('connection', (connection) => vault.replicate(connection))
```

#### `const vault = vault.namespace(name)`
Create a new namespaced Keeper. Namespacing is useful if you're going to be sharing a single Keeper instance between many applications or components, as it prevents name collisions.

Namespaces can be chained:
```js
const ns1 = vault.namespace('a')
const ns2 = ns1.namespace('b')
const scroll1 = ns1.get({ name: 'main' }) // These will load different Scrolls
const scroll2 = ns2.get({ name: 'main' })
```

#### `const vaultB = vaultA.session(opts)`
Create a new Keeper that shares resources with the original, like cache, scrolls, replication streams, and storage, while optionally resetting the namespace, overriding `primaryKey`.
Useful when an application wants to accept an optional Keeper, but needs to maintain a predictable key derivation.

`opts` are the same as the constructor options: 

```js
{
  primaryKey, // Overrides the primaryKey for this session
  namespace, // If set to null it will reset to the DEFAULT_NAMESPACE
  detach: true // By disabling this, closing the session will also close the vault that created the session
}
```

#### `await vault.close()`
Fully close this Keeper instance.

#### `vault.on('scroll-open', scroll)`
Emitted when the first session for a scroll is opened.

*Note: This scroll may close at any time, so treat it as a weak reference*

#### `vault.on('scroll-close', scroll)`
Emitted when the last session for a scroll is closed.

### License
MIT