Async Utility Functions

A well tested and typed collection of map, forEach, reduce, filter etc. utility functions supporting arrays, sets, maps, plain objects, iterators in both async and synchronous versions.

* Core Concepts
* Usage
* Import
* Array Utilities
* Sequential
* Parallel
* Object Utilities
* Sequential
* Parallel
* Using Break and Last
* Synchronous
* Helpers
* Changelog

Core Concepts

Each method (except for "forEach" and all "toArray" utilities) returns the same type as the input: asyncMap(new Map(), () => {}) returns Promise etc.

- Break: A symbol that can be returned to stop the iteration.
- Last: A utility that wraps a value. When returned, it stops the iteration and the provided value becomes the final output.

Usage

$3

javascript
import { asyncMap, map, asyncReduce, Break, Last } from 'async-collection-utils';
const data = [1, 2, 3];
const result = await asyncMap(data, async (item) => Promise.resolve(item * 2));
// result: [2, 4, 6]
const data = new Set([1, 2, 3]);
const result = await asyncMap(data, async (item) => Promise.resolve(item + 1));
// result: Set { 2, 3, 4 }
const data = { a: 1, b: 2, c: 3 };
const result = map(data, async (value, key) => value + key);
// result: { a: '1a', b: '2b', c: '3c' }

const cursor = model.find({}).cursor(); const result = await asyncReduce(cursor, async (acc, item) => Promise.resolve(acc + item.value), 0); // result: number`

`$3`


Each type of utility has both async and sync versions. These return the same type as the input. The "toArray" utilities accept the same input but always return an array.
|               | map | flatMap | filter | reduce | forEach |
|:--------------|:---:|:-------:|:------:|:------:|:-------:|
| async         |  ✅  |    ✅    |   ✅    |   ✅    |    ✅    |
| sync          |  ✅  |    ✅    |   ✅    |   ✅    |    ✅    |
| toArray async |  ✅  |    ✅    |   ✅    |  n/a   |   n/a   |
| toArray sync  |  ✅  |    ✅    |   ✅    |  n/a   |   n/a   |
$3
|                                       | Array          | Set            | Map          | Record          | TypedArray          | Iterable                | AsyncIterable           |
|---------------------------------------|-------------------|-------------------|--------------------|-----------------------|------------------------|----------------------------|----------------------------|
| asyncMap                   | Promise> | Promise>   | Promise> | Promise> | Promise> | Promise> | Promise> |
| map                        | Array          | Set            | Map          | Record          | TypedArray          | Generator               | ❌                          |
| asyncMapToArray            | Promise> | Promise> | Promise>  | Promise>     | Promise>      | Promise>          | Promise>          |
| mapToArray                 | Array          | Array          | Array           | Array              | Array               | Array                   | ❌                          |
| asyncFlatMap        | Promise> | Promise>   | ❌                  | ❌                     | Promise> | Promise> | Promise> |
| flatMap             | Array          | Set            | ❌                  | ❌                     | TypedArray          | Generator               | ❌                          |
| asyncFlatMapToArray | Promise> | Promise> | Promise>  | Promise>     | Promise>      | Promise>          | Promise>          |
| flatMapToArray      | Array          | Array          | Array           | Array              | Array               | Array                   | ❌                          |
| asyncFilter          | Promise> | Promise>   | Promise> | Promise> | Promise> | Promise> | Promise> |   
| filter               | Array          | Set            | Map          | Record          | TypedArray          | Generator               | ❌                          |  
| asyncFilterToArray   | Promise> | Promise> | Promise>  | Promise>     | Promise>      | Promise>          | Promise>          |   
| filterToArray        | Array          | Array          | Array           | Array              | Array               | Array                   | ❌                          |  
| asyncReduce                | Promise        | Promise        | Promise         | Promise            | Promise             | Promise                 | Promise                 |
| reduce                     | R                 | R                 | R                  | R                     | R                      | R                          | ❌                          |
| asyncForEach            | void              | void              | void               | void                  | void                   | void                       | void                       |
| forEach                 | void              | void              | void               | void                  | void                   | void                       | ❌                          |
$3

All functions accept iterables ()
$3

#### map

javascript
import { map } from 'async-collection-utils';
const results = map([1, 2, 3], (item) => item * 2);
// results: [2, 4, 6]
const results = map(new Set([1, 2, 3]), (item) => item * 2);
// results: Set { 2, 4, 6 }
const results = map({ a: 1, b: 2, c: 3 }, (value, key) => value + key);
// results: { a: '1a', b: '2b', c: '3c' }
const results = map(new Map([['a', 1], ['b', 2], ['c', 3]]), (value, key) => value + key);
// results: Map { a: '1a', b: '2b', c: '3c' }
const results = map(model.find({}).cursor(), (item) => parseInt(item.value));
// results: Generator

const generator = function* () { yield 1; yield 2; yield 3; }; const results = map(generator(), async (item) => item * 2); // results: Generator`

