README.md

asyncp

asyncp is a port of the async library to use Promises instead of Node.js callbacks.

Installation

npm install asyncp

You could also download an archive (zip or tar.gz) from the asyncp Github Releases.

Node.js & Browser

Currently, asyncp has been tested against Node.js 4.x and 6.x. asyncp is written in ES2015, but transpiled to ES5 using Babel. The distributed npm package contains only ES5 source code.

TODO: The npm package is also distributed with a single complete file of asyncp and a single minified file of asyncp. The complete files are located in asyncp/dist/asyncp{.min}.js.

Another benefit of asyncp is that it uses the native Promise implementation. This means you can use the native implementation or another library that implements/shims the Promise/A+ specification (e.g. When.js, Bluebird, Q).

Usage

const async = require('asyncp');
const p = async.map([1, 2, 3], value => {
    switch (value) {
        // delayed promise
        case 1:
            return new Promise(resolve => setTimeout(resolve.bind(null, value), 25));
        // sync promise
        case 2:
            return new Promise(resolve => resolve(value));
        // sync return
        case 3:
            return value;
    }
});

p.then(console.log); // [1, 2, 3];

Or, you can require/import individual functions:

const map = require('asyncp/map');
const p = map([1, 2, 3], value => {
    switch (value) {
        // delayed promise
        case 1:
            return new Promise(resolve => setTimeout(resolve.bind(null, value), 25));
        // sync promise
        case 2:
            return new Promise(resolve => resolve(value));
        // sync return
        case 3:
            return value;
    }
});

p.then(console.log); // [1, 2, 3];

Documentation

API documentation is coming soon, but...

Because this is a port of the async library, the API should be the same. Existing async documentation can be found here. The biggest difference is that there won't be a final callback argument. Instead of the callback, the resolved Promise is equivalent.

Another difference is when an async iteratee, task, callback, etc... could allow multiple result arguments, they will be represented as an array of results in the resolved Promise. This concept is similar to Bluebird.spread.

Missing Implementations

The following functions in async are missing from asyncp. Some of the functions are not all that useful when working with Promises, but contributions are welcome!

Control Flow

• auto
• autoInject
• cargo
• priorityQueue
• race => Use Promise.race.
• queue

Utils

• apply => Use function.bind.
• asyncify
• constant => Use lodash#constant.
• dir
• ensureAsync
• log
• memoize => Use lodash#memoize
• nextTick
• reflectAll
• reflect
• setImmediate
• unmemoize

"Gotchas"

• When using collection functions (each, eachOf, detect, etc...), the collection passed into the iteratee is a reference. This means that for each iteration, it's possible to modify the source collection. It's recommended to use the the collection as a read-only reference. This is especially important with *Series and *Limit methods as the iteratee is not called in the same tick as the original function call.

Credits

Much thanks to Brian Cavalier and others in the #cujojs room on freenode!

Also, thanks for David Bushong for inspiration from his async-q library.

License

MIT