v5.1.3: remove deps, update link

.gitignore

@@ -0,0 +1 @@
+bower_components

README.md

@@ -1,49 +1,59 @@
-forEachAsync
+forEachAsync.js
 ===
 
-As I do every few years, I decided to rewrite FuturesJS.
+| A [Root](https://rootprojects.org) project
-This year's remake is extremely lightweight.
-
-v3.x - Diet Cola Edition
-(published on npm as beta, so you must use the @3.x - and don't worry, v2.x is still supported)
 
 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.
 
-Usage
+For cases where you want to loop through batches of items at once (as opposed to strictly one-by-one as forEachAsync does), check out [`forAllAsync`](https://github.com/FuturesJS/forAllAsync) and [`lateral`](https://github.com/FuturesJS/lateral).
-===
 
-It's as simple as you could guess:
+For cases where you want to loop through all items at once and we able to know when they're all done see [`join`](https://github.com/FuturesJS/join)
+
+v5.x
+----
+
+We jumped from 3.x to 5.x because I'm considering creating a backwards-and-forwards compatible 4.x that
+uses AngularJS-style function introspection to allow for having the next param.
+Straight up, that's probably a bad idea and waste of time so I hope I don't actually do it.
+
+Screencast
+---
+
+<https://youtu.be/O7egvEz4scA>
+
+Usage
+-----
 
 ```javascript
-  // waits for one request to finish before beginning the next
+  // EXAMPLE ASYNC FUNCTION
-  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
+  function getPicsAsync(animal) {
-  function getPics(animal, cb) {
+    var flickerApi = "http://api.flickr.com/services/feeds/photos_public.gne?tagmode=any&format=json&tags=" + animal;
-    var flickerAPI = "http://api.flickr.com/services/feeds/photos_public.gne?jsoncallback=?";
+
-    $.getJSON(
+    return requestAsync({ url: flickerApi });
-      flickerAPI
-    , { tags: thing
-      , tagmode: "any"
-      , format: "json"
-      , success: function (data) {
-          console.log('teh animals:', data);
-        }
-      , complete: cb
-      }
-    );
   }
 ```
 
+```javascript
+  forEachAsync(['dogs', 'cats', 'octocats'], function (element) {
+    return getPicsAsync(element);
+  }).then(function () {
+    // then after all of the elements have been handled
+    // the final callback fires to let you know it's all done
+    console.log('All requests have finished');
+  });
+```
+
+### Supplying your own Promises Implementation
+
+If native ES6 promises are not available, then you should supply your own Promises/A+
+implementation like so:
+
+```javascript
+  forEachAsync = forEachAsync.create(window.Promise || require('bluebird'));
+```
 
 Browser Installation
 ===
@@ -51,55 +61,32 @@ Browser Installation
 You can install from bower:
 
 ```bash
-bower install forEachAsync
+bower install --save forEachAsync@5.x
 ```
 
-Or download the raw file from <https://raw.github.com/FuturesJS/forEachAsync/master/forEachAsync.js>:
+Or download the raw file from <https://git.coolaj86.com/coolaj86/foreachasync.js/raw/branch/master/foreachasync.js>:
 
 ```bash
-wget https://raw.github.com/FuturesJS/forEachAsync/master/forEachAsync.js
+wget https://git.coolaj86.com/coolaj86/foreachasync.js/raw/branch/master/foreachasync.js
 ```
 
 ```javascript
 (function () {
   'use strict';
 
-  var forEachAsync = window.forEachAsync
+  var forEachAsync = window.forEachAsync;
-    ;
-
-  // do stuff ...
-}());
-```
-
-Or you can build it alongside other libraries:
-
-```bash
-npm install -g pakmanager
-npm install forEachAsync --save
-pakmanager -e browser build
-```
-
-```html
-<script src="pakmanaged.js"></script>
-```
-
-```javascript
-(function () {
-  'use strict';
-
-  var forEachAsync = require('forEachAsync').forEachAsync
-    ;
 
   // do stuff ...
 }());
 ```
 
+**Note**: If you need both 3.x/4.x and 5.x version of `forEachAsync` in the browser... good luck with that...
 
 Node Installation
 ===
 
 ```bash
-npm install --save forEachAsync@3.x
+npm install --save foreachasync@5.x
 ```
 
 API
@@ -111,7 +98,6 @@ 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
@@ -131,4 +117,4 @@ Internal API
 
 This is used internally for the purposes of the `ArrayAsync` library.
 
-Please don't `break` stuff; use `someAsync` or `everyAsync` instead.
+Please don't `break` stuff; use [`ArrayAsync`](https://github.com/FuturesJS/ArrayAsync)`.someAsync` or [`ArrayAsync`](https://github.com/FuturesJS/ArrayAsync)`.everyAsync` instead.

examples/browser/.gitignore

@@ -0,0 +1 @@
+*.html

examples/browser/build.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+bower install forEachAsync
+jade *.jade

examples/browser/foreach-settimeout.js

@@ -0,0 +1,21 @@
+window.addEventListener('load', function () {
+  'use strict';
+
+  function log() {
+    document.querySelector('#foreach-console').innerHTML +=
+      '\n' + Array.prototype.join.call(arguments, ' | ');
+    console.log.apply(console, arguments);
+  }
+
+  log('i', 'item', 'ms');
+  [2, 11, 37, 42].forEach(function (item, i) {
+    var ms = Math.floor(Math.random() * 1000)
+      ;
+
+    setTimeout(function () {
+      log(i, item, ms);
+    }, ms);
+  });
+
+  log('All Done');
+});

examples/browser/foreachasync-settimeout.js

@@ -0,0 +1,27 @@
+window.addEventListener('load', function () {
+  'use strict';
+
+  function log() {
+    document.querySelector('#foreachasync-console').innerHTML +=
+      '\n' + Array.prototype.join.call(arguments, ' | ');
+    console.log.apply(console, arguments);
+  }
+
+  var forEachAsync = window.forEachAsync
+    ;
+
+  log('i', 'item', 'ms');
+  forEachAsync([2, 11, 37, 42], function (item, i) {
+    var ms = Math.floor(Math.random() * 1000)
+      ;
+
+    return new Promise(function (resolve) {
+      setTimeout(function () {
+        log(i, item, ms);
+        resolve();
+      }, ms);
+    });
+  }).then(function () {
+    log('All Done');
+  });
+});

examples/browser/settimeout.jade

@@ -0,0 +1,14 @@
+doctype html
+html
+  head
+    title forEachAsync example
+    script(src="bower_components/forEachAsync/forEachAsync.js")
+    script(src="foreach-settimeout.js")
+    script(src="foreachasync-settimeout.js")
+  body
+    h1 Array.prototype.forEach
+    code
+      pre#foreach-console
+    h1 forEachAsync
+    code
+      pre#foreachasync-console

examples/node/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+testfiles

examples/node/foreach-fs-readdir.js

@@ -0,0 +1,20 @@
+'use strict';
+
+var fs = require('fs')
+  , path = require('path')
+  , dirpath = path.join(__dirname, 'testfiles')
+  ;
+
+fs.readdir(dirpath, function (err, nodes) {
+  nodes.forEach(function (node) {
+    var filepath = path.join(dirpath, node)
+      ;
+
+    console.log(filepath);
+    fs.readFile(filepath, null, function (err, contents) {
+      console.log(node, contents.length);
+    });
+  });
+
+  console.log('All Done');
+});

examples/node/foreachasync-fs-readdir.js

@@ -0,0 +1,22 @@
+'use strict';
+
+var PromiseA = require('bluebird')
+  , fs = PromiseA.promisifyAll(require('fs'))
+  , forEachAsync = require('foreachasync').forEachAsync
+  , path = require('path')
+  , dirpath = path.join(__dirname, 'testfiles')
+  ;
+
+fs.readdir(dirpath, function (err, nodes) {
+  forEachAsync(nodes, function (node) {
+    var filepath = path.join(dirpath, node)
+      ;
+
+    console.log(filepath);
+    return fs.readFileAsync(filepath, null).then(function (contents) {
+      console.log(node, contents.length);
+    });
+  }).then(function () {
+    console.log('All Done!');
+  });
+});

examples/node/make-files.sh

@@ -0,0 +1,8 @@
+mkdir -p testfiles
+touch ./testfiles/0b.bin
+dd bs=1m count=1 if=/dev/zero of=./testfiles/1mb.bin
+dd bs=1k count=64 if=/dev/zero of=./testfiles/64kb.bin
+dd bs=1k count=96 if=/dev/zero of=./testfiles/96kb.bin
+dd bs=1k count=1 if=/dev/zero of=./testfiles/1kb.bin
+# this will copy one block which could be between 512b and 4k (or more)
+dd bs=1b count=1 if=/dev/zero of=./testfiles/block.bin

forEachAsync.js

@@ -1,35 +0,0 @@
-/*jshint -W054 */
-;(function (exports) {
-  'use strict';
-
-  function forEachAsync(arr, fn, thisArg) {
-    var dones = []
-      , index = -1
-      ;
-
-    function next(BREAK, result) {
-      index += 1;
-
-      if (index === arr.length || BREAK === forEachAsync.__BREAK) {
-        dones.forEach(function (done) {
-          done.call(thisArg, result);
-        });
-        return;
-      }
-
-      fn.call(thisArg, next, arr[index], index, arr);
-    }
-
-    setTimeout(next, 4);
-
-    return {
-      then: function (_done) {
-        dones.push(_done);
-        return this;
-      }
-    };
-  }
-  forEachAsync.__BREAK = {};
-
-  exports.forEachAsync = forEachAsync;
-}('undefined' !== typeof exports && exports || new Function('return this')()));

foreachasync.js

@@ -0,0 +1,79 @@
+/*jshint -W054 */
+;(function (exports) {
+  'use strict';
+
+  var BREAK = {};
+  var exp = {};
+
+  function create(PromiseA) {
+    PromiseA = PromiseA.Promise || PromiseA;
+
+
+    function forEachAsync(arr, fn, thisArg) {
+      var result = PromiseA.resolve();
+
+      arr.forEach(function (item, k) {
+        result = result.then(function () {
+
+          var ret
+            ;
+
+          if (thisArg) {
+            ret = fn.call(thisArg, item, k, arr);
+          } else {
+            ret = result = fn(item, k, arr);
+          }
+
+          if (!ret || !ret.then) {
+            ret = PromiseA.resolve(ret);
+          }
+
+          return ret.then(function (val) {
+            if (val === forEachAsync.__BREAK) {
+              return PromiseA.reject(new Error('break'));
+              //throw new Error('break');
+            }
+
+            return val;
+          });
+        });
+      });
+
+      result.catch(function (e) {
+        if ('break' !== e.message) {
+          throw e;
+        }
+      });
+
+      return result;
+    }
+
+    forEachAsync.__BREAK = BREAK;
+
+    return forEachAsync;
+  }
+
+  /*
+  exp = forEachAsync.forEachAsync = forEachAsync;
+  exports = exports.forEachAsync = forEachAsync.forEachAsycn = forEachAsync;
+  exports.create = forEachAsync.create = function () {};
+  */
+
+  /* globals Promise */
+  if ('undefined' !== typeof Promise) {
+    exp.forEachAsync = create(Promise);
+  }
+  else {
+    try {
+     exp.forEachAsync = create(require('bluebird'));
+    } catch(e) {
+      console.warn("This version of node doesn't support promises. Please `npm install --save bluebird` in your project.");
+    }
+  }
+
+  exports.forEachAsync = exp.forEachAsync.forEachAsync = exp.forEachAsync || function () {
+    throw new Error("You did not supply a Promises/A+ implementation. See the warning above.");
+  };
+  exports.forEachAsync.create = create;
+
+}('undefined' !== typeof exports && exports || window));

package-lock.json

@@ -0,0 +1,5 @@
+{
+  "name": "foreachasync",
+  "version": "5.1.3",
+  "lockfileVersion": 1
+}

package.json

@@ -1,9 +1,10 @@
 {
-  "name": "forEachAsync",
+  "name": "foreachasync",
-  "version": "3.0.0",
+  "version": "5.1.3",
-  "description": "A node- and browser-ready async counterpart of Array.prototype.forEach",
+  "description": "A node- and browser-ready async (now with promises) counterpart of Array.prototype.forEach",
-  "homepage": "https://github.com/FuturesJS/forEachAsync",
+  "homepage": "https://git.coolaj86.com/coolaj86/foreachasync.js",
-  "main": "forEachAsync.js",
+  "main": "foreachasync.js",
+  "files": [],
   "directories": {
     "test": "test"
   },
@@ -12,7 +13,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git://github.com/FuturesJS/forEachAsync.git"
+    "url": "https://git.coolaj86.com/coolaj86/foreachasync.js.git"
   },
   "keywords": [
     "futuresjs",
@@ -21,11 +22,17 @@
     "forEachAsync",
     "async",
     "futures",
+    "promise",
+    "promises",
     "each"
   ],
-  "author": "AJ ONeal <coolaj86@gmail.com> (http://coolaj86.com/)",
+  "trulyOptionalDependencies": {
-  "license": "Apache2",
+    "bluebird": "^3.5.1"
+  },
+  "author": "AJ ONeal <coolaj86@gmail.com> (https://coolaj86.com/)",
+  "license": "(MIT OR Apache-2.0)",
   "bugs": {
-    "url": "https://github.com/FuturesJS/forEachAsync/issues"
+    "url": "https://git.coolaj86.com/coolaj86/foreachasync.js/issues"
-  }
+  },
+  "dependencies": {}
 }

test-bluebird.js

@@ -0,0 +1,37 @@
+(function () {
+  "use strict";
+
+  var PromiseA = require('bluebird');
+  var forEachAsync = require('./forEachAsync').forEachAsync;
+  var context = {};
+
+  forEachAsync([0, 500, 70, 200, 400, 100], function (element, i, arr) {
+    console.log(i, '/', arr.length, 'began');
+
+    var result;
+
+    // test that thisness is applied
+    this[element] = i;
+
+    if (i % 2) {
+      // test that synchronous callbacks don't mess things up
+      result = PromiseA.resolve();
+    } else {
+      // test asynchronous callbacks
+      result = new PromiseA(function (resolve/*, reject*/) {
+        setTimeout(resolve, element);
+      });
+    }
+
+    return result.then(function () {
+      // test that array order is as expected
+      console.log(i, '/', arr.length, 'complete');
+    });
+  }, context).then(function () {
+    // test that thisness carried
+    console.log('context', context);
+  }).then(function () {
+    // test then chaining
+    console.log("now wasn't that nice?");
+  });
+}());

test-native.js

@@ -0,0 +1,35 @@
+(function () {
+  "use strict";
+
+  /* globals Promise */
+  var forEachAsync = require('./forEachAsync').forEachAsync.create(Promise);
+  var context = {};
+
+  forEachAsync([0, 500, 70, 200, 400, 100], function (element, i, arr) {
+    var p;
+
+    // test that thisness is applied
+    this[element] = i;
+
+    if (i % 2) {
+      // test that synchronous callbacks don't mess things up
+      p = Promise.resolve();
+    } else {
+      // test asynchronous callbacks
+      p = new Promise(function (resolve/*, reject*/) {
+        setTimeout(resolve, element);
+      });
+    }
+
+    return p.then(function () {
+      // test that array order is as expected
+      console.log(element, 'is element', i, 'of', arr.length);
+    });
+  }, context).then(function () {
+    // test that thisness carried
+    console.log('context', context);
+  }).then(function () {
+    // test then chaining
+    console.log("now wasn't that nice?");
+  });
+}());

test.js

@@ -1,29 +0,0 @@
-(function () {
-  "use strict";
-
-  var forEachAsync = require('./forEachAsync').forEachAsync
-    ;
-
-  forEachAsync([0, 500, 70, 200, 400, 100], function (next, element, i, arr) {
-    // test that array order is as expected
-    console.log(element, 'is element', i, 'of', arr.length);
-
-    // test that thisness is applied
-    this[element] = i;
-
-    if (i > 2) {
-      // test that synchronous callbacks don't mess things up
-      next();
-    } else {
-      // test asynchronous callbacks
-      setTimeout(next, element);
-    }
-  }, {}).then(function () {
-    // test that thisness carries
-    console.log(this);
-  }).then(function () {
-    // test then chaining
-    console.log("now wasn't that nice?");
-  });
-
-}());