pouchy

"Pouchy is the sugar API for PouchDB that I've been hoping someone would write" @nolanlawson

simple, enhanced PouchDB. Pouchy wraps & extends PouchDB and provides various sorely needed sugar methods. further, it assists by standardizing the returned document format. most methods provided are very simple PouchDB-native method modifiers, but are targeted to save you frequent boilerplate re-typing! this library also proxies the PouchDB API directly, so you can use it like a PouchDB instance itself!

install

yarn add pouchy

if you need node support to flush databases to disk, versus using pouchy as an api client to remote couch/pouches, add your preferred adapters too. e.g.:

yarn add pouchy pouchdb-adapter-leveldb

usage

api docs and examples officially live here.

here are some basic examples:

// local, node database
import Pouchy from 'pouchy'
import level from 'pouchdb-adapter-leveldb'
Pouchy.plugin(level)
type Fruit = { type: string, tastes: string }
const fruit = new Pouchy<Fruit>({ name: 'fruit' })
const orange = await fruit.save({ type: 'orange', tastes: 'delicious' })
console.log(orange)

/**
  {
    type: 'orange',
    tastes: 'delicious',
    _id: 'EA1F2B55-2482-89C6-907E-6F938C59F734',
    _rev: '1-f60b9b7d775a89d280e1f4c07122b863'
  }
*/

// local & remote replicated database!
import Pouchy from 'pouchy'
import memory from 'pouchdb-adapter-memory'
Pouchy.plugin(memory)

const customers = new Pouchy({
  name: 'customers',
  replicate: 'sync',
  url: 'http://mydomain.org/db/customers'
})
customers.save({ firstName: 'bill', lastName: 'brasky' })
// wait for it... and couchdb/pouchdb-server @ http://mydomain.org/db/customers
// will receive bill brasky!

why

why use pouchy over pouchdb?

• because managing _id and _rev can be obnoxious with pouchdb (no hard feelings, of course).
  • pouchdb methods return document _ids and _revs inconsistently. some methods return docs with an id attribute. some return docs with _id. the same happens for rev.
  • different methods return _rev nested under other attributes, vs. being at the top of the document.
  • pouchy lets you get your documents back in the same way they are represented in the store. if you are expecting an _id and a _rev in a return result, you'll get those attributes back on the top of your documents, every time.
• because you need some frequently used sugar methods that aren't keys-included from pouchdb. there are many sugar methods available, make sure to check out the API docs!
  • e.g. .all(), to get all full documents in your store, in a simple array.
  • e.g. .clear()/.deleteAll() to purge your store of its docs.
• because you want .find to return simply an array of docs!
  • note: pouchy pre-loads the pouchdb-find plugin, which is super handy and regularly recommended for use.
• because you want to pre-define *ouchdb synchronization behavior on construction! start syncing pronto, declaratively!

Thanks! cdaringe

changelog

• 12.3.+ - switched to semantic-release. please view the "Releases" GitHub tab
• 12.0.0
  • refactor all of the things!
    • better handle all rev/id ==> _rev/_id mapping
    • if rev or id exist on docs returned from pouch exist, but no _rev or _id exist, that particular kv pair will be moved to the _-prefixed key and the non prefixed key will be removed.
  • more tests!
• 11.0.2
  • drop es6 content. es5 friendly-ify!
• 11.0.0
  • pouchdb 6.0.5!
• 10.1.0
  • expose replication options via getReplicationOptions
  • on destroy, actually destroy gracefully. that means, don't resolve the promise/callback until live dbs have all http requests fully settled. see here for more info.
• 10.0.4 - be compatible with latest bluebird .asCallback.
• 10.0.0 - migrate to PouchDB 5.4.x. @NOTE, some APIs are not available by default anymore. See the custom build blog post on how to add features to your pouch Pouchy.PouchDB.plugin(...). The following plugins are available by default:
  • pouchdb-adapter-http
  • pouchdb-find
  • pouchdb-replication
• 9.0.2 - fix bulkGet when no docs are provided
• 9.0.0-1
  • fix .all({ include_docs: false }) to properly handle .rev/._rev
  • improve docs!
• 8.0.5 - fix issues w/ promise/cbs. sorry for 8.0.x-8.0.5 churn!
• 8.0.0 - support cb & promise interface. added bluebird to make this seamless and less verbose
• 7.1.0 - add hasLikelySynced event
• 7.0.0 - modify replicate API. dropped 'both' sync option, added {} option. dropped replicateLive
• 6.3.0 - add destroy, which .cancels any replication from .syncEmitter (see replicate). deprecate 6.2.0-1. changeEmitter => syncEmitter (rapid patch, so no major bump)
• 6.2.1 - add this.syncEmitter when using the replicate API
• 6.1.0 - add bulkGet
• 6.0.6 - fix issue where _id was still id when doing .all({ include_docs: false })
• 6.0.4 - fix replication issue where db backend not honored
• 6.0.0 - db will store locally via leveldown as name if passed. url will still be used for replication if requested. prior versions preferred url to the Pouch constructor over name
• 5.2.1 - permit / in couchdb db name
• 5.2.0 - bump with couch
• 5.1.0 - deps bump & add cb interface
• 5.0.0 - deps bump only. ~~all future releases with track major version #s with PouchDB~~
• 4.0.0 - major bump with PouchDB
• 3.0.0 - remove default changes, and associated on/off. didn't work out-of-the-box anyway. may return in 4.x
• 2.0.1 - Don't modify constructor opts.name
• 2.0.0 - Fix synced db fs location. Previously was not honoring path option
• 1.0.0 - 2.0.1 pouchdb-wrapper => pouchy