rateLimit
Function: rateLimit()
function rateLimit<TFn>(fn, initialOptions): (...args) => boolean
function rateLimit<TFn>(fn, initialOptions): (...args) => boolean
Defined in: rate-limiter.ts:276
Creates a rate-limited function that will execute the provided function up to a maximum number of times within a time window.
Note that rate limiting is a simpler form of execution control compared to throttling or debouncing:
- A rate limiter will allow all executions until the limit is reached, then block all subsequent calls until the window resets
- A throttler ensures even spacing between executions, which can be better for consistent performance
- A debouncer collapses multiple calls into one, which is better for handling bursts of events
The rate limiter supports two types of windows:
- 'fixed': A strict window that resets after the window period. All executions within the window count towards the limit, and the window resets completely after the period.
- 'sliding': A rolling window that allows executions as old ones expire. This provides a more consistent rate of execution over time.
Consider using throttle() or debounce() if you need more intelligent execution control. Use rate limiting when you specifically need to enforce a hard limit on the number of executions within a time period.
Type Parameters
• TFn extends AnyFunction
Parameters
fn
TFn
initialOptions
RateLimiterOptions<TFn>
Returns
Function
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
Example
// Rate limit to 5 calls per minute with a sliding window
const rateLimited = rateLimit(makeApiCall, {
limit: 5,
window: 60000,
windowType: 'sliding',
onReject: (rateLimiter) => {
console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
}
});
// First 5 calls will execute immediately
// Additional calls will be rejected until the minute window resets
rateLimited();
// For more even execution, consider using throttle instead:
const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
// Rate limit to 5 calls per minute with a sliding window
const rateLimited = rateLimit(makeApiCall, {
limit: 5,
window: 60000,
windowType: 'sliding',
onReject: (rateLimiter) => {
console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
}
});
// First 5 calls will execute immediately
// Additional calls will be rejected until the minute window resets
rateLimited();
// For more even execution, consider using throttle instead:
const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
Subscribe to Bytes
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.