Chainit NPM | npm.io

chainit3

Turn an asynchronous JavaScript api into an asynchronous chainable JavaScript api.

This is a fork of chainit, with more work into getting a well-defined behavior of the transformation.

usage

function MyApi() {}
MyApi.prototype.method1 = function(cb) {cb()}
MyApi.prototype.method2 = function(cb) {cb()}

var chainit = require('chainit');
var MyChainApi = chainit(MyApi);
var obj = new MyChainApi();
obj
  .method1()                      // 1st call
  .method2()                      // 2nd call
  .method1(function(/* args */) { // 3rd call
    this.method1();               // 4th call
  })
  .method2();                     // 5th call

Adding or overriding methods

Adding and overriding methods works at both prototype level and instance level.

You must use chainit.add(chain, methodName, method), since direct assignations won't wrap your method properly.

function MyApi() {}
MyApi.prototype.method1 = function(cb) {cb()}
MyApi.prototype.method2 = function(cb) {cb()}

var chainit = require('chainit');
var MyChainApi = chainit(MyApi);

var obj = new MyChainApi();

// override instance method
chainit.add(obj, 'method1', function(cb) {
  cb()
});

obj
  .method1() // calls the newly added method1
  .method2();

// revert original method
chainit.add(obj, 'method1', MyApi.prototype.method1);

// override prototype method
chainit.add(MyChainApi, 'method1', function(cb) {
  cb()
});

var obj2 = new MyChainApi();

obj2.method1(); // calls the newly chained prototype `method1`

Like a state machine

It is also possible to have a custom function called immediately, in addition to the function that is queued:

chainit.add(obj, 'method1', function queued1(sub, cb) {
  //... the actual method
}, function now1(sub) {
  this.chainState = { one: true };
});
chainit.add(obj, 'method2', function queued2(var1, var2, cb) {

}, function now2(var1, var2) {
  if (!this.chainState || !this.chainState.one) throw new Error("method2 must be called after method1");
  this.chainState.one = false;
});

// this works
obj.method1(a, b).method2(a, b) // ok
obj.method1(a, b, function() {
  this.method2(a, b); // ok
  this.method2(a, b); // not allowed by that simple state machine
});

The first function is pushed to the queue, the second function is called immediately.

The second function can set this.chainState = someObject and the queued function will be able to access that object.

this.chainState reference is copied to the next queued (and immediate if any) functions: this behavior allows queued functions to get information about which functions were queued before or after them.

error handling

Upon error, execution is stopped and the nearest callback is called, or the error is thrown:

obj
  .method1()
  .methodError()
  .notactuallycalled(function(err) {
    // the error that happened in methodError
    // but the method "notactuallycalled" is not called !
    console.error(err);
  });

Uncaught errors are also caught and handled the same way - which adds some safety to the original API.

variable length arguments

Methods that have a variable number of arguments require special handling. It is advised to define those methods with the smallest number of required arguments:

function(uri, cb) {
  var opts = {};
  if (typeof cb != "function") {
    opts = cb;
    cb = arguments[2];
  }
  // ...
}

This automatically excludes the case where the function can accept (uri, myfun, cb) with myfun as an optional argument. This is actually a good thing because it prevents undefined behavior.