Dominic Barnes

What is it?

An easy-to-use, powerful wrapper for the CouchDB HTTP API. It follows Node.js callback conventions, and takes care of many of the details of the HTTP request/response cycle, allowing you to focus on getting your job done.

What is it not?

This is not an ORM for CouchDB, it's simply a JavaScript API to communicate with the CouchDB HTTP API.

Features

  • Clean, discoverable API
  • Consistent with Node.js conventions
  • Built-in caching support (via HTTP Etags)
  • Changes API (queries and streams)
  • Attachments support
  • User API (_users db, see Server API)
  • Utilizes mikeal's request module

Upcoming

  • More auth methods (cookie, oauth, etc.)
  • HTTP COPY support

Installation 

npm install couchdb-api

API Reference

Server API

A Server object represents a single CouchDB node/server instance.

var couchdb = require("couchdb-api");

// only 1 argument, a full URL string pointing to your Couch
var server = couchdb.srv("http://localhost:5984");

server.activeTasks (callback) *

GET /_active_tasks

Get information about all the active tasks currently running on the server

Name Type Description
callback Function

server.allDbs (callback) *

GET /_all_dbs

Get a list of all the databases on the server

Name Type Description
callback Function

server.auth

Getter/setter property for HTTP Basic Auth parameters

// get
server.auth; // "user:pass"

// set
server.auth = [ "user", "pass" ];
server.auth = "user:pass";

server.db (name)

Returns Database object

Returns an object representing a database on this server

Name Type Description
name String

server.info (callback) *

GET /

Get basic information about the server

Name Type Description
callback Function

server.log ([query], callback) *

GET /_log

Get the text of the server's log file

Name Type Description
[query] Object
callback Function

server.login (user, pass, callback) *

POST /_session

Attempt a login against the server itself

Name Type Description
user String
pass String
callback Function

server.logout (callback) *

DELETE /_session

Logout (destroy the session)

Name Type Description
callback Function

server.register (name, pass, [options], callback) *

Create a new user in the _users database

Name Type Description
name String
pass String
[options] Object
callback Function

server.replicate (source, target, [options], callback) *

POST /_replicate

Performs a replication from this database to the destination database

Name Type Description
source String, Object
target String, Object
[options] Object
callback Function

server.restart (callback) *

GET /_restart

Restarts the server

Name Type Description
callback Function

server.session (callback) *

GET /_session

Check the status of the current session

Name Type Description
callback Function

server.stats (callback) *

GET /_stats

Get the server running stats

Name Type Description
callback Function

server.userDoc (name, pass, [options])

Returns New User Document

Creates a properly structured user document

Name Type Description
name String
pass String
[options] Object

server.uuids ([count], callback) *

GET /_uuids

Get a list of generated UUIDs

Name Type Description
[count] Number default = 1
callback Function

Database API

A Database object represents a single CouchDB database.

var couchdb = require("couchdb-api");

// defaults to "http://localhost:5984/db-name"
couchdb.db("db-name");

// or use a Server object to initialize
couchdb.srv().db("db-name");

database.allDocs ([query], [keys], callback) *

GET /db/_all_docs

Query the _all_docs special view

// default behavior
db.allDocs(callback)

// adding query params
db.allDocs({ include_docs: true }, callback)

// querying for specific keys
db.allDocs(null, ["doc-id-1", "doc-id-2"], callback)
Name Type Description
[query] Object
[keys] Array
callback Function

database.bulkDocs (docs, [mode]) *

POST /db/_bulk_docs

Performs a bulk operation

Name Type Description
docs Array Array of document objects
[mode] String "all-or-nothing" or "non-atomic"

database.changes (query, callback) *

GET /db/_changes

Query (or initiate a stream) the CouchDB _changes API

Name Type Description
query Object
callback Function

database.compact ([ddoc], callback) *

POST /db/_compact, POST /db/_compact/ddoc

Perform a database (or design document view index) compation

