bottleneck

Bottleneck is a zero-dependency task scheduler and rate limiter for Node.js and the browser, designed to throttle API calls without adding meaningful complexity to a codebase. It wraps promise-, async/await-, and callback-based functions alike through submit(), schedule(), and wrap(), queuing jobs and releasing them according to configurable concurrency, minimum time between requests, and reservoir-based quotas.

Beyond single-process use, Bottleneck can synchronize rate limits across multiple Node.js instances via Redis (ioredis or node_redis), using atomic Lua scripts to keep counters consistent even when clients disconnect unexpectedly. This clustering support, along with job priorities, retry hooks, batching, and a full event system for debugging, makes it a common choice for applications that need reliable throttling both locally and at scale.

What You Get

• A promise/async-await/callback-agnostic API (schedule(), wrap(), submit()) that rate-limits usage without rewriting the wrapped function
• Concurrency and timing controls (maxConcurrent, minTime, reservoir) to model per-second, per-minute, or bursty rate limits
• Distributed rate limiting across processes and servers via Redis (ioredis or node_redis) with atomic Lua-script coordination
• Job priorities, weights, retries, and expiration for fine-grained control over queue order and failure handling
• A Group helper for managing per-key limiters (e.g., one limiter per API user) without manual bookkeeping
• Batching support (Batcher) to coalesce many small calls into fewer batched requests

Common Use Cases

• Throttling calls to third-party APIs (payment processors, SaaS platforms) that enforce strict per-second or per-minute rate limits
• Coordinating rate limits across multiple worker processes or horizontally scaled servers sharing one external API quota
• Limiting concurrent database or filesystem operations to avoid overwhelming a downstream resource
• Smoothing bursty webhook or event-processing workloads into a steady, predictable request rate

Under The Hood

Architecture Bottleneck follows a layered design: the public Bottleneck class exposes submit/schedule/wrap and delegates queue management to a Queues module, job lifecycle to a Job module, and rate-limit state to a pluggable datastore — a local in-process store for single-process use, or a Redis-backed store for distributed use. Jobs pass through a queue-and-drain cycle that consults the active datastore before releasing a job for execution, with state and events tracked by dedicated subsystems. The Redis-backed datastore swaps in Lua scripts for every state-mutating operation, making cross-process coordination atomic without needing distributed locks. This datastore abstraction is the core seam: switching from local to Redis-backed storage changes only what backs concurrency/timing state, while the public API and job lifecycle stay identical — a clean application of the strategy pattern to state storage. Were the Lua-script contract to change, the local and Redis implementations would need to evolve in lockstep.

Tech Stack Written in CoffeeScript and compiled to two published bundles — a full Node.js build and a lighter browser bundle without Redis support — with zero runtime dependencies. Distributed coordination targets Redis via either of the two dominant Node Redis clients as optional integrations, using hand-written Lua scripts assembled at build time rather than a query builder. Type definitions are hand-authored from a template rather than derived from TypeScript source. Testing runs against real Redis connections in continuous integration rather than mocking the datastore, and a dedicated bundler pipeline produces the browser build.

Code Quality The test suite is extensive and exercises the distributed-coordination paths against real Redis backends rather than mocks, giving strong confidence in cluster behavior specifically. Error handling is explicit and typed through a dedicated error class, and job failures, drops, and retries are modeled as first-class states rather than being swallowed silently. Naming is consistent, with a clear naming convention marking the boundary between the public API and the internal datastore interface. Inline comments are sparse throughout the source, and there is no linter or formatter configuration checked into the repository.

API Design The headline design choice is transport-agnostic scheduling — the same limiter object can rate-limit promise-returning, async/await, and Node-style-callback functions, so adopting the library requires no rewrite of existing call sites. The wrapping helper in particular offers near-zero-boilerplate adoption, and the per-key group helper removes the manual bookkeeping of tracking one limiter per key, including disposing of idle limiters automatically. The reservoir-based options give a well-thought-out vocabulary for modeling everything from simple per-second caps to complex rolling or periodic quotas without hand-rolled timer logic. Documentation is unusually thorough, with a full option reference, a lifecycle explanation, an event list, and a dedicated section anticipating common misuse.