p-limit

Install the p-limit package using npm to run multiple promise-returning or async functions with limited concurrency in Node.js or browsers.

npm install p-limit

The limit(fn, ...args) syntax allows you to pass shared arguments (like a database client or configuration object) to every function call managed by the limiter.

import pLimit from 'p-limit';
import {S3} from '@aws-sdk/client-s3';

const limit = pLimit(2);
const client = new S3({});

const runWithClient = (function_, ...arguments_) => limit(function_, client, ...arguments_);

const fetchFromSomeBucket = (client, fileKey) => client.getObject({
	Bucket: 'someBucket',
	Key: fileKey
});

const results = await Promise.all([
	runWithClient(fetchFromSomeBucket, 'someFileKey1'),
	runWithClient(fetchFromSomeBucket, 'someFileKey2'),
	runWithClient(fetchFromSomeBucket, 'someFileKey3')
]);

You can modify limit.concurrency at runtime. This is useful for implementing backoff strategies, such as reducing concurrency when encountering HTTP 429 (Too Many Requests) errors.

import pLimit from 'p-limit';

const limit = pLimit(10);

const urls = getUrls(); // Assume this returns a list of URLs

async function fetchWithBackoff(url) {
	const response = await fetch(url);

	if (response.status === 429) {
		limit.concurrency = Math.max(1, Math.floor(limit.concurrency / 2));
	} else if (limit.concurrency < 10) {
		limit.concurrency++;
	}

	return response;
}

const results = await limit.map(urls, fetchWithBackoff);

Monitor the state of your task queue using limit.activeCount (number of currently running tasks) and limit.pendingCount (number of tasks waiting in the queue).

import pLimit from 'p-limit';

const limit = pLimit(5);

const urls = getUrls(); // Assume this returns a list of URLs

const progressInterval = setInterval(() => {
	console.log(`Running: ${limit.activeCount}, pending: ${limit.pendingCount}`);
}, 250);

let results;

try {
	results = await limit.map(urls, url => fetch(url));
} finally {
	clearInterval(progressInterval);
}

To limit concurrency, initialize pLimit with a concurrency number, then wrap your function calls in the returned limit function. This allows you to queue tasks that will execute only when the concurrency limit allows.

import pLimit from 'p-limit';

const limit = pLimit(1);

const input = [
	limit(() => fetchSomething('foo')),
	limit(() => fetchSomething('bar')),
	limit(() => doSomething())
];

// Only one promise is run at once
const result = await Promise.all(input);
console.log(result);

Use limit.map() to fetch multiple URLs while controlling the number of concurrent network requests.

import pLimit from 'p-limit';

const limit = pLimit(3);

const urls = [
	'https://api.example.com/users/1',
	'https://api.example.com/users/2',
	'https://api.example.com/users/3',
	'https://api.example.com/users/4',
	'https://api.example.com/users/5',
];

const results = await limit.map(urls, async url => {
	const response = await fetch(url);
	return response.json();
});

Use limit.map() to process a collection of items (like files from a directory) with a fixed concurrency level. This prevents overwhelming the system by limiting how many asynchronous operations run simultaneously.

import fs from 'node:fs/promises';
import pLimit from 'p-limit';

const limit = pLimit(5);

const files = await fs.readdir('uploads');

const results = await limit.map(files, async file => {
	const content = await fs.readFile(`uploads/${file}`, 'utf8');
	return JSON.parse(content);
});

Use the limitFunction() named export to wrap a specific function with its own concurrency management. This is ideal when you want a single function to encapsulate its own rate-limiting logic.

import {limitFunction} from 'p-limit';

const urls = getUrls(); // Assume this returns a list of URLs

const fetchUrl = async url => {
	const response = await fetch(url);

	if (!response.ok) {
		throw new Error(`Request failed with ${response.status} for ${url}`);
	}

	return response.json();
};

const limitedFetchUrl = limitFunction(fetchUrl, {concurrency: 3});

const results = await Promise.all(urls.map(url => limitedFetchUrl(url)));

To prevent one failed task from rejecting the entire batch, wrap your limit() calls inside Promise.allSettled(). This allows you to inspect each result and handle successes and failures individually.

import pLimit from 'p-limit';

const limit = pLimit(3);

const urls = [
	'https://api.example.com/users/1',
	'https://api.example.com/users/2',
	'https://api.example.com/users/3',
];

const results = await Promise.allSettled(
	urls.map(url => limit(async () => {
		const response = await fetch(url);

		if (!response.ok) {
			throw new Error(`Request failed with ${response.status} for ${url}`);
		}

		return response.json();
	}))
);

for (const result of results) {
	if (result.status === 'fulfilled') {
		console.log(result.value);
	} else {
		console.error(result.reason);
	}
}

The named export limitFunction(fn, options) returns a new function that manages its own concurrency. This is ideal for controlling the simultaneous execution of a single specific function rather than managing a shared pool of different functions.

import {limitFunction} from 'p-limit';

const limitedFunction = limitFunction(async () => {
	return doSomething();
}, {concurrency: 1});

const input = Array.from({length: 10}, limitedFunction);

// Only one promise is run at once.
await Promise.all(input);

The default export pLimit(concurrency) returns a limit function. You can pass a number or an options object.

Options:

• concurrency (number): The concurrency limit (minimum 1).
• rejectOnClear (boolean): If true, pending promises are rejected with an AbortError when limit.clearQueue() is called. This is recommended when using Promise.all to prevent pending tasks from remaining unresolved.

import pLimit from 'p-limit';

const limit = pLimit({concurrency: 1});