On this page
- Class: AsyncRateLimiter<TFn>
- Example
- Type Parameters
- Constructors
- new AsyncRateLimiter()
- Parameters
- fn
- initialOptions
- Returns
- Methods
- getErrorCount()
- Returns
- getMsUntilNextWindow()
- Returns
- getOptions()
- Returns
- getRejectionCount()
- Returns
- getRemainingInWindow()
- Returns
- getSettleCount()
- Returns
- getSuccessCount()
- Returns
- maybeExecute()
- Parameters
- args
- Returns
- Example
- reset()
- Returns
- setOptions()
- Parameters
- newOptions
- Returns
AsyncRateLimiter
Class: AsyncRateLimiter<TFn>
Defined in: async-rate-limiter.ts:76
A class that creates an async 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 AsyncRateLimiter(
async (id: string) => await api.getData(id),
{ limit: 5, window: 1000 } // 5 calls per second
);
// Will execute immediately until limit reached, then block
await rateLimiter.maybeExecute('123');
const rateLimiter = new AsyncRateLimiter(
async (id: string) => await api.getData(id),
{ limit: 5, window: 1000 } // 5 calls per second
);
// Will execute immediately until limit reached, then block
await rateLimiter.maybeExecute('123');
Type Parameters
• TFn extends AnyAsyncFunction
Constructors
new AsyncRateLimiter()
new AsyncRateLimiter<TFn>(fn, initialOptions): AsyncRateLimiter<TFn>
new AsyncRateLimiter<TFn>(fn, initialOptions): AsyncRateLimiter<TFn>
Defined in: async-rate-limiter.ts:85
Parameters
fn
TFn
initialOptions
Returns
AsyncRateLimiter<TFn>
Methods
getErrorCount()
getErrorCount(): number
getErrorCount(): number
Defined in: async-rate-limiter.ts:209
Returns the number of times the function has errored
Returns
number
getMsUntilNextWindow()
getMsUntilNextWindow(): number
getMsUntilNextWindow(): number
Defined in: async-rate-limiter.ts:188
Returns the number of milliseconds until the next execution will be possible
Returns
number
getOptions()
getOptions(): Required<AsyncRateLimiterOptions<TFn>>
getOptions(): Required<AsyncRateLimiterOptions<TFn>>
Defined in: async-rate-limiter.ts:106
Returns the current rate limiter options
Returns
Required<AsyncRateLimiterOptions<TFn>>
getRejectionCount()
getRejectionCount(): number
getRejectionCount(): number
Defined in: async-rate-limiter.ts:216
Returns the number of times the function has been rejected
Returns
number
getRemainingInWindow()
getRemainingInWindow(): number
getRemainingInWindow(): number
Defined in: async-rate-limiter.ts:180
Returns the number of remaining executions allowed in the current window
Returns
number
getSettleCount()
getSettleCount(): number
getSettleCount(): number
Defined in: async-rate-limiter.ts:202
Returns the number of times the function has been settled
Returns
number
getSuccessCount()
getSuccessCount(): number
getSuccessCount(): number
Defined in: async-rate-limiter.ts:195
Returns the number of times the function has been executed
Returns
number
maybeExecute()
maybeExecute(...args): Promise<undefined | ReturnType<TFn>>
maybeExecute(...args): Promise<undefined | ReturnType<TFn>>
Defined in: async-rate-limiter.ts:126
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
...Parameters<TFn>
Returns
Promise<undefined | ReturnType<TFn>>
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
reset()
reset(): void
reset(): void
Defined in: async-rate-limiter.ts:223
Resets the rate limiter state
Returns
void
setOptions()
setOptions(newOptions): void
setOptions(newOptions): void
Defined in: async-rate-limiter.ts:99
Updates the rate limiter options Returns the new options state
Parameters
newOptions
Partial<AsyncRateLimiterOptions<TFn>>
Returns
void
Subscribe to Bytes
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.