# Async Control flow ala ES7 async/await with async.js (v2) signatures ------ ## Table of Contents * [Motivation](#Motivation) * [API](#API) * [eachLimit()](#eachLimit) * [eachOfLimit()](#eachOfLimit) * [each()](#each) * [eachOf()](#eachOf) * [eachSeries()](#eachSeries) * [eachOfSeries()](#eachOfSeries) * [retryUntil()](#retryUntil) * [sleep()](#sleep) * [timeout()](#timeout) * [setImmediate()](#setImmediate) * [queue()](#queue) * [throttle()](#throttle) * [Tests](#Tests) * [TODO](#TODO) * [Credits](#Credits) * [Alternatives / relatives](#Alternatives) * [Shoutbox, keywords, SEO love](#keywords) ------ # Motivation [nyks/async](./async/) provide javascript async/await equivalent signatures of the excellent [async](https://github.com/caolan/async) workflow library. Module are exported in standard commonJS module format and written in strict format. (no transpilation required nor used). Use browserify if you need nyks/async modules in a browser environnement. **nyks/async** is not a wrapper on **async**, but rather leverages the full potential of native async/await & promises contract. Code tend to be small & very efficient (far more simplier than using callbacks), just give [nyks/async/queue.js](./async/queue.js) a look. ## Addition to the async library signatures / promise pooling * Async functions cannot use arrow function binding style, yet it might be usefull to bind nyks/async closure, therefore, you can use an extra optional args to all signature to set async function binding context. (i.e. as in native [.forEach](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach) ) * Per design, it's easy to "throttle" a function that return a Promise ; checkout the "throttle" API for a way to make an ultra simple http request pooling. * async logic allow async/each to iterate through array AND objects. Per design sanify, nyks/async does not. Use each/eachLimit/eachSeries for arrays, eachOf/eachOfLimit/eachOfSeries for collections. ------ # API ## eachLimit(arr, concurrency, thunk [, thisobj]) : Promise Applies the function 'thunk' to each item in 'arr', in parallel, with a limit async operations of 'concurrency' at a time. The 'thunk' is called with an item from the Array 'arr'. ```javascript const eachLimit = require('nyks/async/eachLimit'); (async function() { var stuffs = [1, 2, 3, 5, 6]; await eachLimit(stuffs, 2, async function(id) { await dootherStuffs(id); }); })(); ``` ------ ## eachOfLimit(dict, concurrency, thunk [, thisobj]) : Promise Applies the function 'thunk' to each item of 'dict', in parallel, with a limit async operations of 'concurrency' at a time. The 'thunk' is called with an item from the Object 'dict'. ```javascript const eachOfLimit = require('nyks/async/eachOfLimit'); (async function() { var stuffs = { 'number' : 1, 'number' : 2, 'number' : 3, 'number' : 4 }; await eachOfLimit(stuffs, 2, async function(id, key) { await dootherStuffs(id); }); })(); ``` ------ ## each(arr, thunk [, thisobj]) : Promise Like eachLimit with a concurrency of arr.length. ```javascript const each = require('nyks/async/each'); (async function() { var stuffs = [1, 2, 3, 5, 6]; await each(stuffs, async function(id) { await dootherStuffs(id); }); })(); ``` ------ ## eachOf(dict, thunk [, thisobj]) : Promise Like eachOfLimit with a concurrency of dict.length. ```javascript const eachOf = require('nyks/async/eachOf'); (async function() { var stuffs = { 'number' : 1, 'number' : 2, 'number' : 3, 'number' : 4 }; await eachOf(stuffs, async function(id, key) { await dootherStuffs(id); }); })(); ``` ------ ## eachSeries(arr, thunk [, thisobj]) : Function Like eachLimit with a concurrency of 1. ```javascript const eachSeries = require('nyks/async/eachSeries'); (async function() { var stuffs = [1, 2, 3, 5, 6]; await eachSeries(stuffs, async function(id) { await dootherStuffs(id); }); })(); ``` ------ ## eachOfSeries(dict, thunk [, thisobj]) : Function Like eachOfLimit with a concurrency of 1. ```javascript const eachOfSeries = require('nyks/async/eachOfSeries'); (async function() { var stuffs = { 'number' : 1, 'number' : 2, 'number' : 3, 'number' : 4 }; await eachOfSeries(stuffs, async function(id, key) { await dootherStuffs(id); }); })(); ``` ------ ## retryUntil(thunk, timeout, delay, [, failure]) : Function Run thunk until it resolves a truthy value, until timeout is reached. Wait **delay** between each attempt. On timeout, reject with a generic "Timeout" error message (or the specified failure, if any). ```javascript const retryUntil = require('nyks/async/retryUntil'); (async function() { await tryUntil(async () => { return net.connect(...) }, 60 * 1000, 1000, 'Could not connect to remote socket'); })(); ``` ## sleep(delay) : Promise setTimeout as a promise. ```javascript const sleep = require('nyks/async/sleep'); (async function() { // this is now await sleep(2000); // this is now + 2 secondes })(); ``` ------ ## timeout(delay, [, reason]) : Promise return a Promise that reject after delay (with reason = 'timeout') ```javascript const timeout = require('nyks/async/timeout'); (async function() { await timeout(1000); // this will throw with message 'timeout' })(); ``` ------ ## setImmediate(fn) : Function Call a function in javascript next tick (using setImmediate API, or timeout 0 pollyfill) ```javascript const setImmediate = require('nyks/async/setImmediate'); (async function() { // this is now await setImmediate(); // this is still now... })(); ``` ------ ## queue(thunk, concurrency) : Object Return a QueueObject you can push task into. Wait for thunk to process task (wait for worker, if needed). ```javascript const fetch = require('node-fetch'); const queue = require('nyks/async/queue'); var q = queue(fetch, 1); //let's be nice (async function() { await q.push("http://example.com/stuff.json"); })(); (async function() { await q.push("http://example.com/otherstuff.json"); //will wait for stuff to be retrieved })(); ``` ------ ## throttle(thunk, concurrency) : Function Throttle any function that return a promise, sugar syntax helper for nyks/async/queue. ```javascript const fetch = require('node-fetch'); const throttle = require('nyks/async/throttle'); fetch = throttle(fetch, 1); //make fetch behave nicely (async function() { await fetch("http://example.com/stuff.json"); })(); (async function() { await fetch("http://example.com/otherstuff.json"); //will wait for stuff.json to be retrieved })(); ``` ------ # Tests nyks/async is tested against async test suite (of course) ------ # TODO * Get rich or die tryin' * write a working nyks/async/cargo (see [the challenge on stackoverflow](http://stackoverflow.com/questions/39069624)) ------ # Credits * [131](https://github.com/131) * inspired from the excellent [async](https://github.com/caolan/async) * Derived from [async-co](https://github.com/131/async-co) ------ # Alternatives / relatives * [koa-async](https://github.com/eladnava/koa-async); a clever Promisify wrapper on top of async (but not leveraging the full potential of ES7 async/await capabilities) * [caolan/async/asyncify.js](https://github.com/caolan/async/blob/master/lib/asyncify.js); goes the same as koa-async. * [es6-promise-pool](https://github.com/timdp/es6-promise-pool); equivalent to nyks/async/queue, with a different API ------ # Shoutbox, keywords, SEO love async/await, co, nyks/async, promise, Promises, yield, async, queue, map, throttle, "Let's have a beer & talk in Paris"