Class: Throttler<TFn>#

Defined in: throttler.ts:150

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. This synchronous version is lighter weight and often all you need - upgrade to AsyncThrottler when you need promises, retry support, abort/cancel capabilities, or advanced error handling.

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 collapsing rapid-fire events where you only care about the last call, consider using Debouncer.

  State Management:

• Uses TanStack Store for reactive state management

• Use initialState to provide initial state values when creating the throttler

• Use onExecute callback to react to function execution and implement custom logic

• The state includes execution count, last execution time, pending status, and more

• State can be accessed via throttler.store.state when using the class directly

• When using framework adapters (React/Solid), state is accessed from throttler.state

Example#

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

Type Parameters#

TFn#

TFn extends AnyFunction

Constructors#

Constructor#

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

Defined in: throttler.ts:158

Parameters#

fn#

TFn

initialOptions#

ThrottlerOptions<TFn>

Returns#

Throttler<TFn>

Properties#

fn#

fn: TFn;

Defined in: throttler.ts:159

key#

key: string | undefined;

Defined in: throttler.ts:154

options#

options: ThrottlerOptions<TFn>;

Defined in: throttler.ts:155

store#

readonly store: Store<Readonly<ThrottlerState<TFn>>>;

Defined in: throttler.ts:151

Methods#

cancel()#

cancel(): void;

Defined in: throttler.ts:322

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.

Returns#

void

flush()#

flush(): void;

Defined in: throttler.ts:300

Processes the current pending execution immediately

Returns#

void

maybeExecute()#

maybeExecute(...args): void;

Defined in: throttler.ts:241

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

Parameters#

args#

...Parameters<TFn>

Returns#

void

Example#

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');

reset()#

reset(): void;

Defined in: throttler.ts:333

Resets the throttler state to its default values

Returns#

void

setOptions()#

setOptions(newOptions): void;

Defined in: throttler.ts:183

Updates the throttler options

Parameters#

newOptions#

Partial<ThrottlerOptions<TFn>>

Returns#

void