rate-limit package
A framework-agnostic rate-limiting core built on rate-limiter-flexible.
Counters live in an injected Redis (ioredis) client so limits are shared across replicas, with an in-memory fallback that keeps enforcement alive through Redis outages or when no client is configured. A steady window can be composed with a short burst allowance to absorb legitimate spikes.
createGlobalRateLimiter() guards pre-authentication traffic by client IP.
createLocalRateLimiter() enforces per-actor, per-resource quotas for identified traffic.
createRateLimiter() exposes the underlying core for anything else.
Classes
| Class | Description |
|---|---|
| RateLimitExceededError | Thrown when a key has exhausted its rate-limit allowance. Carries everything needed to build an HTTP 429 response. See RateLimitExceededError.toHttpHeaders() for deriving a |
Functions
| Function | Description |
|---|---|
| createGlobalRateLimiter(options) | Create a pre-authentication rate limiter keyed purely by client IP. Mount this before authentication flows that rely on querying critical infrastructure. Defaults to 100 points per second with no burst. Override via CreateRateLimiterOptions.overrides. Pass |
| createLocalRateLimiter(options) | Create a rate limiter enforcing per-actor, per-resource quotas for identified traffic. Defaults to 50 points per 10 seconds with a burst of 20 per 30 seconds. Override via CreateRateLimiterOptions.overrides. |
| createRateLimiter(options) | Create a rate limiter backed by the injected Redis client, or by in-memory counters when no client is configured. |
| normalizeIp(ip) | Derive the store key for a client IP, or IPv4 addresses, including IPv4-mapped IPv6 addresses, are keyed per address. IPv6 addresses are keyed by their /64 prefix, since a subscriber typically holds an entire /64 and could otherwise mint a fresh bucket per request by rotating within it. Output keys have their colons replaced with |
Interfaces
| Interface | Description |
|---|---|
| BurstConfig | A short-lived allowance layered on top of the steady window to absorb legitimate spikes, such as a page load firing several parallel API calls. |
| CreateGlobalRateLimiterOptions | Options for creating a global rate limiter. |
| CreateRateLimiterOptions | Options for creating a rate limiter. |
| FallbackConfig | Fallback allowance for the in-memory limiter used as insurance during a Redis outage, and as the sole limiter when no client is configured. Both fields are required when overriding the factory's built-in fallback. |
| GlobalRateLimiter | A rate limiter keyed purely by client IP, for use before authentication. Obtain one via createGlobalRateLimiter(). |
| LocalRateLimiter | A rate limiter keyed by actor and resource, for identified traffic. Obtain one via createLocalRateLimiter(). |
| Logger | The subset of a structured logger this package needs. Any logger whose |
| RateLimitConfig | Configuration for a rate-limit window. Omitted fields inherit the limiter's defaults. |
| RateLimiter | A rate limiter. Obtain one via createRateLimiter(), createGlobalRateLimiter() or createLocalRateLimiter(). |
| RateLimitInfo | A snapshot of a key's rate-limit state after a check. |
Type Aliases
| Type Alias | Description |
|---|---|
| CreateLocalRateLimiterOptions | Options for creating a local rate limiter. |
| RedisClient | The ioredis client used to share rate-limit counters across instances. |