asyncRateLimit
Function: asyncRateLimit()
function asyncRateLimit<TFn, TArgs>(fn, initialOptions): (...args) => Promise<boolean>
function asyncRateLimit<TFn, TArgs>(fn, initialOptions): (...args) => Promise<boolean>
Defined in: async-rate-limiter.ts:245
Creates an async 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
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 AnyAsyncFunction
• TArgs extends any[]
Parameters
fn
TFn
initialOptions
Omit<AsyncRateLimiterOptions<TFn, TArgs>, "enabled">
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. If execution is allowed, waits for any previous execution to complete before proceeding.
Parameters
args
...TArgs
Returns
Promise<boolean>
Example
const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
// First 5 calls will execute
await rateLimiter.maybeExecute('arg1', 'arg2');
// Additional calls within the window will be rejected
await rateLimiter.maybeExecute('arg1', 'arg2'); // Rejected
const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
// First 5 calls will execute
await rateLimiter.maybeExecute('arg1', 'arg2');
// Additional calls within the window will be rejected
await rateLimiter.maybeExecute('arg1', 'arg2'); // Rejected
Example
// Rate limit to 5 calls per minute
const rateLimited = asyncRateLimit(makeApiCall, {
limit: 5,
window: 60000,
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
await 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
const rateLimited = asyncRateLimit(makeApiCall, {
limit: 5,
window: 60000,
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
await 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.