Defined in: rate-limiter.ts:80

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.

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.

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 RateLimiter(
  (id: string) => api.getData(id),
  { limit: 5, window: 1000, windowType: 'sliding' } // 5 calls per second with sliding window
);

// Will execute immediately until limit reached, then block
rateLimiter.maybeExecute('123');

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

// Will execute immediately until limit reached, then block
rateLimiter.maybeExecute('123');

• TFn extends AnyFunction

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

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

Defined in: rate-limiter.ts:86

TFn

RateLimiterOptions<TFn>

RateLimiter<TFn>

getEnabled(): boolean

getEnabled(): boolean

Defined in: rate-limiter.ts:114

Returns the current enabled state of the rate limiter

boolean

getExecutionCount(): number

getExecutionCount(): number

Defined in: rate-limiter.ts:199

Returns the number of times the function has been executed

number

getLimit(): number

getLimit(): number

Defined in: rate-limiter.ts:121

Returns the current limit of executions allowed within the time window

number

getMsUntilNextWindow(): number

getMsUntilNextWindow(): number

Defined in: rate-limiter.ts:221

Returns the number of milliseconds until the next execution will be possible

number

getOptions(): Required<RateLimiterOptions<TFn>>

getOptions(): Required<RateLimiterOptions<TFn>>

Defined in: rate-limiter.ts:107

Returns the current rate limiter options

Required<RateLimiterOptions<TFn>>

getRejectionCount(): number

getRejectionCount(): number

Defined in: rate-limiter.ts:206

Returns the number of times the function has been rejected

number

getRemainingInWindow(): number

getRemainingInWindow(): number

Defined in: rate-limiter.ts:213

Returns the number of remaining executions allowed in the current window

number

getWindow(): number

getWindow(): number

Defined in: rate-limiter.ts:128

Returns the current time window in milliseconds

number

maybeExecute(...args): boolean

maybeExecute(...args): boolean

Defined in: rate-limiter.ts:147

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

boolean

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

reset(): void

Defined in: rate-limiter.ts:232

Resets the rate limiter state

void

setOptions(newOptions): void

setOptions(newOptions): void

Defined in: rate-limiter.ts:100

Updates the rate limiter options Returns the new options state

Partial<RateLimiterOptions<TFn>>

void