foreachasync.js/README.md

135 lines
3.0 KiB
Markdown
Raw Normal View History

2013-08-06 09:44:04 +00:00
forEachAsync
===
Analogous to `[].forEach`, but handles items asynchronously with a final callback passed to `then`.
This is the most essential piece of the [`ArrayAsync`](https://github.com/FuturesJS/ArrayAsync) package.
v3.x - Diet Cola Edition
---
As I do every few years, I decided to rewrite FuturesJS.
This year's remake is extremely lightweight.
2013-08-06 09:44:04 +00:00
Usage
===
It's as simple as you could guess:
```javascript
// waits for one request to finish before beginning the next
forEachAsync(['dogs', 'cats', 'octocats'], function (next, element, index, array) {
getPics(element, next);
// then after all of the elements have been handled
// the final callback fires to let you know it's all done
}).then(function () {
console.log('All requests have finished');
});
// where `getPics` might be an asynchronous web request such as this
2013-08-06 09:44:04 +00:00
function getPics(animal, cb) {
var flickerAPI = "http://api.flickr.com/services/feeds/photos_public.gne?jsoncallback=?";
$.getJSON(
flickerAPI
, { tags: thing
2013-08-06 09:52:14 +00:00
, tagmode: "any"
2013-08-06 09:44:04 +00:00
, format: "json"
, success: function (data) {
console.log('teh animals:', data);
}
, complete: cb
}
);
}
```
Browser Installation
===
2014-01-12 07:48:18 +00:00
You can install from bower:
2013-08-06 09:44:04 +00:00
2014-01-12 07:48:18 +00:00
```bash
bower install forEachAsync
```
Or download the raw file from <https://raw.github.com/FuturesJS/forEachAsync/master/forEachAsync.js>:
```bash
wget https://raw.github.com/FuturesJS/forEachAsync/master/forEachAsync.js
2013-08-06 09:44:04 +00:00
```
```javascript
(function () {
'use strict';
var forEachAsync = window.forEachAsync
;
// do stuff ...
}());
```
Or you can build it alongside other libraries:
```bash
npm install -g pakmanager
2014-01-13 23:06:56 +00:00
npm install forEachAsync --save
2013-08-06 09:44:04 +00:00
pakmanager -e browser build
```
```html
<script src="pakmanaged.js"></script>
```
```javascript
(function () {
'use strict';
var forEachAsync = require('forEachAsync').forEachAsync
;
// do stuff ...
}());
```
Node Installation
===
```bash
npm install --save forEachAsync@3.x
```
API
===
**`forEachAsync(array, callback[, thisArg])`**
Parameters
* `array` Array of elements to iterate over
* `callback` Function to execute for each element, takes 4 arguments
* `next` the function to call when the current element has been dealt with
* `element` a single element of the aforementioned array
* `index` the index of the current element
* `array` the same array mentioned above
* `thisArg` Object to use as `this` when executing `callback`
**`forEachAsync#then(done)`**
Parameters
* `then` is in the return value of `forEachAsync` and accepts a final `done` callback.
* `done` called after `forEachAsync` is complete, takes no arguments
Internal API
===
`forEachAsync.__BREAK`
This is used internally for the purposes of the `ArrayAsync` library.
Please don't `break` stuff; use [`ArrayAsync`](https://github.com/FuturesJS/ArrayAsync)`.someAsync` or [`ArrayAsync`](https://github.com/FuturesJS/ArrayAsync)`.everyAsync` instead.