Funclet - a simple callback management

Funclet is a simple callback management library for chaining asynchronous function calls. It preserves Node's callback style for those who are used to them.

Install

npm install funclet

Usage

var funclet = require('funclet');
var fs = require('fs');
funclet.bind(fs.readFile, 'test.json', 'utf8') // first is the function, the rest are the args expected by the function.
  .then(function(data, next) {
    obj = JSON.parse(data); // if this errors it automatically catches.
    next(null, obj);
  })
  .catch(function(err) {
    console.error('ERROR:', err);
  })
  .done(function(obj) {
    console.log(obj);
  })

Similar to other "thenable", funclet is meant to tame the callback hell that occurs in the node world. The focus of funclet though is to keep the paradigm of the node-style callbacks - i.e. instead of trying to convert all functions into returning promises that can be incompatible with each other, funclet allows you to continue to use node style callbacks to keep things simple.

This is designed specifically for library writers who do not want to impose the choice of callback management mechanism on users of the library, since this follows the node's way and can be self-contained (unlike promises) within the library, users can integrate with your library via any callback management of their choosing.

.bind(proc, arg, arg2, ...)

binds a function and the arguments expected by the function (besides the last argument, which is the callback).

bind is a top-level function, and it will return a Functlet object that can be further chained with other function calls.

.bind(proc, arg, arg2, ....)

is equivalent to calling then in the following method:

.then(function(next) {
  proc(arg, arg2, ..., next);  
})

.then(function(next) { ... })

then is not a top-level function; i.e. it can only be called once you have first called one of the top level functions, such as bind. All top level functions are wrappers around then though.

The important thing about then is to make sure you call the next callback the same way you would with other node-style functions.

If you are calling a function that can throw, you do not need to explicitly try/catch unless you want to do specific handling - the error will be automatically propagated to catch otherwise.

When you are chaining multiple thens - make sure the following function will handle the results generated by the previous function. That means if the previous function passes 3 arguments (besides err), the next function in the chain should expect 3 arguments + the callback. i.e.,

.then(function(next) {
  next(null, 1, 2, 3); // passes 3 arguments to next in chain.
})
.then(function(a, b, c, next) { // handles 3 parameters + next
  .... 
})

.catch(function(err) { ... })

catch is the one place to setup error handler. It expects a callback with first parameter being the error parameter. Any error occurred from the previous chains will automatically be sent here (and the rest of the chain will not be invoked).

.done(function (arg...) { ...})

done is the last in the chain and the one that will trigger the processing. It expects the number of parameters from the last then call, without the next parameter, since this is the last callback in the chain.

.map(array, function(item, cb) { ... })

map does async.map but in chainable style. This is equivalent to

.then(function (next) {
  async.map(array, function(item, cb) { ... }, next);
})

The next in chain should expect an array as the first parameter.

map is also a top-level function.

thenMap(function(item, cb) { ... })

thenMap is a combination of then and map. It expects the previous function in the chain to return an array.

thenMap is not a top level function, since it expects an array from previous call.

.mapSeries(array, function(item, cb) { ... })

mapSeries does async.mapSeries but in chainable style. This is equivalent to

.then(function (next) {
  async.mapSeries(array, function(item, cb) { ... }, next);
})

The next in chain should expect an array as the first parameter.

mapSeries is also a top-level function.

thenMapSeries(function(item, cb) { ... })

thenMapSeries is a combination of then and mapSeries. It expects the previous function in the chain to return an array.

thenMapSeries is not a top level function, since it expects an array from previous call.

.each(array, function(item, cb) { ... })

each does async.each but in chainable style. This is equivalent to

.then(function (next) {
  async.each(array, function(item, cb) { ... }, next);
})

The next in chain should expect no result parameters.

each is also a top-level function.

thenEach(function(item, cb) { ... })

thenEach is a combination of then and each. It expects the previous function in the chain to return an array.

thenEach is not a top level function, since it expects an array from previous call.

.eachSeries(array, function(item, cb) { ... })

eachSeries does async.eachSeries but in chainable style. This is equivalent to

.then(function (next) {
  async.eachSeries(array, function(item, cb) { ... }, next);
})

The next in chain should expect no result parameters.

eachSeries is also a top-level function.

thenEachSeries(function(item, cb) { ... })

thenEachSeries is a combination of then and eachSeries. It expects the previous function in the chain to return an array.

thenEachSeries is not a top level function, since it expects an array from previous call.

'.parallel([ function(cb) { ...}, ... ])

.parallel does async.parallel but in chainable style. This is equivalent to

.then(function (next) {
  async.parallel(array, function(item, cb) { ... }, next);
})

The next in chain expects an array of results.

parallel is also a top-level function.

thenParallel()

thenParallel is a combination of then and parallel. It expects the previous function in the chain to return an array. It takes no parameters otherwise.

thenParallel is not a top level function, since it expects an array from previous call.