commit	17d7f401bde5bf63c9f0dd22412bec3622e6273a	[log] [tgz]
author	Nuno Job <nunojobpinto@gmail.com>	Mon Aug 15 12:48:14 2011 +0200
committer	Nuno Job <nunojobpinto@gmail.com>	Mon Aug 15 12:48:14 2011 +0200
tree	186449eb06e3060bb52352fc070443434b8c1f11
parent	bfea28892bb2bf948e8308f262f835f3421f6f84 [diff]

tree: 186449eb06e3060bb52352fc070443434b8c1f11

README.md

Nano

nano (short for NanoCouch) is a minimalistic CouchDB driver for Node.js.

Instalation

Install npm
npm install nano

Usage

A quick example on using nano.

In nano callback always return three arguments:

  err: The error, if any. Check error.js for more info.
  headers: The HTTP response headers from CouchDB, if no error.
  response: The HTTP response body from CouchDB, if no error.

Because in nano you can do database operations you are not bound to one and only one database. The first thing you do is load the module pointing either providing a JSON configuration object or a string that represents the relative file path of that config, e.g. ‘cfg/tests.js’. Do refer to cfg/couch.example.js for a sample.

  var nano = require('nano')('./cfg/tests.js');

Now you can do your database operations using nano. These include things like create, delete or list databases. Let's create a database to store some documents:

  nano.db.create("alice");

Where is my callback? Well in nano you have the option of not having a callback and say “I don't care”.

Of course now you want to insert some documents and you wish you had the callback, so let's add it:

  // Clean up the database we created previously
  nano.db.destroy("alice", function(err,headers,response) {
    nano.db.create("alice", function(){
      // Specify the database we are going to use
      var alicedb = nano.use("alice");
      alicedb.insert("rabbit", {crazy: true}, function(e,h,r){
        if(e) { throw e; }
        console.log("You have inserted the rabbit.")
      });
    });
  });

The alicedb.use method creates a scope where you operate inside a single database. This is just a convenience so you don't have to specify the database name every single time you do an update or delete.

Don't forget to delete the database you created:

  nano.db.destroy("alice");

Interfaces

Documents

Assuming var db = nano.use("somedb");:

  db.insert(doc_name,doc,callback) // doc_name is optional
  db.update(doc_name,rev,doc,callback)
  db.destroy(doc_name,rev,callback)
  db.get(doc_name,callback)
  db.list(callback)

Databases

  nano.db.create(db_name,callback)
  nano.db.destroy(db_name,callback)
  nano.db.get(db_name,callback)
  nano.db.list(callback) 
  nano.db.compact(db_name,callback)
  nano.db.replicate(source,target,continuous,callback) // continuous is optional

Other / Advanced

  nano.use(db_name)
  nano.request(opts,callback)

Aliases

You can use nano.scope instead of nano.use. They are both also available inside db, e.g. nano.db.scope.

When using a database with nano.use you can still replicate, compact, and list the database you are using. e.g. to list you can use db.info (because db.list is for listing documents). Other methods remain the same, e.g. db.replicate.

Future plans

Some future plans are mostly:

Add proxy, pipe, and ssl support as provided by request
Explore adding _changes feed
Convenience functions for attachments
Support views
Support bulk load
_uuids, _stats, _config, _active_tasks, _all_docs_by_seq
Support batch in updates and inserts.

Great segway to contribute.

Contribute

Everyone is welcome to contribute.

Fork nano in github
Create a new branch - git checkout -b my_branch
Create tests for the changes you made
Make sure you pass both existing and newly inserted tests
Commit your changes
Push to your branch - git push origin my_branch
Create an pull request

Running the tests

To run the tests simply browse to test/ and ./run. Don't forget to install the packages referred as dev dependencies in package.json.

Always make sure all the tests pass before sending in your pull request! OR I'll tell Santa!