couchdb-promises

couchdb-promises

Yet another Node.js module for CouchDB that uses ES6 promises

• no dependencies
• as simple as possible

All Functions return a Promise object whose fulfillment or failure handler receives an object of 5 properties:

• headers: {Object} - HTTP response headers from CouchDB
• data: {Object} - CouchDB response body
• status: {Number} - HTTP status code from CouchDB
• message: {String} - description of the status code from CouchDB API
• duration: {Number} - execution time in milliseconds

The promise is resolved if the CouchDB status code is < 400 otherwise rejected.

Installation

npm install couchdb-promises

Example.js

const db = require('couchdb-promises')({
  baseUrl: 'http://localhost:5984', // required
  requestTimeout: 10000
})
const dbName = 'testdb'

get info

db.getInfo()
.then(console.log)
// { headers: { ... },
//   data:
//    { couchdb: 'Welcome',
//      version: '2.0.0',
//      vendor: { name: 'The Apache Software Foundation' } },
//   status: 200,
//   message: 'OK - Request completed successfully'
//   duration: 36 }

create database

db.createDatabase(dbName)
.then(console.log)
// { headers: { ... },
//   data: { ok: true },
//   status: 201,
//   message: 'Created - Database created successfully',
//   duration: 131 }

get database head

.then(() => db.getDatabaseHead(dbName))
.then(console.log)
// { headers: { ... },
//   data: {},
//   status: 200,
//   message: 'OK - Database exists',
//   duration: 4 }

list databases

.then(() => db.listDatabases())
.then(console.log)
// { headers: { ... },
//   data: [ '_replicator', '_users', 'testdb' ],
//   status: 200,
//   message: 'OK - Request completed successfully',
//   duration: 4 }

create document

.then(() => db.createDocument(dbName, {name: 'Bob'}))
.then(console.log)
// { headers: { ... },
//   data:
//    { ok: true,
//      id: 'daae0752c6909d7ca4cd833f46014605',
//      rev: '1-5a26fa4b20e40bc9e2d3e47b168be460' },
//   status: 201,
//   message: 'Created – Document created and stored on disk',
//   duration: 42 }

create document by id

.then(() => db.createDocument(dbName, {name: 'Alice'}, 'doc2'))
.then(console.log)
// { headers: { ... },
//   data:
//    { ok: true,
//      id: 'doc2',
//      rev: '1-88b10f13383b5d1e34d1d66d296f061f' },
//   status: 201,
//   message: 'Created – Document created and stored on disk',
//   duration: 38 }

get document head

.then(() => db.getDocumentHead(dbName, 'doc2'))
.then(console.log)
// { 'cache-control': 'must-revalidate',
//   connection: 'close',
//   'content-length': '74',
//   'content-type': 'application/json',
//   date: 'Sun, 06 Nov 2016 08:56:47 GMT',
//   etag: '"1-88b10f13383b5d1e34d1d66d296f061f"',
//   server: 'CouchDB/2.0.0 (Erlang OTP/17)',
//   'x-couch-request-id': '041e46071b',
//   'x-couchdb-body-time': '0' },
//   data: {},
//   status: 200,
//   message: 'OK - Document exists',
//   duration: 6 }

get document

.then(() => db.getDocument(dbName, 'doc2'))
.then(response => { console.log(response); return response.data })
// { headers: { ... },
//   data:
//    { _id: 'doc2',
//      _rev: '1-88b10f13383b5d1e34d1d66d296f061f',
//      name: 'Alice' },
//   status: 200,
//   message: 'OK - Request completed successfully',
//   duration: 11 }

update document

.then((doc) => {
  doc.age = 42
  return db.createDocument(dbName, doc, 'doc2')
})
.then(console.log)
// { headers: { ... },
//   data:
//    { ok: true,
//      id: 'doc2',
//      rev: '2-ee5ea9ac0bb1bec913a9b5e7bc11b113' },
//   status: 201,
//   message: 'Created – Document created and stored on disk',
//   duration: 36 }

