Nano doc

README.md

nano

minimalistic couchdb driver for node.js

nano features:

• minimalistic - there is only a minimun of abstraction between you and couchdb
• pipes - proxy requests from couchdb directly to your end user
• errors - errors are proxied directly from couchdb: if you know chouchdb you already know nano

installation

1. install npm
2. npm install nano

getting started

to use nano you need to connect it to your couchdb install, to do that:

var nano = require('nano')('http://localhost:5984');

to create a new database:

nano.db.create('alice');

and to use it:

var alice = nano.db.use('alice');

in this examples we didn't specify a callback function, the absence of a callback means "do this, ignore what happens". in nano the callback function receives always three arguments:

• err - the error, if any
• body - the http response body from couchdb, if no error. json parsed body, binary for non json responses
• header - the http response header from couchdb, if no error

a simple but complete example using callbacks is:

var nano = require('nano')('http://localhost:5984');

// clean up the database we created previously
nano.db.destroy('alice', function() {
  // create a new database
  nano.db.create('alice', function() {
    // specify the database we are going to use
    var alice = nano.use('alice');
    // and insert a document in it
    alice.insert({ crazy: true }, 'rabbit', function(err, body, header) {
      if (err) {
        console.log('[alice.insert] ', err.message);
        return;
      }
      console.log('you have inserted the rabbit.')
      console.log(body);
    });
  });
});

if you run this example(after starting couchdb) you will see:

you have inserted the rabbit.
{ ok: true,
  id: 'rabbit',
  rev: '1-6e4cb465d49c0368ac3946506d26335d' }

you can also see your document in futon

database functions

nano.db.create(name, [callback])

creates a couchdb database with the given name.

nano.db.create('alice', function(err, body) {
  if (!err) {
    console.log('database alice created!');
  }
});

nano.db.get(name, [callback])

get informations about name.

nano.db.get('alice', function(err, body) {
  if (!err) {
    console.log(body);
  }
});

nano.db.destroy(name, [callback])

destroys name.

nano.db.destroy('alice');

even though this examples looks sync it is an async function.

nano.db.list([callback])

lists all the databases in couchdb

nano.db.list(function(err, body) {
  // body is an array
  body.foreach(function(db) {
    console.log(db);
  });
});

nano.db.compact(name, [designname], [callback])

compacts name, if designname is specified also compacts its views.

nano.db.replicate(source, target, [opts], [callback])

replicates source on target with options opts. target has to exist, add create_target:true to opts to create it prior to replication.

nano.db.replicate('alice', 'http://admin:[email protected]:5984/alice',
                  { create_target:true }, function(err, body) {
    if (!err) 
      console.log(body);
});

nano.db.changes(name, [params], [callback])

asks for the changes feed of name, params contains additions to the querystring.

nano.db.changes('alice', function(err, body) {
  if (!err)
    console.log(body);
});

nano.use(name)

creates a scope where you operate inside name.

var alice = nano.use('alice');
alice.insert({ crazy: true }, 'rabbit', function(err, body) {
  // do something
});

nano.db.use(name)

alias for nano.use

nano.db.scope(name)

alias for nano.use

nano.scope(name)

alias for nano.use

nano.request(opts, [callback])

makes a request to couchdb, the available opts are:

• opts.db - the database name
• opts.method - the http method, defaults to get
• opts.path - the full path of the request, overrides opts.doc and opts.att
• opts.doc - the document name
• opts.att - the attachment name
• opts.content_type - the content type of the request, default to json
• opts.body - the document or attachment body
• opts.encoding - the encoding for attachments

nano.relax(opts, [callback])

alias for nano.request

nano.dinosaur(opts, [callback])

alias for nano.request

            / _) roar! i'm a vegan!
     .-^^^-/ /
  __/       /
 /__.|_|-|_|

nano.config

an object containing the nano configurations, possible keys are:

• url - the couchdb url
• db - the database name

document functions

db.insert(doc, [docname], [callback])

inserts doc in the database with an optional docname.

var alice = nano.use('alice');
alice.insert({ crazy: true }, 'rabbit', function(err, body) {
  if (!err)
    console.log(body);
});

db.destroy(docname, rev, [callback])

removes revision rev of docname from couchdb.

alice.destroy('alice', '3-66c01cdf99e84c83a9b3fe65b88db8c0', function(err, body) {
  if (!err)
    console.log(body);
});

db.get(docname, [params], [callback])

gets docname from the database with optional querystring additions params.

alice.get('rabbit', { revs_info: true }, function(err, body) {
  if (!err)
    console.log(body);
});

db.bulk(docs, [params], [callback])

