# kappa-drive

> a multiwriter peer to peer filesystem

Latest version **3.1.1** (published 2022-04-06) · AGPL-3.0-only license · 0 weekly downloads

## Install

```sh
npm install kappa-drive
pnpm add kappa-drive
yarn add kappa-drive
bun add kappa-drive
```

Provides the command `kappa-drive`.

## Health

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

Positive: no vulnerabilities.

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

Negative: insecure dependencies; abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.1.1 |
| Published | 2022-04-06 |
| First published | 2019-08-06 |
| Weekly downloads | 0 |
| License | AGPL-3.0-only |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 33 |
| Unpacked size | 2.2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Karissa McKelvey |
| Maintainers | kyphae, ameba23 |
| Keywords | kappa, peer-fs, kappa-drive, hyperdrive, dat, kappa-core, multiwriter |

## Links

- npm: https://www.npmjs.com/package/kappa-drive
- Repository: https://gitlab.com/coboxcoop/kappa-drive
- Homepage: https://gitlab.com/coboxcoop/kappa-drive#readme
- Issues: https://gitlab.com/coboxcoop/kappa-drive/issues
- npm.io page: https://npm.io/package/kappa-drive

## Dependencies (33)

- [pump](https://npm.io/package/pump.md) ^3.0.0
- [chalk](https://npm.io/package/chalk.md) ^4.0.0
- [level](https://npm.io/package/level.md) ^5.0.1
- [assert](https://npm.io/package/assert.md) ^2.0.0
- [unixify](https://npm.io/package/unixify.md) ^1.0.0
- [minimist](https://npm.io/package/minimist.md) ^1.2.0
- [through2](https://npm.io/package/through2.md) ^3.0.1
- [corestore](https://npm.io/package/corestore.md) ^5.8.2
- [hypertrie](https://npm.io/package/hypertrie.md) ^5.1.0
- [level-mem](https://npm.io/package/level-mem.md) ^5.0.1
- [hyperdrive](https://npm.io/package/hyperdrive.md) git+https://gitlab.com/coboxcoop/hyperdrive.git#allow-content-options
- [hyperswarm](https://npm.io/package/hyperswarm.md) ^2.5.0
- [kappa-core](https://npm.io/package/kappa-core.md) github:Frando/kappa-core#exp-0.2.3
- [dat-encoding](https://npm.io/package/dat-encoding.md) ^5.0.1
- [nanoresource](https://npm.io/package/nanoresource.md) ^1.3.0
- [run-parallel](https://npm.io/package/run-parallel.md) ^1.1.9
- [subleveldown](https://npm.io/package/subleveldown.md) ^4.1.4
- [call-me-maybe](https://npm.io/package/call-me-maybe.md) ^1.0.1
- [contains-path](https://npm.io/package/contains-path.md) ^1.0.0
- [kappa-view-kv](https://npm.io/package/kappa-view-kv.md) github:coboxcoop/kappa-view-kv
- [unique-stream](https://npm.io/package/unique-stream.md) ^2.3.1
- [collect-stream](https://npm.io/package/collect-stream.md) ^1.2.1
- [crypto-encoder](https://npm.io/package/crypto-encoder.md) git+https://gitlab.com/coboxcoop/crypto-encoder.git
- [hypercore-crypto](https://npm.io/package/hypercore-crypto.md) ^1.0.0
- [kappa-drive-mount](https://npm.io/package/kappa-drive-mount.md) git+https://gitlab.com/coboxcoop/kappa-drive-mount.git
- [hyperdrive-schemas](https://npm.io/package/hyperdrive-schemas.md) ^1.11.0
- [mountable-hypertrie](https://npm.io/package/mountable-hypertrie.md) ^2.6.0
- [@coboxcoop/multifeed](https://npm.io/package/@coboxcoop/multifeed.md) ^0.0.2
- [@corestore/networker](https://npm.io/package/@corestore/networker.md) ^1.1.0
- [kappa-sparse-indexer](https://npm.io/package/kappa-sparse-indexer.md) 0.6.0
- [random-access-memory](https://npm.io/package/random-access-memory.md) ^3.1.1
- [hypercore-default-storage](https://npm.io/package/hypercore-default-storage.md) ^1.1.0
- [protocol-buffers-encodings](https://npm.io/package/protocol-buffers-encodings.md) ^1.1.0

## Alternatives

- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads
- [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads
- [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads
- [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads

## Recent versions

- 3.1.1 (latest) — 2022-04-06
- 2.0.0-alpha1 (alpha) — 2020-01-20
- 3.1.0 — 2022-04-04
- 3.0.5 — 2021-06-18
- 3.0.3 — 2021-06-07
- 3.0.2 — 2021-06-07
- 3.0.0 — 2020-07-29
- 2.1.1-alpha1 — 2020-02-11
- 2.1.0-alpha1 — 2020-02-11
- 2.0.3-alpha1 — 2020-01-23
- 2.0.2-alpha1 — 2020-01-22
- 2.0.1-alpha1 — 2020-01-21
- 1.2.0 — 2019-12-11
- 1.1.0 — 2019-11-15
- 1.0.0 — 2019-09-16
- … 1 more at https://npm.io/package/kappa-drive/versions

## README

# kappa-drive

A multiwriter peer-to-peer filesystem built on [`kappa-core`](https://github.com/kappa-db/kappa-core).

Supports [Hyperdrive V10](https://github.com/mafintosh/hyperdrive/). Originally known as 'peerfs'.

Designed to be compatible with [`hyperdrive-fuse`](https://github.com/andrewosh/hyperdrive-fuse/)

## Installation

To use the CLI...

```
npm install -g kappa-drive

kappa-drive --help
```

or as an npm package

```
# with optional dependencies includes FUSE and hyperswarm for the CLI script to work
npm install

# or without the fluff, just a raw kappa-drive
npm install --no-optional
```

## Usage

```js
const KappaDrive = require('.')
var aliceDrive = KappaDrive('./alice-drive')
var bobDrive = KappaDrive('./bob-drive')

aliceDrive.ready(() => {
  aliceDrive.writeFile('/hello.txt', 'world', (err) => {
    if (err) throw err
    bobDrive.ready(() => {
      replicate(bobOverwrite)
    })
  })
})

function bobOverwrite () {
  bobDrive.writeFile('/hello.txt', 'mundo', (err) => {
    if (err) throw err
    check()
  })
}

function replicate (cb) {
  var aliceStream = aliceDrive.replicate(true, { live: false })
  aliceStream.pipe(bobDrive.replicate(false, { live: false })).pipe(aliceStream)
  aliceStream.on('end', cb)
}

function check () {
  replicate(() => {
    aliceDrive.readFile('/hello.txt', 'utf-8', (err, data) => {
      if (err) throw err
      console.log(data) // mundo
    })
  })
}
```

See [test/index.test.js](test/index.test.js) for more examples.

## API

#### ```var drive = KappaDrive(storage, key, options)```

Returns a kappa-drive instance instance. `options` are passed directly to an instance of [KappaCore](kappa-db/kappa-core).

In addition, peer-fs accepts the following optional arguments:

* `resolveFork`: a function taking `values` of known versions of that file. If there are more than one here, there is a fork. By default, this returns the first item in the list. Overwrite this to get more fancy. 

#### ```drive.key```

The public key identifying the drive

#### ```drive.discoveryKey```

The discovery key identifying the drive

#### ```drive.ready(callback)```

Callback is called when the drive is ready and properties are populated.

#### ```drive.replicate(isInitiator, options)```

* `isInitiator` - should be true if you are initiating the replication.
Replicate between two `peer-fs` instances. Behaves similar to `kappacore.replicate`

#### ```drive.readFile(filename, options, callback)```

Read a file asyncronously. Behaves similar to `hyperdrive.readFile` or `fs.readFile`

#### ```drive.writeFile(filename, content, callback)```

Write a file asyncronously. Behaves similar to `hyperdrive.writeFile` or `fs.writeFile`

#### ```drive.createWriteStream(filename, callback)```

Write a stream to a file. Behaves similar to `hyperdrive.createWriteStream` or `fs.createWriteStream`

#### ```drive.createReadStream(filename, [options])```

Read file from a stream. Behaves similar to `hyperdrive.createReadStream` or `fs.creadReadStream`

#### ```drive.exists(filename, callback)```

Check a file exists.

#### ```drive.truncate(filename, size, callback)```

Truncate a file to `size`. Behaves similar to `hyperdrive.truncate` or 

#### ```drive.readdir(name, [options], callback)```

List all files within a specified directory path. Behaves similar to `hyperdrive.readdir` or `fs.readdir`

#### ```drive.stat(filename, opts, callback)```

Callback with an object containing information about a file. Behaves similar to `hyperdrive.stat` or `fs.stat`

#### ```drive.lsstat(filename, opts, callback)```

Callback with an object containing information about a file (without following symbolic links). Behaves similar to `hyperdrive.lstat` or `fs.lstat`

#### ```drive.unlink(target, callback)```

Delete a file.  Behaves similar to `hyperdrive.unlink` or `fs.unlink` 

#### ```drive.mkdir(directory, callback)```

Create a directory in the archive. Behaves similar to `hyperdrive.mkdir` or `fs.mkdir`

#### ```drive.rmdir(directory, callback)```

Remove a directory from the archive. Behaves similar to `hyperdrive.rmdir` or `fs.mkdir`

#### ```drive.open(filename, flags, callback)```

Open a file and get a file descriptor in the callback. Behaves similar to `hyperdrive.open` or `fs.open`.  Currently only limited support for random access writes.

#### ```drive.close(fd, callback)```

Close a file referred to by a given file descriptor. Behaves similar to `hyperdrive.close` or `fs.close`.  Note that any writes made to the file will only be applied when the file is closed.

#### ```drive.read(fd, buffer, offset, length, position, callback)```

Read from a file descriptor into a buffer. Behaves similar to `hyperdrive.read` or `fs.read`.

#### ```drive.write(fd, buffer, offset, length, position, callback)```

Write from a buffer to a file descriptor.  Positional writes are not currently supported, only overwrite or append. Behaves similar to `hyperdrive.write` or `fs.write`


#### ```drive.symlink(target, linkname, callback)``` 

Create a symbolic link from `linkname` to `target`. Behaves similar to `hyperdrive.symlink` or `fs.symlink`.

#### ```drive.create(filename, [mode], callback)```

Create a file (used when opening a new file in write mode with fuse). Behaves similar to `hyperdrive.create`

## Bugs / issues

Please add issues here: https://gitlab.com/coboxcoop/kappa-drive/issues

## License

AGPL-3.0.0-or-later

## Credit & Thanks

Huge credit to [Karissa](https://github.com/karissa) for ideating and writing [peerfs](https://github.com/karissa/peerfs) and allowing us to continue the project and complete the API.

Thanks to [Frando](https://github.com/frando) for helping with the recent upgrade to [kappa-core](https://github.com/frando/kappa-core) and [kappa-sparse-indexer](https://github.com/frando/kappa-sparse-indexer).

:purple_heart: :green_heart:

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