Defined in: async-throttler.ts:105

A class that creates an async throttled function.

Throttling limits how often a function can be executed, allowing only one execution within a specified time window. Unlike debouncing which resets the delay timer on each call, throttling ensures the function executes at a regular interval regardless of how often it's called.

Unlike the non-async Throttler, this async version supports returning values from the throttled 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 throttled function.

This is useful for rate-limiting API calls, handling scroll/resize events, or any scenario where you want to ensure a maximum execution frequency.

Error Handling:

• If an onError handler is provided, it will be called with the error and throttler instance
• If throwOnError is true (default when no onError handler is provided), the error will be thrown
• If throwOnError is false (default when onError handler is provided), the error will be swallowed
• Both onError and throwOnError can be used together - the handler will be called before any error is thrown
• The error state can be checked using the underlying AsyncThrottler instance

const throttler = new AsyncThrottler(async (value: string) => {
  const result = await saveToAPI(value);
  return result; // Return value is preserved
}, {
  wait: 1000,
  onError: (error) => {
    console.error('API call failed:', error);
  }
});

// Will only execute once per second no matter how often called
// Returns the API response directly
const result = await throttler.maybeExecute(inputElement.value);

const throttler = new AsyncThrottler(async (value: string) => {
  const result = await saveToAPI(value);
  return result; // Return value is preserved
}, {
  wait: 1000,
  onError: (error) => {
    console.error('API call failed:', error);
  }
});

// Will only execute once per second no matter how often called
// Returns the API response directly
const result = await throttler.maybeExecute(inputElement.value);

• TFn extends AnyAsyncFunction

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

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

Defined in: async-throttler.ts:118

TFn

AsyncThrottlerOptions<TFn>

AsyncThrottler<TFn>

cancel(): void

cancel(): void

Defined in: async-throttler.ts:247

Cancels any pending execution or aborts any execution in progress

void

getEnabled(): boolean

getEnabled(): boolean

Defined in: async-throttler.ts:152

Returns the current enabled state of the throttler

boolean

getErrorCount(): number

getErrorCount(): number

Defined in: async-throttler.ts:297

Returns the number of times the function has errored

number

getIsExecuting(): boolean

getIsExecuting(): boolean

Defined in: async-throttler.ts:311

Returns the current executing state

boolean

getIsPending(): boolean

getIsPending(): boolean

Defined in: async-throttler.ts:304

Returns the current pending state

boolean

getLastExecutionTime(): number

getLastExecutionTime(): number

Defined in: async-throttler.ts:262

Returns the last execution time

number

getLastResult(): undefined | ReturnType<TFn>

getLastResult(): undefined | ReturnType<TFn>

Defined in: async-throttler.ts:276

Returns the last result of the debounced function

undefined | ReturnType<TFn>

getNextExecutionTime(): number

getNextExecutionTime(): number

Defined in: async-throttler.ts:269

Returns the next execution time

number

getOptions(): AsyncThrottlerOptions<TFn>

getOptions(): AsyncThrottlerOptions<TFn>

Defined in: async-throttler.ts:145

Returns the current options

AsyncThrottlerOptions<TFn>

getSettleCount(): number

getSettleCount(): number

Defined in: async-throttler.ts:290

Returns the number of times the function has settled (completed or errored)

number

getSuccessCount(): number

getSuccessCount(): number

Defined in: async-throttler.ts:283

Returns the number of times the function has been executed successfully

number

getWait(): number

getWait(): number

Defined in: async-throttler.ts:159

Returns the current wait time in milliseconds

number

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

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

Defined in: async-throttler.ts:177

Attempts to execute the throttled function. If a call is already in progress, it may be blocked or queued depending on the wait option.

Error Handling:

• If the throttled function throws and no onError handler is configured, the error will be thrown from this method.
• If an onError handler is configured, errors will be caught and passed to the handler, and this method will return undefined.
• The error state can be checked using getErrorCount() and getIsExecuting().

...Parameters<TFn>

Promise<undefined | ReturnType<TFn>>

A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError

The error from the throttled function if no onError handler is configured

setOptions(newOptions): void

setOptions(newOptions): void

Defined in: async-throttler.ts:133

Updates the throttler options Returns the new options state

Partial<AsyncThrottlerOptions<TFn>>

void