combox

ComBox

A PouchDB plugin that mirrors the database with a Dat archive using Beaker's DatArchive API. As a result, you can use ComBox in the browser with Beaker! To use it in NodeJS, you'll need node-dat-archive.

Install

You can get ComBox with npm:

$ npm i combox

Once installed, you can require() it in your projects:

const PouchDB = require('PouchDB')
const ComBox = require('combox')
PouchDB.plugin(ComBox)

const db = new PouchDB('combox')
await db.setupDatArchive()

Once the archive has been set up, its contents will be automatically mirrored to PouchDB.

If you cannot write to the attached archive, any calls to destructive methods like .bulkDocs will fail. Read-only methods like .get() and .query() will continue to operate normally.

Usage

ComBox

The ComBox plugin adds and modifies some methods. They are documented here:

async .setupDatArchive([options])

Creates, loads, or simply attaches an archive to the database, and initializes the mirroring process.

Parameters:

• options: Options object.
• options.archive: A specific archive to mirror. Must have been created using DatArchive.
• options.DatArchive: A DatArchive constructor. Use this parameter with node-dat-archive if you are writing a server-side application.
• options.options: Options for DatArchive when it constructs the archive. Only useful when the constructor from node-dat-archive is used, as Beaker's does not take options.
• options.url: A Dat URL to follow. Following an archive you cannot write to will block destructive methods like .bulkDocs().

async .bulkDocs(docs, [options], [callback])

ComBox wraps PouchDB#bulkDocs to mirror writes, including deletes, to the archive. Because of how PouchDB performs writes internally, wrapping this method causes other methods like .put, .post, and .remove to also affect the archive.

The parameters are unchanged from the original.

async .destroy([options], [callback])

Wraps PouchDB#destroy to also stop sharing the associated archive and destroy any associated files.

The parameters are unchanged from the original.

Development

To hack on ComBox, check out the issues page. To submit a patch, submit a pull request.

To run the test suite, use npm test in the source directory:

$ git clone garbados/combox
$ cd combox
$ npm i
$ npm test

A formal code of conduct is forthcoming. Pending it, contributions will be moderated at the maintainers' discretion.

License

Apache-2.0