Thanks for the detailed feedback, @tomstuart; this is all gold!

The stashing of the timeout ID in a ref and not using the cleanup functionality useEffect were both things that bothered me and it's now clear from your comments the root issue was trying to do the imperative work when the user clicks rather than deferring the work until next render. This is something I felt uneasy about (I was torn about whether the click handler should follow the React programming model or whether the user can expect the setTimeout to fire immediately when they click) but the fact my original solution requires both the extra ref and the manual timeout cleanup is clearly a smell.

Responding to changes in delay is something I conveniently skipped from Dan Abramov's original example with setInterval but I think your changes make sense. I was initially reticent about using real Dates but it seems that JavaScript should do the right thing with edge cases like Daylight Saving Time (but I'm not certain about leap seconds), e.g.

> (new Date('2019-03-31 02:00:01')) - (new Date('2019-03-31 00:59:59'))
2000

My only concern would be that the delay could result in a negative delay passed to setTimeout but we could easily clamp this with Math.max, e.g.

import React, { useState, useEffect, useRef } from 'react';

const useDebounce = (callback, delay) => {
  const latestCallback = useRef();
  const [lastCalledAt, setLastCalledAt] = useState(null);

  useEffect(() => {
    latestCallback.current = callback;
  }, [callback]);

  useEffect(() => {
    if (lastCalledAt) {
      const fire = () => {
        setLastCalledAt(null);
        latestCallback.current();
      };
      const fireAt = lastCalledAt + delay;
      const fireIn = Math.max(fireAt - Date.now(), 0);
      const id = setTimeout(fire, fireIn);

      return () => clearTimeout(id);
    }
  }, [lastCalledAt, delay]);

  return () => setLastCalledAt(Date.now());
};

const App = () => {
  const [count, setCount] = useState(0);
  const [delay, setDelay] = useState(3000);

  const handleIncrement = () => setCount(count => count + 1);
  const handleClick = useDebounce(() => alert(`I've been clicked ${count} times`), delay);
  const handleChange = ({ target: { value } }) => setDelay(parseInt(value));

  return (
    <>
      <button onClick={handleClick}>Click</button>
      <button onClick={handleIncrement}>Increment {count}</button>
      <input type="range" min="0" max="10000" value={delay} onChange={handleChange} />
      Debouncing for {delay}ms
    </>
  );
};

export default App;

Thanks for the detailed feedback, @tomstuart; this is all gold!

You’re very welcome! It was a lot of fun to think about.

I was initially reticent about using real Dates but it seems that JavaScript should do the right thing with edge cases like Daylight Saving Time (but I'm not certain about leap seconds)

Fear not: Date.now() returns a number rather than a Date instance, and the spec explicitly says “leap seconds are ignored”, so stuff like daylight savings and leap seconds [0] shouldn’t be a problem (although I guess that depends on what exactly “ignored” means). Of course we’re exposed to all the usual issues that can occur if the system clock is set backwards or forwards in the middle of our code, but I think that’s the price we pay for involving global time.

My only concern would be that the delay could result in a negative delay passed to setTimeout but we could easily clamp this with Math.max

Fear not: setTimeout()’s delay argument is already clamped to zero (see timer initialisation step 10) so we don’t need to do this ourselves.

[0] Having thought about this, I suspect “leap seconds are ignored” probably means that it is a problem. If that were important then I guess we could use performance.now() as our clock and fall back to Date.now() only when it’s unsupported, or of course switch back to the callCount Lamport clock and avoid global time altogether. Pragmatically it seems likely that leap seconds aren’t significant enough to worry about.

Phew, thanks for putting my mind at ease on both points.

How do I stop the propagation when the handler is an onSubmit function on form?