Cradle – A Node.js Module You Should Know About

Hello everyone! This is the twelfth post in the node.js modules you should know about article series.

The first post was about dnode - the freestyle rpc library for node, the second was about optimist - the lightweight options parser for node, the third was about lazy - lazy lists for node, the fourth was about request - the swiss army knife of HTTP streaming, the fifth was about hashish - hash combinators library, the sixth was about read - easy reading from stdin, the seventh was about ntwitter - twitter api for node, the eighth was about socket.io that makes websockets and realtime possible in all browsers, the ninth was about redis - the best redis client API library for node, the tenth was on express - an insanely small and fast web framework for node, the eleventh was semver - a node module that takes care of versioning.

Today I'll introduce you to cradle - a high-level, caching, CouchDB client for Node.js. Cradle is written by Alexis Sellier (cloudhead).

Cradle 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.

Here is an example of how simple it's to use cradle:

var cradle = require('cradle');
var db = new(cradle.Connection)().database('starwars');

db.get('vader', function (err, doc) {
    doc.name; // 'Darth Vader'
    assert.equal(doc.force, 'dark');
});

db.save('skywalker', {
    force: 'light',
    name: 'Luke Skywalker'
}, function (err, res) {
    if (err) {
        // Handle error
    } else {
        // Handle success
    }
});

Cradle supports all the operations that you'd expect an API for CouchDB to support like creating a database:

var db = c.database('starwars');
db.create();

Checking if a db exists:

db.exists(function (err, exists) {
  if (err) {
    console.log('error', err);
  } else if (exists) {
    console.log('the force is with you.');
  } else {
    console.log('database does not exists.');
    db.create();
    /* populate design documents */
  }
});

Destroying a db:

db.destroy(cb);

Fetching a document:

db.get('vader', function (err, doc) {
    console.log(doc);
});

Querying a view:

db.view('characters/all', function (err, res) {
    res.forEach(function (row) {
        console.log(row.name + " is on the " +
            row.force + " side of the force.");
    });
});

Creating and updating documents:

db.save('vader', {
    name: 'darth', force: 'dark'
}, function (err, res) {
    // Handle response
});

Creating views:

db.save('_design/characters', {
    all: {
        map: function (doc) {
            if (doc.name) emit(doc.name, doc);
        }
    },
    darkside: {
        map: function (doc) {
            if (doc.name && doc.force == 'dark') {
                emit(null, doc);
            }
        }
    }
});

Deleting documents:

db.remove('luke', '1-94B6F82', function (err, res) {
    // Handle response
});

And it also supports streaming, changes api, and many other things. See the cradle documentation to learn more.

You can install cradle through npm as always:

npm install cradle

Cradle on GitHub: https://github.com/cloudhead/cradle.