rename forEach functions to each and add aliases for old names

3 files changed, 95 insertions, 74 deletions

diff --git a/README.md b/README.md
index d7ab284..879bccd 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ use with [node.js](http://nodejs.org), it can also be used directly in the
 browser.
 
 Async provides around 20 functions that include the usual 'functional'
-suspects (map, reduce, filter, forEach…) as well as some common patterns
+suspects (map, reduce, filter, each…) as well as some common patterns
 for asynchronous control flow (parallel, series, waterfall…). All these
 functions assume you follow the node.js convention of providing a single
 callback as the last argument of your async function.
@@ -72,7 +72,7 @@ So far its been tested in IE6, IE7, IE8, FF3.6 and Chrome 5. Usage:
 
 ### Collections
 
-* [forEach](#forEach)
+* [each](#each)
 * [map](#map)
 * [filter](#filter)
 * [reject](#reject)
@@ -114,12 +114,13 @@ So far its been tested in IE6, IE7, IE8, FF3.6 and Chrome 5. Usage:
 ## Collections
 
 <a name="forEach" />
-### forEach(arr, iterator, callback)
+<a name="each" />
+### each(arr, iterator, callback)
 
 Applies an iterator function to each item in an array, in parallel.
 The iterator is called with an item from the list and a callback for when it
 has finished. If the iterator passes an error to this callback, the main
-callback for the forEach function is immediately called with the error.
+callback for the each function is immediately called with the error.
 
 Note, that since this function applies the iterator to each item in parallel
 there is no guarantee that the iterator functions will complete in order.
@@ -140,7 +141,7 @@ __Example__
 // assuming openFiles is an array of file names and saveFile is a function
 // to save the modified contents of that file:
 
-async.forEach(openFiles, saveFile, function(err){
+async.each(openFiles, saveFile, function(err){
     // if any of the saves produced an error, err would equal that error
 });
 ```
@@ -148,9 +149,10 @@ async.forEach(openFiles, saveFile, function(err){
 ---------------------------------------
 
 <a name="forEachSeries" />
-### forEachSeries(arr, iterator, callback)
+<a name="eachSeries" />
+### eachSeries(arr, iterator, callback)
 
-The same as forEach only the iterator is applied to each item in the array in
+The same as each only the iterator is applied to each item in the array in
 series. The next iterator is only called once the current one has completed
 processing. This means the iterator functions will complete in order.
 
@@ -158,9 +160,10 @@ processing. This means the iterator functions will complete in order.
 ---------------------------------------
 
 <a name="forEachLimit" />
-### forEachLimit(arr, limit, iterator, callback)
+<a name="eachLimit" />
+### eachLimit(arr, limit, iterator, callback)
 
-The same as forEach only no more than "limit" iterators will be simultaneously 
+The same as each only no more than "limit" iterators will be simultaneously 
 running at any time.
 
 Note that the items are not processed in batches, so there is no guarantee that
@@ -184,7 +187,7 @@ __Example__
 // Assume documents is an array of JSON objects and requestApi is a
 // function that interacts with a rate-limited REST api.
 
-async.forEachLimit(documents, 20, requestApi, function(err){
+async.eachLimit(documents, 20, requestApi, function(err){
     // if any of the saves produced an error, err would equal that error
 });
 ```
diff --git a/lib/async.js b/lib/async.js
index 7305d9a..3ebad60 100755
--- a/lib/async.js
+++ b/lib/async.js
@@ -27,7 +27,7 @@
 
     //// cross-browser compatiblity functions ////
 
-    var _forEach = function (arr, iterator) {
+    var _each = function (arr, iterator) {
         if (arr.forEach) {
             return arr.forEach(iterator);
         }
@@ -41,7 +41,7 @@
             return arr.map(iterator);
         }
         var results = [];
-        _forEach(arr, function (x, i, a) {
+        _each(arr, function (x, i, a) {
             results.push(iterator(x, i, a));
         });
         return results;
@@ -51,7 +51,7 @@
         if (arr.reduce) {
             return arr.reduce(iterator, memo);
         }
-        _forEach(arr, function (x, i, a) {
+        _each(arr, function (x, i, a) {
             memo = iterator(memo, x, i, a);
         });
         return memo;
@@ -89,13 +89,13 @@
         async.nextTick = process.nextTick;
     }
 
-    async.forEach = function (arr, iterator, callback) {
+    async.each = function (arr, iterator, callback) {
         callback = callback || function () {};
         if (!arr.length) {
             return callback();
         }
         var completed = 0;
-        _forEach(arr, function (x) {
+        _each(arr, function (x) {
             iterator(x, only_once(function (err) {
                 if (err) {
                     callback(err);
@@ -110,8 +110,9 @@
             }));
         });
     };
+    async.forEach = async.each;
 
-    async.forEachSeries = function (arr, iterator, callback) {
+    async.eachSeries = function (arr, iterator, callback) {
         callback = callback || function () {};
         if (!arr.length) {
             return callback();
@@ -143,13 +144,15 @@
         };
         iterate();
     };
+    async.forEachSeries = async.eachSeries;
 
-    async.forEachLimit = function (arr, limit, iterator, callback) {
-        var fn = _forEachLimit(limit);
+    async.eachLimit = function (arr, limit, iterator, callback) {
+        var fn = _eachLimit(limit);
         fn.apply(null, [arr, iterator, callback]);
     };
+    async.forEachLimit = async.eachLimit;
 
-    var _forEachLimit = function (limit) {
+    var _eachLimit = function (limit) {
 
         return function (arr, iterator, callback) {
             callback = callback || function () {};
@@ -193,19 +196,19 @@
     var doParallel = function (fn) {
         return function () {
             var args = Array.prototype.slice.call(arguments);
-            return fn.apply(null, [async.forEach].concat(args));
+            return fn.apply(null, [async.each].concat(args));
         };
     };
     var doParallelLimit = function(limit, fn) {
         return function () {
             var args = Array.prototype.slice.call(arguments);
-            return fn.apply(null, [_forEachLimit(limit)].concat(args));
+            return fn.apply(null, [_eachLimit(limit)].concat(args));
         };
     };
     var doSeries = function (fn) {
         return function () {
             var args = Array.prototype.slice.call(arguments);
-            return fn.apply(null, [async.forEachSeries].concat(args));
+            return fn.apply(null, [async.eachSeries].concat(args));
         };
     };
 
@@ -237,7 +240,7 @@
     // reduce only has a series version, as doing reduce in parallel won't
     // work in many situations.
     async.reduce = function (arr, memo, iterator, callback) {
-        async.forEachSeries(arr, function (x, callback) {
+        async.eachSeries(arr, function (x, callback) {
             iterator(memo, x, function (err, v) {
                 memo = v;
                 callback(err);
@@ -328,7 +331,7 @@
     async.detectSeries = doSeries(_detect);
 
     async.some = function (arr, iterator, main_callback) {
-        async.forEach(arr, function (x, callback) {
+        async.each(arr, function (x, callback) {
             iterator(x, function (v) {
                 if (v) {
                     main_callback(true);
@@ -344,7 +347,7 @@
     async.any = async.some;
 
     async.every = function (arr, iterator, main_callback) {
-        async.forEach(arr, function (x, callback) {
+        async.each(arr, function (x, callback) {
             iterator(x, function (v) {
                 if (!v) {
                     main_callback(false);
@@ -407,7 +410,7 @@
             }
         };
         var taskComplete = function () {
-            _forEach(listeners.slice(0), function (fn) {
+            _each(listeners.slice(0), function (fn) {
                 fn();
             });
         };
@@ -419,7 +422,7 @@
             }
         });
 
-        _forEach(keys, function (k) {
+        _each(keys, function (k) {
             var task = (tasks[k] instanceof Function) ? [tasks[k]]: tasks[k];
             var taskCallback = function (err) {
                 if (err) {
@@ -503,7 +506,7 @@
         }
         else {
             var results = {};
-            eachfn.forEach(_keys(tasks), function (k, callback) {
+            eachfn.each(_keys(tasks), function (k, callback) {
                 tasks[k](function (err) {
                     var args = Array.prototype.slice.call(arguments, 1);
                     if (args.length <= 1) {
@@ -519,11 +522,11 @@
     };
 
     async.parallel = function (tasks, callback) {
-        _parallel({ map: async.map, forEach: async.forEach }, tasks, callback);
+        _parallel({ map: async.map, each: async.each }, tasks, callback);
     };
 
     async.parallelLimit = function(tasks, limit, callback) {
-        _parallel({ map: _mapLimit(limit), forEach: _forEachLimit(limit) }, tasks, callback);
+        _parallel({ map: _mapLimit(limit), each: _eachLimit(limit) }, tasks, callback);
     };
 
     async.series = function (tasks, callback) {
@@ -543,7 +546,7 @@
         }
         else {
             var results = {};
-            async.forEachSeries(_keys(tasks), function (k, callback) {
+            async.eachSeries(_keys(tasks), function (k, callback) {
                 tasks[k](function (err) {
                     var args = Array.prototype.slice.call(arguments, 1);
                     if (args.length <= 1) {
@@ -694,7 +697,7 @@
           if(data.constructor !== Array) {
               data = [data];
           }
-          _forEach(data, function(task) {
+          _each(data, function(task) {
               var item = {
                   data: task,
                   callback: typeof callback === 'function' ? callback : null
@@ -783,7 +786,7 @@
                 if(data.constructor !== Array) {
                     data = [data];
                 }
-                _forEach(data, function(task) {
+                _each(data, function(task) {
                     tasks.push({
                         data: task,
                         callback: typeof callback === 'function' ? callback : null
@@ -815,7 +818,7 @@
                     working = false;
 
                     var args = arguments;
-                    _forEach(ts, function (data) {
+                    _each(ts, function (data) {
                         if (data.callback) {
                             data.callback.apply(null, args);
                         }
@@ -846,7 +849,7 @@
                         }
                     }
                     else if (console[name]) {
-                        _forEach(args, function (x) {
+                        _each(args, function (x) {
                             console[name](x);
                         });
                     }
diff --git a/test/test-async.js b/test/test-async.js
index 8414c22..e9efdd3 100755
--- a/test/test-async.js
+++ b/test/test-async.js
@@ -10,7 +10,7 @@ if (!Function.prototype.bind) {
     };
 }
 
-function forEachIterator(args, x, callback) {
+function eachIterator(args, x, callback) {
     setTimeout(function(){
         args.push(x);
         callback();
@@ -37,7 +37,7 @@ function detectIterator(call_order, x, callback) {
     }, x*25);
 }
 
-function forEachNoCallbackIterator(test, x, callback) {
+function eachNoCallbackIterator(test, x, callback) {
     test.equal(x, 1);
     callback();
     test.done();
@@ -694,17 +694,17 @@ exports['iterator.next'] = function(test){
     test.done();
 };
 
-exports['forEach'] = function(test){
+exports['each'] = function(test){
     var args = [];
-    async.forEach([1,3,2], forEachIterator.bind(this, args), function(err){
+    async.each([1,3,2], eachIterator.bind(this, args), function(err){
         test.same(args, [1,2,3]);
         test.done();
     });
 };
 
-exports['forEach extra callback'] = function(test){
+exports['each extra callback'] = function(test){
     var count = 0;
-    async.forEach([1,3,2], function(val, callback) {
+    async.each([1,3,2], function(val, callback) {
         count++;
         callback();
         test.throws(callback);
@@ -714,9 +714,9 @@ exports['forEach extra callback'] = function(test){
     });
 };
 
-exports['forEach empty array'] = function(test){
+exports['each empty array'] = function(test){
     test.expect(1);
-    async.forEach([], function(x, callback){
+    async.each([], function(x, callback){
         test.ok(false, 'iterator should not be called');
         callback();
     }, function(err){
@@ -725,9 +725,9 @@ exports['forEach empty array'] = function(test){
     setTimeout(test.done, 25);
 };
 
-exports['forEach error'] = function(test){
+exports['each error'] = function(test){
     test.expect(1);
-    async.forEach([1,2,3], function(x, callback){
+    async.each([1,2,3], function(x, callback){
         callback('error');
     }, function(err){
         test.equals(err, 'error');
@@ -735,21 +735,26 @@ exports['forEach error'] = function(test){
     setTimeout(test.done, 50);
 };
 
-exports['forEach no callback'] = function(test){
-    async.forEach([1], forEachNoCallbackIterator.bind(this, test));
+exports['each no callback'] = function(test){
+    async.each([1], eachNoCallbackIterator.bind(this, test));
 };
 
-exports['forEachSeries'] = function(test){
+exports['forEach alias'] = function (test) {
+    test.strictEqual(async.each, async.forEach);
+    test.done();
+};
+
+exports['eachSeries'] = function(test){
     var args = [];
-    async.forEachSeries([1,3,2], forEachIterator.bind(this, args), function(err){
+    async.eachSeries([1,3,2], eachIterator.bind(this, args), function(err){
         test.same(args, [1,3,2]);
         test.done();
     });
 };
 
-exports['forEachSeries empty array'] = function(test){
+exports['eachSeries empty array'] = function(test){
     test.expect(1);
-    async.forEachSeries([], function(x, callback){
+    async.eachSeries([], function(x, callback){
         test.ok(false, 'iterator should not be called');
         callback();
     }, function(err){
@@ -758,10 +763,10 @@ exports['forEachSeries empty array'] = function(test){
     setTimeout(test.done, 25);
 };
 
-exports['forEachSeries error'] = function(test){
+exports['eachSeries error'] = function(test){
     test.expect(2);
     var call_order = [];
-    async.forEachSeries([1,2,3], function(x, callback){
+    async.eachSeries([1,2,3], function(x, callback){
         call_order.push(x);
         callback('error');
     }, function(err){
@@ -771,14 +776,19 @@ exports['forEachSeries error'] = function(test){
     setTimeout(test.done, 50);
 };
 
-exports['forEachSeries no callback'] = function(test){
-    async.forEachSeries([1], forEachNoCallbackIterator.bind(this, test));
+exports['eachSeries no callback'] = function(test){
+    async.eachSeries([1], eachNoCallbackIterator.bind(this, test));
 };
 
-exports['forEachLimit'] = function(test){
+exports['forEachSeries alias'] = function (test) {
+    test.strictEqual(async.eachSeries, async.forEachSeries);
+    test.done();
+};
+
+exports['eachLimit'] = function(test){
     var args = [];
     var arr = [0,1,2,3,4,5,6,7,8,9];
-    async.forEachLimit(arr, 2, function(x,callback){
+    async.eachLimit(arr, 2, function(x,callback){
         setTimeout(function(){
             args.push(x);
             callback();
@@ -789,9 +799,9 @@ exports['forEachLimit'] = function(test){
     });
 };
 
-exports['forEachLimit empty array'] = function(test){
+exports['eachLimit empty array'] = function(test){
     test.expect(1);
-    async.forEachLimit([], 2, function(x, callback){
+    async.eachLimit([], 2, function(x, callback){
         test.ok(false, 'iterator should not be called');
         callback();
     }, function(err){
@@ -800,27 +810,27 @@ exports['forEachLimit empty array'] = function(test){
     setTimeout(test.done, 25);
 };
 
-exports['forEachLimit limit exceeds size'] = function(test){
+exports['eachLimit limit exceeds size'] = function(test){
     var args = [];
     var arr = [0,1,2,3,4,5,6,7,8,9];
-    async.forEachLimit(arr, 20, forEachIterator.bind(this, args), function(err){
+    async.eachLimit(arr, 20, eachIterator.bind(this, args), function(err){
         test.same(args, arr);
         test.done();
     });
 };
 
-exports['forEachLimit limit equal size'] = function(test){
+exports['eachLimit limit equal size'] = function(test){
     var args = [];
     var arr = [0,1,2,3,4,5,6,7,8,9];
-    async.forEachLimit(arr, 10, forEachIterator.bind(this, args), function(err){
+    async.eachLimit(arr, 10, eachIterator.bind(this, args), function(err){
         test.same(args, arr);
         test.done();
     });
 };
 
-exports['forEachLimit zero limit'] = function(test){
+exports['eachLimit zero limit'] = function(test){
     test.expect(1);
-    async.forEachLimit([0,1,2,3,4,5], 0, function(x, callback){
+    async.eachLimit([0,1,2,3,4,5], 0, function(x, callback){
         test.ok(false, 'iterator should not be called');
         callback();
     }, function(err){
@@ -829,12 +839,12 @@ exports['forEachLimit zero limit'] = function(test){
     setTimeout(test.done, 25);
 };
 
-exports['forEachLimit error'] = function(test){
+exports['eachLimit error'] = function(test){
     test.expect(2);
     var arr = [0,1,2,3,4,5,6,7,8,9];
     var call_order = [];
 
-    async.forEachLimit(arr, 3, function(x, callback){
+    async.eachLimit(arr, 3, function(x, callback){
         call_order.push(x);
         if (x === 2) {
             callback('error');
@@ -846,14 +856,14 @@ exports['forEachLimit error'] = function(test){
     setTimeout(test.done, 25);
 };
 
-exports['forEachLimit no callback'] = function(test){
-    async.forEachLimit([1], 1, forEachNoCallbackIterator.bind(this, test));
+exports['eachLimit no callback'] = function(test){
+    async.eachLimit([1], 1, eachNoCallbackIterator.bind(this, test));
 };
 
-exports['forEachLimit synchronous'] = function(test){
+exports['eachLimit synchronous'] = function(test){
     var args = [];
     var arr = [0,1,2];
-    async.forEachLimit(arr, 5, function(x,callback){
+    async.eachLimit(arr, 5, function(x,callback){
         args.push(x);
         callback();
     }, function(err){
@@ -862,6 +872,11 @@ exports['forEachLimit synchronous'] = function(test){
     });
 };
 
+exports['forEachLimit alias'] = function (test) {
+    test.strictEqual(async.eachLimit, async.forEachLimit);
+    test.done();
+};
+
 exports['map'] = function(test){
     var call_order = [];
     async.map([1,3,2], mapIterator.bind(this, call_order), function(err, results){
@@ -2262,9 +2277,9 @@ exports['avoid stack overflows for sync tasks'] = function (test) {
         cb();
     }
     async.series([
-        async.apply(async.forEach, arr, iter),
-        async.apply(async.forEachSeries, arr, iter),
-        async.apply(async.forEachLimit, arr, iter, 2),
+        async.apply(async.each, arr, iter),
+        async.apply(async.eachSeries, arr, iter),
+        async.apply(async.eachLimit, arr, iter, 2),
         async.apply(async.whilst, pred1, iter),
         resetCounter,
         async.apply(async.until, pred2, iter),