Debouncer

class ui.Debouncer()

A utility class that delays the execution of a callback function until after a specified delay period has elapsed since the last time it was invoked. This is useful for optimizing performance by limiting the rate at which a function executes, such as handling rapid user input events.

The debouncer returns a Promise that resolves with the callback’s return value or rejects if the callback throws an error or if the debounced call is cancelled.

Examples

// Basic usage with synchronous callback
const debouncer = new Debouncer((value: string) => {
  console.log('Search for:', value);
  return value.toUpperCase();
});

const result = await debouncer.debounce(500, 'hello');
console.log(result); // 'HELLO'

// Handling search input with async callback
const searchDebouncer = new Debouncer(async (query: string) => {
  const response = await fetch(`/api/search?q=${query}`);
  return response.json();
});

inputElement.addEventListener('input', async (e) => {
  try {
    const results = await searchDebouncer.debounce(300, e.target.value);
    displayResults(results);
  } catch (error) {
    if (error.message !== 'Debounced call was cancelled') {
      console.error('Search failed:', error);
    }
  }
});

// Error handling
const debouncer = new Debouncer((value: number) => {
  if (value < 0) throw new Error('Value must be positive');
  return value * 2;
});

try {
  await debouncer.debounce(500, -5);
} catch (error) {
  console.error('Callback error:', error.message);
}

Since

2025.9.0

Index

Constructors

Properties

Accessors

Methods

Constructors

ui.Debouncer.constructor()
Debouncer(callback: (args: TArgs) => TReturn): Debouncer<TArgs, TReturn>

Creates a new Debouncer instance with the specified callback function.

Parameters

callback: (args: TArgs) => TReturn

The function to debounce. Can be synchronous or asynchronous.

Returns: Debouncer<TArgs, TReturn>

Examples

const debouncer = new Debouncer((x: number, y: number) => x + y);

Properties

ui.Debouncer.callback
callback: (args: TArgs) => TReturn

The callback function to be executed after the debounce delay. This can be updated dynamically to change the debounced behavior.

Accessors

ui.Debouncer.isPending()
get isPending(): boolean

Indicates whether a debounced callback is currently waiting to execute.

Returns: boolean

true if a callback is scheduled to execute, false otherwise

Examples

const debouncer = new Debouncer(() => console.log('Execute'));

console.log(debouncer.isPending); // false

debouncer.debounce(500);
console.log(debouncer.isPending); // true

await new Promise(resolve => setTimeout(resolve, 500));
console.log(debouncer.isPending); // false

Methods

ui.Debouncer.clear()
clear(): void

Cancels any pending debounced execution. If a debounced callback is waiting to execute, it will be cancelled and the associated Promise will reject with no error.

This method is safe to call multiple times and can be called even when no execution is pending.

Returns: void

Examples

const debouncer = new Debouncer(() => console.log('Execute'));

const promise = debouncer.debounce(500);
debouncer.clear(); // Cancels the pending execution

try {
  await promise;
} catch (error) {
  console.log('Execution was cancelled');
}
ui.Debouncer.debounce()
debounce(delay: number, args: TArgs): Promise

Schedules the callback to execute after the specified delay. If called again before the delay elapses, the previous call is cancelled and a new delay period begins.

Parameters

delay: number

The number of milliseconds to wait before executing the callback

args: TArgs

Arguments to pass to the callback function

Returns: Promise

A Promise that resolves with the callback’s return value or rejects if:
  • The callback throws an error
  • The debounced call is cancelled via clear() or another debounce() call

Examples

const debouncer = new Debouncer((text: string) => text.toUpperCase());

// Only the last call executes after 500ms
debouncer.debounce(500, 'first');  // Cancelled
debouncer.debounce(500, 'second'); // Cancelled
const result = await debouncer.debounce(500, 'third'); // Executes
console.log(result); // 'THIRD'