bucks

Async utilities for node and the browser. (amd support)

bucks.js

Async chain utility for node and the browser. (amd support)

Build

dependence) node.js

$ npm install .

$ make

Examples

add is general way to add a task to bucks object. end starts executing added tasks. Results and errors can be passed to next task in various way.

task is generally task(err, res, next) form function. next task waits until next is called in previous task. if next is not specified, next task is called immediately with returned value.

// 
// new Bucks object 
// 
var b = new Bucks();
 
// 
// Add and add several tasks. 
// 
b.add(function f1(errres) {
 
    return 'a';
 
}).add(function f2(errresnext) {
 
    // res => 'a' 
    return next(null, 3);
 
}).add(function f3(errresnext) {
 
    // res => 3 
    return next(new Error('error after 3'));
 
}).add(function f4(errresnext) {
 
    // err => 'error after 3' 
    return next(null, "recover 4");
 
}).add(function f5(errres) {
 
    // res => 'recover 4' 
    throw new Error('error in f5');
 
}).add(function f6(errres) {
 
    // err => 'error in f5' 
    throw err;
 
}).add(function f7(errres) {
 
    // err => 'error in f5' 
    // ignore and return 
    return "recover 7";
 
}).add(function f8(errresnext) {
 
    // res => 'recover 7'; 
    throw new Error('error in f8');
 
}).add(function f9(errresnext) {
 
    // err => 'Error in f8' 
    // ignore error 
    return next(null, 'result of 9');
 
}).end(function last(errresults) {
 
    // all of results 
    // are obtained in #end 
 
    // err => null 
 
    // results => [ 
    //     'a', 
    //     null, 
    //     null, 
    //     'recover 4', 
    //     null, 
    //     null, 
    //     'recover 7', 
    //     null, 
    //     'result of 9' 
    // ]; 
});

then adds a task called only in case of success

= new Bucks();
b.then(function start() {
    return 'start';
}).then(function second(resnext) {
    // res => 'start' 
    return next(null, 'second')
}).end();

delay add delay execution

= new Bucks();
b.add(function (){ /** program */ })
.delay(1 * 1000) // 1ms 
.add(function() { /** program */})
.end();

error adds a task called only in case of error

b.then(function start() {
    throw new Error('error in start');
    return 'start';
}).error(function onError(enext) {
    // e => 'error in start' 
    return next();
}).end();

Second param in end works as final errorback.

// 
// last error back 
// 
= new Bucks();
b.empty(
    // add empty task (#end with no task cause error) 
).end(function last(errres) {
    // error in last callback 
    throw new Error('error in end');
}, function finalErrorback(err) {
    // catch uncaught error in last callback 
    // err => 'error in end' 
});

uncaught errors properly thrown to outside of chain.

try {
    var b = new Bucks();
    b.then(function () {
        throw new Error('error');
    ).end();
} catch(e) {
    // e => 'error' 
}
 

waterfall is another way to add several tasks.

var t1 = function t1(errres) {
    return 't1';
};
var t2 = funciton t2(err, res) {
    return 't2';
};
 
new Bucks.waterfall([t1, t2]).end(function finish(errress) {
    // ress => ['t1', 't2'] 
});
 
// same as 
new Bucks.add(t1).add(t2).end(function finish(errress) {
    // ress => ['t1', 't2'] 
});

parallel executes tasks in asynchronous way and join their results

 
= new Bucks();
 
b.parallel([
    function task1(errres) {
        return "task1";
    },
    function task2(errresnext) {
        return next(null, "task2");
    },
    function task3(errresnext) {
        return next(new Error('passed error in task3'));
    },
    function task4(errresnext) {
        throw new Error('thrown error in task4');
    }
]).add(function getResults(errresnext) {
    // res => { 
    //     err: [ 
    //         null, 
    //         null, 
    //         [Error: passed error in task3], 
    //         [Error: thrown error in task4] 
    //     ], 
    //     res: [ 
    //         'task1', 
    //         'task2', 
    //         null, 
    //         null 
    //     ] 
    // } 
    next();
}).end();

onError Function to handle exceptions that have not been processed

var onError = function (ebucks) {
    console.log("Custom onError");
};
 
// Bucks.onError!! 
Bucks.onError(onError);
var b0 = new Bucks();
b0
    .add(function(errnext) {
        throw new Error('b0');
    })
    .end()
;
 
var b0 = new Bucks();
 
b0.dispose = function dispose () {
    delete b0.dummy;
}
 
b0
    .add(function(errnext) {
        b0.dummy = "dummy";
        next();
    })
    .end(null, null)
;
 

The output debug log

Bucks.DEBUG = true;

AUTHORS

Changelog

@see https://github.com/CyberAgent/bucks.js/blob/master/Changelog

Copyright

CyberAgent, Inc. All rights reserved.

License

MIT @see https://github.com/CyberAgent/bucks.js/blob/master/LICENSE