p-iteration

Make array iteration easy when using async/await and promises

• Same functionality as the ES5 Array iteration methods we all know
• All the methods return a Promise, making them awaitable and thenable
• Allow the usage of async functions as callback
• Callbacks run concurrently
• Lightweight (no prd dependencies)

Install

$ npm install --save p-iteration

Usage

Smooth asynchronous iteration using async/await:

1const { map } = require('p-iteration');
2
3// map passing an async function as callback
4function getUsers (userIds) {
5  return map(userIds, async userId => {
6    const response = await fetch(`/api/users/${userId}`);
7    return response.json();
8  });
9}
10
11// map passing a non-async function as callback
12async function getRawResponses (userIds) {
13  const responses = await map(userIds, userId => fetch(`/api/users/${userId}`));
14  // ... do some stuff
15  return responses;
16}
17
18// ...

1const { filter } = require('p-iteration');
2
3async function getFilteredUsers (userIds, name) {
4  const filteredUsers = await filter(userIds, async userId => {
5    const response = await fetch(`/api/users/${userId}`);
6    const user = await response.json();
7    return user.name === name;
8  });
9  // ... do some stuff
10  return filteredUsers;
11}
12
13// ...

All methods return a Promise so they can just be used outside an async function just with plain Promises:

1const { map } = require('p-iteration');
2
3map([123, 125, 156], (userId) => fetch(`/api/users/${userId}`))
4  .then((result) => {
5    // ...
6  })
7  .catch((error) => {
8    // ...
9  });

If there is a Promise in the array, it will be unwrapped before calling the callback:

1const { forEach } = require('p-iteration');
2const fetchJSON = require('nonexistent-module');
3
4function logUsers () {
5  const users = [
6    fetchJSON('/api/users/125'), // returns a Promise
7    { userId: 123, name: 'Jolyne', age: 19 },
8    { userId: 156, name: 'Caesar', age: 20 }
9  ];
10  return forEach(users, (user) => {
11    console.log(user);
12  });
13}

1const { find } = require('p-iteration');
2const fetchJSON = require('nonexistent-module');
3
4function findUser (name) {
5  const users = [
6    fetchJSON('/api/users/125'), // returns a Promise
7    { userId: 123, name: 'Jolyne', age: 19 },
8    { userId: 156, name: 'Caesar', age: 20 }
9  ];
10  return find(users, (user) => user.name === name);
11}

The callback will be invoked as soon as the Promise is unwrapped:

1const { forEach } = require('p-iteration');
2
3// function that returns a Promise resolved after 'ms' passed
4const delay = (ms) => new Promise(resolve => setTimeout(() => resolve(ms), ms));
5
6// 100, 200, 300 and 500 will be logged in this order
7async function logNumbers () {
8  const numbers = [
9    delay(500),
10    delay(200),
11    delay(300),
12    100
13  ];
14  await forEach(numbers, (number) => {
15    console.log(number);
16  });
17}

API

The methods are implementations of the ES5 Array iteration methods we all know with the same syntax, but all return a Promise. Also, with the exception of reduce(), all methods callbacks are run concurrently. There is a series version of each method, called: ${methodName}Series, series methods use the same API that their respective concurrent ones.

There is a link to the original reference of each method in the docs of this module:

• forEach(array, callback, [thisArg])

• forEachSeries(array, callback, [thisArg])

• map(array, callback, [thisArg])

• mapSeries(array, callback, [thisArg])

• find(array, callback, [thisArg])

• findSeries(array, callback, [thisArg])

• findIndex(array, callback, [thisArg])

• findIndexSeries(array, callback, [thisArg])

• some(array, callback, [thisArg])

• someSeries(array, callback, [thisArg])

• every(array, callback, [thisArg])

• everySeries(array, callback, [thisArg])

• filter(array, callback, [thisArg])

• filterSeries(array, callback, [thisArg])

• reduce(array, callback, [initialValue])

Instance methods

Extending native objects is discouraged and I don't recommend it, but in case you know what you are doing, you can extend Array.prototype to use the above methods as instance methods. They have been renamed as async${MethodName}, so the original ones are not overwritten.

1const { instanceMethods } = require('p-iteration');
2
3Object.assign(Array.prototype, instanceMethods);
4
5async function example () {
6  const foo = await [1, 2, 3].asyncMap((id) => fetch(`/api/example/${id}`));
7}

License

MIT © Antonio V