Array map, flatMap, filter, reduce, etc. with async callback and predicate
npm install array-async-utils
!GitHub License

Small set of utility functions to perform async array mapping, filtering and reducing.
- How to install
- Usage
- asyncMap
- Specify mapped element type
- asyncSerialMap
- Specify mapped element type
- asyncFlatMap
- Specify mapped element type
- asyncFilter
- Filtered array type narrowing
- asyncReduce
- Specify initialValue/accumulator and reduced value type
Simply install the array-async-utils from npm.
You can use one of the following commands, or the equivalent command of the package manager of your choice.
```
npm install array-async-utils
``
yarn add array-async-utils
These funcitons accepts the input array as first paramenter, while the arguments, types and returned value resemble as much as possible the ones of the equivalent Array method.
Same behaviour as Array.map, but supports an async callback: all async callbacks are executed in parallel.
If one callback throws an error, the whole map function throws as well.
`ts
import { asyncMap } from 'array-async-utils';
import { getUser } from 'apis/user';
const yourFunction = async () => {
const userIds = ['92f9e7a1', '59ef0d84', '6b6cafba'];
const users = await asyncMap(userIds, async (userId) => {
const { user } = await getUser(userId);
return user;
});
};
`
##### Specify mapped element type
`ts`
// ...
const array = [1, 2, 3];
const mappedArray = await asyncMap
array,
async (element) => {
// ...
}
);
// ^^^ callback will expect Promise
Same as asyncMap, but async callbacks are executed in series: each one is executed when the previous is finished.
Even if not common, it can be useful when some rece condition might happen in the async callback.
If one callback throws an error, the whole map function throws as well.
`ts
import { asyncSerialMap } from 'array-async-utils';
import { getUser } from 'apis/user';
import { userCache } from 'cache/user';
const yourFunction = async () => {
const userIds = ['92f9e7a1', '59ef0d84', '6b6cafba'];
const users = await asyncSerialMap(userIds, async (userId) => {
const cachedUser = userCache.get(userId);
if (cachedUser) {
return cachedUser;
}
const { user } = await getUser(userId);
cachedUser.set(userId, user);
return user;
});
};
`
##### Specify mapped element type
`ts`
// ...
const array = [1, 2, 3];
const mappedArray = await asyncMap
array,
async (element) => {
// ...
}
);
// ^^^ callback will expect Promise
Same behaviour as Array.flatMap, but supports an async callback: all async callbacks are executed in parallel.
If one callback throws an error, the whole map function throws as well.
`ts
import { asyncFlatMap } from 'array-async-utils';
import { getUsersByGroup } from 'apis/user';
const yourFunction = async () => {
const userGroups = ['groupA', 'groupB', 'groupC'];
const users = await asyncFlatMap(userIds, async (userId) => {
const { groupUsers } = await getUsersByGroup(userId);
return groupUsers;
});
};
`
##### Specify mapped element type
`ts`
// ...
const array = [1, 2, 3];
const mappedArray = await asyncFlatMap
array,
async (element) => {
// ...
}
);
// ^^^ callback will expect Promise
Same behaviour as Array.filter, but supports an async predicate: all async predicates are executed in parallel.
If one callback throws an error, the whole filter function throws as well.
> IMPORTANT: unfortunately typescript doesn't support type guards with async function, so if you need to narrow down the type of the filtered array, please use the generics as described below
`ts
import { asyncFilter } from 'array-async-utils';
import { getUserStatus } from 'apis/user';
const yourFunction = async () => {
const userIds = ['asyncFilter', '59ef0d84', '6b6cafba'];
const users = await asyncFilter(userIds, async (userId) => {
const { isOnline } = await getUserStatus(userId);
return isOnline;
});
};
`
##### Filtered array type narrowing
`ts`
// ...
const array = [1, 2, 3, undefined];
const filteredArray = await asyncFilter
array,
async (element) => {
// ...
}
);
// ^^^ filteredArray will be of type number[]
Same behaviour as Array.reduce, but supports an async callback. Async callbacks are executed in series: each one is executed when the previous is finished.
If one callback throws an error, the whole map function throws as well.
`ts
import { asyncReduce } from 'array-async-utils';
import { getArticleStats } from 'apis/user';
const yourFunction = async () => {
const articleIds = ['92f9e7a1', '59ef0d84', '6b6cafba'];
const totalInteractions = await asyncReduce(
articleIds,
async (accumulator, articleId) => {
const { articleInteractions } = getArticleStats(articleId);
return accumulator + articleInteractions;
},
0
);
};
`
##### Specify initialValue/accumulator and reduced value type
`ts``
// ...
const array = [1, 2, 3];
const reducedValue = await asyncReduce
array,
async (accumulator, element) => {
// ...
},
{}
);
// ^^^ callback will expect Promise
// initialValue, accumulator and reducedValue will be of type Record