# async-foreach

> An optionally-asynchronous forEach with an interesting interface.

Latest version **0.1.3** (published 2013-04-29) · 0 weekly downloads

## Install

```sh
npm install async-foreach
pnpm add async-foreach
yarn add async-foreach
bun add async-foreach
```

## Health

**Score 10/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; low quality score; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.3 |
| Published | 2013-04-29 |
| First published | 2012-01-11 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Node | * |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 75 |
| Author | "Cowboy" Ben Alman |
| Maintainers | cowboy |
| Keywords | array, loop, sync, async, foreach |

## Links

- npm: https://www.npmjs.com/package/async-foreach
- Repository: https://github.com/cowboy/javascript-sync-async-foreach
- Homepage: http://github.com/cowboy/javascript-sync-async-foreach
- Issues: https://github.com/cowboy/javascript-sync-async-foreach/issues
- npm.io page: https://npm.io/package/async-foreach

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 0.1.3 (latest) — 2013-04-29
- 0.1.2 — 2012-01-11

## README

# JavaScript Sync/Async forEach

An optionally-asynchronous forEach with an interesting interface.

## Getting Started

This code should work just fine in Node.js:

First, install the module with: `npm install async-foreach`

```javascript
var forEach = require('async-foreach').forEach;
forEach(["a", "b", "c"], function(item, index, arr) {
  console.log("each", item, index, arr);
});
// logs:
// each a 0 ["a", "b", "c"]
// each b 1 ["a", "b", "c"]
// each c 2 ["a", "b", "c"]
```

Or in the browser:

```html
<script src="dist/ba-foreach.min.js"></script>
<script>
forEach(["a", "b", "c"], function(item, index, arr) {
  console.log("each", item, index, arr);
});
// logs:
// each a 0 ["a", "b", "c"]
// each b 1 ["a", "b", "c"]
// each c 2 ["a", "b", "c"]
</script>
```

In the browser, you can attach the forEach method to any object.

```html
<script>
this.exports = Bocoup.utils;
</script>
<script src="dist/ba-foreach.min.js"></script>
<script>
Bocoup.utils.forEach(["a", "b", "c"], function(item, index, arr) {
  console.log("each", item, index, arr);
});
// logs:
// each a 0 ["a", "b", "c"]
// each b 1 ["a", "b", "c"]
// each c 2 ["a", "b", "c"]
</script>
```

## The General Idea (Why I thought this was worth sharing)

The idea is to allow the callback to decide _at runtime_ whether the loop will be synchronous or asynchronous. By using `this` in a creative way (in situations where that value isn't already spoken for), an entire control API can be offered without over-complicating function signatures.

```javascript
forEach(arr, function(item, index) {
  // Synchronous.
});

forEach(arr, function(item, index) {
  // Only when `this.async` is called does iteration becomes asynchronous. The
  // loop won't be continued until the `done` function is executed.
  var done = this.async();
  // Continue in one second.
  setTimeout(done, 1000);
});

forEach(arr, function(item, index) {
  // Break out of synchronous iteration early by returning false.
  return index !== 1;
});

forEach(arr, function(item, index) {
  // Break out of asynchronous iteration early...
  var done = this.async();
  // ...by passing false to the done function.
  setTimeout(function() {
    done(index !== 1);
  });
});
```

## Examples
See the unit tests for more examples.

```javascript
// Generic "done" callback.
function allDone(notAborted, arr) {
  console.log("done", notAborted, arr);
}

// Synchronous.
forEach(["a", "b", "c"], function(item, index, arr) {
  console.log("each", item, index, arr);
}, allDone);
// logs:
// each a 0 ["a", "b", "c"]
// each b 1 ["a", "b", "c"]
// each c 2 ["a", "b", "c"]
// done true ["a", "b", "c"]

// Synchronous with early abort.
forEach(["a", "b", "c"], function(item, index, arr) {
  console.log("each", item, index, arr);
  if (item === "b") { return false; }
}, allDone);
// logs:
// each a 0 ["a", "b", "c"]
// each b 1 ["a", "b", "c"]
// done false ["a", "b", "c"]

// Asynchronous.
forEach(["a", "b", "c"], function(item, index, arr) {
  console.log("each", item, index, arr);
  var done = this.async();
  setTimeout(function() {
    done();
  }, 500);
}, allDone);
// logs:
// each a 0 ["a", "b", "c"]
// each b 1 ["a", "b", "c"]
// each c 2 ["a", "b", "c"]
// done true ["a", "b", "c"]

// Asynchronous with early abort.
forEach(["a", "b", "c"], function(item, index, arr) {
  console.log("each", item, index, arr);
  var done = this.async();
  setTimeout(function() {
    done(item !== "b");
  }, 500);
}, allDone);
// logs:
// each a 0 ["a", "b", "c"]
// each b 1 ["a", "b", "c"]
// done false ["a", "b", "c"]

// Not actually asynchronous.
forEach(["a", "b", "c"], function(item, index, arr) {
  console.log("each", item, index, arr);
  var done = this.async()
  done();
}, allDone);
// logs:
// each a 0 ["a", "b", "c"]
// each b 1 ["a", "b", "c"]
// each c 2 ["a", "b", "c"]
// done true ["a", "b", "c"]

// Not actually asynchronous with early abort.
forEach(["a", "b", "c"], function(item, index, arr) {
  console.log("each", item, index, arr);
  var done = this.async();
  done(item !== "b");
}, allDone);
// logs:
// each a 0 ["a", "b", "c"]
// each b 1 ["a", "b", "c"]
// done false ["a", "b", "c"]
```

## Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using [grunt](https://github.com/cowboy/grunt).

_Also, please don't edit files in the "dist" subdirectory as they are generated via grunt. You'll find source code in the "lib" subdirectory!_

## Release History

04/29/2013
v0.1.3
Removed hard Node.js version dependency.

11/17/2011
v0.1.2
Adding sparse array support.
Invalid length properties are now sanitized.
This closes issue #1 (like a boss).

11/11/2011
v0.1.1
Refactored code to be much simpler. Yay for unit tests!

11/11/2011
v0.1.0
Initial Release.

## License
Copyright (c) 2012 "Cowboy" Ben Alman  
Licensed under the MIT license.  
<http://benalman.com/about/license/>

---
_Source: https://npm.io/package/async-foreach · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._