async-as-promised is a utility module that provides straight-forward, powerful functions for working with Promise based JavaScript.
The functions contained within this module are modeled off the API provided by @caolan's excellent async module. This module is intended to provide a similar API for working with Promise based modules as async provides for callback based modules.
async-as-promised provides over twenty functions that include the usual 'functional' suspects (map
, reduce
,
filter
, each
…) as well as some common patterns for asynchronous control flow (parallel
, series
, waterfall
…).
var fs = require('fs');
var async = require('async-as-promised');
var statPromise = async.promisify(fs, fs.stat);
var existsPromise = async.promisify(fs, fs.exists);
async.map(['file1', 'file2', 'file3'], statPromise).then(function (results){
// results is now an array of stats for each file
});
async.parallel([
function(){}, // Functions that return promises when called
function(){},
function(){}
]).then(function (results){
// results is an array of the values the provided functions eventually resolved to.
});
async.series([ // Like async.parallel, except each function will be run only after the previous one has resolved
function(){}, // Functions that return promises when called
function(){},
function(){}
]).then(function (results){
// results is an array of the values the provided functions eventually resolved to.
});
This section is really about bind, not about async-as-promised. If you are wondering how to make async-as-promised execute your iterators in a given context, or are confused as to why a method of another library isn't working as an iterator, study this example:
// Here is a simple object with an (unnecessarily roundabout) squaring method
var PromiseSquaringLibrary = {
squareExponent: 2,
square: function(number, callback){
var result = Math.pow(number, this.squareExponent);
return Promise.resolve(result);
}
};
async.map([1, 2, 3], PromiseSquaringLibrary.square).then(function (result) {
// result is [NaN, NaN, NaN]
// This fails because the `this.squareExponent` expression in the square
// function is not evaluated in the context of PromiseSquaringLibrary, and is
// therefore undefined.
});
async.map([1, 2, 3], PromiseSquaringLibrary.square.bind(PromiseSquaringLibrary),).then(function(result) {
// result is [1, 4, 9]
// With the help of bind we can attach a context to the iterator before
// passing it to async. Now the square function will be executed in its
// 'home' PromiseSquaringLibrary context and the value of `this.squareExponent`
// will be as expected.
});
The source is available for download from GitHub.
Alternatively, you can install using Node package manager (npm
):
npm install async-as-promised
By default async-as-promised uses the global default Promise object (falling back to promise-polyfill if there is no global Promise object). However async-as-promised supports using any promises/A+ compliant promise library, such as bluebird
To change the Promise library used async-as-promised use the setPromise()
method as shown below:
var async = require('async-as-promised');
var bluebird = require('bluebird');
async.setPromise(bluebird);
// async-as-promised will now use bluebird promises for all functions
// to return to the default Promise type simply reset the Promise:
async.resetPromise();