var Series = require('series');var series = Series();var async = require('async'); // <~~ simply for usage example// Add methods to our series sequenceseries.add('map', function (items, iterator, next) { async.map(items, iterator, next);});series.add('sortBy', function (items, iterator, next) { async.sortBy(items, iterator, next);});series.add('filter', function (items, iterator, next) { var self = this; var error; async.filter(items, function (item, callback) { iterator(item, function (err, matched) { if (err) { error = err; return; } callback(matched); }); }, function (filteredItems) { next(error, filteredItems); });});// Use our seriesvar list = [ { name: 'John', age: 25 }, { name: 'Jane', age: 20 }];series(list) .sortBy(function (item, next) { next(null, item.age); }) .map(function (item, next) { next(null, item.age); }) .then(function (items) { // items now equals: [20, 25] }, function () { // oops, an error may have occured });
series
The instance value returned from calling Series() is both a function and an object. The object is the instance and the function returns the series chain.
series() supports the follow as initial values to start the series:
Primitive - strings, numbers, etc.
Array - an array of primitives or objects
Function - a function that is passed a next callback that must be called with the following: next(err, value). The value passed as the second argument becomes the initial value of the series.
###For example:
Primitive
var Series = require('series');var series = Series();var someValue = 'my value';series(someValue);
Array
var Series = require('series');var series = Series();var someValue = [1,2,3,4,5];series(someValue);
Function
var Series = require('series');var series = Series();series(function (next) { var someValue = 'my value'; next(null, someValue);});
instance methods
These methods are available on the series variable.
add(methodName, methodTask)
Composes a chainable method on the series. The method is added for all instances of that particular series.
methodName
A string that will be used as the method name
methodTask
A callback function that is passed the following parameters
items - any value that you would like passed to the first method in the series
iterator - the method called on the value from the previous method that performs some sort of user defined operation
next - the callback once all items in the list or collection have been processed.
For Example:
var Series = require('series');var series = Series();// Add methods to our series sequenceseries.add('map', function (items, iterator, next) { iterator(items, function (err, processItems) { next(err, processItems); });});
series sequence methods
These methods are available on the value returned from called series(someValue)
The methods available vary according to which methods have been added to the series. In the usage example above, we've added map, sortBy, and filter. These methods would be available on the series as well as:
then(successCallback, errorCallback)
Each series sequence returns a promise. Refer to the Promises/A+ spec for more details.
successCallback
This is called once all chained methods have processed the initial value, unless an error has occurred.
errorCallback
This is called if an error occurs anywhere when processing the initial value in any of the chainable methods. If an error occurs, all processing stops.
For Example:
var Series = require('series');var series = Series();var someValue = 'my value';series(someValue) .someChainableMethod(function (value, next) { next(null, value + 's'); }) .then(function (processedValue) { // processedValue == my values });
TODO
more detailed documentation
allow callbacks on each chained method
allow promises to be passed in as inititial value to series