buster.promise

Version
0.3.0 (2011-08-09)
Module
require("buster-promise");
In browsers
buster.promise;

A promise represents the eventual value returned from the single completion of an operation. It is used to simplify asynchronous control flow in several Buster modules. This particular implementation is a simple one, and loosely based on the CommonJS "A" proposal by Kris Zyp.

Methods

create([func])

Creates a new promise. The optional function argument will be immediately invoked and receives the newly created promise as its only argument.

var promise = buster.promise.create();
var promise2 = buster.promise.create(function (p) {
    require("child_process").exec("ls -l", function (err, out) {
        if (err) {
            promise2.reject(err);
        } else {
            promise2.resolve(out);
        }
    });
});

var promise = then(fulfilledHandler, errorHandler)

Register callbacks to handle the promise once it fulfills. fulfilledHandler is called when resolve is called and errorHandler is called when reject is called. Arguments passed to resolve/reject are passed as is to the respective handlers.

The handlers are also called in the event that the promise is already fulfilled when then is called.

then returns the promise itself for chainable thens.

var promise = buster.promise.create();
promise.then(function (str) {
    console.log(str);
}, function (err) {
    console.log(err.message);
});
promise.resolve("Hey there"); // then-listener prints "Hey there"
// or:
promise.reject(new Error("Oops!")); // then-listener prints "Oops!"

resolve([arg1, arg2, ...])

Resolves the promise. If either resolve or reject has already been called, the method will throw an error.

reject([arg1, arg2, ...])

Rejects the promise. If either reject or resolve has already been called, the method will throw an error.

thenable(value)

Utility function that accepts an object - possibly a promise - and returns a promise. If value is a promise, it is returned as is. For any other values, a new promise is returned, that resolves with the value.

var promise = buster.promise.thenable(32);
promise.then(function (val) {
    console.log(val);
});
// Prints 32

sequential(funcs[, opt])

Calls a series of asynchronous functions in sequence - i.e., the second function is called when the first function fully completes and so on. If a function returns a promise, the next function is called when the promise resolves. Otherwise, the next function is passed to buster.nextTick.

The options object may be used to provide a thisObject to call functions on and an error handler. The error handler is used whenever a function throws an exception. If an exception is thrown and an error handler is not specified, the execution is aborted and the promise returned from sequential is rejected with the exception object.

var myLib = { /* ... */ };
buster.promise.sequential([myLib.asyncFunc1, myLib.asyncFunc2], {
    thisObject: thisObject
}).then(function () {
    console.log("Called when asyncFunc1 and asyncFunc2 have resolved");
});

all(promise1, promise2, ...)

Returns a promise that resolves when all arguments have resolved. Arguments can either be several promises as separate arguments or a single array of promises.

var all = require("buster-promise").all;
fs.readdir(fpath, function (err, files) {
    var promises = [];
    (files || []).forEach(function (file) {
        promises.push(processFileAsynchronously(file));
    });
    all.apply(null, promises).then(function () {
        console.log("Done asynchronously processing files")
    });
});

With array of promises

var all = require("buster-promise").all;
fs.readdir(fpath, function (err, files) {
    var promises = [];
    (files || []).forEach(function (file) {
        promises.push(processFileAsynchronously(file));
    });
    all(promises).then(function () {
        console.log("Done asynchronously processing files")
    });
});