cubesat-db

A small connector for big things.

CubeSatDB uses PouchDB and the ipfs-log module from OrbitDB to store, index, and replicate documents between peers over IPFS and CouchDB.

Install

Install CubeSatDB using npm:

$ npm install -S cubesat-db

Usage

CubeSatDB is just a database: you can add, update, remove, and query records:

const CubeSatDB = require('cubesat-db')
 
let cube = new CubeSatDB('hello-world')
 
cube.all().then(function (result) {
    // Print all of the documents in the db
    console.log(result)
    // Add a document to the database
    return cube.post({ status: 'ok', date: Date.now() })
}).then(function () {
    // Add a document with a known ID
    return cube.put({ _id: 'mars-rover', status: 'landing' })
}).then(function (result) {
    // extract the updated document from the response
    let doc = result.payload
    // Remove a document
    return cube.del(doc)
})

But you can also replicate it between computers:

// on one computer:
let cube = new CubeSatDB('hello-world')
/*
... add documents ...
then get the cube's multihash
 */
cube.toMultihash().then(function (hash) {
    // pass this value to your friend
    console.log(hash)
})
 
// on another computer
const hash = '...' // that value from above
let cube = new CubeSatDB({ hash, name: 'hello-world' })
cube.load().then(function () {
    console.log('Cube up to date!')
})

And you can join one CubeSatDB instances with another. It will merge all the entries from the other that it does not already have:

let cube1 = new CubeSatDB('cube-1')
let cube2 = new CubeSatDB('cube-2', { ipfs: cube1.ipfs })
Promise.all([
    cube1.post.bind(cube1, { status: 'ok' })
    cube2.post.bind(cube2, { status: 'fine' })
]).then(function () {
    return cube1.join(cube2)
}).then(function () {
    // cube1 has all the values in cube2
    // but cube2 doesn't have cube1's records
    console.log(cube1.log.values)
    })

If you have any questions, please leave an issue!

API

Table of Contents

• CubeSatDB
  • put
  • post
  • get
  • all
  • del
  • find
  • query
  • join
  • load
  • validate
  • toMultihash
  • hash
  • name
  • pouch
  • log
  • ipfs
  • Error

CubeSatDB

Parameters

• name String A name, URL (of a CouchDB instance), or multihash (of an IPFS log)
• options Object An object of settings and configuration values. (optional, default {})
  • options.ipfs (IPFS | Object) [description]
  • options.pouch Object [description]
  • options._IpfsLog IpfsLog [description]
  • options._IPFS IPFS [description]
  • options._PouchDB PouchDB [description]

put

Add or update a document.

If you pass an array of docs, it will pass each of them to this method and resolve once they all resolve.

Parameters

• doc (Object | Array) The document to save, or an array of such documents.
  • doc._id String The document's ID. Required for .put()

Returns Promise

post

Post a document to the store, creating an ID for it. To add a document with an ID, see .put().

If you pass an array of docs, it will pass each of them to this method and resolve once they all resolve.

Parameters

• doc (Object | Array) The document to save, or an array of such documents.

Returns Promise

get

Retrieve a document. Wrapper around PouchDB#get()

Returns Promise<Object> A promise that resolves to the specified document.

all

Retrieve all documents. Wrapper around PouchDB#allDocs

Parameters

• options Object (optional, default {})

Returns Promise<Array<Object>> Resolves to an array of retrieved documents.

del

Delete a document using its ID and revision value.

Parameters

• doc Object The document to delete.
  • doc._id String The document's ID. Required.
  • doc._rev String The document's revision value. Required.

Returns Promise

find

Wrapper around PouchDB#find that returns each selected document.

Returns Promise<Array<Object>> Selected documents.

query

Alias to PouchDB#query().

Returns Promise<Object> Query result.

join

Merges another CubeSatDB or IpfsLog into this one.

Parameters

• log (IpfsLog | CubeSatDB) An instance of IpfsLog or CubeSatDB.

Returns Promise [description]

load

Loads the oplog from the store's IPFS hash.

Errors out if the store wasnt constructed with a hash or hasn't established one yet using .toMultihash().

Returns Promise A promise that resolves once the store has loaded.

validate

A document validator. It makes sure a document is an object but not an array.

Subclasses can extend this method to enforce a schema.

Parameters

• doc Object A document.

• Throws CubeError An error about the document.

toMultihash

Returns Promise<String> The multihash for this store. Use this value to clone the store.

hash

• Throws CubeError If CubeSatDB#toMultihash() has not been called yet.

Returns String The multihash for the store.

name

Returns String The name of this database.

pouch

Returns PouchDB The CubeSatDB instance's instance of PouchDB.

log

Returns IpfsLog The CubeSatDB instance's instance of IpfsLog.

ipfs

Returns IPFS The CubeSatDB instance's instance of an IPFS node.

Error

A subclass of Error for describing cube-related problems.

Returns CubeError

Development

Get the source with git:

git clone https://github.com/garbados/cubesat-db
cd cubesat-db
npm i
npm test

Contributions

All contributions are welcome: bug reports, feature requests, "why doesn't this work" questions, patches for fixes and features, etc. For all of the above, file an issue or submit a pull request.

License

Apache-2.0