Defined in: async-rate-limiter.ts:95

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.

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.

Unlike the non-async RateLimiter, this async version supports returning values from the rate-limited function, making it ideal for API calls and other async operations where you want the result of the maybeExecute call instead of setting the result on a state variable from within the rate-limited function.

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.

const rateLimiter = new AsyncRateLimiter(
  async (id: string) => await api.getData(id),
  { limit: 5, window: 1000, windowType: 'sliding' } // 5 calls per second with sliding window
);

// Will execute immediately until limit reached, then block
// Returns the API response directly
const data = await rateLimiter.maybeExecute('123');

const rateLimiter = new AsyncRateLimiter(
  async (id: string) => await api.getData(id),
  { limit: 5, window: 1000, windowType: 'sliding' } // 5 calls per second with sliding window
);

// Will execute immediately until limit reached, then block
// Returns the API response directly
const data = await rateLimiter.maybeExecute('123');

• TFn extends AnyAsyncFunction

new AsyncRateLimiter<TFn>(fn, initialOptions): AsyncRateLimiter<TFn>

new AsyncRateLimiter<TFn>(fn, initialOptions): AsyncRateLimiter<TFn>

Defined in: async-rate-limiter.ts:105

TFn

AsyncRateLimiterOptions<TFn>

AsyncRateLimiter<TFn>

getErrorCount(): number

getErrorCount(): number

Defined in: async-rate-limiter.ts:250

Returns the number of times the function has errored

number

getIsExecuting(): boolean

getIsExecuting(): boolean

Defined in: async-rate-limiter.ts:264

Returns whether the function is currently executing

boolean

getMsUntilNextWindow(): number

getMsUntilNextWindow(): number

Defined in: async-rate-limiter.ts:225

Returns the number of milliseconds until the next execution will be possible For fixed windows, this is the time until the current window resets For sliding windows, this is the time until the oldest execution expires

number

getOptions(): Required<AsyncRateLimiterOptions<TFn>>

getOptions(): Required<AsyncRateLimiterOptions<TFn>>

Defined in: async-rate-limiter.ts:126

Returns the current rate limiter options

Required<AsyncRateLimiterOptions<TFn>>

getRejectionCount(): number

getRejectionCount(): number

Defined in: async-rate-limiter.ts:257

Returns the number of times the function has been rejected

number

getRemainingInWindow(): number

getRemainingInWindow(): number

Defined in: async-rate-limiter.ts:215

Returns the number of remaining executions allowed in the current window

number

getSettleCount(): number

getSettleCount(): number

Defined in: async-rate-limiter.ts:243

Returns the number of times the function has been settled

number

getSuccessCount(): number

getSuccessCount(): number

Defined in: async-rate-limiter.ts:236

Returns the number of times the function has been executed

number

maybeExecute(...args): Promise<undefined | ReturnType<TFn>>

maybeExecute(...args): Promise<undefined | ReturnType<TFn>>

Defined in: async-rate-limiter.ts:146

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<TFn>

Promise<undefined | ReturnType<TFn>>

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(): void

reset(): void

Defined in: async-rate-limiter.ts:271

Resets the rate limiter state

void

setOptions(newOptions): void

setOptions(newOptions): void

Defined in: async-rate-limiter.ts:119

Updates the rate limiter options Returns the new options state

Partial<AsyncRateLimiterOptions<TFn>>

void