get all documents

.then(() => db.getAllDocuments(dbName, {
  descending: true,
  include_docs: true
}))
.then(console.log)
// { headers: { ... },
//   data: { total_rows: 2, offset: 0, rows: [ [Object], [Object] ] },
//   status: 200,
//   message: 'OK - Request completed successfully',
//   duration: 9 }

delete document

.then(() => db.deleteDocument(dbName, 'doc2', '2-ee5ea9ac0bb1bec913a9b5e7bc11b113'))
.then(console.log)
// { headers: { ... },
//   data:
//    { ok: true,
//      id: 'doc2',
//      rev: '3-ec0a86a95c5e98a5cd52c29b79b66372' },
//   status: 200,
//   message: 'OK - Document successfully removed',
//   duration: 39 }

copy document

.then(() => db.copyDocument(dbName, 'doc', 'docCopy'))
.then(console.log)
// { headers: { ... },
//   data:
//    { ok: true,
//      id: 'doc3',
//      rev: '1-4c6114c65e295552ab1019e2b046b10e' },
//   status: 201,
//   message: 'Created – Document created and stored on disk',
//   duration: 42 }

bulk create documents

.then(() => db.createBulkDocuments(dbName, [
  {name: 'Tick'}, {name: 'Trick'}, {name: 'Track'}
], {all_or_nothing: true}))
.then(console.log)
// { headers: { ... },
//   data:
//   [ { ok: true,
//       id: '5413cf41edaedaec6b63aee93db86e1f',
//       rev: '1-d7f23e94e65978ea9252d753fe5dc3f6' },
//     { ok: true,
//       id: '5413cf41edaedaec6b63aee93db877cc',
//       rev: '1-646cd5f84634632f42fee2bdf4ff753a' },
//     { ok: true,
//       id: '5413cf41edaedaec6b63aee93db87c3d',
//       rev: '1-9cc8cf1e775b686ca337f69cd39ff772' } ],
//   status: 201,
//   message: 'Created – Document(s) have been created or updated',
//   duration: 74 }

find documents (requires CouchDB >= 2.0.0)

.then(() => db.findDocuments(dbName, {
  selector: {
    $or: [{ name: 'Tick' }, {name: 'Track'}]
  },
  fields: ['_id', 'name']
}))
.then(console.log)
// { headers: { ... },
//   data:
//    { warning: 'no matching index found, create an index to optimize query time',
//      docs: [ [Object], [Object] ] },
//   status: 200,
//   message: 'OK - Request completed successfully',
//   duration: 14 }

get uuids

.then(() => db.getUuids(3))
.then(console.log)
// { headers: { ... },
//   data:
//    { uuids:
//       [ 'daae0752c6909d7ca4cd833f46014c47',
//         'daae0752c6909d7ca4cd833f460150c5',
//         'daae0752c6909d7ca4cd833f460156c5' ] },
//   status: 200,
//   message: 'OK - Request completed successfully',
//   duration: 4 }

delete database

.then(() => db.deleteDatabase(dbName))
.then(console.log)
// { headers: { ... },
//   data: { ok: true },
//   status: 200,
//   message: 'OK - Database removed successfully' }
//   duration: 40 }

run generic HTTP GET request

.then(() => db.getUrlPath('_all_dbs'))
.then(console.log)
// { headers: { ... },
//  data: [ '_replicator', '_users' ],
//  status: 200,
//  message: 'OK',
//  duration: 6 }

on error

.then(() => db.getDocument(dbName, 'doc1'))
.catch(console.error)
// { headers: { ... },
//   data: { error: 'not_found', reason: 'Database does not exist.' },
//   status: 404,
//   message: 'Not Found - Document not found',
//   duration: 5 }

---

View and Design Functions (View.js)

create design document

const ddoc = {
  language: 'javascript',
  views: { view1: { map: 'function (doc) {emit(doc.name, doc.number)}' } }
}
const docId = 'ddoc1'

