On this page
- Class: RateLimiter<TFn>
- 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>
Defined in: rate-limiter.ts:63
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
Constructors
new RateLimiter()
new RateLimiter<TFn>(fn, initialOptions): RateLimiter<TFn>
new RateLimiter<TFn>(fn, initialOptions): RateLimiter<TFn>
Defined in: rate-limiter.ts:69
Parameters
fn
TFn
initialOptions
RateLimiterOptions<TFn>
Returns
RateLimiter<TFn>
Methods
getExecutionCount()
getExecutionCount(): number
getExecutionCount(): number
Defined in: rate-limiter.ts:149
Returns the number of times the function has been executed
Returns
number
getMsUntilNextWindow()
getMsUntilNextWindow(): number
getMsUntilNextWindow(): number
Defined in: rate-limiter.ts:171
Returns the number of milliseconds until the next execution will be possible
Returns
number
getOptions()
getOptions(): Required<RateLimiterOptions<TFn>>
getOptions(): Required<RateLimiterOptions<TFn>>
Defined in: rate-limiter.ts:90
Returns the current rate limiter options
Returns
Required<RateLimiterOptions<TFn>>
getRejectionCount()
getRejectionCount(): number
getRejectionCount(): number
Defined in: rate-limiter.ts:156
Returns the number of times the function has been rejected
Returns
number
getRemainingInWindow()
getRemainingInWindow(): number
getRemainingInWindow(): number
Defined in: rate-limiter.ts:163
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:109
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
...Parameters<TFn>
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:179
Resets the rate limiter state
Returns
void
setOptions()
setOptions(newOptions): void
setOptions(newOptions): void
Defined in: rate-limiter.ts:83
Updates the rate limiter options Returns the new options state
Parameters
newOptions
Partial<RateLimiterOptions<TFn>>
Returns
void
Subscribe to Bytes
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.