Throttler

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