cot

What is Cot?

Cot is a rather simple but quite pleasant interface for CouchDB. It doesn't attempt to implement everything, but it covers the important stuff for using couch as an effective database.

var Cot = require('cot');
var cot = new Cot({port: 5984, hostname: 'localhost'});
var db = cot.db('my-db');

db.getDoc('counter', onGet);

function onGet(err, doc) {
	if (err) throw err;
	
	if (doc === null) {
		doc = {
			_id: 'counter',
			count: 0
		};
	}
	
	doc.count += 1;
	
	db.putDoc(doc, {conflictOk: true}, onPut);
}

function onPut(err, response) {
	if (err) throw err;
	
	if (response.conflict) {
		db.getDoc('counter', onGet);
	}
	else {
		console.log('done!');
	}
}

There's actually a utility function for an optimistic update loop:

db.updateDoc('counter', mutate, onUpdate);

function mutate(doc, next) {
	doc.count = (doc.count || 0) + 1;
	next();
}

function onUpdate(err) {
	if (err) throw err;
	console.log('done!');
}

API Reference

cot = new Cot(opts)

opts must contain the following keys:

• port: the port number of your couchdb server
• hostname: the hostname of your couchdb server

opts may contain the following keys:

• ssl: if set to true, Cot will use https
• auth: may be set to a string in the format 'username:password' for basic auth

db = cot.db(dbName)

Returns an object representing the specified database.

db.info(next(err, info))

Queries database info and calls next when done.

db.getDoc(docId, next(err, doc))

Gets a doc out of the database. If the doc is missing, err will be null and doc will be null.

db.getDocWhere(docId, condition(doc), next(err, doc))

Gets a doc out of the database and passes it to condition. If condition returns false, next will be called with doc === null as if the doc did not exist. This is useful for avoiding the easy mistake of writing code that allows access to your entire database:

db.getDocWhere(query.docId, function(doc) { return doc.isPublic }, onGet);

db.putDoc(doc, [opts,] next(err, response))

Attempts to put doc into database. The doc must have an _id field. If you expect to handle update conflicts, send {conflictOk: true} in opts. Otherwise, conflicts will be treated as errors. In any case, the response from couch is passed to next so you can retrieve the new rev or detect a conflict if conflictOk: true. Response may be something like:

{ok: true, rev: '2-whatever'}

Or, in case of a conflict where conflictOk: true:

{error: 'conflict'}

db.updateDoc(doc, fn, next(err, response))

Reads doc from the database and calls fn(doc, cb). fn may directly mutate doc and call cb when done. Then updateDoc will attempt to put the modified document back in the database. If there is an update conflict, the process will start over and repeat until success.

db.deleteDoc(docId, rev, [opts,] next)

Attempts to delete the document with the specified docId and rev. As with putDoc, you may pass {conflictOk: true} in opts.

db.view(designName, viewName, query, next(err, response))

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

• descending
• endkey
• endkey_docid
• group
• group_level
• include_docs
• inclusive_end
• key
• limit
• reduce
• skip
• stale
• startkey
• startkey_docid
• update_seq

For more information, refer to http://wiki.apache.org/couchdb/HTTP_view_API#Querying_Options

db.allDocs(query, next(err, response))

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

db.viewKeys(designName, viewName, keys, next(err, response))

Queries the specified keys from the specified view. Keys should be an array of keys.

db.allDocsKeys(keys, next(err, response))

Loads documents with the specified keys.

db.postBulkDocs(docs, allOrNothing, next(err, response))

Posts multiple updates to the database in one request. docs should be an array of documents. allOrNothing should be a boolean. See http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API for more information.

db.changes(query, next)

Queries the changes feed given the specified query. query may contain the following keys:

• filter: filter function to use
• include_docs: if true, results will contain entire document
• limit: the maximum number of change rows this query should return
• since: results will start immediately after the sequence number provided here
• longpoll: if true, query will send feed=longpoll
• timeout: timeout in milliseconds for logpoll queries

For more information about the CouchDB changes feed, see http://wiki.apache.org/couchdb/HTTP_database_API#Changes