clamped-promise-all

Executes an array of promises with a max number of parallel executions.

This library contains two functions, clampedAll which behaves similar to Promise.all, and clampedAllSettled which behaves similar to Promise.allSettled.

Useful for situations where you may only make a specified number of parallel promises at a given time, e.g. Cloudflare Workers.

Installation

npm install clamped-promise-all

Usage

1. require or import the version you need:

const { clampedAll, clampedAllSettled } = require('clamped-promise-all');

import { clampedAll, clampedAllSettled } from 'clamped-promise-all';

2. Pass an array of functions that return promises, along with the maximum level of parallelization:

import { clampedAll } from 'clamped-promise-all';

const apiCalls = [
    () => fetch('https://api.github.com/search/repositories?q=clamped-promise-all'),
    () => fetch('https://api.github.com/search/repositories?q=throttled-queue'),
    () => fetch('https://api.github.com/search/repositories?q=sql-where-parser'),
    () => fetch('https://api.github.com/search/repositories?q=tokenize-this'),
];
const apiResponses = await clampedAll(apiCalls, 2); // make at most 2 api calls in parallel

clampedAllSettled works in exactly the same way as clampedAll, except its behavior and return type matches Promise.allSettled, in that it will not reject if a promise rejects.

Take note

Unlike Promise.all and Promise.allSettled, clampedAll and clampedAllSettled require an array of functions that return promises, not an array of promises themselves!

Here's a typical "real-world" map example to further illustrate the difference:

import { clampedAll } from 'clamped-promise-all';

const repos = ['clamped-promise-all', 'throttled-queue', 'sql-where-parser', 'tokenize-this'];
const apiCalls = repos.map(
    (repo) => () => fetch(`https://api.github.com/search/repositories?q=${repo}`),
);
const apiResponses = await clampedAll(apiCalls, 2); // make at most 2 api calls in parallel

Note that the repo name is not mapped to the fetch call directly, but is instead mapped to a wrapper function that then invokes the fetch.

Typescript support

The package is written in Typescript and includes types by default. Both clampedAll and clampedAllSettled are generic, and in most cases will automatically use the input array's types to create it's output type.

However, you may also specify the array item type when needed:

import { clampedAll } from 'clamped-promise-all';
const apiCalls = [
  () => fetch('https://api.github.com/search/repositories?q=clamped-promise-all'),
  () => fetch('https://api.github.com/search/repositories?q=throttled-queue'),
  () => fetch('https://api.github.com/search/repositories?q=sql-where-parser'),
  () => fetch('https://api.github.com/search/repositories?q=tokenize-this'),
];
const apiResponses = await clampedAll<GithubSearchResponse>(apiCalls, 2); // apiResponses is now typed as GithubSearchResponse[]