README.md

cradle

A high-level, caching, CouchDB client for Node.js

introduction

Cradle is an asynchronous javascript client for CouchDB.
It is somewhat higher-level than most other CouchDB clients, requiring a little less knowledge of CouchDB's REST API.
Cradle also has built-in write-through caching, giving you an extra level of speed, and making document updates and deletion easier.
Cradle was built from the love of CouchDB and Node.js, and tries to make the most out of this wonderful marriage of technologies.

philosophy

The key concept here is the common ground shared by CouchDB and Node.js, that is, javascript. The other important aspect of this marriage is the asynchronous behaviors of both these technologies. Cradle tries to make use of these symmetries, whenever it can.
Cradle's API, although closely knit with CouchDB's, isn't overly so. Whenever the API can be abstracted in a friendlier, simpler way, that's the route it takes. So even though a large part of the Cradle <--> CouchDB mappings are one to one, some Cradle functions, such as save(), can perform more than one operation, depending on how they are used.

updating an existing document with the revision

Note that when saving a document this way, CouchDB overwrites the existing document with the new one. If you want to update only certain fields of the document, you have to fetch it first (with get), make your changes, then resave the modified document with the above method.

If you only want to update one or more attributes, and leave the others untouched, you can use the merge() method:

db.merge('luke', {jedi: true}, function (err, res) {
// Luke is now a jedi,
// but remains on the dark side of the force.
});

Note that we didn't pass a _rev, this only works because we previously saved a full version of 'luke', and the cache option is enabled.

bulk insertion

If you want to insert more than one document at a time, for performance reasons, you can pass an array to save():

These views can later be queried with db.view('characters/all'), for example.

Here we create a temporary view. WARNING: do not use this in production as it is extremely slow (use it to test views).
db.temporaryView({
map: function(doc) {
if (doc.color) emit(doc._id, doc);
}
}, function (err, res) {
if (err) console.log(err);
console.log(res);
});

creating validation

when saving a design document, cradle guesses you want to create a view, mention views explicitly to work around this.