📄 tanstack/pacer/latest/docs/reference/functions/asyncDebounce

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


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

Defined in: async-debouncer.ts:553

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<ReturnType<TFn> | undefined>;


(...args): Promise<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<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");


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

Edit on GitHub

debounce

Debouncer

Partners Become a Partner

scarf analytics