OrbitPouchStore

An OrbitDB store that uses PouchDB for indexing, allowing you to perform flexible mango queries. It extends orbit-db-docstore.

Why?

OrbitDB is a distributed database that stores records as IPFS blocks so that they can be 1) de-duplicated 2) replicated with peers. You can get and share OrbitDB stores by sharing their address, and you can create subsets of your data that peer from users that have the same blocks, even if those blocks aren't part of the same subset or even of the same originating data.

However, OrbitDB's default stores provide only rudimentary indexing, limiting the queries you can make of your data. So, I created a store that used PouchDB for indexing.

OrbitPouchStore is an OrbitDB store that uses a PouchDB instance to index its oplog. That allows you to perform mango queries and map/reduce queries, among other neat things.

I hope you find it useful!

Install

Install using npm:

npm i -S orbit-pouch-store

Now you can use it with OrbitDB:

// 1. add pouch as a store type
const OrbitPouchStore = require('orbit-pouch-store')
OrbitDB.addType('pouch', OrbitPouchStore)

// 2. once you have an orbitdb instance, create the store
const pouch = await orbitdb.create('my-app', 'pouch', options)

// 3. do the thing!
let result = await pouch.put({ greetings: 'hello world' })
let doc = await pouch.get(result.id)
console.log(doc.greetings)
> hello world

Usage

Table of Contents

• OrbitPouchStore
  • all
  • find
  • query
  • get
  • del
  • stop
  • db
  • Index
  • type
• PouchIndex
  • get
  • find
  • query
  • db

OrbitPouchStore

Extends OrbitDocStore

OrbitPouchStore - an OrbitDB store indexed by PouchDB

Generally, you will not instantiate this class directly unless you are extending it. Instead, you'll probably use it like this:

// when your app starts:
OrbitDB.addType(OrbitPouchStore.type, OrbitPouchStore)
// then, once you have an orbitdb instance:
let pouch = orbitdb.create(dbName, 'pouch')

Parameters

• ipfs IPFS An instance of an IPFS node.
• id String Name of the store, ex: 'blog' or 'test'
• address Object Address for the store's IPFS feed. Optional.
• options Object Options object passed through to OrbitDocStore. (optional, default {})

all

Retrieves all documents in the database.

await store.all()
// [{ _id: '...', _rev: '...', ...}, ...]

Returns Array

find

Perform a mango query.

Parameters

• query Object Same as the first parameter for PouchDB#find

Returns Array An array of the documents that matched the query.

query

Performs a map/reduce query.

Parameters

• query Object Same as the first parameter for PouchDB#query
• options Object [{}] Same as the second parameter for PouchDB#query (optional, default {})

Returns Array

get

Retrieve a document by ID. Without an ID, defaults to retrieving all documents.

Get a single doc:

await store.get(id)
> { _id: '...', _rev: '...', name: 'Mario' }

Get all docs:

await store.get()
> [{ _id: '...', _rev: '...', name: 'Mario' }, ...]

Parameters

• id String The ID of the document to retrieve.

Returns (Object | Array)

del

Deletes the document with the given ID.

await store.del(id)
> { ok: true }

Parameters

• id String The '_id' value of the document to delete.

stop

Stop the store and close its resources.

store.stop().then(() => {
  // store has been closed
})

db

Getter for the PouchDB instance used by the index.

store.db

Returns PouchDB

Index

Static getter that returns the class of index used by this store.

OrbitPouchStore.Index

Returns PouchIndex

type

Returns the canonical name of this store, 'pouch'. Useful if you'd rather not type in a raw string.

OrbitPouchStore.type

Returns String

PouchIndex

[PouchIndex description]

Parameters

• id String [description]
• options Object [description] (optional, default {})

get

Retrieve a document by ID. Without an ID, defaults to retrieving all documents.

Parameters

• id String The ID of the document to retrieve.

Returns (Object | Array)

find

Perform a mango query.

Parameters

• query Object Same as the first parameter for PouchDB#find

Returns Array An array of the documents that matched the query.

query

Performs a map/reduce query.

Parameters

• query Object Same as the first parameter for PouchDB#query
• options Object [{}] Same as the second parameter for PouchDB#query (optional, default {})

Returns Array

db

Getter for the index's PouchDB instance.

Returns PouchDB

Contributing

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

License

Apache-2.0