Implementing Debounce from Scratch

A debounce needs one piece of state, the pending timer, and two actions: cancel the pending call when a new one arrives, and schedule the real call when the calls stop.

const debounce = (fn, waitMs) => {
  let timer = null;

  const debounced = (...args) => {
    if (timer) clearTimeout(timer);
    timer = setTimeout(() => {
      timer = null;
      fn(...args);
    }, waitMs);
  };

  return debounced;
};

// Try it.
const log = (value) => console.log("called with", value);

const debounced = debounce(log, 30);

debounced("a");
debounced("b");
debounced("c");
// Only "c" is logged, 30ms after the last call.

The rest parameters matter. The debounced function accepts any arguments and forwards the ones from the final call, which is what you want for a search box, where the last keystroke is the one that matters. The this binding is another detail worth getting right, because a debounced method still needs its receiver, and an arrow function inside the returned wrapper is the simplest way to keep it.

Note the timer being reset to null inside the callback. Without that, the function would still hold the identifier of a timer that has already fired, and the next cancel would clear a timer that no longer exists. It is harmless but it is untidy, and it is the kind of thing that shows you are comfortable with the timer API.

That is the whole implementation. Around fifteen lines, and it is a good question because it tests whether you understand the timer API, closures and the difference between scheduling and cancelling work.

Both methods hang off the returned function. Cancel drops the pending call, and flush runs it immediately instead of waiting.

const debounce = (fn, waitMs) => {
  let timer = null;
  let lastArgs = null;

  const debounced = (...args) => {
    lastArgs = args;
    if (timer) clearTimeout(timer);
    timer = setTimeout(() => {
      timer = null;
      fn(...lastArgs);
      lastArgs = null;
    }, waitMs);
  };

  debounced.cancel = () => {
    if (timer) clearTimeout(timer);
    timer = null;
    lastArgs = null;
  };

  debounced.flush = () => {
    if (!timer) return;
    clearTimeout(timer);
    timer = null;
    fn(...lastArgs);
    lastArgs = null;
  };

  return debounced;
};

const log = (v) => console.log("called with", v);
const debounced = debounce(log, 30);

debounced("a");
debounced.cancel();     // nothing will be logged

debounced("b");
debounced.flush();      // "called with b" runs right away

Cancel is the one you will actually need. When a component unmounts, the pending call must not fire, because it usually touches state that no longer exists, and that is a common source of the warning about setting state on an unmounted component. The cancel method gives the cleanup code something clean to call.

Flush is the useful one when you are about to lose the pending work. A form that is being submitted, or a component that is being hidden, may want the last value applied right now rather than thrown away. The guard at the start of the flush method matters, because flushing when nothing is pending would call the function with empty arguments.

Note that keeping the last arguments is what makes flush possible. A debounce that discarded them would have nothing to run.

The case for writing it is that it is small and that you understand exactly what it does. The case against is that the battle-tested versions handle the edge cases you will forget.

Four things a hand written debounce usually gets wrong. The this binding, if the wrapped function is a method. The arguments, if you forget to forward the ones from the final call. The this of the returned function, which should usually be the object the debounced method belongs to. And the cancellation, without which a pending call can fire after the component is gone.

There is also the trailing versus leading question. The version most people write is trailing, meaning the function runs after the calls stop. Some use cases want the opposite, where the function runs on the first call and ignores the rest of the burst. A production library offers both, and the name usually tells you which is which, so it is worth checking before you rely on one.

One more consideration is bundling. If your project already depends on a library that exports a debounce, using it costs nothing and gives you the tested behaviour. Writing your own adds code that somebody has to maintain, and the marginal benefit over a well-made library is small.

The practical advice is to write it once, as an exercise, so that you understand the mechanism, and then use a library in production code. If you do write your own, add the cancel method and the leading and trailing options from the start, because retrofitting them into something that is already used in twenty places is much harder than starting with them.