What is it?

There are a lot of nice Promise libraries out there like bluebird and q, with many handy functions that go above and beyond the small set of standard functions defined in the ECMAScript 2015 standard. But all of these libraries make you use their implementation of Promise (because all of them have been around since before Promises were part of the ECMAScript standard), and most of them are kind of on the big side (bluebird clocks in at almost 166k, unminified.)

The goal of promise-tools is to provide a small library of async-like functions, and some other handy functions, and let you use these functions on top of any Promise implementation.

(Also, if you're writing a library and you want to make it easy for your callers to use either Promises or callbacks, be sure to check out promise-breaker).

Installation

npm install --save promise-tools

Requirements

This library assumes that Promise is a defined global variable. If this is not the case on your platform, you can use a polyfill:

npm install --save es6-promise

Then somewhere in your node.js application:

require('es6-promise');

API

Collections

• map

Utilities

• defer
• delay

Control Flow

• parallel, parallelLimit
• series
• timeout
• whilst, doWhilst
• retry

Collections

map(arr, iterator, limit)

Calls iterator(item, index) for every item in map, which should return a Promise. If limit is specified, then at most limit calls to iterator will be started at a time (defaults to 1). Resolves to an array of items (the resolved value of each promise returned by iterator()). If any iterator rejects, this will reject immediately.

Utilities

defer()

Returns a {promise, resolve, reject} object. The returned promise will resolve or reject when resolve or reject are called.

Example:

var deferred = promiseTools.defer();
deferred.promise.then(function(result) {console.log(result);});
deferred.resolve("Hello world!");

delay(ms)

Returns a Promise which resolves after ms milliseconds have elapsed. The returned Promise will never reject.

Example:

console.log("start!");
promiseTools.delay(100)
.then(function() {console.log("end!");});

Control Flow

parallel(tasks, limit)

Alias: parallelLimit

Given an array of tasks, where each task is a function which takes no arguments and returns a Promise, executes each task in parallel (which is to say that all tasks will be started at once). If limit is supplied, then at most limit tasks will be started, and then as soon as any of these tasks complete a new task will be started to replace it.

Resolves to an array of equal length to tasks containing results returned by each task. If any task rejects, then this will reject immediately.

Example:

promiseTools.parallel([
    function() {return Promise.resolve("a");},
    function() {return "b";} // Note that raw return values are OK.
]).then(function(results) {
    // `results` will be ["a", "b"]
});

// Start 3 tasks, and then whenever a task completes will
// run another task, until all tasks are complete.
promiseTools.parallel(tasks, 3);

series(tasks)

Given an array of tasks, where each task is a function which takes no arguments and returns a Promise, executes each task one after another in series. A given task will not be started until the preceding task completes.

Resolves to an array of equal length to tasks containing results returned by each task. If any task rejects, then this will reject immediately.

Example:

promiseTools.series(
    function() {return Promise.resolve("a");}
    function() {return "b";} // Note that raw return values are OK.
).then(function(results) {
    // `results` will be ["a", "b"]
});

timeout(promise, ms)

Adds a timeout to an existing Promise.

Resolves to the same value as promise if promise resolves within ms milliseconds, otherwise the returned Promise will reject with the error "Timeout: Promise did not resolve within ${ms} milliseconds". The generated error will be an instance of promiseTools.TimeoutError.

Note that the underlying promise will continue to run, as there is no way to "cancel" a Promise in JavaScript.

Example:

// Will reject if `doSomething` takes longer than 500 milliseconds.
promiseTools.timeout(doSomething(), 500)
.then(...)

whilst(test, fn), doWhilst(fn, test)

While the synchronous function test() returns true, whilst will continuously execute fn(). fn() should return a Promise. whilst will resolve to the same value as the final call to fn(). If fn() or test() throw an error, then whilst() will reject immediately.

doWhilst() is similar to whilst(), but whilst() might execute fn() zero times if test() returns false on the first run, where doWhilst() is guaranteed to call fn() at least once. Note that the parameters are reversed between whilst() and doWhilst() to reflect the fact that one is "while /test/ do /fn/", and the other is "do /fn/ while /test/" (and to preserve API compatibility with async).

Example:

var count = 0;
promiseTools.whilst(
    () => count < 10, /* While count is less than 10... */
    function() {
        /* Do this... */
        count++;
        return Promise.resolve(count);
    }
)
.then(result => {
   // result will be 10 here.
});

retry(options, fn)

Will continuously call fn until it returns a synchronous value, doesn't throw, or returns a Promise that resolves. It will be retried options.times. You can pass {times: Infinity} to retry indefinitely. The fn will be passed the lastAttempt object which is the Error object of the last attempt.

Options: times (Default=5) and interval (Default=0). interval is the time between retries in milliseconds. If the options argument is passed as just a number, only times will be set.

Examples:

var count = 0;
promiseTools.retry({times: 4, interval: 5}, function(lastAttempt) {
    count++;
    if (count === 2) Promise.resolve(true);
    else Promise.reject(new Error('boom'));
})
.then(function(result) {
   // result will be `true` here.
});

---------------------------------------------

var count = 0;
promiseTools.retry(1, function(lastAttempt) {
    count++;
    if (count === 2) Promise.resolve(true);
    else Promise.reject(new Error('boom'));
})
.then(function(result) {
   // will not resolve.
})
.catch(function(err) {
    // err.message should be `boom` here.
});