Do asynchronous iteration on sets of deferred data.
npm install async-iteration[![License][license-image]][license-url]
[![Build status][travis-image]][travis-url]
Enables asynchronous iteration on sets of deferred data.
* Installation
* Examples
* Basic
* Advanced
* API
* License
##### As a node package
``
npm install async-iteration
##### As a standalone source
Download [uncompressed] or [minified] source.
This NPM package is transpiled using [Babel] to support ES5 environments, but
the linked standalone sources aren't. You'll need to transpile them yourself
in your project if support of older environments is needed.
#### Basic example
##### With es8 async functions
`js
const AsyncIteration = require('async-iteration');
const iteration = AsyncIteration(async (include) => {
include(3);
await new Promise((res) => { setTimeout(res, 1000); }); // Wait for 1 second
include(4);
include(2);
// Population finishes when this async function resolves
// (subsequent calls to include will throw an error)
});
// Iterate asynchronously
(async () => {
for (const iter = iteration.iterate(); await iter();) {
console.log(iter.result);
}
})();
// Wait for completion
(async () => {
const values = await iteration.promise();
console.log('completed!');
console.log(values);
})();
`
Outputs:
`
3
4
2
completed!
[3, 4, 2]
##### With es6 promises only
`js
var AsyncIteration = require('async-iteration');
var iteration = AsyncIteration(function (include) {
// Population finishes when the returned promise resolves
// (subsequent calls to include will throw an error)
return new Promise(function (resolve, reject) {
include(3);
setTimeout(resolve, 1000); // wait for 1 second
}).then(function () {
include(4);
include(2);
});
});
// Iterate asynchronously
var iter = iteration.iterate();
iter().then(function iterate(more) {
if (!more) return;
console.log(iter.result);
iter().then(iterate);
});
// Wait for completion
iteration.promise().then(function (values) {
console.log('completed!');
console.log(values);
});
`
Outputs:
`
3
4
2
completed!
[3, 4, 2]
#### Advanced example: reading files using [mz]
##### With es8 async functions
`js
const { readFile } = require('mz/fs');
const AsyncIteration = require('async-iteration');
const files = ['path/to/file1', 'path/to/file2', 'path/to/file3'];
const results = AsyncIteration(async (include) => {
// Read all files, order will depend on read speed,
// the first files to be read are the first to be included
await Promise.all(files.map((file) => (async () => {
const content = await readFile(file, 'utf8');
include({ file, content });
})()));
});
(async () => {
// Iterate asynchronously through results
for (const iter = results.iterate(); await iter();) {
const { file, content } = iter.result;
console.log(file);
console.log(content);
}
// Note: It is possible to handle eventual errors, iter doesn't silence`
// errors, it will throw if readFile throws.
})();
Possible output:
`
path/to/file2
... (content of file2)
path/to/file1
... (content of file1)
path/to/file3
... (content of file3)
##### With es6 promises only
`js
var readFile = require('mz/fs').readFile;
var AsyncIteration = require('async-iteration');
var files = ['path/to/file1', 'path/to/file2', 'path/to/file3'];
var results = AsyncIteration(function (include) {
// Read all files, order will depend on read speed,
// the first files to be read are the first to be included
var promises = [];
files.forEach(function (file) {
var promise = readFile(file, 'utf8').then(function (content) {
include({
file: file,
content: content
});
});
promises.push(promise);
});
return Promise.all(promises);
});
// Iterate asynchronously through results
var iter = results.iterate();
iter().then(function iterate(more) {
if (!more) return;
var file = iter.result.file;
var content = iter.result.content;
console.log(file);
console.log(content);
iter().then(iterate);
});
// Note: It is possible to handle eventual errors with Promise.prototype.catch,
// iter doesn't silence errors, it will reject if readFile rejects.
`
Possible output:
`
path/to/file2
... (content of file2)
path/to/file1
... (content of file1)
path/to/file3
... (content of file3)
* __AsyncIteration factory__
var iteration = AsyncIteration(asyncFn);
Factory function that creates and returns a plain object used for asynchronous
iteration.
* __asyncFn__
async (include) => { ... }
[ES8 async function][async-funcs] or function that returns an
[ES6 promise][promises]. It will be invoked
immediately with an __include__ parameter.
* __include__
include(val);
Function passed as parameter to __asyncFn__. It accepts one argument.asyncFn
It can be invoked before ____ resolves to resolve the nextasyncFn
deferred value. It will throw an error if it is invoked after
____ resolves.
* __iteration__
var iter = iteration.iterate();
var promise = iteration.promise();
Plain object used for iterating asynchronously through the values resolved
by __asyncFn__.
* __iter__
for (const iter = iteration.iterate(); await iter();)
{ const { result } = iter; ... }
Function that on its Nth invocation will promise the
Nth value inclusion by __asyncFn__. It always returns aresult
promise that always resolves a boolean telling if the iteration has
concluded or not. It has a property that will contain theasyncFn
Nth included value on resultion of its Nth returned
promise. If ____ rejects at some point, the returned promisesasyncFn
after after the included values will all reject with the same error of
____.
* __promise__
const values = await promise;
Promise that resolves an array of all included values after __asyncFn__asyncFn
resolves. If ____ rejects, the promise will reject the same errorasyncFn`__.
of __
MIT
[Babel]: https://babeljs.io/
[uncompressed]: build/async-iteration.js
[minified]: build/async-iteration.min.js
[mz]: https://github.com/normalize/mz#mz---modernize-nodejs
[license-image]: https://img.shields.io/badge/license-MIT-blue.svg
[license-url]: LICENSE
[travis-image]: https://travis-ci.org/JD342/async-iteration.svg?branch=master
[travis-url]: https://travis-ci.org/JD342/async-iteration
[async-funcs]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
[promises]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise