blue-cot

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

Forked from Cot

Summary

• Installing
• Differences with Cot
• Initialization
• API
  • Common API
  • Specific API
    • Extended functions
      • get
    • Additional database functions
      • fetch
      • listRevs
      • revertLastChange
      • revertToLastVersionWhere
      • undelete
    • View functions
      • viewCustom
      • viewByKeysCustom
      • viewByKey
      • viewFindOneByKey
      • viewByKeys

Installing

npm install blue-cot

Differences with Cot

• Returns Bluebird promises
• 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

Initialization

const bluecot = require('blue-cot')
const config = {
  // MUST
  hostname: 'localhost'
  port: 5984,

  // MAY
  ssl: true
  // use one of the two:
  // together
  auth: 'username:password'
  // or separated
  user: 'username'
  pass: 'password'
  // logs the generated URLs and body
  debug: true
}

const getDbApi = bluecot(config)

const db = getDbApi('some-db-name')

API

Common API

Cot API Documentation

Those are the same than for cot-node. Just remember this difference in error handling: here, 4xx and 5xx responses from CouchDB will return rejected promises (should be handled with .catch)

• docUrl
• info
• get
• exists
• put
• post
• batch
• update
• delete
• bulk
• buildQueryString
• viewQuery
• view
• allDocs
• viewKeysQuery
• viewKeys
• allDocsKeys
• changes

Specific API

Extended functions

get

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

db.get('doc-1')
.then(function (lastDocVersion) {
  // do something
})

db.get('doc-1', '2-b8476e8877ff5707de9e62e70a8e0aeb')
.then(function (specificVersion) {
  // doc._rev === '2-b8476e8877ff5707de9e62e70a8e0aeb'
})

Additional database functions

fetch

Takes doc ids, returns docs

db.fetch([ 'doc-1', 'doc-2', 'doc-3' ])
.then(function (docs) {
  docs[0]._id === 'doc-1' // true
  docs[1]._id === 'doc-2' // true
  docs[2]._id === 'doc-3' // true
})

listRevs

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

db.listRevs('doc-1')
.then(function (revsInfo) {
  // do your thing
})

revsInfo will look something like:

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

revertLastChange

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.

db.revertLastChange('doc-1')

revertToLastVersionWhere

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) => doc.foo === 2

db.revertToLastVersionWhere('doc-1', desiredVersionTestFunction)

undelete

Mistakes happen

db.delete(docId, docRev)
.then(res => db.undelete(docId))
.then(res => db.get(docId))
.then(restoredDoc => // celebrate)

:warning: 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

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

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

viewCustom

viewByKeysCustom

viewByKey

viewFindOneByKey

viewByKeys

see lib/view_functions

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