# @frando/corestore-multifeed

> multi-writer hypercore

Latest version **0.0.1** (published 2020-06-29) · ISC license · 0 weekly downloads

## Install

```sh
npm install @frando/corestore-multifeed
pnpm add @frando/corestore-multifeed
yarn add @frando/corestore-multifeed
bun add @frando/corestore-multifeed
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.1 |
| Published | 2020-06-29 |
| First published | 2020-06-29 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 15 |
| Unpacked size | 145.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Stephen Whitmore |
| Maintainers | frando |

## Links

- npm: https://www.npmjs.com/package/@frando/corestore-multifeed
- Repository: https://github.com/noffle/multifeed
- Issues: https://github.com/noffle/multifeed/issues
- npm.io page: https://npm.io/package/@frando/corestore-multifeed

## Dependencies (15)

- [once](https://npm.io/package/once.md) ^1.4.0
- [debug](https://npm.io/package/debug.md) ^4.1.0
- [inherits](https://npm.io/package/inherits.md) ^2.0.3
- [mutexify](https://npm.io/package/mutexify.md) ^1.2.0
- [through2](https://npm.io/package/through2.md) ^3.0.0
- [corestore](https://npm.io/package/corestore.md) ^5.5.0
- [hypercore](https://npm.io/package/hypercore.md) ^9.2.2
- [nanoresource](https://npm.io/package/nanoresource.md) ^1.3.0
- [hypercore-crypto](https://npm.io/package/hypercore-crypto.md) ^2.0.0
- [stream-collector](https://npm.io/package/stream-collector.md) ^1.0.1
- [abstract-extension](https://npm.io/package/abstract-extension.md) ^3.1.0
- [hypercore-protocol](https://npm.io/package/hypercore-protocol.md) ^8
- [random-access-file](https://npm.io/package/random-access-file.md) ^2.0.1
- [random-access-memory](https://npm.io/package/random-access-memory.md) ^3.1.1
- [corestore-swarm-networking](https://npm.io/package/corestore-swarm-networking.md) ^5.5.1

## Recent versions

- 0.0.1 (latest) — 2020-06-29

## README

# @frando/corestore-multifeed

Run the [https://github.com/kappa-db/multifeed](multifeed) model of managing hypercores on top of [corestore](https://github.com/andrewosh/corestore) and [corestore-swarm-networking](https://github.com/andrewosh/corestore-swarm-networking).

No docs yet - see [test/new-basic.js](test/new-basic.js) for an example.

The main export (`new Multifeed(storage, opts)`) is API compatible to the current multifeed as documented below. `storage` can also be a corestore (otherwise one is created with `storage`). Then connect it to a corestore swarm networker to apply multifeed replication.

```javascript
const corestore = new Corestore(ram)
const networker = new CorstoreSwarmNetworker(corestore)
const multifeedNetworker = new MultifeedNetworker(networker)

const key = hcrypto.keyPair().publicKey
const multi1 = new Multifeed(corestore, { key })
multfeedNetworker.swarm(multi1)

// use as multifeed as documented below
// you can add as many multifeeds as you want to a single networker instance
```

---

> multi-writer hypercore

Multifeed lets you:

1. manage many hypercores, stored together
2. replicate a local set of hypercores with a remote set of hypercores (union-syle)

It solves the problem of [hypercore](https://github.com/mafintosh/hypercore)
only allowing one writer by making it easy to manage and sync a set of
hypercores -- by a variety of authors -- across peers.

Replication works by extending the regular hypercore exchange mechanism to
include a meta-exchange, where peers share information about the feeds they
have locally, and choose which of the remote feeds they'd like to download in
exchange. Right now, the replication mechanism defaults to sharing all local
feeds and downloading all remote feeds.

## Usage

```js
var multifeed = require('multifeed')
var ram = require('random-access-memory')

var multi = multifeed('./db', { valueEncoding: 'json' })

// a multifeed starts off empty
console.log(multi.feeds().length)             // => 0

