https://github.com/131/nyks
nodejs Exupery's style.
https://github.com/131/nyks
Last synced: about 1 year ago
JSON representation
nodejs Exupery's style.
- Host: GitHub
- URL: https://github.com/131/nyks
- Owner: 131
- License: mit
- Created: 2014-06-05T22:47:54.000Z (about 12 years ago)
- Default Branch: master
- Last Pushed: 2024-01-10T10:27:10.000Z (over 2 years ago)
- Last Synced: 2024-04-10T14:07:30.709Z (about 2 years ago)
- Language: JavaScript
- Size: 586 KB
- Stars: 6
- Watchers: 5
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README-async.md
- License: LICENSE
Awesome Lists containing this project
README
# 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)
------
[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.
------
## 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');
})();
```
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"