limiter vs p-limit vs p-throttle
JavaScript 任务并发与速率限制方案对比
limiterp-limitp-throttle类似的npm包:

JavaScript 任务并发与速率限制方案对比

这三个库都用于控制代码执行的频率和并发量,但核心机制不同。p-limit 用于限制同时运行的任务数量(并发度);p-throttle 用于限制单位时间内的调用次数(速率);limiter 提供基于令牌桶算法的底层限流,更偏向 Node.js 服务端场景。前端开发中通常首选 p-* 系列以获得更好的 Promise 支持。

npm下载趋势

3 年

GitHub Stars 排名

统计详情

npm包名称
下载量
Stars
大小
Issues
发布时间
License
limiter01,565103 kB58 天前MIT
p-limit02,92516.1 kB04 小时前MIT
p-throttle052222.2 kB06 天前MIT

JavaScript 任务并发与速率限制方案对比

在前端和 Node.js 开发中,控制任务执行的速度和数量是常见需求。limiter、p-limit 和 p-throttle 都解决了这个问题,但它们的适用场景和实现方式有很大区别。让我们从实际工程角度看看它们如何工作。

🚀 核心机制:并发数 vs 速率 vs 令牌桶

p-limit 关注的是同时有多少个任务在运行。

  • 它限制的是并发度(Concurrency)。
  • 即使你有 100 个任务,如果限制为 2,那么同一时刻只有 2 个在执行,其余排队。
// p-limit: 限制同时运行 2 个任务
import pLimit from 'p-limit';
const limit = pLimit(2);

const jobs = Array.from({ length: 5 }).map(() => 
  limit(() => fetch('/api/data'))
);
await Promise.all(jobs);
// 同一时刻最多 2 个 fetch 在进行

p-throttle 关注的是单位时间内允许通过多少个任务。

  • 它限制的是速率(Rate)。
  • 即使并发只有 1 个,如果限制每秒 2 次,第 3 次调用会被延迟到下一秒。
// p-throttle: 限制每秒最多 2 次调用
import pThrottle from 'p-throttle';
const throttle = pThrottle({limit: 2, interval: 1000});

const throttledFetch = throttle(() => fetch('/api/data'));
await throttledFetch();
await throttledFetch();
await throttledFetch(); // 这次会被延迟到下一个时间窗口

limiter 关注的是令牌桶算法。

  • 它维护一个令牌池,每次执行消耗令牌,令牌随时间自动补充。
  • 更灵活,但配置更复杂,通常用于服务端限流。
// limiter: 每秒生成 2 个令牌,桶容量 2
const { RateLimiter } = require('limiter');
const limiter = new RateLimiter(2, 'second');

limiter.removeTokens(1, (err, remaining) => {
  // 拿到令牌后才能执行请求
  fetch('/api/data');
});

📦 Promise 支持:现代异步流程的关键

对于前端开发者来说,是否原生支持 Promise 是选择的重要标准。

p-limit 完全基于 Promise 设计。

  • 返回的是一个 Promise。
  • 可以直接配合 async/await 使用,代码清晰。
// p-limit: 原生 Promise 支持
async function run() {
  const limit = pLimit(2);
  await limit(() => doSomething());
}

p-throttle 同样完全基于 Promise 设计。

  • 包装后的函数返回 Promise。
  • 错误处理可以直接用 try/catch。
// p-throttle: 原生 Promise 支持
async function run() {
  const throttle = pThrottle({limit: 1, interval: 1000});
  try {
    await throttle(() => doSomething());
  } catch (e) {
    // 直接捕获错误
  }
}

limiter 主要基于回调函数(Callback)。

  • 默认 API 使用回调,不支持直接 await。
  • 在现代 async/await 代码中需要额外包装,增加复杂度。
// limiter: 主要基于回调
function run() {
  limiter.removeTokens(1, (err, remaining) => {
    // 需要在回调里继续逻辑
    // 如果要转 Promise 需手动封装
  });
}

⚠️ 错误处理与排队行为

当任务失败或队列满时,各包的表现不同。

