pouchdb-wrappers

    5.0.0 • Public • Published

    PouchDB-Wrappers

    CI NPM Version JS Standard Style

    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')
    
    // wrap static methods
    wrapper.install(PouchDB, {
      // wrap the sync method so that we can time synchronization
      sync: async function (original, ...args) {
        console.time('sync')
        const result = await original(...args)
        console.timeEnd('sync')
        return result
      }
    })
    
    // or wrap instance methods
    const db = new PouchDB('your_cool_project')
    wrapper.install(db, {
      bulkDocs: async function (original, docs, ...args) {
        // handler methods receive unmodified parameters
        docs = docs.docs || docs
        for (const doc of docs) {
          // assign a timestamp to documents when added to the database
          if (doc._deleted || doc.createdAt) { continue }
          doc.createdAt = Date.now()
        }
        // then pass the modified params to the original
        return original(docs, ...args)
      }
    })
    
    // you can even wrap methods multiple times!
    // the latest handler is run first, then the second-latest, and so on
    wrapper.install(db, {
      bulkDocs: async function (original, docs, ...args) {
        docs = docs.docs || docs
        for (const doc of docs) {
          if (doc._deleted) { continue }
          // assign an update timestamp if it already has a creation timestamp
          if (doc.createdAt) { doc.updatedAt = Date.now() }
        }
        return original(docs, ...args)
      }
    })
    
    // you can also uninstall methods by signature
    const handlers = { get: (original, ...args) => { return original(...args) } }
    wrapper.install(db, handlers)    // wrap a method
    wrapper.uninstall(db, handlers)  // remove a handler using its function

    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:

    // a custom constructor method
    PouchDB.new = function (...args) {
      return new PouchDB(...args)
    }
    // now let's wrap the custom method
    wrapper.install(PouchDB, {
      new: function (original, ...args) { /* wrap the 'new' method */ }
    })

    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) => {
      // doc.modified === true
    })

    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.

    Install

    npm i pouchdb-wrappers

    DownloadsWeekly Downloads

    4,739

    Version

    5.0.0

    License

    Apache-2.0

    Unpacked Size

    9.59 kB

    Total Files

    3

    Last publish

    Collaborators

    • jan
    • daleharvey
    • garethbowen
    • garrensmith
    • nolanlawson
    • commandoline
    • jcoglan
    • gr2m
    • willholley