asyncDebounce

function asyncDebounce<TFn>(fn, initialOptions): (...args) => Promise<Awaited<ReturnType<TFn>> | undefined>;

Defined in: async-debouncer.ts:560

Creates an async debounced function that delays execution until after a specified wait time. The debounced function will only execute once the wait period has elapsed without any new calls. If called again during the wait period, the timer resets and a new wait period begins.

Async vs Sync Versions: The async version provides advanced features over the sync debounce function:

• Returns promises that can be awaited for debounced function results
• Built-in retry support via AsyncRetryer integration
• Abort support to cancel in-flight executions
• Cancel support to prevent pending executions from starting
• Comprehensive error handling with onError callbacks and throwOnError control
• Detailed execution tracking (success/error/settle counts)

The sync debounce function is lighter weight and simpler when you don't need async features, return values, or execution control.

What is Debouncing? Debouncing ensures that a function is only executed after a specified delay has passed since its last invocation. Each new invocation resets the delay timer. This is useful for handling frequent events like window resizing or input changes where you only want to execute the handler after the events have stopped occurring.

Configuration Options:

• wait: Delay in milliseconds to wait after the last call (required)
• leading: Execute on the leading edge of the timeout (default: false)
• trailing: Execute on the trailing edge of the timeout (default: true)
• enabled: Whether the debouncer is enabled (default: true)
• asyncRetryerOptions: Configure retry behavior for executions

Error Handling:

• If an onError handler is provided, it will be called with the error and debouncer 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
• The error state can be checked using the underlying AsyncDebouncer instance
• Both onError and throwOnError can be used together - the handler will be called before any error is thrown

State Management:

• Uses TanStack Store for reactive state management
• Use initialState to provide initial state values when creating the async debouncer
• Use onSuccess callback to react to successful function execution and implement custom logic
• Use onError callback to react to function execution errors and implement custom error handling
• Use onSettled callback to react to function execution completion (success or error) and implement custom logic
• The state includes canLeadingExecute, error count, execution status, and success/settle counts
• State can be accessed via asyncDebouncer.store.state when using the class directly
• When using framework adapters (React/Solid), state is accessed from asyncDebouncer.state

Type Parameters

TFn

TFn extends AnyAsyncFunction

Parameters

fn

TFn

initialOptions

AsyncDebouncerOptions<TFn>

Returns

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

Attempts to execute the debounced function. If a call is already in progress, it will be queued.

Error Handling:

• If the debounced 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

args

...Parameters<TFn>

Returns

Promise<Awaited<ReturnType<TFn>> | undefined>

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

Throws

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

Example

const debounced = asyncDebounce(async (value: string) => {
  const result = await saveToAPI(value);
  return result; // Return value is preserved
}, {
  wait: 1000,
  onError: (error) => {
    console.error('API call failed:', error);
  },
  throwOnError: true // Will both log the error and throw it
});

// Will only execute once, 1 second after the last call
// Returns the API response directly
const result = await debounced("third");