bulk operations(update/delete/insert) on the database, refer to the couchdb doc.

db.list([params], [callback])

list all the docs in the database with optional querystring additions params.

alice.list(function(err, body) {
  if (!err) {
    body.rows.foreach(function(doc) {
      console.log(doc);
    });
  }
});

db.fetch(docnames, [params], [callback])

bulk fetch of the database documents, docnames are specified as per couchdb doc. additionals querystring params can be specified, include_doc is always set to true.

attachments functions

db.attachment.insert(docname, attname, att, contenttype, [params], [callback])

inserts an attachment attname to docname, in most cases params.rev is required. refer to the doc for more details.

var fs = require('fs');

fs.readfile('rabbit.png', function(err, data) {
  if (!err) {
    alice.attachment.insert('rabbit', 'rabbit.png', data, 'image/png',
      { rev: '12-150985a725ec88be471921a54ce91452' }, function(err, body) {
        if (!err)
          console.log(body);
    });
  }
});

or using pipe:

var fs = require('fs');

fs.createreadstream('rabbit.png').pipe(
    alice.attachment.insert('new', 'rab.png', {}, 'image/png')
);

db.attachment.get(docname, attname, [params], [callback])

get docname's attachment attname with optional querystring additions params.

var fs = require('fs');

alice.attachment.get('rabbit', 'rabbit.png', function(err, body) {
  if (!err) {
    fs.writefile('rabbit.png', body);
  }
});

or using pipe:

var fs = require('fs');

alice.attachment.get('rabbit', 'rabbit.png').pipe(fs.createwritestream('rabbit.png'));

db.attachment.destroy(docname, attname, rev, [callback])

destroy attachment attname of docname's revision rev.

alice.attachment.destroy('rabbit', 'rabbit.png',
    '1-4701d73a08ce5c2f2983bf7c9ffd3320', function(err, body) {
      if (!err)
        console.log(body);
});

views and design functions

db.view(designname, viewname, [params], [callback])

calls a view of the specified design with optional querystring additions params.

alice.view('characters', 'crazy_ones', function(err, body) {
  if (!err) {
    body.rows.foreach(function(doc) {
      console.log(doc.value);
    });
  }
});

db.updatewithhandler(designname, updatename, docname, [body], [callback])

calls the design's update function with the specified doc in input.

advanced features

extending nano

nano is minimalistic but you can add your own features with nano.request(opts, callback)

for example, to create a function to retrieve a specific revision of the rabbit document:

function getrabbitrev(rev, callback) {
  nano.request({ db: 'alice',
                 doc: 'rabbit',
                 method: 'get',
                 params: { rev: rev }
               }, callback);
}

getrabbitrev('4-2e6cdc4c7e26b745c2881a24e0eeece2', function(err, body) {
  if (!err) {
    console.log(body);
  }
});

pipes

you can pipe in nano like in any other stream.
for example if our rabbit document has an attachment with name picture.png (with a picture of our white rabbit, of course!) you can pipe it to a writable stream

var fs = require('fs'),
    nano = require('nano');
var alice = nano.use('alice');
alice.attachment.get('rabbit', 'picture.png').pipe(fs.createwritestream("/tmp/rabbit.png"));

then open /tmp/rabbit.png and you will see the rabbit picture.

tutorials & screencasts

• screencast: couchdb and nano
• article: nano - a minimalistic couchdb client for nodejs
• article: getting started with node.js and couchdb
• article: document update handler support

roadmap

check issues

tests

to run (and configure) the test suite simply:

cd nano
vi cfg/tests.js
npm install # should install ensure and async, if it doesn't install manually
npm test

after adding a new test you can run it individually (with verbose output) using:

nano_env=testing node tests/doc/list.js list_doc_params

where list_doc_params is the test name.

contribute

everyone is welcome to contribute with patches, bugfixes and new features

1. create an issue on github so the community can comment on your idea
2. fork nano in github
3. create a new branch git checkout -b my_branch
4. create tests for the changes you made
5. make sure you pass both existing and newly inserted tests
6. commit your changes
7. push to your branch git push origin my_branch
8. create a pull request

meta

                _
              / _) roar! i'm a vegan!
       .-^^^-/ /
    __/       /
   /__.|_|-|_|     cannes est superb

• code: git clone git://github.com/dscape/nano.git
• home: http://github.com/dscape/nano
• bugs: http://github.com/dscape/nano/issues
• build:

(oo)--',- in caos

license

copyright 2011 nuno job <nunojob.com> (oo)--',--

licensed under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at

http://www.apache.org/licenses/license-2.0

unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.