p-limit 会保留所有任务直到执行。

  • 任务会排队等待,不会因为并发满而丢弃。
  • 如果某个任务报错,不影响其他任务。
// p-limit: 任务排队,错误隔离
const limit = pLimit(2);
// 即使并发满,新任务也会进入队列等待
await limit(() => riskyOperation()); 

p-throttle 会延迟执行直到时间窗口允许。

  • 任务不会丢失,只是被推迟。
  • 适合需要保证最终执行但不在乎稍慢的场景。
// p-throttle: 自动延迟
const throttle = pThrottle({limit: 1, interval: 1000});
// 调用过快会自动排队延迟执行
await throttle(() => apiCall()); 

limiter 取决于你如何处理回调。

  • 如果没有令牌,回调会等待直到有令牌。
  • 需要手动处理等待逻辑,不如 p-* 系列自动化。
// limiter: 手动处理等待
limiter.removeTokens(1, (err, remaining) => {
  // 如果没有令牌,回调会阻塞直到可用
  // 需要自己处理超时或放弃逻辑
});

🌐 真实场景推荐

场景 1:批量上传图片

你需要上传 50 张图片,但浏览器同时连接数有限,且不想卡死界面。

  • ✅ 最佳选择:p-limit
  • 理由:限制同时上传数量(如 5 个),避免占用所有网络资源。
// 使用 p-limit
const limit = pLimit(5);
const uploads = images.map(img => limit(() => upload(img)));
await Promise.all(uploads);

场景 2:调用有限制的 API

第三方 API 规定每秒最多调用 10 次,否则会返回 429 错误。

  • ✅ 最佳选择:p-throttle
  • 理由:严格控制时间窗口内的请求次数,避免触发限流。
// 使用 p-throttle
const throttle = pThrottle({limit: 10, interval: 1000});
const callApi = throttle(() => fetch('/external-api'));
await callApi();

场景 3:Node.js 服务端网关

你在编写一个 API 网关,需要根据用户等级分配不同的令牌速率。

  • ✅ 最佳选择:limiter
  • 理由:令牌桶算法更适合复杂的服务端流控策略。
// 使用 limiter
const userLimiter = new RateLimiter(userTokens, 'second');
userLimiter.removeTokens(1, callback);

📊 核心差异总结

特性p-limitp-throttlelimiter
控制目标同时运行的任务数单位时间内的调用次数令牌消耗速率
异步风格Promise / async-awaitPromise / async-await回调函数 (Callback)
主要场景并发控制 (上传/下载)速率限制 (API 调用)服务端流控 (网关)
前端友好度⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
配置复杂度低 (仅并发数)中 (次数 + 时间)高 (令牌 + 间隔)

💡 最终建议

对于现代前端开发,优先选择 p-limit 或 p-throttle。

  • 如果你的问题是**“太多任务同时跑会卡死”**,用 p-limit。
  • 如果你的问题是**“请求太快会被服务器拒绝”**,用 p-throttle。
  • 除非你在 Node.js 服务端需要复杂的令牌桶逻辑,否则不建议在前端使用 limiter,因为它的回调风格会增加代码维护成本,且不如 p-* 系列对 Promise 友好。

这三个工具都很小巧,但它们解决的是不同维度的问题。选对工具能让你的异步代码更稳定,也更易读。

如何选择: limiter vs p-limit vs p-throttle

  • limiter:

    选择 limiter 如果你在 Node.js 服务端需要实现复杂的令牌桶算法,或者需要精细控制令牌生成速率。由于它主要基于回调函数,不太适合现代前端基于 async/await 的流程,新项目建议优先考虑其他方案。

  • p-limit:

    选择 p-limit 如果你需要限制同时执行的任务数量,例如同时只允许 5 个文件上传或 3 个 API 请求。它非常适合控制并发度,防止浏览器或服务器因过多同时请求而过载。

  • p-throttle:

    选择 p-throttle 如果你需要限制单位时间内的调用频率,例如每秒最多调用 10 次 API。它适合应对有严格速率限制的第三方接口,确保不会因请求过快而被封禁。