Name Type Description
[ddoc] String If passed, will compact the specified design document's view indexes
callback Function

database.create (callback) *

PUT /db

Create the database

Name Type Description
callback Function

database.designDoc (name)

Returns a new DesignDocument object

Initializes a new DesignDocument object for this database

Name Type Description
name String

database.doc ([id])

Returns a new Document object

Initializes a new Document object for this database

Name Type Description
[id] String

database.drop (callback) *

DELETE /db

Drop the database

Name Type Description
callback Function

database.ensureFullCommit (callback) *

POST /db/_ensure_full_commit

Commits recent db changes to disk

Name Type Description
callback Function

database.info (callback) *

GET /db

Get basic information about the database

Name Type Description
callback Function

database.localDoc (name)

Returns a new LocalDocument object

Initializes a new LocalDocument object for this database

Name Type Description
name String

database.name

Getter/setter property for database name

Note It is entirely dependent on _url.pathname[1]

database.pull (source, [query], callback) *

POST /_replicate

Similar to replicate, except it uses the current db as the target instead of the source

Name Type Description
source Object
[query] Object
callback Function

database.purge (callback) *

POST /db/_purge

Purges references to deleted documents from the database

Name Type Description
callback Function

database.recreate (callback) *

DELETE /db, PUT /db

Drop the database, then create it again

Name Type Description
callback Function

database.replicate (target, [query], callback) *

POST /_replicate

Replicates the current db to another db

Name Type Description
target String, Object
[query] Object
callback Function

database.security (callback) *

POST /db/_security

Gets/sets the security object for this db

Name Type Description
callback Function

database.tempView (map, [reduce], [query], callback) *

POST /db/_temp_view

Execute a temporary view

Name Type Description
map Function
[reduce] Function
[query] Object
callback Function

database.viewCleanup (callback) *

POST /db/_view_cleanup

Clear the cached view output

Name Type Description
callback Function

Document API

A Document object represents a single document.

var doc = db.doc("my-doc-id")

document.attachment (name)

Returns

Create a new Attachment object

Name Type Description
name String

document.body

This property helps maintain the internals of the object if it is set after
initialization. (keeps _id in sync with the rest of the body)

document.del (callback) *

DELETE /db/doc

Delete the document from the server

Name Type Description
callback Function

document.get (callback) *

GET /db/doc

Retrieve the document from the server

Name Type Description
callback Function

document.id

Another property to help keep the internals in line. This will make sure the
internal URL is in sync with the _id property even after initialization.

document.prop (field, [value])

Returns Set = chainable, Get = returns current value

Shorthand for getting/setting basic properties (only works 1 level deep)

Name Type Description
field String
[value] Various

document.save (callback) *

PUT /db/doc, POST /db

Save the document to the server

Name Type Description
callback Function

document.show (show, [query], [options], callback) *

GET /db/_design/design-doc/_show/show-name/doc

Execute a show function for the current document

Name Type Description
show String The name of the show function (ddoc/show)
[query] Object
[options] Object
callback Function

Attachment API

An Attachment object represents a single attachment on a document.

var attachment = doc.attachment("my-ddoc-name");

attachment.del (callback)

Returns this

DELETE /db/doc/attachment

Removes an attachment from a document on the server

Name Type Description
callback Function

attachment.get (stream, [options], callback) *

GET /db/doc/attachment

Retrieve an attachment from a document

Name Type Description
stream Boolean
[options] Object
callback Function

attachment.name

Maintains the name as part of the URL

attachment.save (callback) *

PUT /db/doc/attachment

Saves an attachment to the server

Name Type Description
callback Function

attachment.setBody (format, body) *

Set up the body of this attachment

Name Type Description
format String
body Various

View API

A View object represents a single view within a design document

var view = ddoc.view("my-view-name");

view.list (list, [query], callback) *

GET /db/_design/design-doc/_list/list-name/doc

