PouchDB-Wrappers
A library used to wrap PouchDB functions easily.
Multiple handlers can be attached to methods,
so that multiple plugins can safely wrap the same methods.
As an example:
const PouchDB = require('pouchdb')
const wrapper = require('pouchdb-wrappers')
wrapper.install(PouchDB, {
sync: async function (original, ...args) {
console.time('sync')
const result = await original(...args)
console.timeEnd('sync')
return result
}
})
const db = new PouchDB('your_cool_project')
wrapper.install(db, {
bulkDocs: async function (original, docs, ...args) {
docs = docs.docs || docs
for (const doc of docs) {
if (doc._deleted || doc.createdAt) { continue }
doc.createdAt = Date.now()
}
return original(docs, ...args)
}
})
wrapper.install(db, {
bulkDocs: async function (original, docs, ...args) {
docs = docs.docs || docs
for (const doc of docs) {
if (doc._deleted) { continue }
if (doc.createdAt) { doc.updatedAt = Date.now() }
}
return original(docs, ...args)
}
})
const handlers = { get: (original, ...args) => { return original(...args) } }
wrapper.install(db, handlers)
wrapper.uninstall(db, handlers)
Installation
The wrapper can be installed using npm:
$ npm install pouchdb-wrappers
Usage
wrapper.install(base, handlers)
Install wrapper methods on the base
object. Only methods that already exist
can be wrapped.
base
: The object to modify. May be either the PouchDB class or an instance of it.handlers
: An object whose keys are the methods to wrap, and whose values are
the functions to wrap the original in.
The function signature of wrapper methods is original, ...args
,
where original
is the underlying method,
and ...args
is the list of arguments passed in.
As methods may be wrapped multiple times, original
may refer to another handler.
Handlers are run from first-added to last-added, so that the first methods
installed are run first. The original method is run very last.
Attempting to wrap methods that do not exist will throw an error. Thus, to wrap
a custom method, you must first create that custom method. For example:
PouchDB.new = function (...args) {
return new PouchDB(...args)
}
wrapper.install(PouchDB, {
new: function (original, ...args) { }
})
PouchDB supports using callbacks with its API methods, but callbacks will not
be passed to your wrapper methods. Wrappers which wrap asynchronous methods
should return a Promise
and they should assume that the original
function
returns a Promise
. pouchdb-wrappers
takes care of making callbacks work for
external callers. For example, if you install a get()
wrapper...
wrapper.install(db, {
get: async function (original, ...args) {
let doc = await original(...args)
doc.modified = true
return doc
}
})
... then the application can still call db.get()
with a callback. The callback
will not be included in the wrapper's args
parameter and the wrapper doesn't
need to include any logic to make callbacks work.
db.get('mydoc', { revs: true }, (error, doc) => {
})
wrapper.uninstall(base, handlers)
Uninstall wrapper methods on the base
object. Attempting to uninstall handlers
that do not exist will throw an error.
base
: The object to modify. May be either the PouchDB class or an instance.handlers
: An object whose keys are the methods to wrap, and whose values are
the functions to wrap the original in.
Development
If you encounter bugs or want to request features, please file an issue!
To hack on this project locally, first get the source and install dependencies:
$ git clone git@github.com:pouchdb/pouchdb-wrappers.git
$ cd pouchdb-wrappers
$ npm install
Then you can run the test suite:
$ npm test
When contributing patches, be a good neighbor and include tests!
License
Apache License 2.0.