raptor-async is a simple library for orchestrating asynchronous operations. It was inspired by the popular caolan/async library. The main difference being that this library only includes parallel and series functions. This library also supports an optional thisObj argument that determines the scope that will be used when invoking job and completion functions.

The raptor-async library handles invoking functions (a.k.a. jobs) in parallel or series. Each function is invoked with a single argument — a callback function that should be invoked when the job completes. The callback function is a Node-style callback so it expects the first parameter to be an error object and the second parameter to be the data.

The parallel method is used to handle invoking worker jobs in parallel and notifying the provided callback when all of the jobs complete.

The parallel function supports the following calling conventions:

async.parallel(function[],function, thisObj)

or

async.parallel(object,function, thisObj)

If parallel is invoked with an array of functions as first argument, then results will provided to the completion callback as an array with the value at each index corresponding to the data returned by the job at that index. The order of the results will not be arbitrary — it will always correspond to the order in which the jobs were provided to the parallel function.

If parallel is invoked with an object as first argument, then each property is expected to be a function. The results will provided to the completion callback as an object with the value of each property corresponding to the data returned by the job with the corresponding key.

The thisObj argument is optional, but if it is provided then each job function will be invoked in the scope of the given value. Also, the final completion callback will be invoked in the scope of the given value.

Example of calling parallel with an array of functions as first argument:

The series method is used to handle invoking worker jobs in series and notifying the provided callback when all of the jobs complete. Execution of jobs will stop if a job provides an error to the callback. The results will always be an array whose order will correspond to the order in which the jobs were placed in array.

The series function supports the following calling convention:

async.series(function[],function, thisObj)

The thisObj argument is optional, but if it is provided then each job function will be invoked in the scope of the given value. Also, the final completion callback will be invoked in the scope of the given value.

For both parallel and series methods, if errors occur during execution of jobs then completion callback will be invoked with an error object as first argument.

The error object will have a toMap function that can be used to inspect which jobs returned errors. Each property in this map will have a key that corresponds to index (if input work was provided as array of functions) or key (if input work was provided as object) of original input job. The toString function will also provide a human-readable description of the error by invoking toString on each error and concatenating the results together in a meaningful way.

Sometimes you need to keep track of an asynchronous operation to know if it is still pending, successfully completed or if it completed with an error. Promises allow for this, but Promises introduce a fair amount of overhead. The DataHolder class offered by this module can be used as a lightweight alternative to promises with a much more limited feature set. DataHolder instances do not support chaining, but they do support attaching Node.js-style callbacks. The usage of the DataHolder class is best described using code as shown below:

var DataHolder =require('raptor-async/DataHolder');

var configDataHolder =newDataHolder();

functionloadConfig(){

require('fs').readFile('config.json','utf8',function(err, json){

if(err){

// Something with wrong, I guess we won't be able to get a valid config...

return configDataHolder.reject(err);

}

var config = JSON.parse(json);

// Success! We completed the asynchronous operation of loading the config

// and now we can store the result in the async data holder instance.

configDataHolder.resolve(config);

});

}

// Start loading the config immediately

loadConfig();

exports.onConfigLoaded=function(callback){

// Attach a listener to the data holder

configDataHolder.done(callback);

}

The constructor for the DataHolder supports an optional options argument (described later).

The most important methods provided by DataHolder instances are the following:

resolve(data) - Move the data holder ot the "resolved" state and store the resulting data in the data holder

reject(err) - Move the data holder ot the "rejected" state and store the resulting error in the data holder

done(callback) - Attach a Node.js-style callback to the data holder (i.e. function(err, data)). If the data holder has already been resolved then the provided callback will be invoked with the stored data as the second argument. If the data holder has already been rejected then the provided callback will be invoked with the stored error as the first argument. If the data holder has not been resolved or rejected then a listener will be attached and the listener will later be invoked when the data holder is later resolved or rejected.

The complete set of DataHolder properties are shown below:

data - The resolved data or if the data holder has not been resolved

error - The rejected error or if the data holder has not been rejected

The signature for a DataHolder is function DataHolder(options) where options is an object with any of the following properties (all optional):

loader - A function that can be used to load the asynchronous data. The provided loader function will be invoked with a callback argument when load() is called or lazily when a done listener is added for the first time.

'ttl' - A time-to-live in milliseconds. The data holder will go back into the initial unsettled state if the time-to-live is exceeded

scope - The default value of this when invoking any of the provided callbacks or the loader function