Documentation! 🎉

README.md

@@ -2,17 +2,14 @@
 
 It's the `map()`, `reduce()` & `filter()` you know, but with support for async callbacks!
 
-
 <img src="http://i.imgur.com/yiiq6Gx.png" width="275" alt="preview">
 
-
 ### Installation
 
 ```sh
 npm install --save asyncro
 ```
 
-
 ### Example
 
 ```js
@@ -25,3 +22,120 @@ async function example() {
 	)
 }
 ```
+
+### API
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+#### reduce
+
+Invoke an async reducer function on each item in the given Array,
+where the reducer transforms an accumulator value based on each item iterated over.
+**Note:** because `reduce()` is order-sensitive, iteration is sequential.
+
+> This is an asynchronous version of `Array.prototype.reduce()`
+
+**Parameters**
+
+-   `array` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** The Array to reduce
+-   `reducer` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Async function, gets passed `(accumulator, value, index, array)` and returns a new value for `accumulator`
+-   `accumulator` **\[Any]** Optional initial accumulator value
+
+**Examples**
+
+```javascript
+await reduce(
+	['/foo', '/bar', '/baz'],
+	async (accumulator, value) => {
+		accumulator[v] = await fetch(value);
+		return accumulator;
+	},
+	{}
+);
+```
+
+Returns **any** final `accumulator` value
+
+#### map
+
+Invoke an async transform function on each item in the given Array **in parallel**,
+returning the resulting Array of mapped/transformed items.
+
+> This is an asynchronous, parallelized version of `Array.prototype.map()`.
+
+**Parameters**
+
+-   `array` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** The Array to map over
+-   `mapper` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Async function, gets passed `(value, index, array)`, returns the new value.
+
+**Examples**
+
+```javascript
+await map(
+	['foo', 'baz'],
+	async v => await fetch(v)
+)
+```
+
+Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** resulting mapped/transformed values.
+
+#### filter
+
+Invoke an async filter function on each item in the given Array **in parallel**,
+returning an Array of values for which the filter function returned a truthy value.
+
+> This is an asynchronous, parallelized version of `Array.prototype.filter()`.
+
+**Parameters**
+
+-   `array` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** The Array to filter
+-   `filterer` **[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)** Async function. Gets passed `(value, index, array)`, returns true to keep the value in the resulting filtered Array.
+
+**Examples**
+
+```javascript
+await filter(
+	['foo', 'baz'],
+	async v => (await fetch(v)).ok
+)
+```
+
+Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** resulting filtered values
+
+#### parallel
+
+Invoke all async functions in an Array or Object **in parallel**, returning the result.
+
+**Parameters**
+
+-   `list` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)> | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)&lt;[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)>)** Array/Object with values that are async functions to invoke.
+
+**Examples**
+
+```javascript
+await parallel([
+	async () => await fetch('foo'),
+	async () => await fetch('baz')
+])
+```
+
+Returns **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** same structure as `list` input, but with values now resolved.
+
+#### series
+
+Invoke all async functions in an Array or Object **sequentially**, returning the result.
+
+**Parameters**
+
+-   `list` **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)&lt;[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)> | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)&lt;[Function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function)>)** Array/Object with values that are async functions to invoke.
+
+**Examples**
+
+```javascript
+await series([
+	async () => await fetch('foo'),
+	async () => await fetch('baz')
+])
+```
+
+Returns **([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) \| [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** same structure as `list` input, but with values now resolved.

package.json

@@ -7,11 +7,12 @@
   "minified:main": "dist/asyncro.min.js",
   "scripts": {
     "clean": "rimraf dist/",
-    "build": "npm-run-all clean transpile minify size",
+    "build": "npm-run-all --silent clean transpile minify docs size",
     "prepublish": "npm-run-all build test",
     "transpile": "rollup -c rollup.config.js -m ${npm_package_main}.map -f umd -n $npm_package_name $npm_package_jsnext_main -o $npm_package_main",
     "minify": "uglifyjs $npm_package_main -cm -o $npm_package_minified_main -p relative --in-source-map ${npm_package_main}.map --source-map ${npm_package_minified_main}.map",
     "size": "size=$(gzip-size $npm_package_minified_main) && echo \"gzip size: $size / $(pretty-bytes $size)\"",
+    "docs": "documentation readme src/index.js --section API -q",
     "test": "ava --verbose",
     "lint": "eslint {src,test}",
     "release": "npm run -s build && git commit -am $npm_package_version && git tag $npm_package_version && git push && git push --tags && npm publish"
@@ -33,6 +34,7 @@
     "babel-cli": "^6.14.0",
     "babel-plugin-async-to-promises": "^1.0.5",
     "babel-preset-es2015": "^6.14.0",
+    "documentation": "^4.0.0-beta11",
     "eslint": "^3.8.1",
     "gzip-size-cli": "^1.0.0",
     "npm-run-all": "^3.1.1",

src/index.js

@@ -8,21 +8,25 @@ import { resolve, pushReducer } from './util';
  *	> This is an asynchronous version of `Array.prototype.reduce()`
  *
  *	@param {Array} array			The Array to reduce
- *	@param {Function} reducer		Async function that gets passed `(accumulator, value, index, array)`.
- *	@param {Any} [initialValue]		An initial accumulator value
- *	@returns {Any} accumulator		The final value of the accumulator
+ *	@param {Function} reducer		Async function, gets passed `(accumulator, value, index, array)` and returns a new value for `accumulator`
+ *	@param {Any} [accumulator]		Optional initial accumulator value
+ *	@returns final `accumulator` value
  *
  *	@example
- *	await reduce(['/foo', '/bar', '/baz'], async (acc, v) => {
- *		acc[v] = await (await fetch(v)).json();
- *		return acc;
- *	}, {});
+ *	await reduce(
+ *		['/foo', '/bar', '/baz'],
+ *		async (accumulator, value) => {
+ *			accumulator[v] = await fetch(value);
+ *			return accumulator;
+ *		},
+ *		{}
+ *	);
  */
-export async function reduce(arr, fn, val) {
-	for (let i=0; i<arr.length; i++) {
-		val = await fn(val, arr[i], i, arr);
+export async function reduce(array, reducer, accumulator) {
+	for (let i=0; i<array.length; i++) {
+		accumulator = await reducer(accumulator, array[i], i, array);
 	}
-	return val;
+	return accumulator;
 }
 
 
@@ -32,17 +36,17 @@ export async function reduce(arr, fn, val) {
  *	> This is an asynchronous, parallelized version of `Array.prototype.map()`.
  *
  *	@param {Array} array			The Array to map over
- *	@param {Function} mapper		Async function. Gets passed `(value, index, array)`, returns the new value.
- *	@returns {Array} mappedValues	The resulting mapped/transformed values.
+ *	@param {Function} mapper		Async function, gets passed `(value, index, array)`, returns the new value.
+ *	@returns {Array} resulting mapped/transformed values.
  *
  *	@example
  *	await map(
  *		['foo', 'baz'],
  *		async v => await fetch(v)
  *	)
  */
-export function map(arr, fn) {
-	return Promise.all(arr.map(fn));
+export function map(array, mapper) {
+	return Promise.all(array.map(mapper));
 }
 
 
@@ -53,23 +57,23 @@ export function map(arr, fn) {
  *
  *	@param {Array} array			The Array to filter
  *	@param {Function} filterer		Async function. Gets passed `(value, index, array)`, returns true to keep the value in the resulting filtered Array.
- *	@returns {Array} filteredValues	The resulting filtered values.
+ *	@returns {Array} resulting filtered values
  *
  *	@example
  *	await filter(
  *		['foo', 'baz'],
  *		async v => (await fetch(v)).ok
  *	)
  */
-export async function filter(arr, fn) {
-	let mapped = await map(arr, fn);
-	return arr.filter( (v, i) => mapped[i] );
+export async function filter(array, filterer) {
+	let mapped = await map(array, filterer);
+	return array.filter( (v, i) => mapped[i] );
 }
 
 
 /** Invoke all async functions in an Array or Object **in parallel**, returning the result.
  *	@param {Array<Function>|Object<Function>} list		Array/Object with values that are async functions to invoke.
- *	@returns {Array|Object} mappedList					Same structure as `list` input, but with values now resolved.
+ *	@returns {Array|Object} same structure as `list` input, but with values now resolved.
  *
  *	@example
  *	await parallel([
@@ -84,7 +88,7 @@ export async function parallel(list) {
 
 /** Invoke all async functions in an Array or Object **sequentially**, returning the result.
  *	@param {Array<Function>|Object<Function>} list		Array/Object with values that are async functions to invoke.
- *	@returns {Array|Object} mappedList					Same structure as `list` input, but with values now resolved.
+ *	@returns {Array|Object} same structure as `list` input, but with values now resolved.
  *
  *	@example
  *	await series([