Novel Planetary Movement


    7.0.3 • Public • Published

    CouchDB library with a simple, functional-programing-friendly API.

    Forked from Cot, and renamed blue-cot in reference to the Bluebird promises it was returning until v4.0.0 (it returns native promises since).



    npm install blue-cot

    Specificities of this lib

    Especially compared to Cot from which it is forked

    • Class-less, thus a different initialization, but the rest of the API stays the same
    • Consequently, blue-cot is this-free: no need to bind functions contexts!
    • 4xx and 5xx responses will return rejected promises (should be handled with .catch)
    • Adds a few new functions, notably some view functions goodies
    • Uses Cookie Authentication instead of Basic Auth for better performance
    • Uses a single persistent connexion to CouchDB by default


    const bluecot = require('blue-cot')
    const config = {
      // Required
      protocol: 'http',
      hostname: 'localhost',
      port: 5984,
      // Required if the database you are querying requires authentification
      username: 'your-couchdb-username',
      password: 'your-couchdb-password',
      // Optinonal
      // Logs the generated URLs, body, and response time
      debug: true, // default: false
      // The default http agent already sets keepAlive=true
      // but if for some reason you want to pass your own http agent, you can.
      // Some documentation on the subject of http agents
      // And the recommandations of the official CouchDB NodeJS lib
      agent: myAgent
    const getDbApi = bluecot(config)
    const db = getDbApi('some-db-name')

    with Bluebird

    From v4.0.0, blue-cot stopped returning Bluebird promises, but if you miss that feature, you can recover it by initializing bluebird before blue-cot:

    global.Promise = require('bluebird')
    const bluecot = require('blue-cot')
    const getDbApi = bluecot(config)
    const db = getDbApi('some-db-name')


    Database functions

    To handle database and design documents creation, see couch-init2


    GET /<dbName>

    const data = await

    Documents functions


    GET /<dbName>/<docId>

    Takes a document id and optionaly a rev id to get a specific version:

    const latestDocVersion = await db.get('doc-1')
    const specificVersion = await db.get('doc-1', '2-b8476e8877ff5707de9e62e70a8e0aeb')

    Missing documents are treated as an error, and thus return a rejected promise.


    POST /<dbName>

    const res = await

    Creates a new document or updates an existing document. If doc._id is undefined, CouchDB will generate a new ID for you.

    On 201, returns result from CouchDB which looks like: {"ok":true, "id":"<docId>", "rev":"<docRev>"}

    All other status codes (including 409, conflict) are treated as errors, and thus return a rejected promise.


    PUT /<dbName>/<doc._id>

    const res = await db.put(doc)

    On 409 (conflict) returns result from CouchDB which looks like: {"error":"conflict"}

    On 201, returns result from CouchDB which looks like: {"ok":true, "id":"<docId>", "rev":"<docRev>"}

    All other status codes are treated as errors, and thus return a rejected promise.


    DELETE /<dbName>/<docId>?rev=<rev>

    const res = await db.delete(docId, rev)

    On 200, returns result from CouchDB which looks like: {"ok":true, "id":"<docId>", "rev":"<docRev>"}

    All other status codes are treated as errors, and thus return a rejected promise.

    If you wish to gracefully handle update conflicts while deleting, use db.put() on a document with _deleted set to true:

    doc._deleted = true
    const res = await db.put(doc)
    if (!res.ok) {
      // something went wrong, possibly a conflict


    POST /<dbName>/_find_ (endpoint available in CouchDB >= 2.0)

    Takes a _find query object

    const { docs, bookmark } = await db.find({
      selector: {
        year: { $gt: 2010 }
      fields: [ '_id', '_rev', 'year', 'title' ],
      sort: [ { year: 'asc' } ],
      limit: 2,
      skip: 0,
      use_index: [ 'some_design_doc_name', 'some_index_name' ],
      execution_stats: true

    By default, this function will throw if receiving a warning; this behavior can be disable by passing strict=false:

    const query = {
      selector: {
        year: { $gt: 2010 }
    const { docs, bookmark, warning } = await db.find(query, { strict: false })

    To send the same query to the _explain endpoint instead, use the explain flag:

    const query = {
      selector: { name: 'foo' }
    const { docs, bookmark, warning } = await db.find(query, { explain: true )


    POST /<dbName>/_index

    const { result } = await db.postIndex({
      index: {
        fields: [ 'type' ]
      ddoc: 'some_ddoc_name',
      name: 'by_type'


    GET /<dbName>/<docId>

    const res = await db.exists(docId)

    Returns a promise resolving to true if it exist, or a rejected promise if it doesn't.


    POST /<dbName>?batch=ok

    const res = await db.batch(doc)

    doc: Batch Mode

    Creates or updates a document but doesn't wait for success. Conflicts will not be detected.

    On 202, returns result from CouchDB which looks like: {"ok":true, "id":"<docId>"}

    The rev isn't returned because CouchDB returns before checking for conflicts. If there is a conflict, the update will be silently lost.

    All other status codes are treated as errors, and thus return a rejected promise.


    const res = await db.update(docId, updateFunction)

    Gets the specified document, passes it to updateFunction, and then saves the results of updateFunction over the document

    The process loops if there is an update conflict.

    By default, db.update only accepts to update existing docs, but this can be changed by setting createIfMissing=true:

    const res = await db.update(docId, updateFunction, { createIfMissing: true })


    POST /<dbName>/_bulk_docs

    const res = await db.bulk(docs)

    See CouchDB documentation for more information


    GET /<dbName>/_all_docs?<properly encoded query>

    const { rows } = await db.allDocs(query)

    Queries the _all_docs view. query supports the same keys as in db.view.


    Loads documents with the specified keys and query parameters

    const { rows } = await db.allDocsKeys(keys, query)

    Couchdb documentation


    Takes doc ids, returns docs.

    const { docs, errors } = await db.fetch([ 'doc-1', 'doc-2', 'doc-3', 'some-non-existing-doc' ])
    docs[0]._id === 'doc-1' // true
    docs[1]._id === 'doc-2' // true
    docs[2]._id === 'doc-3' // true
    errors[0].key === 'some-non-existing-doc' // true
    errors[0].error === 'not_found' // true


    Queries the changes given the specified query parameters.

    const latestChanges = await db.changes({ descending: true, limit: 10 })

    ⚠️ the feed mode is not supported as a feed can not be returned as a stream. To follow a change feed, see cloudant-follow


    Takes a doc id, returns the doc's rev infos

    const revsInfo = await db.listRevs('doc-1')

    revsInfo will look something like:

      { rev: '3-6a8869bc7fff815987ff9b7fda3e10e3', status: 'available' },
      { rev: '2-88476e8877ff5707de9e62e70a8e0aeb', status: 'available' },
      { rev: '1-a8bdf0ef0b7049d35c781210723b9ff9', status: 'available' }


    Takes a doc id and reverts its last change, recovering the previous version. Only works if there is a previous version and if it is still available in the database (that is, if it wasn't deleted by a database compaction). It doesn't delete the last version, it simply creates a new version that is exactly like the version before the current one.

    const res = await db.revertLastChange('doc-1')


    Takes a doc id and a function, and reverts to the last version returning a truthy result when passed through this function. Same warnings apply as for revertLastChange.

    const desiredVersionTestFunction = doc => === 2
    db.revertToLastVersionWhere('doc-1', desiredVersionTestFunction)


    Mistakes happen

    await db.delete(docId, docRev)
    await db.undelete(docId))
    const restoredDoc = await db.get(docId))

    ⚠️ this will obviously not work if the version before deletion isn't in the database (because the database was compressed or it's a freshly replicated database), or if the database was purged from deleted documents.

    View functions


    GET /<dbName>/_desgin/<designName>/_view/<viewName>?<properly encoded query>

    const { rows, total_rows, offset } = db.view(designName, viewName, query)

    Queries a view with the given name in the given design doc. query should be an object with any of the query parameters

    const { rows } = await db.view('someDesignDocName', 'someViewName', {
      keys: [ 'a', 'b', 'c' ],
      include_docs: true,
      limit: 5,
      skip: 1




    Design doc specific view functions

    Those functions are pre-filled versions of the view functions above for the most common operations, like to get all the documents associated to an array of ids.

    To access those, pass a design doc name as second argument

    const db = getDbApi('some-db-name', 'some-design-doc-name')

    see lib/view_functions

    If you find this module useful, consider making a PR to improve the documentation



    See also

    you might want to consider using couchdb-nano, the now offical (but bloated ;p) CouchDB NodeJS lib


    npm i blue-cot

    DownloadsWeekly Downloads






    Unpacked Size

    35.5 kB

    Total Files


    Last publish


    • maxlath