Add 'map'

Author: Jason Walton

README.md

@@ -32,6 +32,10 @@ Then somewhere in your node.js application:
 
 # API
 
+## Collections
+
+* [`map`](#map)
+
 ## Utilities
 
 * [`defer`](#defer)
@@ -44,6 +48,14 @@ Then somewhere in your node.js application:
 * [`whilst`](#whilst), `doWhilst`
 * [`retry`](#retry)
 
+# Collections
+
+<a name="map"/>
+### map(arr, iterator, limit)
+
+Calls `iterator(item, index)` for every item in `map`, which should return a Promise.  If `limit` is specified,
+then at most `limit` calls to iterator will be started at a time.  Resolves to an array of items (the resolved
+value of each promise returned by `iterator()`).  If any iterator rejects, this will reject immediately.
 
 # Utilities
 

src/index.js

@@ -118,6 +118,21 @@ exports.parallel = exports.parallelLimit = (tasks, limit) => {
     });
 };
 
+/*
+ * Given an array `arr` of items, calls `iter(item, index)` for every item in `arr`.  `iter()` should return a
+ * Promise.  Up to `limit` items will be called in parallel (defaults to 1.)
+ */
+exports.map = (arr, iter, limit) => {
+    let taskLimit = limit;
+    if (!limit || limit < 1) {taskLimit = 1;}
+    if (limit >= arr.length) {taskLimit = arr.length;}
+
+    let tasks = arr.map((item, index) => (() => iter(item, index)));
+    return exports.parallel(tasks, taskLimit);
+};
+
+
+
 /*
  * Add a timeout to an existing Promise.
  *

test/map.js

@@ -0,0 +1,28 @@
+"use strict"
+
+let chai = require('chai');
+chai.use(require('chai-as-promised'));
+let expect = chai.expect;
+let promiseTools = require('../src');
+
+describe('map', () => {
+    it('should map an array of values', () => {
+        let arr = ['a', 'b', 'c'];
+        let iter = (value, index) => Promise.resolve(value + index);
+        return expect(promiseTools.map(arr, iter)).to.eventually.eql(['a0', 'b1', 'c2']);
+    });
+
+    it('should map an array of values without using promises', () => {
+        let arr = ['a', 'b', 'c'];
+        let iter = (value, index) => value + index;
+        return expect(promiseTools.map(arr, iter)).to.eventually.eql(['a0', 'b1', 'c2']);
+    });
+
+    it('should work if the limit is 0, or too large', () => {
+        let arr = ['a', 'b', 'c'];
+        let iter = (value, index) => value + index;
+        return expect(promiseTools.map(arr, iter, 0)).to.eventually.eql(['a0', 'b1', 'c2'])
+        .then(() => expect(promiseTools.map(arr, iter, 100)).to.eventually.eql(['a0', 'b1', 'c2']));
+    });
+
+});