runnel

Simple and small flow control library to execute async functions in sequence

runnel

run·nel/ˈrənl/ - A narrow channel in the ground for liquid to flow through.

Simple and small (~ 80 loc) flow control library to execute async functions in sequence.

Table of Contents generated with DocToc

npm install runnel
var runnel = require('runnel');
 
function uno (cb) {
  setTimeout(function () { cb(null, 'eins'); } , 100);
}
 
function dos (resunocb) {
  setTimeout(function () { cb(null, resuno, 'zwei'); } , 100);
}
 
function tres (resunoresdoscb) {
  setTimeout(function () { cb(null, resuno, resdos, 'drei'); } , 100);
}
 
runnel(
    uno
  , dos
  , tres 
  , function done(errresunoresdosrestres) {
      if (err) return console.error('Error: ', err);
      console.log('Success: uno: %s, dos: %s, tres: %s', resuno, resdos, restres);
    }
);
 
// => Success: uno: eins, dos: zwei, tres: drei 
// using uno, dos, tres and done functions from above 
 
var funcs = [uno, dos, tres ];
funcs.push(done);
 
runnel(funcs);
function size (fileacccb) {
  var p = path.join(__dirname, '..', file);
 
  fs.stat(p, function (errstat) {
    if (err) return cb(err);
 
    acc[file] = stat.size;
    cb(null, acc);
  });
}
 
runnel(
    // {} will be passed as the first value to next function  
    // and thus become 'acc', the accumulator 
    runnel.seed({})
  
    // after we bind 'file' to the size function the resulting  
    // custom size function has signature 'function (acc, cb) {}' 
  , size.bind(null, '.gitignore')
  , size.bind(null, '.jshintrc')
  , size.bind(null, '.travis.yml')
 
  , function done (erracc) {
      if (err) return console.error(err);
      console.log('sizes:', acc);
    }
);
 
// => sizes: { '.gitignore': 96, '.jshintrc': 249, '.travis.yml': 52 } 

full example

same example using array of functions

  • intuitive argument passing
  • seeding a start value to enable async reduce like functionality
  • fails early
  • no magic
    • no special (ab)uses of this
    • no context passing
  • adheres to known nodejs pattern i.e., callbacks are expected to be of the form function (err[,res]*) { ... }
  • super small
  • browser support

All functions below are expected to invoke the callback like so:

  • cb(null, res1[, res2][,..] if no error occurred
  • cb(err) if an error occurred

Sequentially runs all the given functions, passing results from one to the next. In case any of the functions calls back with an error done will be called with that error immediately.

Same as above except that functions are passed as an array rather than as separate values, which allows building up a flows with array operations like concat and push like is done in this example.

More importantly it allows mapping values to async functions and then execute them sequentially, akin to Q.all.

For more information see this real world example.

Returns a function that will call back with the seeded value as the result, which can then be consumed by the next function in line. This allows easily implementing async reduce flows as shown in this example

  • commonJS compatible, so it works with nodejs and browserify
  • AMD compliant (i.e., shimlessly works with requirejs)
  • attaches itself to the window object if neither commonJS or AMD support is detected

In order to avoid surprises runnel aborts the entire call chain once any function calls back with an error.

In that case the last function in the chain is called with the error in order to provide feedback that something went wrong.

From my experience simple, sequential flow control is sufficient in 90% of the cases and therefore using fuller featured and therefore also larger flow control libraries is unnecessary in those instances.

runnel however was designed for exactly these situations.

It helps avoid nesting callbacks and results in much more readable and maintainable code.

It also helps minimize repetitive if (err) { cb(err); return; } ... occurences.

Finally because runnel focuses only on one thing it's a very small module (~ 80 loc).

Looky here: examples or consult the tests.