#### asyncMap`javascript import { asyncMap } from 'async-collection-utils';

const results = await asyncMap([1, 2, 3], async (item) => Promise.resolve(item * 2)); // results: [2, 4, 6]

const results = await asyncMap(new Set([1, 2, 3]), async (item) => Promise.resolve(item * 2)); // results: Set { 2, 4, 6 }

const results = await asyncMap({ a: 1, b: 2, c: 3 }, async (value, key) => Promise.resolve(value + key)); // results: { a: '1a', b: '2b', c: '3c' }

const results = await asyncMap(new Map([['a', 1], ['b', 2], ['c', 3]]), async (value, key) => Promise.resolve(value + key)); // results: Map { a: '1a', b: '2b', c: '3c' }

const results = await asyncMap(model.find({}).cursor(), async (item) => Promise.resolve(parseInt(item.value))); // results: AsyncGenerator

const asyncGenerator = function* () { yield 1; yield 2; yield 3; }; const results = await asyncMap(generator(), async (item) => Promise.resolve(item * 2)); // results: AsyncGenerator

const generator = function* () { yield 1; yield 2; yield 3; }; const results = await asyncMap(generator(), async (item) => Promise.resolve(item * 2)); // results: AsyncGenerator`

#### mapToArray`javascript import { mapToArray } from 'async-collection-utils';

const results = mapToArray([1, 2, 3], (item) => item * 2); // results: [2, 4, 6]

const results = mapToArray(new Set([1, 2, 3]), (item) => item * 2); // results: [2, 4, 6]

const results = mapToArray({ a: 1, b: 2, c: 3 }, (value, key) => value + key); // results: ['1a', '2b', '3c']

const results = mapToArray(new Map([['a', 1], ['b', 2], ['c', 3]]), (value, key) => value + key); // results: ['1a', '2b', '3c']

const results = mapToArray(model.find({}).cursor(), (item) => parseInt(item.value)); // results: number[]

const generator = function* () { yield 1; yield 2; yield 3; }; const results = mapToArray(generator(), async (item) => item * 2); // results: [2, 4, 6]`

`$3`


You can use

Break to finish the iteration early in all functions.

`javascript const data = [1, 2, 3, 4, 5]; const result = await asyncFlatMap(data, async (item) => { if (item === 3) return Break; return item * 2; }); // result: [2, 4]`

`javascript const data = { a: 1, b: 2, c: 3, d: 4, e: 5 }; const result = await asyncMap(data, async (value) => { if (value === 3) return Break; return value * 2; }); // result: { a: 2, b: 4 }`

You can use Last wrapper, to finish the iteration early while still returning last value. It works in all map, flatMap, reduce and filter functions.

`javascript const data = [1, 2, 3, 4, 5]; const result = await asyncFlatMap(data, async (item) => { if (item === 3) return Last(item * 2); return item * 2; }); // result: [2, 4, 6]`

`javascript const data = [1, 2, 3, 4, 5]; const reduced = await asyncReduce(data, async (acc, item) => { if (item === 3) return Last(acc + item); return acc + item; }, 0); // result: 6`

`$3`


Two helpers used internally are exported as well:

- entries: The same as Object.entriesbut with better typings`javascript import { entries } from 'async-collection-utils'; enum SomeEnum { foo = 'foo', bar = 'bar', } const obj = { [SomeEnum.foo]: 1, [SomeEnum.bar]: 2 }; const result: [SomeEnum, number][] = await entries(obj); // result: [[SomeEnum.foo, 1], [SomeEnum.bar, 2]]`

- keys: The same as Object.keysbut with better typings`javascript import { keys } from 'async-collection-utils'; enum SomeEnum { foo = 'foo', bar = 'bar', } const obj = { [SomeEnum.foo]: 1, [SomeEnum.bar]: 2 }; const result: SomeEnum[] = await keys(obj); // result: [SomeEnum.foo, SomeEnum.bar]`

`Array-like objects`


Methods are not generic meaning that they won't treat array-like objects as arrays. They will be iterated over just like plain objects.

`javascript import { map } from 'async-collection-utils';

const obj = { 0: 'a', 1: 'b', length: 2 }; const result = map(obj, (value, key) => value + key); // result: { 0: 'a0', 1: 'b1', length: '2length' }`

`Notes`


- Remember to always pass async iteratee to async functions; otherwise, type inference will fail
Changelog
$3

- Initial release
$3

- Added synchronous utilities
- Added

