node-fnqueue

A powerful utility for function chaining (inspired by async).

Engine

nodejs v0.4.12+ (tested with v0.6.x)

Installation with npm

$ npm install fnqueue

Syntax

new FnQueue(functionsList[, callback, concurrencyLevel, isStopped]);

##Parameters

functionsList (Object) a list of Functions. Each function can declare implicit dependencies as arguments and assume you provide a single callback as the last argument.
callback (Function(err, data)) the complete callback in the conventional form of function (err, data) { ... }
concurrencyLevel (Number/String: defaults to 'auto') the concurrency level of the chain execution, can be 'auto' or N* = { 1, 2, ... }
isStopped (Boolean: defaults to false) if true you must call the start method in order to execute the function list.

##Methods

start: will start the execution, used in combination with isStopped = true constructor parameter

##Attributes

isVerbose (Boolean): will change the instance verbose mode

##Notes

FnQueue runs a list of functions, each passing their results to the dependent function in the list. However, if any of the functions pass an error to the callback, the next function is not executed and the main callback is immediately called with the error.

Each dependency/argument must be named with the label of the dependent function in the functionsList (the first constructor argument). Each function with a dependency will be called with the result of the dependent function as expected. (Introspection by introspect)

The global callback is called once, on the first error or at the end of the execution. A data object will be provided with the indexed result of the functions.

FnQueue magically resolves all dependencies and executes functions in the right order with the provided concurrency level.

##Example

var FnQueue = require('fnqueue');

or for a verbose mode:

var FnQueue = require('fnqueue').verbose();

Example:

new FnQueue({
  // this will wait for 'processSomething' and 'searchSomething' and will be called with the respective results
  funnyStuff: function (processSomething, searchSomething, callback) {
    // do something silly
    callback(null, 'ciao!');
  },
  // this will be called instantly
  searchSomething: function (callback) {
    // do something with database
    callback(err, results);
  },
  // this will wait 'searchSomething'
  update: function (searchSomething, callback) {
    // change values inside results and save to db
    callback(err); // no needs to return values
  },
  // this will wait 'searchSomething'
  processSomething: function (searchSomething, callback) {
    var start = new Date().getTime();
    // do something slow
    var elapsedTime = new Date().getTime() - start;
    callback(err, elapsedTime);
  }]
}, function (err, data) {

  if (err) {
    throw err;
  }

  console.log(data.searchSomething);  // results
  console.log(data.update);           // undefined
  console.log(data.processSomething); // elapsedTime
  console.log(data.funnyStuff);       // 'ciao!'
}, 1);

Test

Tests depends on http://vowsjs.org/ then

npm install -g vows
npm install
npm test

License

This software is released under the MIT license cited below.