db.createDesignDocument(dbName, ddoc, docId)
.then(console.log)
// { headers: { ... },
//   data:
//    { ok: true,
//      id: '_design/ddoc1',
//      rev: '1-548c68d8cc2c1fac99964990a58f66fd' },
//   status: 201,
//   message: 'Created – Document created and stored on disk',
//   duration: 271 }

get design document

db.getDesignDocument(dbName, docId)
.then(console.log)
// { headers: { ... },
//   data:
//    { _id: '_design/ddoc1',
//      _rev: '1-548c68d8cc2c1fac99964990a58f66fd',
//      language: 'javascript',
//      views: { view1: [Object] } },
//   status: 200,
//   message: 'OK - Request completed successfully',
//   duration: 5 }

get design document info

db.getDesignDocumentInfo(dbName, docId)
.then(console.log)
// { headers: { ... },
//   data:
//   { name: 'ddoc1',
//     view_index:
//      { updates_pending: [Object],
//        waiting_commit: false,
//        waiting_clients: 0,
//        updater_running: false,
//        update_seq: 0,
//        sizes: [Object],
//        signature: '1e86d92af43c47ef58da4b645dbd47f1',
//        purge_seq: 0,
//        language: 'javascript',
//        disk_size: 408,
//        data_size: 0,
//        compact_running: false } },
//   status: 200,
//   message: 'OK - Request completed successfully',
//   duration: 54 }

get view

db.getView(dbName, docId, viewName, {limit: 3})
.then(console.log)
// { headers: { ... },
//   data:
//    { total_rows: 12,
//      offset: 0,
//      rows: [ [Object], [Object], [Object] ] },
//   status: 200,
//   message: 'OK - Request completed successfully',
//   duration: 834 }

delete design document

db.deleteDesignDocument(dbName, docId, rev)
.then(console.log)
// { headers: { ... },
//   data:
//    { ok: true,
//      id: '_design/ddoc1',
//      rev: '2-fd68157ec3c1915ebe0b248343292d34' },
//   status: 200,
//   message: 'OK - Document successfully removed',
//   duration: 49 }

Update Handler Functions (update-handler.js)

execute update function

db.executeUpdateFunction(dbName, ddocId, func, queryObj)

execute update function for document

db.executeUpdateFunctionForDocument(dbName, ddocId, func, queryObj, docId)
// { headers: { ... },
//   status: 201,
//   data: { text: 'added 10' },
//   message: 'Created - Document was created or updated',
//   duration: 49 }

---

Index Functions (index.js)

CouchDB >= 2.0

create index

db.createIndex(dbName, {
  index: {
    fields: ['foo']
  },
  name: 'foo-index'
})
.then(console.log)
// { headers: { ... },
//   data:
//    { result: 'exists',
//      id: '_design/a5f4711fc9448864a13c81dc71e660b524d7410c',
//      name: 'foo-index' },
//   status: 200,
//   message: 'OK - Index created successfully or already exists',
//   duration: 14 }

get index

db.getIndex(dbName)
.then(console.log)
// { headers: { ... },
//   data: { total_rows: 2, indexes: [ [Object], [Object] ] },
//   status: 200,
//   message: 'OK - Success',
//   duration: 6 }

delete index

db.getIndex(dbName)
.then(response => {
  const docId = response.data.indexes.find(e => e.name === 'foo-index').ddoc
  return db.deleteIndex(dbName, docId, 'foo-index')
})
.then(console.log)
// { headers: { ... },
//  data: { ok: true },
//  status: 200,
//  message: 'OK - Success',
//  duration: 45 }

---

API Reference

See examples for details.

configuration

db = couchdb-promises(options)

The options object has the following properties:

• baseUrl: String - e.g. 'http://localhost:5984' (required)
• requestTimeout: Number=10000 - http request timeout in milliseconds
• verifyCertificate: Boolean=true - verify server SSL certificate (https only)

database functions