entries and keys` helpers

$3

- BREAKING CHANGE: complete rewrite of the library
- All async utilities accept: arrays, sets, maps, typed arrays, iterators, async iterators and plain objects and return the same type as the input
- All async utilities have sync counterparts
- All sync utilities accept: arrays, sets, maps, typed arrays, iterators, and plain objects and return the same type as the input
- Utilities available:
- asyncMap
- map
- asyncMapToArray
- mapToArray
- asyncFlatMap
- flatMap
- asyncFlatMapToArray
- flatMapToArray
- asyncFilter
- filter
- asyncFilterToArray
- filterToArray
- asyncReduce
- reduce
- asyncForEach
- forEach
- batch
- entries
- keys

Async Utility Functions

A well tested and typed collection of map, forEach, reduce, filter etc. utility functions supporting arrays, sets, maps, plain objects, iterators in both async and synchronous versions.

* Core Concepts
* Usage
* Import
* Array Utilities
* Sequential
* Parallel
* Object Utilities
* Sequential
* Parallel
* Using Break and Last
* Synchronous
* Helpers
* Changelog

Core Concepts

Each method (except for "forEach" and all "toArray" utilities) returns the same type as the input: asyncMap(new Map(), () => {}) returns Promise etc.

- Break: A symbol that can be returned to stop the iteration.
- Last: A utility that wraps a value. When returned, it stops the iteration and the provided value becomes the final output.

Usage

$3

javascript
import { asyncMap, map, asyncReduce, Break, Last } from 'async-collection-utils';
const data = [1, 2, 3];
const result = await asyncMap(data, async (item) => Promise.resolve(item * 2));
// result: [2, 4, 6]
const data = new Set([1, 2, 3]);
const result = await asyncMap(data, async (item) => Promise.resolve(item + 1));
// result: Set { 2, 3, 4 }
const data = { a: 1, b: 2, c: 3 };
const result = map(data, async (value, key) => value + key);
// result: { a: '1a', b: '2b', c: '3c' }

const cursor = model.find({}).cursor(); const result = await asyncReduce(cursor, async (acc, item) => Promise.resolve(acc + item.value), 0); // result: number`

`$3`


Each type of utility has both async and sync versions. These return the same type as the input. The "toArray" utilities accept the same input but always return an array.
|               | map | flatMap | filter | reduce | forEach |
|:--------------|:---:|:-------:|:------:|:------:|:-------:|
| async         |  ✅  |    ✅    |   ✅    |   ✅    |    ✅    |
| sync          |  ✅  |    ✅    |   ✅    |   ✅    |    ✅    |
| toArray async |  ✅  |    ✅    |   ✅    |  n/a   |   n/a   |
| toArray sync  |  ✅  |    ✅    |   ✅    |  n/a   |   n/a   |
$3
|                                       | Array          | Set            | Map          | Record          | TypedArray          | Iterable                | AsyncIterable           |
|---------------------------------------|-------------------|-------------------|--------------------|-----------------------|------------------------|----------------------------|----------------------------|
| asyncMap                   | Promise> | Promise>   | Promise> | Promise> | Promise> | Promise> | Promise> |
| map                        | Array          | Set            | Map          | Record          | TypedArray          | Generator               | ❌                          |
| asyncMapToArray            | Promise> | Promise> | Promise>  | Promise>     | Promise>      | Promise>          | Promise>          |
| mapToArray                 | Array          | Array          | Array           | Array              | Array               | Array                   | ❌                          |
| asyncFlatMap        | Promise> | Promise>   | ❌                  | ❌                     | Promise> | Promise> | Promise> |
| flatMap             | Array          | Set            | ❌                  | ❌                     | TypedArray          | Generator               | ❌                          |
| asyncFlatMapToArray | Promise> | Promise> | Promise>  | Promise>     | Promise>      | Promise>          | Promise>          |
| flatMapToArray      | Array          | Array          | Array           | Array              | Array               | Array                   | ❌                          |
| asyncFilter          | Promise> | Promise>   | Promise> | Promise> | Promise> | Promise> | Promise> |   
| filter               | Array          | Set            | Map          | Record          | TypedArray          | Generator               | ❌                          |  
| asyncFilterToArray   | Promise> | Promise> | Promise>  | Promise>     | Promise>      | Promise>          | Promise>          |   
| filterToArray        | Array          | Array          | Array           | Array              | Array               | Array                   | ❌                          |  
| asyncReduce                | Promise        | Promise        | Promise         | Promise            | Promise             | Promise                 | Promise                 |
| reduce                     | R                 | R                 | R                  | R                     | R                      | R                          | ❌                          |
| asyncForEach            | void              | void              | void               | void                  | void                   | void                       | void                       |
| forEach                 | void              | void              | void               | void                  | void                   | void                       | ❌                          |
$3

All functions accept iterables ()
$3

#### map

javascript
import { map } from 'async-collection-utils';
const results = map([1, 2, 3], (item) => item * 2);
// results: [2, 4, 6]
const results = map(new Set([1, 2, 3]), (item) => item * 2);
// results: Set { 2, 4, 6 }
const results = map({ a: 1, b: 2, c: 3 }, (value, key) => value + key);
// results: { a: '1a', b: '2b', c: '3c' }
const results = map(new Map([['a', 1], ['b', 2], ['c', 3]]), (value, key) => value + key);
// results: Map { a: '1a', b: '2b', c: '3c' }
const results = map(model.find({}).cursor(), (item) => parseInt(item.value));
// results: Generator