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

1. 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.
2. callback (Function(err, data)) the complete callback in the conventional form of function (err, data) { ... }
3. concurrencyLevel (Number/String: defaults to 'auto') the concurrency level of the chain execution, can be 'auto' or N* = { 1, 2, ... }
4. 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.

Copyright (c) 2010 Kilian Ciuffolo, [email protected]. All Rights Reserved.

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the 'Software'), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.