relax-component

superagent on a couch

Relax, superagent on a couch

Relax is a small component and node.js module.

Relax is a high-level CouchDB client on a top of superagent. It's goal is to help you write not so criminally-long http-requests in Couch style, leaving the rest of a heavy job to a powerful superagent. It can be a lightweight replacement of a jquery.couch.js and has almost the same methods. Except those that are easier and more reasonable to be used in the console. And it is is tiny ~ 10K as non-minified component, and ~20K in standalone form.

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

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(errres){
    JSON.parse(res.text).text.should.equal('some text');
  })

Callback-form:

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

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

- .dbname()

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

- .uuids()

  relax
    .uuids(2)
    .end(function(res) {
      console.log(JSON.parse(res.text));
    });
--> {"uuids":["11eaa495bfae96d36d6a53f21a01adf6","11eaa495bfae96d36d6a53f21a01b9b7"]}
  relax.uuids(2, function(errres) {
      console.log(res);
  });
--> ["11eaa495bfae96d36d6a53f21a01adf6","11eaa495bfae96d36d6a53f21a01b9b7"]

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

relax.exists(name)
    .end(function(errres){
      console.log(res.ok);
  })
--> true

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

var doc = {text: 'some text', count: 1};
relax.post(doc)
    .end(function(errres){
        doc._id = res.id;
        console.log(res);
  })
--> {
  ok: true,
  id: '11eaa495bfae96d36d6a53f21a0e357c',
  rev: '1-69aed0cf2cf6e13d7209219e4e814c74' }
relax.get(doc, function(errres){
     console.log(res);
  })
--> {
  _id: '11eaa495bfae96d36d6a53f21a0ede9d',
  _rev: '1-69aed0cf2cf6e13d7209219e4e814c74',
  text: 'some text',
  count: 1 }

- .all(), .bulk()

relax
   .all(docs)
   .query({startkey: '"1"', endkey: '"2"'})
   .end(function(errres){
      log(err, JSON.parse(res.text));
  })
-->
{ total_rows: 5,
  offset: 1,
  rows:
   [ { id: '1', key: '1', value: [Object] },
     { id: '2', key: '2', value: [Object] } ] }

- .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(errres){
      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(docreq) {
   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(headreq) {
   start({"headers":{"Content-Type" : "text/html"}});
   var row;
   while(row = getRow()) {
      send(row.key);
  };
}

component:

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

_update

design document:

var inPlace = function(docreq) {
   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(errres){
      console.log(res.text);
   });
--> set world to test

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

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

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>

View more examples in test suite

$ make test

include xxx

GNU GPL