On this page
- Class: RateLimiter<TFn, TArgs>
- Example
- Type Parameters
- Constructors
- new RateLimiter()
- Parameters
- fn
- initialOptions
- Returns
- Methods
- getExecutionCount()
- Returns
- getMsUntilNextWindow()
- Returns
- getOptions()
- Returns
- getRejectionCount()
- Returns
- getRemainingInWindow()
- Returns
- maybeExecute()
- Parameters
- args
- Returns
- Example
- reset()
- Returns
- setOptions()
- Parameters
- newOptions
- Returns
RateLimiter
Class: RateLimiter<TFn, TArgs>
Defined in: rate-limiter.ts:66
A class that creates a rate-limited function.
Rate limiting is a simple approach that allows a function to execute up to a limit within a time window, then blocks all subsequent calls until the window passes. This can lead to "bursty" behavior where all executions happen immediately, followed by a complete block.
For smoother execution patterns, consider using:
- Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)
- Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)
Rate limiting is best used for hard API limits or resource constraints. For UI updates or smoothing out frequent events, throttling or debouncing usually provide better user experience.
Example
const rateLimiter = new RateLimiter(
(id: string) => api.getData(id),
{ limit: 5, window: 1000 } // 5 calls per second
);
// Will execute immediately until limit reached, then block
rateLimiter.maybeExecute('123');
const rateLimiter = new RateLimiter(
(id: string) => api.getData(id),
{ limit: 5, window: 1000 } // 5 calls per second
);
// Will execute immediately until limit reached, then block
rateLimiter.maybeExecute('123');
Type Parameters
• TFn extends AnyFunction
• TArgs extends Parameters<TFn>
Constructors
new RateLimiter()
new RateLimiter<TFn, TArgs>(fn, initialOptions): RateLimiter<TFn, TArgs>
new RateLimiter<TFn, TArgs>(fn, initialOptions): RateLimiter<TFn, TArgs>
Defined in: rate-limiter.ts:75
Parameters
fn
TFn
initialOptions
RateLimiterOptions<TFn, TArgs>
Returns
RateLimiter<TFn, TArgs>
Methods
getExecutionCount()
getExecutionCount(): number
getExecutionCount(): number
Defined in: rate-limiter.ts:161
Returns the number of times the function has been executed
Returns
number
getMsUntilNextWindow()
getMsUntilNextWindow(): number
getMsUntilNextWindow(): number
Defined in: rate-limiter.ts:183
Returns the number of milliseconds until the next execution will be possible
Returns
number
getOptions()
getOptions(): Required<RateLimiterOptions<TFn, TArgs>>
getOptions(): Required<RateLimiterOptions<TFn, TArgs>>
Defined in: rate-limiter.ts:102
Returns the current rate limiter options
Returns
Required<RateLimiterOptions<TFn, TArgs>>
getRejectionCount()
getRejectionCount(): number
getRejectionCount(): number
Defined in: rate-limiter.ts:168
Returns the number of times the function has been rejected
Returns
number
getRemainingInWindow()
getRemainingInWindow(): number
getRemainingInWindow(): number
Defined in: rate-limiter.ts:175
Returns the number of remaining executions allowed in the current window
Returns
number
maybeExecute()
maybeExecute(...args): boolean
maybeExecute(...args): boolean
Defined in: rate-limiter.ts:121
Attempts to execute the rate-limited function if within the configured limits. Will reject execution if the number of calls in the current window exceeds the limit.
Parameters
args
...TArgs
Returns
boolean
Example
const rateLimiter = new RateLimiter(fn, { limit: 5, window: 1000 });
// First 5 calls will return true
rateLimiter.maybeExecute('arg1', 'arg2'); // true
// Additional calls within the window will return false
rateLimiter.maybeExecute('arg1', 'arg2'); // false
const rateLimiter = new RateLimiter(fn, { limit: 5, window: 1000 });
// First 5 calls will return true
rateLimiter.maybeExecute('arg1', 'arg2'); // true
// Additional calls within the window will return false
rateLimiter.maybeExecute('arg1', 'arg2'); // false
reset()
reset(): void
reset(): void
Defined in: rate-limiter.ts:191
Resets the rate limiter state
Returns
void
setOptions()
setOptions(newOptions): RateLimiterOptions<TFn, TArgs>
setOptions(newOptions): RateLimiterOptions<TFn, TArgs>
Defined in: rate-limiter.ts:89
Updates the rate limiter options Returns the new options state
Parameters
newOptions
Partial<RateLimiterOptions<TFn, TArgs>>
Returns
RateLimiterOptions<TFn, TArgs>
Subscribe to Bytes
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.