async-iterators

Classic iterators (each, map, reduce) with support for Async functions (or Promise based functions). It automatically waits for functions to resolve if they are asynchronous. They work pretty much the same as lodash ones.

No dependencies! Tested on Node/LTS and Node stable!

Use case

Problem

  const ids = [1,2,3,4,5...1000]
  /** 
   ** reallyExpensiveFetchFunction is going run as soon as you call the function
   ** about 1000 times at the same, probably crashing/slowing your app, db, etc...
   ** imagine with millions or records
   **/
  const promises = ids.map(id => reallyExpensiveAsyncFunction(id)) 
  const result = await Promise.all(promises)
  // result will contain a 1000 results

Solution

Vanilla js #1

  const ids = [1,2,3,4,5...1000]
  /** 
   ** It works but it is unredable and looks hackish
   **/
  const result = await ids.reduce((p, id) => {
             return p.then(id => reallyExpensiveAsyncFunction(id));
         }, Promise.resolve())
  // result will contain a 1000 results

Vanilla js #2

  const ids = [1,2,3,4,5...1000]
  /** 
   ** It is readable, but still kind of verbose, and it gets messier when 
   ** simulating a reduce iterator.
   **/
  const result = []
  for(const id of ids) {
    result.push(await reallyExpensiveAsyncFunction(id));
  }
  // result will contain a 1000 results

async-iterators

  const {mapAsync} = require('async-function-iterators')
  const ids = [1,2,3,4,5...1000]
  /** 
   ** same readibility and simplicity as array.map(fn) or lodash's map(array, fn)
   ** runs the reallyExpensiveAsyncFunction in series, thus not overloading your
   ** system 
   **/
  const result = await mapAsync(ids, id => reallyExpensiveAsyncFunction(id))
  // result will contain a 1000 results

Quick start

This project is intended to be used with >=v8 (requires support for async/await) release of Node.js or newer

Install with yarn

yarn add async-function-iterators

Install with npm

npm install --save async-function-iterators

Docs

Index

• eachAsync
• eachRightAsync
• mapAsync
• mapRightAsync
• reduceAsync
• reduceRightAsync

Functions

eachAsync

► eachAsync(array: any[], iteratee: Function): Promise.<void>

Iterates over elements of array and invokes iteratee for each element. The iteratee is invoked with three arguments: (value, index|key, collection), and it is awaited if it is async. see: eachRightAsync

example: async function asyncFn(value) { return value * 2 }

await eachAsync([1, 2], value => { const result = await asyncFn(value) console.log(result) }) // => Logs 2 then 4.

Parameters:

| Param | Type | Description | | ------ | ------ | ------ | | array | any[] | The array to iterate over. | | iteratee | Function | The function invoked per iteration. (It may be async function). |

Returns: Promise.<void> Returns a Promise that resolves when all the calls have been done or rejects when the first one fails.

eachRightAsync

► eachRightAsync(array: any[], iteratee: Function): Promise.<void>

Iterates over elements of array and invokes iteratee for each element in reverse order. The iteratee is invoked with three arguments: (value, index|key, collection), and it is awaited if it is async. see: eachAsync

example: async function asyncFn(value) { return value * 2 }

await eachRightAsync([1, 2], value => { const result = await asyncFn(value) console.log(result) }) // => Logs 4 then 2.

Parameters:

| Param | Type | Description | | ------ | ------ | ------ | | array | any[] | The array to iterate over. | | iteratee | Function | The function invoked per iteration. (It may be async function). |

Returns: Promise.<void> Returns a Promise that resolves when all the calls have been done or rejects when the first one fails.

mapAsync

► mapAsync(array: any[], iteratee: Function): Promise.<any[]>

Creates Promise that resolves with an array of values by running each element of array thru iteratee. The iteratee is invoked with three arguments: (value, index, array), and it is awaited if it is async. see: mapRightAsync

example: async function square(n) { return n * n }

await mapAsync([4, 8], square) // => [16, 64]

Parameters:

| Param | Type | Description | | ------ | ------ | ------ | | array | any[] | The array to iterate over. | | iteratee | Function | The function invoked per iteration. (It may be async function) |

Returns: Promise.<any[]> Returns a promise that resolves into the new mapped array.

mapRightAsync

► mapRightAsync(array: any[], iteratee: Function): Promise.<any[]>

Creates Promise that resolves with an array of values by running each element of array thru iteratee in reverse order. The iteratee is invoked with three arguments: (value, index, array), and it is awaited if it is async. see: mapAsync

example: async function square(n) { return n * n }

await mapRightAsync([4, 8], square) // => [64, 16]

Parameters:

| Param | Type | Description | | ------ | ------ | ------ | | array | any[] | The array to iterate over. | | iteratee | Function | The function invoked per iteration. (It may be async function) |

Returns: Promise.<any[]> Returns a promise that resolves into the new mapped array.

reduceAsync

► reduceAsync(array: any[], iteratee: Function, accumulator?: any): Promise.<any>

Reduces collection to a value which is the accumulated result of running each element in collection thru iteratee and awaited, where each successive invocation is supplied the return value of the previous. If accumulator is not given, the first element of collection is used as the initial value. The iteratee is invoked with four arguments: (accumulator, value, index|key, collection). see: reduceRightAsync

example: await reduceAsync([1, 2], async (sum, n) => sum + n, 0) // => 3

await reduceAsync({ 'a': 1, 'b': 2, 'c': 1 }, async (result, value, key) => { (result[value] || (result[value] = [])).push(key) return result }, {}) // => { '1': ['a', 'c'], '2': ['b'] } (iteration order is not guaranteed)

Parameters:

| Param | Type | Description | | ------ | ------ | ------ | | array | any[] | The collection to iterate over. | | iteratee | Function | The function invoked per iteration. (It may be async function) | | accumulator | any | - |

Returns: Promise.<any> Returns the accumulated value.

reduceRightAsync

► reduceRightAsync(array: any[], iteratee: Function, accumulator?: any): Promise.<any>

Reduces collection in reverse order to a value which is the accumulated result of running each element in collection thru iteratee and awaited, where each successive invocation is supplied the return value of the previous. If accumulator is not given, the first element of collection is used as the initial value. The iteratee is invoked with four arguments: (accumulator, value, index|key, collection). see: reduceAsync

example: await reduceRightAsync(array, async (flattened, other) => flattened.concat(other), []) // => [4, 5, 2, 3, 0, 1]

Parameters:

| Param | Type | Description | | ------ | ------ | ------ | | array | any[] | The collection to iterate over. | | iteratee | Function | The function invoked per iteration. (It may be async function) | | accumulator | any | - |

Returns: Promise.<any> Returns the accumulated value.

Available scripts

• clean - remove coverage data, Jest cache and transpiled files,
• build - transpile TypeScript to ES6,
• watch - interactive watch mode to automatically transpile source files,
• lint - lint source files and tests,
• test - run tests,
• test:watch - interactive watch mode to automatically re-run tests

License

Licensed under the Apache-2.0. See the LICENSE file for details.