limiter的README

limiter

CI npm

Control when work starts in Node.js and browsers. limiter provides an interval rate limiter and a hierarchical token bucket, with Promise-based waiting, synchronous admission checks, and no runtime dependencies.

Use it to pace API calls, throttle messages, or budget bytes. Waiting requests run in FIFO order on each instance with one active timer, even with thousands of callers. CommonJS, ES modules, and TypeScript declarations are included.

ChooseWhen you need
RateLimiterA maximum token count per interval, with continuous refill underneath
TokenBucketSeparate burst capacity and refill rate, optionally shared through parent buckets

Install

npm install limiter

Pace work

Save as example.mjs and run node example.mjs. The first message starts immediately; subsequent messages start at least 250 ms apart.

import { RateLimiter } from "limiter";

const limiter = new RateLimiter({ tokensPerInterval: 1, interval: 250 });

await Promise.all(["first", "second", "third"].map(async (message) => {
  await limiter.removeTokens(1);
  console.log(message);
}));

For CommonJS, use const { RateLimiter, TokenBucket } = require("limiter"). Create and reuse a limiter for each resource whose budget should be shared. Each token represents an application-defined unit: a request, a message, a byte, or a fractional cost. Work starts after removeTokens() resolves.

Reject instead of waiting

tryRemoveTokens() atomically checks capacity and consumes tokens on success. This complete HTTP example applies one shared budget to all incoming requests:

import { createServer } from "node:http";
import { RateLimiter } from "limiter";

const limiter = new RateLimiter({ tokensPerInterval: 10, interval: "second" });

createServer((request, response) => {
  if (!limiter.tryRemoveTokens(1)) {
    const seconds = Math.max(1, Math.ceil(limiter.getWaitTime(1) / 1000));
    response.writeHead(429, { "Retry-After": String(seconds) });
    response.end("Too many requests\n");
    return;
  }
  response.end("Accepted\n");
}).listen(3000);

getWaitTime(count) returns an estimated delay in milliseconds without consuming tokens. On RateLimiter it accounts for both refill and the interval allowance. It returns zero when capacity is currently available. This RateLimiter helper is new in 4.1; TokenBucket.getWaitTime() is available in 4.0.

For the Promise API with immediate rejection signaling, construct a limiter with fireImmediately: true: removeTokens() resolves to -1 when denied, otherwise to the remaining bucket balance. Invalid inputs still reject the promise.

Budget bytes and bursts

A standalone bucket starts empty and refills as time passes. This example allows a 150 KiB burst after enough idle time and refills at 50 KiB per second:

import { TokenBucket } from "limiter";

const bucket = new TokenBucket({
  bucketSize: 150 * 1024,
  tokensPerInterval: 50 * 1024,
  interval: "second"
});

const chunks = [new Uint8Array(1024), new Uint8Array(2048)];
for (const chunk of chunks) {
  await bucket.removeTokens(chunk.byteLength);
  console.log(`Ready to send ${chunk.byteLength} bytes`);
}

Split any chunk larger than bucketSize before requesting tokens. To share a budget, pass another TokenBucket as parentBucket. A successful removal charges the child and every finite ancestor together; a failed attempt charges none.

API at a glance

APIResult
new RateLimiter({ tokensPerInterval, interval, fireImmediately? })A full bucket plus an interval allowance
new TokenBucket({ bucketSize, tokensPerInterval, interval, parentBucket? })An empty bucket with independent burst and refill settings
removeTokens(count)Promise<number>: wait, consume, and return remaining balance
tryRemoveTokens(count)boolean: consume immediately if possible
getWaitTime(count)Estimated milliseconds until capacity is available; never consumes tokens
RateLimiter.getTokensRemaining()Underlying bucket balance, which can exceed the current interval allowance

Intervals accept positive milliseconds or "second", "minute", "hour", and "day" (also "sec", "min", and "hr"). Token amounts may be fractional. Always handle rejected promises for invalid or oversized requests.

Additional Notes