db.createDatabase( dbName )

create new database
[CouchDB API] [example]

db.getDatabase( dbName )

get information about the specified database
[CouchDB API] [example]

db.getDatabaseHead( dbName )

get minimal amount of information about the specified database
[CouchDB API] [example]

db.deleteDatabase( dbName )

delete the specified database
[CouchDB API] [example]

db.listDatabases()

get list of all databases
[CouchDB API] [example]

db.findDocuments( dbName, queryObj )

find documents using a declarative JSON querying syntax (CouchDB >= 2.0)
[CouchDB API] [example]

document functions

db.getAllDocuments( dbName, [queryObj] )

returns a JSON structure of all of the documents in a given database
[CouchDB API] [example]

db.createDocument( dbName, doc )

create a new document
[CouchDB API] [example]

db.createDocument( dbName, doc, [docId] )

create a new document or a new revision of the existing document.
[CouchDB API] [example]

db.deleteDocument( dbName, docId, rev )

marks the specified document as deleted
[CouchDB API] [example]

db.getDocument( dbName, docId, [queryObj] )

get document by the specified docId
[CouchDB API] [example]

db.getDocumentHead(dbName, docId, [queryObj])

get a minimal amount of information about the specified document
[CouchDB API] [example]

db.copyDocument(dbName, docId, newDocId)

copy an existing document to a new document
[CouchDB API]

index functions

db.createIndex( dbName, queryObj )

create database index (CouchDB >= 2.0)
[CouchDB API]

db.getIndex( dbName )

get all database indexes (CouchDB >= 2.0)
[CouchDB API]

db.deleteIndex( dbName, docId, name )

delete database index (CouchDB >= 2.0)
[CouchDB API]

document attachment functions

db.addAttachment( dbName, docId, attName, rev, contentType, data )

upload the supplied data as an attachment to the specified document
[CouchDB API] [example]

db.getAttachment( dbName, docId, attachmentName, writeStream, [rev] )

get the attachment associated with the document
[CouchDB API] [example]

db.getAttachmentHead( dbName, docName, docId, attachmentName, [rev] )

get minimal amount of information about the specified attachment
[CouchDB API] [example]

db.deleteAttachment( dbName, docId, attachmentName, rev )

deletes the attachment attachment of the specified doc
[CouchDB API] [example]

view and design document functions

db.createDesignDocument( dbName, doc, docId )

create new design document or new revision of an existing design document
[CouchDB API] [example]

db.deleteDesignDocument( dbName, doc, docId, rev)

delete design document
[CouchDB API] [example]

db.getDesignDocument( dbName, docId, queryObj )

get the contents of the design document
[CouchDB API] [example]

db.getDesignDocumentInfo( dbName, docId )

obtain information about the specified design document, including the index, index size and current status of the design document and associated index information
[CouchDB API] [example]

db.getView( dbName, docId, viewName, queryObj )

execute the specified view function from the specified design document
[CouchDB API] [example]

bulk document functions

db.createBulkDocuments( dbName, docs, opts )

create or update multiple documents at the same time within a single request
[CouchDB API] [example]

miscellaneous functions

db.getInfo()

get meta information about the CouchDB server
[CouchDB API] [example]

db.getUuids( count )

get one or more Universally Unique Identifiers (UUIDs) from the CouchDB server
[CouchDB API] [example]

db.getUrlPath( path )

generic http GET request function
[example]

Changelog

3.0.0 - 2017-02-21

• baseUrl is now a required property of the options object. This is an API breaking change.

old:
const db = require('couchdb-promises')({})
const baseUrl = 'http://localhost:5984'
db.getDocument(baseUrl, dbName, 'mydoc')

new:
const db = require('couchdb-promises')({
    baseUrl: 'http://localhost:5984'
})
db.getDocument(dbName, 'mydoc')

• new functions for server-side update handlers. See Document_Update_Handlers for details

• executeUpdateFunction()
• executeUpdateFunctionForDocument()