SuperCouch

Features

• compatable with node.js and browser
• chainable or callback-style api
• based on superagent
• tiny (4.3kb minified)

Quick Start Guide

Installation

Node

supercouch package is available through npm.

npm install supercouch

Browser

A commented and minified version are available in the repo. You must load the SuperAgent dependancy prior to loading SuperCouch. Recommended SuperAgent version is 0.7.x.

<script src="superagent.min.js"></script>
<script src="supercouch.min.js"></script>

Connecting to CouchDB

The first level of SuperCouch's chainable API is the making a connection to CouchDB. This can be done by simply invoking the primary export with the URL of your CouchDB installation:

var supercouch = require('supercouch')
  , couch = supercouch('http://localhost:5984');

Now, all requests using the couch variable will be directed to that URL.,

Managing Databases

With the couch variable you can easily manage creating, updating, deleting and invoking actions upon specific databases. All methods (less the db modifier will return an instance of a Request that can be ended to make the request. Alternatively, if you prefer to use SuperCouch in aj less chainable fashion, you may provide a callback to make the request immediately. The following two examples are equivalant.

Chaining

couch
  .dbExists('supercouch')
  .end(function (err, res) {
    if (err) throw err; // instanceof supercouch.CouchError
    console.log(res); // true or false
  });

Callback

couch.dbExists('supercouch', function (err, res) {
  if (err) throw err; // instanceof supercouch.CouchError
  console.log(res); // true or false
});

All methods that return an actual Request can be used in either manner. See the API docs for further information. For consistency, the remainder of this documentation will be presented using the chaining method.

Managing Documents

For managing documents, all you have to do is select the database for which you wish to work with.

couch
  .db('supercouch')
  .insert({ _id: 'abc', foo: 'bar' })
  .end(function (err, res) {
    if (err) throw err; // instanceof supercouch.CouchError
    console.log(res.ok); // true if successful
  });

The _id option is optional. SuperCouch will transparently handle the appropriate request methodology to ensure your insert sticks. You may also store a reference to a specific database if you are performing multiple actions:

var scdb = couch.db('supercouch');

scdb
  .insert({ foo: 'bar' })
  .end(cb);

scdb
  .insert({ foo: 'baz' })
  .end(cb);

There are a number a variations for each method. Consult to the API documentation below to find a suitable style.

Requests are the last part of any of the chainable methods. Providing API access to the Request API allows for a way to directly manipulate and initialize the request.

Further API documentation will note when a method returns a Request. You can also initialize custom requests using the .request method of the Database API.

Modify key/values to the JSON body being sent during PUT and POST based operations. This is usually the case of insert or update commands from supercouch.

var req = couch.request('post', '/mydb/abc');

Can be used to update key/value pairs...

req.send('hello', 'world');

Or, as an object to be shallow-merged with the current parameters.

req.send({ hello: 'universe', scope: 'ubiquitous' });

Modify key/values to the querystring being appended to the url for a request.

var req = couch.request('get', '/mydb/_changes');

Can be used to update key/value pairs...

req.send('since', 123);

Or, as an object to be shallow-merged with the current parameters.

req.send({ since: 123, feed: 'continuous' });

Interprets all the given parameters into a request, sends reqest to superagent, parses results, and sends appropriate values back to callback.

If an error occurs on the CouchDB side of an operation, the results will be constructed into a supercouch.CouchError, which is an instance of a javascript Error.

req.end(function (err, res) {
  if (err) throw err; // likely instanceof CouchError
  console.log(res); // json of CouchDB response
});

After you have specified your CouchDB url, the next level in the chainable API is the Database API. It exposes methods to interact with server and database level events. Note that some methods will construct Requests, while others will construct the next level chainable objects.

Helper method to directly create Requests to the server. Useful for any urls that might not be included in the chainable api.

Providing a callback will immediately execute the request. Returns a Request.

Constructs a request that performs an CouchDb action on the server. If the name of the action is not valid an error will be thrown.

couch
  .action('all dbs')
  .end(db);

Proving a callback will immediately execute the request. Returns a Request.

Actions

• all dbs - get a list of all databases
• active tasks - get a list of currenly running tasks
• uuids - get a list of all uuids generated on the server
• stats - get all couch server statistics
• log - get a tail of ther server's log file (requires admin priv)
• replicate - post a replicate command to the couch server
• restart - port a restart command to the server

Constructs a request that will add a database to the CouchDb server.

couch
  .dbAdd('my_app')
  .end(cb);

Providing a callback will immediately execute the request. Returns a Request.

Constructs a request that will get the information about a database in the CouchDb server.

couch
  .dbInfo('my_app')
  .end(cb);

Providing a callback will immediately execute the request. Returns a Request.

Constructs a request that will check if database exists.

couch
  .dbExists('my_app')
  .end(cb);

Providing a callback will immediately execute the request. Returns a Request.

Constructs a request that will remove a database to the CouchDb server.

couch
  .dbDel('my_app')
  .end(cb);

Providing a callback will immediately execute the request. Returns a Request.

Contructs a Db interface for chaining actions on a specific database. See the Document API.

var mydb = couch.db('mydb');

Provides chainable API for requests to a specific db. Constructed when .db('name') method is performed on a database instance.

Constructs a request that performs a CouchDb action on the currently selected database.

If the name of the action is not valid an error will be thrown.

Proving a callback will immediately execute the request to the server. Returns a Request.

Actions

• changes - gets changes for the database
• compact - post instructing the db to compact
• view cleanup - post instructing the db to perform view cleanup
• temp view - post instructing the db to execute view function (admin privileges)
• ensure full commit - post instructing the db commit all changes to disk
• purge - post instructing the db to purge history docs from db history

Here is very simple map temporary view example.

couch
  .db('mydb')
  .action('temp view')
  .send({
    map: function (doc) {
      emit(doc._id, doc);
    }
  })
  .end(cb);

Inserts a new document to the currently selected database.

couch
  .db('my_app')
  .insert(docObj)
  .end(cb);

Document is optional but should be provided using the requests send command in the chainable api.

couch
  .db('my_app')
  .insert()
  .send(docObj)
  .end(cb);

If a callback is provided will execute the insert request immediately. Returns a Request.

Retrieves a document, optionally at a specific revision, from the currently selected database.

couch
  .db('my_app')
  .get('123', 'rev123')
  .end(cb);

Revision is optional, or can also be provided using the requests qs method.

couch
  .db('my_app')
  .get('123')
  .qs('rev', 'rev123')
  .end(cb);

If a callback is provided will execute the insert request immediately. Returns a Request.

Updates a document, optionally at a specific revision, to the provided document object, from the currently selected database.

couch
  .db('my_app')
  .update(123, docObj)
  .end(cb);

Revision is optional. Document is also optional but should be provided using the requests send command in the chainable api.

couch
  .db('my_app')
  .update(123)
  .send(docObj)
  .end(cb);

When updating the document, if you wish to use an aleady existing document object, you can provide that directly without specifing the id parameter. This does not work with the requests send method.

couch
  .db('my_app')
  .update({
      _id: 123
    , _rev: 'rev123'
    , name: 'Arthur Dent'
  })
  .end(cb);

If a callback is provided will execute the insert request immediately. Returns a Request.

Remove a document from the selected database. A revision is required per CouchDB specifications.

If a callback is provided will execute the insert request immediately. Returns a Request.

Resources

Tests

Tests are written in the BDD styles for the Mocha test runner using the expect assertion interface from Chai. Running tests is simple:

Preperation

You will need to start the test server. This will allow you test both the server and browser versions simultaneously. You will also need a CouchDB server running locally using the default configuration.

make test-server

Server Tests

To run the server side tests:

make test

Browser Tests

To run the browser side tests, first make the most recent version of the browser build.

make 

Then point your browser to http://localhost:5000/test/browser/.

License

(The MIT License)