Relax, superagent on a couch

Relax is a lightweight, high-level CouchDB client. It's built upon superagent library. Relax API eliminates the need to write so criminally-long HTTP-requests in the Couch style. Relax API has been inspired by the jQuery.couch.js API.

It's available as a node.js module, named relax-component

v 0.1.x works with node.js v.6.x and superagent v.2.1.0

Usage

var Relax = require('relax');
var relax = new Relax();
relax.dbname('relax-specs');
var admin = new Relax('http://admin:kjre4317@localhost:5984');

Chainable or callback forms

Each method has chainable and callback-style api. Chainable form always returns superagent-response. While callback form returns what you are expect to be returned from CouchDB:

Chainable-form:

relax
  .get(doc)
  .query({conflicts: true})
  .set('X-API-Key', 'foobar')
  .end(function(err, res){
    JSON.parse(res.text).text.should.equal('some text');
  })

Callback-form:

relax.get(uuid, function(err, res){
  res.text.should.equal('some text');
})

complex ddoc handlers

Note complex form of ddoc handlers .show().get(), .list().view(), .update().post(), .update().put()

Methods

setters:

- .dbname()

session methods:

- .login(), .logout(), .session(), .signup()

server methods:

- .uuids()

example

  relax
    .uuids(2)
    .end(function(res) {
      console.log(JSON.parse(res.text));
    });

--> {"uuids":["11eaa495bfae96d36d6a53f21a01adf6","11eaa495bfae96d36d6a53f21a01b9b7"]}

  relax.uuids(2, function(err, res) {
      console.log(res);
  });

--> ["11eaa495bfae96d36d6a53f21a01adf6","11eaa495bfae96d36d6a53f21a01b9b7"]

database methods:

- .exists(), .create(), .drop(), .info()

example

relax.exists(name)
    .end(function(err, res){
      console.log(res.ok);
  })

--> true

document methods:

- .get(), .post(), .put(), .push() (aka crude get-then-put, use .update instead)

example

var doc = {text: 'some text', count: 1};
relax.post(doc)
    .end(function(err, res){
        doc._id = res.id;
        console.log(res);
  })

--> {
  ok: true,
  id: '11eaa495bfae96d36d6a53f21a0e357c',
  rev: '1-69aed0cf2cf6e13d7209219e4e814c74' }

relax.get(doc, function(err, res){
     console.log(res);
  })

--> {
  _id: '11eaa495bfae96d36d6a53f21a0ede9d',
  _rev: '1-69aed0cf2cf6e13d7209219e4e814c74',
  text: 'some text',
  count: 1 }

array of documents methods:

- .all(), .bulk()

relax
   .all(docs)
   .query({startkey: '"1"', endkey: '"2"'})
   .end(function(err, res){
      log(err, JSON.parse(res.text));
  })

-->
{ total_rows: 5,
  offset: 1,
  rows:
   [ { id: '1', key: '1', value: [Object] },
     { id: '2', key: '2', value: [Object] } ] }

design doc handlers:

- .view(), .show().get(), .list().view(), .update().post(), .update().put()

_view

design document:

function(doc) { emit(doc.text, null) };

component:

relax
   .view('spec/byText')
   .query({startkey:'"some text 1"', endkey:'"some text 3"'})
   .end(function(err, res){
      console.log(JSON.parse(res.text));
  });

-->
{ total_rows: 5,
  offset: 1,
  rows:
   [ { id: '1', key: 'some text 1', value: null },
     { id: '2', key: 'some text 2', value: null },
     { id: '3', key: 'some text 3', value: null } ] }

_show

design document:

var justText = function(doc, req) {
   return { body : "just " + doc.text };
}
var doc = {_id: 'some-id', text: 'some text', count: 0};
var ddoc = {_id: '_design/spec', shows: {'justText': justText.toString() } };

component:

relax
   .show('spec/justText')
   .get(doc)
   .end(function(res){
      console.log(res.text);
  });

--> just some text

_list

design document:

var basicList = function(head, req) {
   start({"headers":{"Content-Type" : "text/html"}});
   var row;
   while(row = getRow()) {
      send(row.key);
  };
}

component:

relax
   .list('spec/basicList')
   .view('spec/basicView', function(err, res) {
      console.log(res.text);
  });

--> some text

_update

design document:

var inPlace = function(doc, req) {
   var field = req.query.field;
   var value = req.query.value;
   var message = "set "+field+" to "+value;
   doc[field] = value;
   return [doc, message];
}

component:

relax
   .update('spec/inPlace/')
   .put(doc._id)
   .query({field:'world', value:'test'})
   .end(function(err, res){
      console.log(res.text);
   });

--> set world to test

not yet included

- .allDbs, .activeTasks, .stats, .config, .compact, .replicate, .viewCleanUp, etc

if you need them, use straight SA-request.get(path) instead

Installation

With node.js:

$ npm install relax-component

or with component

$ component install mbykov/relax

Or as standalone and minified version:

<script src="relax.min.js"></script>

API

View more examples in test suite

Running node tests

$ make test

Running browser tests

push test/* to local couchdb, and open text/index.html

License

GNU GPL