Skip to content

Commit f2b2c9e

Browse files
developitdevelopit
committed
Documentation! 🎉
1 parent 36113dd commit f2b2c9e

File tree

3 files changed

+145
-25
lines changed

3 files changed

+145
-25
lines changed

‎README.md‎

Lines changed: 117 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,14 @@
22

33
It's the `map()`, `reduce()` & `filter()` you know, but with support for async callbacks!
44

5-
65
<img src="http://i.imgur.com/yiiq6Gx.png" width="275" alt="preview">
76

8-
97
### Installation
108

119
```sh
1210
npm install --save asyncro
1311
```
1412

15-
1613
### Example
1714

1815
```js
@@ -25,3 +22,120 @@ async function example() {
2522
)
2623
}
2724
```
25+
26+
### API
27+
28+
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
29+
30+
#### reduce
31+
32+
Invoke an async reducer function on each item in the given Array,
33+
where the reducer transforms an accumulator value based on each item iterated over.
34+
**Note:** because `reduce()` is order-sensitive, iteration is sequential.
35+
36+
> This is an asynchronous version of `Array.prototype.reduce()`
37+
38+
**Parameters**
39+
40+
- `array` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** The Array to reduce
41+
- `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`
42+
- `accumulator` **\[Any]** Optional initial accumulator value
43+
44+
**Examples**
45+
46+
```javascript
47+
await reduce(
48+
['/foo', '/bar', '/baz'],
49+
async (accumulator, value) => {
50+
accumulator[v] = await fetch(value);
51+
return accumulator;
52+
},
53+
{}
54+
);
55+
```
56+
57+
Returns **any** final `accumulator` value
58+
59+
#### map
60+
61+
Invoke an async transform function on each item in the given Array **in parallel**,
62+
returning the resulting Array of mapped/transformed items.
63+
64+
> This is an asynchronous, parallelized version of `Array.prototype.map()`.
65+
66+
**Parameters**
67+
68+
- `array` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** The Array to map over
69+
- `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.
70+
71+
**Examples**
72+
73+
```javascript
74+
await map(
75+
['foo', 'baz'],
76+
async v => await fetch(v)
77+
)
78+
```
79+
80+
Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** resulting mapped/transformed values.
81+
82+
#### filter
83+
84+
Invoke an async filter function on each item in the given Array **in parallel**,
85+
returning an Array of values for which the filter function returned a truthy value.
86+
87+
> This is an asynchronous, parallelized version of `Array.prototype.filter()`.
88+
89+
**Parameters**
90+
91+
- `array` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** The Array to filter
92+
- `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.
93+
94+
**Examples**
95+
96+
```javascript
97+
await filter(
98+
['foo', 'baz'],
99+
async v => (await fetch(v)).ok
100+
)
101+
```
102+
103+
Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** resulting filtered values
104+
105+
#### parallel
106+
107+
Invoke all async functions in an Array or Object **in parallel**, returning the result.
108+
109+
**Parameters**
110+
111+
- `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.
112+
113+
**Examples**
114+
115+
```javascript
116+
await parallel([
117+
async () => await fetch('foo'),
118+
async () => await fetch('baz')
119+
])
120+
```
121+
122+
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.
123+
124+
#### series
125+
126+
Invoke all async functions in an Array or Object **sequentially**, returning the result.
127+
128+
**Parameters**
129+
130+
- `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.
131+
132+
**Examples**
133+
134+
```javascript
135+
await series([
136+
async () => await fetch('foo'),
137+
async () => await fetch('baz')
138+
])
139+
```
140+
141+
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‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,12 @@
77
"minified:main": "dist/asyncro.min.js",
88
"scripts": {
99
"clean": "rimraf dist/",
10-
"build": "npm-run-all clean transpile minify size",
10+
"build": "npm-run-all --silent clean transpile minify docs size",
1111
"prepublish": "npm-run-all build test",
1212
"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",
1313
"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",
1414
"size": "size=$(gzip-size $npm_package_minified_main) && echo \"gzip size: $size / $(pretty-bytes $size)\"",
15+
"docs": "documentation readme src/index.js --section API -q",
1516
"test": "ava --verbose",
1617
"lint": "eslint {src,test}",
1718
"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 @@
3334
"babel-cli": "^6.14.0",
3435
"babel-plugin-async-to-promises": "^1.0.5",
3536
"babel-preset-es2015": "^6.14.0",
37+
"documentation": "^4.0.0-beta11",
3638
"eslint": "^3.8.1",
3739
"gzip-size-cli": "^1.0.0",
3840
"npm-run-all": "^3.1.1",

‎src/index.js‎

Lines changed: 25 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,25 @@ import { resolve, pushReducer } from './util';
88
* > This is an asynchronous version of `Array.prototype.reduce()`
99
*
1010
* @param {Array} array The Array to reduce
11-
* @param {Function} reducer Async function that gets passed `(accumulator, value, index, array)`.
12-
* @param {Any} [initialValue] An initial accumulator value
13-
* @returns {Any} accumulator The final value of the accumulator
11+
* @param {Function} reducer Async function, gets passed `(accumulator, value, index, array)` and returns a new value for `accumulator`
12+
* @param {Any} [accumulator] Optional initial accumulator value
13+
* @returns final `accumulator` value
1414
*
1515
* @example
16-
* await reduce(['/foo', '/bar', '/baz'], async (acc, v) => {
17-
* acc[v] = await (await fetch(v)).json();
18-
* return acc;
19-
* }, {});
16+
* await reduce(
17+
* ['/foo', '/bar', '/baz'],
18+
* async (accumulator, value) => {
19+
* accumulator[v] = await fetch(value);
20+
* return accumulator;
21+
* },
22+
* {}
23+
* );
2024
*/
21-
export async function reduce(arr, fn, val) {
22-
for (let i=0; i<arr.length; i++) {
23-
val = await fn(val, arr[i], i, arr);
25+
export async function reduce(array, reducer, accumulator) {
26+
for (let i=0; i<array.length; i++) {
27+
accumulator = await reducer(accumulator, array[i], i, array);
2428
}
25-
return val;
29+
return accumulator;
2630
}
2731

2832

@@ -32,17 +36,17 @@ export async function reduce(arr, fn, val) {
3236
* > This is an asynchronous, parallelized version of `Array.prototype.map()`.
3337
*
3438
* @param {Array} array The Array to map over
35-
* @param {Function} mapper Async function. Gets passed `(value, index, array)`, returns the new value.
36-
* @returns {Array} mappedValues The resulting mapped/transformed values.
39+
* @param {Function} mapper Async function, gets passed `(value, index, array)`, returns the new value.
40+
* @returns {Array} resulting mapped/transformed values.
3741
*
3842
* @example
3943
* await map(
4044
* ['foo', 'baz'],
4145
* async v => await fetch(v)
4246
* )
4347
*/
44-
export function map(arr, fn) {
45-
return Promise.all(arr.map(fn));
48+
export function map(array, mapper) {
49+
return Promise.all(array.map(mapper));
4650
}
4751

4852

@@ -53,23 +57,23 @@ export function map(arr, fn) {
5357
*
5458
* @param {Array} array The Array to filter
5559
* @param {Function} filterer Async function. Gets passed `(value, index, array)`, returns true to keep the value in the resulting filtered Array.
56-
* @returns {Array} filteredValues The resulting filtered values.
60+
* @returns {Array} resulting filtered values
5761
*
5862
* @example
5963
* await filter(
6064
* ['foo', 'baz'],
6165
* async v => (await fetch(v)).ok
6266
* )
6367
*/
64-
export async function filter(arr, fn) {
65-
let mapped = await map(arr, fn);
66-
return arr.filter( (v, i) => mapped[i] );
68+
export async function filter(array, filterer) {
69+
let mapped = await map(array, filterer);
70+
return array.filter( (v, i) => mapped[i] );
6771
}
6872

6973

7074
/** Invoke all async functions in an Array or Object **in parallel**, returning the result.
7175
* @param {Array<Function>|Object<Function>} list Array/Object with values that are async functions to invoke.
72-
* @returns {Array|Object} mappedList Same structure as `list` input, but with values now resolved.
76+
* @returns {Array|Object} same structure as `list` input, but with values now resolved.
7377
*
7478
* @example
7579
* await parallel([
@@ -84,7 +88,7 @@ export async function parallel(list) {
8488

8589
/** Invoke all async functions in an Array or Object **sequentially**, returning the result.
8690
* @param {Array<Function>|Object<Function>} list Array/Object with values that are async functions to invoke.
87-
* @returns {Array|Object} mappedList Same structure as `list` input, but with values now resolved.
91+
* @returns {Array|Object} same structure as `list` input, but with values now resolved.
8892
*
8993
* @example
9094
* await series([

0 commit comments

Comments
 (0)