Execute a list function for the current document

Name Type Description
list String The name of the list function in the above design document
[query] Object
callback Function

view.map ([query], callback) *

GET /db/ddoc/_view/view

Perform a map query against a stored view

Name Type Description
[query] Object
callback Function

view.name

Gets/sets the name as part of the URL

view.query ([query], [data], callback) *

GET /db/ddoc/_view/view

Perform a generic query against a stored view

Name Type Description
[query] Object If only one of the optional params is provided, this is assumed to be the one
[data] Array, Various Array = pass as `keys` in body, Various = pass as complete body
callback Function

view.reduce ([query], callback) *

GET /db/ddoc/_view/view

Perform a reduce query against a stored view

Name Type Description
[query] Object
callback Function

DesignDocument API

A DesignDocument object represents a single design document.

var doc = db.ddoc("my-ddoc-name")

designdoc.info (callback) *

GET /db/_design/ddoc

Get statistical information about the design document

Name Type Description
callback Function

designdoc.list (name, fn)

Returns Set = chainable, Get = list function

Get/set a single list function

Name Type Description
name String
fn Function

designdoc.lists ([lists])

Returns Set = chainable, Get = list hash

Get/set all the list functions

Name Type Description
[lists] Object

designdoc.name

Behaves similarly to the Document property with the same now

designdoc.show (name, fn)

Returns Set = chainable, Get = show function

Get/set a single show function

Name Type Description
name String
fn Function

designdoc.shows ([shows])

Returns Set = chainable, Get = show hash

Get/set all the show functions

Name Type Description
[shows] Object

designdoc.update (name, fn)

Returns Set = chainable, Get = update function

Get/set a single update handler

Name Type Description
name String
fn Function

designdoc.updates ([updates])

Returns Set = chainable, Get = update hash

Get/set the update handlers

Name Type Description
[updates] Object

designdoc.val ([fn])

Returns Set = chainable, Get = validation function

Method wrapper for validate, to allow for chaining

Name Type Description
[fn] Function

designdoc.validate

Get/set the validation function

designdoc.view (map, [reduce])

Returns Set = chainable, Get = view object

Set a single named view

Name Type Description
map Function
[reduce] Function, String

designdoc.views ([views])

Returns Set = chainable, Get = view hash

Get/set all the views

Name Type Description
[views] Object

LocalDocument API

A LocalDocument object represents a single local document
(a document that does not get replicated)

var ldoc = db.ldoc("my-ldoc-id")

localdoc.name

Behaves similar to the Document property with the same name,
also keeping the id and url in sync.

Code / Object Structure

Great care has been taken to leverage the powerful nature of JavaScript. This includes using prototypes for inheritance and code encapsulation, cached mixins for a smaller type of inheritance and performance as well as leveraging every object as a reference to allow for lots of useful references and discoverability.

The Client Object

Every API object inherits from a HTTP client object that is the workhorse of HTTP requests and responses. All requests are routed through here, and responses are automatically handled before being sent back to the calling objects.

Every callback executes in the context of the object that made the request. Also, the 3rd parameter to each callback is the HttpResponse object from the request. (if available)

The API Hierarchy

Server
└→ Database
   └→ Document
      └→ Attachment
   └→ Design Document
      └→ View
   └→ Local Document

As you descend into the inheritance chain, all the parent objects are also included with each instance. For example, a database object will have a server property that references the object that initialized it. A document object will have a db property and a server property. Feel free to inspect the objects as well, there's plenty to see and use there!

Callbacks

Every HTTP request method in couchdb-api follows the same conventions, because they are all routed through the same request function.

Every callback receives the same set of parameters and is given the same context. (the object itself that made the API call)

Name DataType Comments
err object Not included if no errors took place
data mixed Not included if an error occurred. In most cases, this will return a parsed JSON object, but sometimes it will simply return a string of the response body.
response HttpResponse The raw HttpResponse object from Node.js