bluejeansandrain.series

Execute a series of asynchronous method calls in sequence, optionally passing data from the previous to the next.

npm install bluejeansandrain.series
16 downloads in the last month

node-series

A fairly simple flow control system for asynchronous method calls that must be performed in series, possibly passing data to the next call in the series. This is mostly to save horizontal space that would be eaten up by indenting many nested callbacks, and to provide a readable and clearly linear asynchronous flow statement.

var series = require( 'bluejeansandrain.series' );

series
    .begin( [callback, [arg, arg, ...]] )
    .then( [callback], [arg, arg, ...] )
    .then( ... )
    .end( [callback], [arg, arg, ...] );

The begin is identical to then, but the begin method is included and by convention used first just to be more symantically correct. Begin also can be called with no arguments to create a new Series instance without adding any steps to it.

series.begin()
    .on( 'error', callback )
    .then( [callback], [arg, arg, ...] )
    .then( ... )
    .end( [callback], [arg, arg, ...] );

var mySeries = series.begin();

mySeries
    .begin( ... )
    .then( ... )
    .end( ... );

Callbacks must accept next as the first argument.

callback( next, ... );

next must be called to execute the next step in the series, or next.error can be called to abort the series and raise the error event. Only one next method (next or next.error) can be called and only called once. You can pass any and as many arguments as you want to either method. Arguments passed to next will be passed to the next step in the series. Arguments passed to next.error will be passed to error event handlers.

callback( next, ... )
{
    next( 'some data', ... );
}

callback( next, ... )
{
    next.error( 'some data', ... );
}

Calling next is similar to calling the next method in the chain directly, except that a next method may be inserted at the beginning of the passed arguments next will never return anything. The last step added with via end will not be passed next as a first argument. If your last step expects the next first argument, you can use then followed by end with no arguments.

Example:

function first( next, a )
{
    // a was set when `then` was called.

    next( a );
}

function second( next, b, a )
{
    // b was set when `then` was called.
    // a was passed to `next` in `first`.

    next( b, a );
}

function third( c, b, a )
{
    // c was set when `then` was called.
    // b and a where passed to `next` in `second`.

    console.log( arguments );
}

function third_alternative( next, c, b, a )
{
    // c was set when `then` was called.
    // b and a where passed to `next` in `second`.

    console.log( arguments );
    next();
}

series
    .begin( first, 'a' )
    .then( second, 'b' )
    .end( 'third', 'c' );

// equivalent to...

series.begin()
    .then( first, 'a' )
    .then( second, 'b' )
    .then( third_alternative, 'c' )
    .end();

Output:

> ["c", "b", "a"]
> ["c", "b", "a"]
npm loves you