3.2.1 • Public • Published


    Abstract CouchDB worker module

    Deprication Note

    This is depricated in favour of couch-daemon

    Getting Started

    Install the module with: npm install couchdb-worker

    var config = {
      id: 'my-worker',
      db: 'http://localhost:5984/mydb',
      process: function(doc, db, done) {
        doc.computed_value = Math.random();
        db.insert(doc, done);


    The object returned by worker.listen() is a Feed object, which is an EventEmitter. See follow for documentation.


    • id | Unique identifier for the worker.
    • process | Processor function. Receives doc and done arguments.
    • db | nano options
    • follow | follow options
    • status | status options (optional). Default is false.
    • status.db | nano options for status database connection. Default is to use the db connection.
    • | id for status document. Default is worker-status/<id>.
    • lock | lock options (optional). Default is false.
    • lock.db | nano options for lock database connection. Default is to use the status.db connection.
    • lock.prefix | prefix for lock document ids. Default is worker-lock/<id>/.

    process(doc, done)

    This is where you do your work. It receives a doc, which is the current document, as well as a done callback function, which must be invoked when the work is done.

    The done callback accepts itself an error argument, where you can inform couchdb-worker about any errors.


    couchdb-worker can maintain a status document, where some stats are stored:

      "_id": "worker-status/my-worker",
      "worker_id": "my-worker",
      "seq": 123,
      "last_doc_id": "mydoc",
      "checked": 42,
      "triggered": 42,
      "completed": 40,
      "failed": 2

    Its disabled by default as of 3.2.0. To enable, set status: true.


    To prevent two same workers from processing the same document twice, couchdb-worker can keep a lock on the document.

    This is achieved by putting an empty doc inside the lock.db while processing. It will be deleted when done.

    The id of that lock document is calculated by appending the documents id to lock.prefix.

    Its disabled by default as of 3.2.0. To enable locking, set lock: true.


    var worker = require('couchdb-worker')({
      id: 'my-worker',
      db: {
        url: 'http://localhost:5984/mydb',
        request_defaults: {
          auth: {
            user: 'me',
            pass: 'secret'
      status: {
        db: {
          url: 'http://localhost:5984/worker-stats',
          request_defaults: {
            auth: {
              user: 'me',
              pass: 'secret'
      follow: {
        since: 42,
        heartbeat: 1000,
        filter: 'myddoc/myfilter',
        query_params: {
          worker: 'my-worker',
          app: '1234'
      process: function(doc, db, done) {
        doc.computed_value = Math.random();
        db.insert(doc, done);
    // listen to some events
    worker.on('error', function(err) {
      console.error('Since Follow always retries on errors, this must be serious');
    worker.on('worker:complete', function(doc) {
      console.log('worker completed: ', doc);
    worker.on('worker:error', function(err, doc) {
      console.log('worker error: ', err, doc);
    // start work
    // you can pause the worker
    // and resume...
    // and finally stop it.


    To run the tests, run npm test.

    The tests run agains a CouchDB server, and they create random databases of the form couchdb-worker-test-<uuid>. The default url is http://localhost:5984, which can be changed by setting the COUCH_URL environment variable, eg:

    COUCH_URL= npm test


    In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint your code using npm run jshint.


    couchdb-worker follows semver-ftw. Dont think 1.0.0 means production ready yet. There were some breaking changes, so had to move up the major version.

    Release History

    • 3.2.0: configurable status and lock behaviour
    • 3.1.1: fix issue with db objects
    • 3.1.0: process function receives db object
    • 3.0.0: return function (worker.listen(config) -> worker(config).listen())
    • 2.0.0: do not store worker status in documents, store lock in extra documents
    • 1.0.0: complete rewrite and new (functional) API using nano (and follow) - currently no attachment support
    • 0.x: object oriented version with attachment support - The 0.x line continues on the v0 branch


    Copyright (c) 2012-2013 Johannes J. Schmidt, null2 GmbH

    Licensed under the MIT license.


    npm i couchdb-worker

    DownloadsWeekly Downloads






    Last publish


    • jo