// create as many writeable feeds as you want; returns hypercores
multi.writer('local', function (err, w) {
  console.log(w.key, w.writeable, w.readable)   // => Buffer <0x..> true true
  console.log(multi.feeds().length)             // => 1

  // write data to any writeable feed, just like with hypercore
  w.append('foo', function () {
    var m2 = multifeed(hypercore, ram, { valueEncoding: 'json' })
    m2.writer('local', function (err, w2) {
      w2.append('bar', function () {
        replicate(multi, m2, function () {
          console.log(m2.feeds().length)        // => 2
          m2.feeds()[1].get(0, function (_, data) {
            console.log(data)                   // => foo
          })
          multi.feeds()[1].get(0, function (_, data) {
            console.log(data)                   // => bar
          })
        })
      })
    })
  })
})

function replicate (a, b, cb) {
  var r = a.replicate()
  r.pipe(b.replicate()).pipe(r)
    .once('end', cb)
    .once('error', cb)
}
```

## API

```js
var multifeed = require('multifeed')
```

### var multi = multifeed(storage[, opts])

Pass in a [random-access-storage](https://github.com/random-access-storage/random-access-storage) backend, and options. Included `opts` are passed into new hypercores created, and are the same as [hypercore](https://github.com/mafintosh/hypercore#var-feed--hypercorestorage-key-options)'s.

Valid `opts` include:
- `opts.encryptionKey` (string): optional encryption key to use during replication. If not provided, a default insecure key will be used.
- `opts.hypercore`: constructor of a hypercore implementation. `hypercore@8.x.x` is used from npm if not provided.

### multi.writer([name], [options], cb)

If no `name` is given, a new local writeable feed is created and returned via
`cb`.

If `name` is given and was created in the past on this local machine, it is
returned. Otherwise it is created. This is useful for managing multiple local
feeds, e.g.

```js
var main = multi.writer('main')        // created if doesn't exist
var content = multi.writer('content')  // created if doesn't exist

main === multi.writer('main')          // => true
```

`options` is an optional object which may contain: 
- `options.keypair` - an object with a custom keypair for the new writer.  This should have properties `keypair.publicKey` and `keypair.secretKey`, both of which should be buffers.

### var feeds = multi.feeds()

An array of all hypercores in the multifeed. Check a feed's `key` to
find the one you want, or check its `writable` / `readable` properties.

Only populated once `multi.ready(fn)` is fired.

### var feed = multi.feed(key)

Fetch a feed by its key `key` (a `Buffer` or hex string).

### var stream = multi.replicate(isInitiator, [opts])

Create an encrypted duplex stream for replication.

Ensure that `isInitiator` to `true` to one side, and `false` on the other. This is necessary for setting up the encryption mechanism.

Works just like hypercore, except *all* local hypercores are exchanged between
replication endpoints.

### stream.on('remote-feeds', function () { ... })

Emitted when a new batch (1 or more) of remote feeds have begun to replicate with this multifeed instance.

This is useful for knowing when `multi.feeds()` contains the full set of feeds from the remote side.

### multi.on('feed', function (feed, name) { ... })

Emitted whenever a new feed is added, whether locally or remotely.

## multi.close(cb)

Close all file resources being held by the multifeed instance. `cb` is called once this is complete.

## multi.closed

`true` if `close()` was run successfully, falsey otherwise.

# Errors

The duplex stream returned by `.replicate()` can emit, in addition to regular
stream errors, two fatal errors specific to multifeed:

- `ERR_VERSION_MISMATCH`
  - `err.code = 'ERR_VERSION_MISMATCH'`
  - `err.usVersion = 'X.Y.Z'` (semver)
  - `err.themVersion = 'A.B.C'` (semver)

- `ERR_CLIENT_MISMATCH`
  - `err.code = 'ERR_CLIENT_MISMATCH'`
  - `err.usClient = 'MULTIFEED'`
  - `err.themClient = '???'`

## Install

With [npm](https://npmjs.org/) installed, run

```
$ npm install multifeed
```

## See Also

- [multifeed-index](https://github.com/noffle/multifeed-index)
- [hypercore](https://github.com/mafintosh/hypercore)
- [kappa-core](https://github.com/noffle/kappa-core)

## License

ISC

---
_Source: https://npm.io/package/@frando/corestore-multifeed · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._