debounce

Delays a function until calls have stopped for a specified duration.

Code

debounce.ts

export type DebouncedFunction<
  Arguments extends unknown[],
  This = unknown,
> = ((
  this: This,
  ...args: Arguments
) => void) & {
  cancel: () => void;
  flush: () => void;
  pending: () => boolean;
};

/** Delays a function until calls have stopped for the configured duration. */
export const debounce = <This, Arguments extends unknown[]>(
  fn: (this: This, ...args: Arguments) => unknown,
  delayMs: number = 300
): DebouncedFunction<Arguments, This> => {
  if (!Number.isFinite(delayMs) || delayMs < 0) {
    throw new RangeError("delayMs must be a finite, non-negative number");
  }

  let timer: ReturnType<typeof setTimeout> | undefined;
  let latestArguments: Arguments | undefined;
  let latestReceiver: This | undefined;

  const invoke = () => {
    const args = latestArguments;
    const receiver = latestReceiver;
    timer = undefined;
    latestArguments = undefined;
    latestReceiver = undefined;
    if (args) {
      Reflect.apply(fn, receiver, args);
    }
  };

  const debounced = function (this: This, ...args: Arguments) {
    latestArguments = args;
    latestReceiver = this;
    if (timer !== undefined) clearTimeout(timer);
    timer = setTimeout(invoke, delayMs);
  };

  return Object.assign(debounced, {
    cancel: () => {
      if (timer !== undefined) clearTimeout(timer);
      timer = undefined;
      latestArguments = undefined;
      latestReceiver = undefined;
    },
    flush: () => {
      if (timer === undefined) return;
      clearTimeout(timer);
      invoke();
    },
    pending: () => timer !== undefined,
  });
};

Download

wget

Terminal

wget -O src/lib/debounce.ts https://raw.githubusercontent.com/jrTilak/lazykit/HEAD/registry/functions/debounce.ts

degit

Terminal

temp_dir="$(mktemp -d)" && bunx degit jrTilak/lazykit/registry/functions "$temp_dir" && mv "$temp_dir/debounce.ts" src/lib/debounce.ts && rm -r "$temp_dir"

Examples

debounce.example.ts

import { debounce } from "./debounce";

const search = debounce((query: string) => {
  console.log("Searching for", query);
}, 300);

search("lazy");
search("lazykit");
// After 300ms: Searching for lazykit

Props

• fn ((...args: A) => unknown) — Function invoked with the arguments and receiver from the latest call.
• delayMs (number, default: 300) — Finite, non-negative quiet period in milliseconds.

Returns

A debounced function with cancel(), flush(), and pending() controls.