README.md

pouchdb-hoodie-api

Hoodie-like API for PouchDB

This plugin provides simple methods to add, find, update and remove data.

Usage

Initialisation

var db = new PouchDB('dbname')
var api = db.hoodieApi()

API

// Options
// emitter: Optionally pass an instance of EventEmitter for hoodieApi to use

var db = new PouchDB('dbname')
var api = db.hoodieApi({
  emitter: existingEventEmitter
})

// all methods return promises
api.add(object)
api.add([object1, id2])
api.find(id)
api.find(object) // with id property
api.find([object1, id2])
api.findOrAdd(id, object)
api.findOrAdd(object)
api.findOrAdd([object1, object2])
api.findAll()
api.findAll(filterFunction)
api.update(id, changedProperties)
api.update(id, updateFunction)
api.update(object)
api.update([object1, object2])
api.updateOrAdd(id, object)
api.updateOrAdd(object)
api.updateOrAdd([object1, object2])
api.updateAll(changedProperties)
api.updateAll(updateFunction)
api.remove(id)
api.remove(object)
api.remove([object1, id2])
api.removeAll()
api.removeAll(filterFunction)
api.clear()

// events
// Important: the order of when the methods promises resolve and the events get
//            triggered cannot be guaranteed as we rely on PouchDB’s .changes().
//            We would love to enforce promises to resolve after changes get
//            emitted, but the required complexity to do that is not worth it.
api.on('add', function(object, options) {})
api.on('update', function(object, options) {})
api.on('remove', function(object, options) {})
api.on('change', function(eventName, object, options) {})
api.on('clear', function() {})
api.one(eventName, eventHandlerFunction)
api.off(eventName, eventHandlerFunction)

// returns an API with all methods above, but implicitly scoped to the passed
// id prefix. Meaning events are only triggered for documents that match the id
// prefix, and documents are not found unless they have the id prefix.
// See https://github.com/hoodiehq/discussion/issues/106 for more context.
var todoStore = api.withIdPrefix('todo/')
todoStore.on('change', renderTodoList)
todoStore.add({text: 'Remember the milk!'})

// original PouchDB (http://pouchdb.com/api.html) instance used for the store
api.db

Full API documentation is available at: http://hoodiehq.github.io/pouchdb-hoodie-api/

Installation

Install via npm

npm install pouchdb
npm install pouchdb-hoodie-api

Including the plugin

With browserify or on node.js

Attach this plugin to the PouchDB object:

var PouchDB = require('pouchdb')
PouchDB.plugin(require('pouchdb-hoodie-api'))

In the browser

Include this plugin after pouchdb.js in your HTML page:

<script src="node_modules/pouchdb/dist/pouchdb.js"></script>
<script src="node_modules/pouchdb-hoodie-api/dist/pouchdb-hoodie-api.js"></script>

Testing

In Node.js

Run all tests and validates JavaScript Code Style using standard

npm test

To run only the tests

npm run test:node

In the browser

test:browser:local

This will start a local server. All tests and coverage will be run at http://localhost:8080/__zuul

Contributing

Have a look at the Hoodie project's contribution guidelines. If you want to hang out you can join #hoodie-pouch on our Hoodie Community Slack.

License

Apache 2.0