promise-list v0.2.0

PromiseList is an extension to Promise.all() and Promise.race() and, more generally, a series of utilities around Promises.

Documentation

Promise.all() returns a Promise that succeeds only if all the Promises succeed and Promise.race() returns a Promise that succeeds when any Promise succeeds. This extension add a new function that returns a Promise that succeeds when all the Promises finished, no matter if they succeed or not.

Example 1: return all the results

Without any optional arguments, PromiseList always succeeds. The result is a list of [succeed, result] pairs, where succeed is a boolean indicating if the related Promise succeeded or not, and result is the related result.

var p1 = Promise.resolv("1");
var p2 = Promise.reject("2");
var p3 = Promise.resolv("3");
var pl = PromiseList([p1, p2, p3]).then(cb);

function cb(results) {
    for (let [succeed, result] of results) {
        if (succeed) {
            doStuff(result);
        } else {
            // probably an instance of Error
            reportError(result);
        }
    }
}

Another example using Array.map and Array.filter:

var urls = [/*...*/];
var pl = PromiseList(urls.map(retrievePage))
    .then(results => results.filter([succeed, v] => succeed))
    .then(results => results.forEach(parsePage))

Example 2: mimic Promise.all()

PromiseList resolves if all the Promises resolve or rejects if one of them rejects.

From Mozilla's MDN:

Returns a promise that either resolves when all of the promises in the iterable argument have resolved or rejects as soon as one of the promises in the iterable argument rejects. If the returned promise resolves, it is resolved with an array of the values from the resolved promises in the iterable. If the returned promise rejects, it is rejected with the reason from the promise in the iterable that rejected. This method can be useful for aggregating results of multiple promises together.

The error, in case of failure, is always an instance of FirstError.

var p1 = Promise.resolv("1");
var p2 = Promise.reject(new Error("fail"));
var p3 = Promise.resolv("3");
var pl = PromiseList([p1, p2, p3], false, true).then(cb, eb);
// eb(err) [=> err.failure === new Error("fail")]

Example 3: mimic Promise.race()

From Mozilla's MDN:

Returns a promise that resolves or rejects as soon as one of the promises in the iterable resolves or rejects, with the value or reason from that promise.

var p1 = new Promise((res, rej) => {});  // don't resolv or reject
var p2 = Promise.resolv("2");
var p3 = Promise.reject(new Error("fail"));
var pl = PromiseList([p1, p2, p3], true, true).then(cb, eb);
// cb(["2", 1])

Example 4: resolve with the first successful Promise

var p1 = Promise((res, rej) => {});  // don't resolv or reject
var p2 = Promise.reject(new Error("fail"));
var p3 = Promise.resolv("3");
var pl = PromiseList([p1, p2, p3], true, false).then(cb);
// cb(["3", 2])

trap()

trap() is an utility to filter errors in a promise's catch clause. Consider this code:

try {
    doStuff();
}
catch(e) {
    if (e instanceof IOError) {
        handleIOError(e);
    } else if (e instanceof TypeError) {
        handleTypeError(e);
    } else {
        throw e;
    }
}

Translated to asynchronous code with Promises and trap() became:

function onIOError(failure) {
    trap(failure, IOError);
    handleIOError(failure);
}
function onTypeError(failure) {
    trap(failure, TypeError);
    handleTypeError(failure);
}
var promise = doStuff().catch(onIOError).catch(onTypeError);

execute()

Execute a function and return a Promise:

function func1() {
    return "sync";
}
execute(func1).then(v => v === "sync");

This function is useful if it is not known if a certain function returns a Promise or not.

function func1() {
    return "sync";
}
function func2() {
    return Promise.resolve("async");
}
var promises = [func1, func2].map(f => f());
PromiseList(promises).then(r => console.log(r));

vim: tw=72