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).
npm install --save promise-tools
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');
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.then(function(result) {console.log(result);});
deferred.resolve("Hello world!");
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!");});
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);
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"]
});
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".
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(...)