Waiting calls to removeTokens() are processed in FIFO order on each instance, using one active timer per instance. Concurrent calls are supported. A request is charged only when it can succeed; hierarchical buckets debit the child and all parents together. Independent children sharing a parent do not have a global FIFO order. tryRemoveTokens() and fireImmediately requests do not join the waiting queue and may consume capacity ahead of waiting requests.

RateLimiter combines a continuously refilled token bucket with an interval counter. Its interval starts at construction and resets on the first removal attempt at or after the previous interval expires. It is not a rolling-window limiter: traffic around an interval boundary can exceed the configured count in a sliding window. It does not track when your asynchronous work finishes, and it does not limit simultaneous in-flight operations. Use a concurrency limiter or rolling-window algorithm separately when those are your requirements.

getTokensRemaining() reports the underlying bucket's balance (possibly fractional), not the interval counter's remaining allowance. Use getWaitTime(count) for a non-consuming cooldown estimate, or tryRemoveTokens(count) to check and consume in one step. Estimates ignore queued requests and are not reservations; other calls can change availability.

Awaiting two independent rate limiters in sequence does not atomically enforce both limits at the eventual work start: work can collect behind the second limiter. For atomic burst and sustained-rate budgets, use parent/child TokenBucket instances. Those implement token-bucket limits, not rolling windows.

Token counts and capacities must be finite, non-negative numbers at most Number.MAX_SAFE_INTEGER; fractional tokens are supported. Numeric intervals must be finite and greater than zero. Invalid input throws RangeError (an async call rejects). An oversized request returns false from tryRemoveTokens() and rejects from removeTokens(). A standalone TokenBucket starts empty; RateLimiter starts full. For compatibility, bucketSize: 0 means unlimited capacity and bypasses parents, and tokensPerInterval: 0 refills a finite bucket to capacity on every attempt. These zero values do not disable all traffic. RateLimiter with tokensPerInterval: 0 accepts only zero-token requests.

Timing uses a monotonic clock. Timers can run late when the event loop is busy; availability is rechecked after every wait. Balances use JavaScript floating-point numbers, so fractional results can have normal rounding error. State is local to the instance and is not shared across processes, workers, or machines. Configure instances at the scope of the resource you want to limit; creating a new limiter for every request defeats a shared rate limit.

Upgrading from 3.x

Version 4 fixes concurrent accounting and waiting behavior. It keeps the existing constructors, methods, CommonJS/ESM imports, and fractional-token support, but is a major release because these observable behaviors change:

  • Token counts and capacities must be finite, non-negative numbers no greater than Number.MAX_SAFE_INTEGER. Numeric intervals must be finite and positive. Invalid values now throw RangeError, or reject an asynchronous call. Validate configuration and handle rejected removeTokens() promises; do not use negative values, NaN, or Infinity as sentinels.
  • Waiting removeTokens() calls on the same instance run in FIFO order. A large request at the front can delay smaller requests behind it. Synchronous calls and fireImmediately requests can still consume capacity ahead of the queue; children sharing a parent do not have a global FIFO order.
  • Concurrent requests now respect the interval allowance and charge a hierarchy only once per successful removal. Workloads that previously exceeded their configured limits may wait longer or receive an immediate rejection signal.
  • Remaining balances retain fractional millisecond timing precision. Avoid exact equality checks on fractional balances; use tryRemoveTokens() to check whether a request can proceed immediately.

Zero-value conventions are unchanged: a standalone TokenBucket with bucketSize: 0 is unlimited and bypasses parents; tokensPerInterval: 0 refills a finite bucket on every attempt. A RateLimiter with tokensPerInterval: 0 accepts only zero-token requests. These settings are not a general off switch.

See the changelog for the release history and Additional Notes for the full timing and queue semantics.

Development

yarn install --frozen-lockfile
yarn lint:ci
yarn test
yarn prepack

CI checks the source and both module distributions. Tests cover concurrent accounting, hierarchical buckets, FIFO backlogs, timing boundaries, and invalid inputs using deterministic clocks.

License

MIT.