p-queue

To prevent the queue from growing unbounded and causing memory issues when producers are faster than consumers, use .onSizeLessThan(). This allows you to wait for the queue to have space before adding more tasks.

Note that .size counts queued items, while .pending counts running items. The total number of items in the queue is queue.size + queue.pending.

const queue = new PQueue();

// Wait for queue to have space before adding more
await queue.onSizeLessThan(100);
queue.add(() => someTask());

Install p-queue using npm.

Warning: This package is native ESM and does not provide a CommonJS export. If your project uses CommonJS, you must convert it to ESM.

npm install p-queue

p-queue executes tasks in priority order but does not guarantee completion order. If you need results to match the input order, wrap the task additions in Promise.all().

import PQueue from 'p-queue';

const queue = new PQueue({concurrency: 4});

const tasks = [
	() => fetchData(1), // May finish third
	() => fetchData(2), // May finish first
	() => fetchData(3), // May finish second
];

const results = await Promise.all(
	tasks.map(task => queue.add(task))
);
// results = [result1, result2, result3] ✅ Always in input order

Use AbortSignal for targeted cancellation. When a signal is aborted, a queued task is removed and the promise returned by .add() rejects.

Important: Aborting only rejects the promise returned by .add(); it does not automatically stop the async work inside your function. For running tasks, you must handle the signal inside the function itself.

Avoid using queue.clear() alone for cancellation, as it removes queued tasks but their .add() promises will never settle, causing dangling promises.

import PQueue from 'p-queue';

const queue = new PQueue();
const controller = new AbortController();

const promise = queue.add(({signal}) => doWork({signal}), {signal: controller.signal});

controller.abort(); // Cancels if still queued; running tasks must handle `signal` themselves

Because p-queue uses queueMicrotask internally, Jest fake timers may not work as expected. Use a flushPromises helper to ensure microtasks are processed.

const flushPromises = () => new Promise(resolve => setImmediate(resolve));

jest.useFakeTimers();

// ... your test code ...

await jest.runAllTimersAsync();
await flushPromises();

To achieve progressive results that maintain input order while using p-queue for concurrency or priority management, combine p-queue with pMapIterable from the p-map package.

import PQueue from 'p-queue';
import {pMapIterable} from 'p-map';

// Let p-queue handle concurrency
const queue = new PQueue({concurrency: 4});

for await (const result of pMapIterable(
	items,
	item => queue.add(() => fetchItem(item), {priority: item.priority})
)) {
	console.log(result); // Still in input order
}

Use PQueue to limit the number of concurrent asynchronous or synchronous operations. This is useful for rate-limiting tasks like REST API calls or CPU/memory intensive operations.

By default, you can specify the concurrency option in the constructor to control how many promises run at the same time.

import PQueue from 'p-queue';
import got from 'got';

const queue = new PQueue({concurrency: 1});

(async () => {
	await queue.add(() => got('https://sindresorhus.com'));
	console.log('Done: sindresorhus.com');
})();

(async () => {
	await queue.add(() => got('https://avajs.dev'));
	console.log('Done: avajs.dev');
})();

To cancel multiple tasks at once, share a single AbortController across all tasks added to the queue. When controller.abort() is called, all queued tasks are removed and their .add() promises reject cleanly.

import PQueue from 'p-queue';
const queue = new PQueue({concurrency: 2});
const controller = new AbortController();

// All tasks share the same signal
queue.add(({signal}) => doWork(signal), {signal: controller.signal}).catch(() => {});
queue.add(({signal}) => doWork(signal), {signal: controller.signal}).catch(() => {});
queue.add(({signal}) => doWork(signal), {signal: controller.signal}).catch(() => {});

// Cancel all queued (and signal running) tasks — promises reject cleanly
controller.abort();

Access real-time information about the queue's state:

• .size: Number of items waiting in the queue.
• .pending: Number of items currently running.
• .isPaused: Boolean indicating if the queue is paused.
• .isRateLimited: Boolean indicating if the queue is currently rate-limited.
• .isSaturated: Boolean indicating if all concurrency slots are occupied OR the queue is rate-limited and tasks are waiting.
• .sizeBy(options): Returns the size of the queue filtered by specific options (e.g., {priority: 1}).
• .runningTasks: Returns an array of objects containing info for currently executing tasks (id, priority, startTime, timeout, timeoutRemaining).

// Check for backpressure
if (queue.isSaturated) {
	await queue.onSizeLessThan(queue.concurrency);
}

// Inspect running tasks
console.log(queue.runningTasks);

Update the priority of a task using its id. This affects the execution order and requires a defined concurrency limit to be effective.

• To prioritize: Pass a higher number.
• To deprioritize: Pass a lower number.

import PQueue from 'p-queue';

const queue = new PQueue({concurrency: 1});

queue.add(async () => '🦄', {priority: 1});
queue.add(async () => '🦀', {priority: 0, id: '🦀'});

// Move '🦀' to the front
queue.setPriority('🦀', 2);

// Move '🦀' to the end
queue.setPriority('🦀', -1);