Concurrency and Rate Limiting: p-limit vs p-queue vs p-throttle

When building robust JavaScript applications, uncontrolled asynchronous operations can lead to crashed servers, tripped API rate limits, or sluggish UIs. The p-* ecosystem offers three distinct tools to manage this flow: p-limit, p-queue, and p-throttle. While they all wrap async functions, they solve different problems. Let's compare how they handle execution control.

🚦 Execution Control Strategy: Count vs Time

The core difference lies in what they limit: simultaneous active tasks or the frequency of tasks over time.

p-limit restricts the number of promises that are active at the same time.

• Once the limit is reached, new tasks wait in a hidden queue.
• As soon as one finishes, the next starts.

import pLimit from 'p-limit';

const limit = pLimit(2); // Max 2 concurrent

const tasks = [1, 2, 3, 4].map(id => 
  limit(() => fetch(`/api/item/${id}`))
);

await Promise.all(tasks);
// Only 2 fetches happen at once

p-queue also restricts concurrency but wraps it in a managed queue object.

• It tracks pending, active, and completed tasks.
• Useful when you need to know when the queue is empty.

import PQueue from 'p-queue';

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

[1, 2, 3, 4].forEach(id => {
  queue.add(() => fetch(`/api/item/${id}`));
});

await queue.onIdle();
// Waits until all tasks are done

p-throttle restricts how often a function can run over a time interval.

• It does not care about concurrency count, but rather time spacing.
• Ideal for APIs with "X requests per second" rules.

import pThrottle from 'p-throttle';

const throttled = pThrottle({
  limit: 2,
  interval: 1000 // 2 calls per 1000ms
});

const tasks = [1, 2, 3, 4].map(id => 
  throttled(() => fetch(`/api/item/${id}`))()
);

await Promise.all(tasks);
// Calls are spaced out over time

🗄️ Queue & State Management: Stateful vs Stateless

Managing the lifecycle of tasks often requires state. p-queue is stateful, while the others are stateless wrappers.

p-limit is stateless.

• It returns a function wrapper.
• You cannot pause or clear the internal queue directly.
• To stop, you must manage external flags.

import pLimit from 'p-limit';

const limit = pLimit(1);
let shouldStop = false;

const task = async () => {
  if (shouldStop) return;
  return limit(() => doWork());
};
// No built-in pause method

p-queue is stateful.

• It exposes methods to pause, resume, and clear the queue.
• Essential for long-running workers or UI interactions.

import PQueue from 'p-queue';

const queue = new PQueue();

queue.add(() => doWork());

queue.pause(); // Stops processing new items
queue.clear(); // Removes pending items
queue.start(); // Resumes processing

p-throttle is stateless.

• It maintains internal timers but exposes no queue controls.
• You cannot drain or pause the throttle itself.

import pThrottle from 'p-throttle';

const throttled = pThrottle({ limit: 1, interval: 1000 });

// No pause/clear methods available
await throttled(() => doWork())();

📉 Priority and Ordering

In complex systems, not all tasks are equal. Some need to jump the line.

p-limit processes tasks in FIFO (First-In-First-Out) order.

• No priority support.
• Simple and predictable.

import pLimit from 'p-limit';

const limit = pLimit(1);

// First added runs first
limit(() => console.log('A'));
limit(() => console.log('B'));

p-queue supports priority levels.

• Lower numbers usually mean higher priority.
• Critical tasks can bypass less important ones.

import PQueue from 'p-queue';

const queue = new PQueue();

queue.add(() => console.log('Low'), { priority: 10 });
queue.add(() => console.log('High'), { priority: 1 });
// 'High' runs before 'Low' if both are waiting

p-throttle processes tasks in FIFO order.

• No priority support.
• Focuses strictly on time spacing.

import pThrottle from 'p-throttle';

const throttled = pThrottle({ limit: 1, interval: 1000 });

// First called runs first (when interval allows)
await throttled(() => console.log('A'))();
await throttled(() => console.log('B'))();

⚠️ Error Handling & Resilience

How failures affect the flow differs slightly, though all propagate rejections.

p-limit propagates errors directly.

• If a task fails, the returned promise rejects.
• Other queued tasks continue normally.

import pLimit from 'p-limit';

const limit = pLimit(1);

try {
  await limit(() => Promise.reject(new Error('Fail')));
} catch (err) {
  console.error(err); // Caught here
}
// Next task in queue still runs

p-queue propagates errors but emits events.

• You can listen for error events globally.
• Useful for logging without wrapping every task.

import PQueue from 'p-queue';

const queue = new PQueue();

queue.on('error', err => console.error(err));

queue.add(() => Promise.reject(new Error('Fail')));
// Error caught by listener, queue continues

p-throttle propagates errors directly.

• Similar to p-limit, rejection is handled by the caller.
• Throttling continues regardless of success/failure.

import pThrottle from 'p-throttle';

const throttled = pThrottle({ limit: 1, interval: 1000 });

try {
  await throttled(() => Promise.reject(new Error('Fail')))();
} catch (err) {
  console.error(err);
}
// Throttle timer continues

📊 Summary: Key Differences

💡 The Big Picture

p-limit is the lightweight choice 🪶. Use it when you just need to stop your code from opening 1000 database connections at once. It adds almost no overhead and requires minimal setup.

p-queue is the command center 🎛️. Use it when you need visibility and control. If you need to pause a batch job, prioritize urgent tasks, or wait for everything to finish before shutting down, this is the tool.

p-throttle is the metronome 🎵. Use it when time is the constraint. If an API says "100 requests per minute," p-limit might still burst 100 requests in one second. p-throttle ensures they are spread out correctly.

Final Thought: While p-queue can technically replace p-limit (by setting concurrency), it brings extra weight. Conversely, p-throttle solves a problem the others cannot (time-based rate limiting). Choose the tool that matches your constraint: count, control, or time.