Defined in: throttler.ts:61

A class that creates a throttled function.

Throttling ensures a function is called at most once within a specified time window. Unlike debouncing which waits for a pause in calls, throttling guarantees consistent execution timing regardless of call frequency.

Supports both leading and trailing edge execution:

• Leading: Execute immediately on first call (default: true)
• Trailing: Execute after wait period if called during throttle (default: true)

For rate limiting or hard API limits, consider using RateLimiter instead. For collapsing rapid-fire events, consider using Debouncer.

const throttler = new Throttler(
  (id: string) => api.getData(id),
  { wait: 1000 } // Execute at most once per second
);

// First call executes immediately
throttler.maybeExecute('123');

// Subsequent calls within 1000ms are throttled
throttler.maybeExecute('123'); // Throttled

const throttler = new Throttler(
  (id: string) => api.getData(id),
  { wait: 1000 } // Execute at most once per second
);

// First call executes immediately
throttler.maybeExecute('123');

// Subsequent calls within 1000ms are throttled
throttler.maybeExecute('123'); // Throttled

• TFn extends (...args) => any

• TArgs extends Parameters<TFn>

new Throttler<TFn, TArgs>(fn, initialOptions): Throttler<TFn, TArgs>

new Throttler<TFn, TArgs>(fn, initialOptions): Throttler<TFn, TArgs>

Defined in: throttler.ts:71

TFn

ThrottlerOptions

Throttler<TFn, TArgs>

cancel(): void

cancel(): void

Defined in: throttler.ts:174

Cancels any pending trailing execution and clears internal state.

If a trailing execution is scheduled (due to throttling with trailing=true), this will prevent that execution from occurring. The internal timeout and stored arguments will be cleared.

Has no effect if there is no pending execution.

void

getExecutionCount(): number

getExecutionCount(): number

Defined in: throttler.ts:98

Returns the number of times the function has been executed

number

getLastExecutionTime(): number

getLastExecutionTime(): number

Defined in: throttler.ts:105

Returns the last execution time

number

maybeExecute(...args): void

maybeExecute(...args): void

Defined in: throttler.ts:131

Attempts to execute the throttled function. The execution behavior depends on the throttler options:

• If enough time has passed since the last execution (>= wait period):

  • With leading=true: Executes immediately
  • With leading=false: Waits for the next trailing execution

• If within the wait period:

  • With trailing=true: Schedules execution for end of wait period
  • With trailing=false: Drops the execution

...TArgs

void

const throttled = new Throttler(fn, { wait: 1000 });

// First call executes immediately
throttled.maybeExecute('a', 'b');

// Call during wait period - gets throttled
throttled.maybeExecute('c', 'd');

const throttled = new Throttler(fn, { wait: 1000 });

// First call executes immediately
throttled.maybeExecute('a', 'b');

// Call during wait period - gets throttled
throttled.maybeExecute('c', 'd');

setOptions(newOptions): Required<ThrottlerOptions>

setOptions(newOptions): Required<ThrottlerOptions>

Defined in: throttler.ts:85

Updates the throttler options Returns the new options state

Partial<ThrottlerOptions>

Required<ThrottlerOptions>