Debounce vs throttle.
Group or space. Not both.

The mental model:

Debounce = "wait until quiet, then act"
  → Like an elevator: door waits until no one
    has entered for 3 seconds, then closes.
  → Every event resets the timer.

Throttle = "act at most once per period"
  → Like a metronome: ticks every 100ms regardless
    of what you do in between.
  → Events don't reset the timer.

Which to use:

Debounce — the function should run ONCE,
           after the events stop:
  ✅ Search as you type
  ✅ Autosave after edits
  ✅ Form validation after input
  ✅ Resize layout calculation after resize
  ✅ API calls triggered by user input

Throttle — the function should run periodically
           DURING the events:
  ✅ Scroll handlers
  ✅ Mousemove tracking
  ✅ Infinite scroll checks
  ✅ Drag position updates
  ✅ Progress bar updates

The key question:
  "Do I want the FINAL value, or REGULAR updates?"
  Final value → debounce
  Regular updates → throttle

The wrong choice:
  Debounce on scroll — the handler only runs
    after the user stops scrolling. Janky.
  Throttle on search — the API is called every
    300ms during typing. Wasteful.

Match the pattern to the use case.

How the implementation works:

1. timerId is captured in the closure.
   It survives between calls to the returned function.

2. Each call clears the previous timer.
   The pending call is cancelled.

3. Each call sets a new timer.
   If the user doesn't call again within `delay`,
   the timer fires and calls fn.

4. ...args and this preserve the arguments
   and context of the most recent call.
   Without this, the handler would receive
   the wrong event or lose `this`.

What it doesn't handle:

❌ Leading edge — calling on the first event
   instead of the last.
❌ Cancel — a way to cancel a pending call.
❌ Flush — a way to run immediately.
❌ Immediate call — an option to call fn on
   the first event, not the last.

For these, use lodash.debounce:

  import debounce from 'lodash/debounce';

  const search = debounce(fn, 300, {
    leading: false,
    trailing: true,
    maxWait: 1000
  });

  search.cancel();   // cancel pending
  search.flush();    // run immediately

The simple implementation is enough for
90% of cases. The library handles the rest.

How the implementation works:

1. lastCall is captured in the closure.
   It tracks when fn was last called.

2. Each call checks the current time.

3. If enough time has passed since lastCall,
   the function runs and lastCall is updated.

4. If not enough time has passed, the call is
   ignored entirely.

What it does NOT do:

❌ Trailing call — if the last event in a burst
   happened after the last call, the handler
   doesn't run for that final event.
❌ Configurable leading/trailing — the simple
   version is leading-only (fires on the first
   event of each interval, then ignores the rest).
❌ Cancel / flush.

For these, use lodash.throttle:

  import throttle from 'lodash/throttle';

  const onScroll = throttle(fn, 100, {
    leading: true,
    trailing: true
  });

  onScroll.cancel();
  onScroll.flush();

The simple version is enough for most cases.
The library handles the edge cases.

⚠️ requestAnimationFrame is often better than throttle
   for visual updates:

   let ticking = false;
   window.addEventListener('scroll', () => {
     if (!ticking) {
       requestAnimationFrame(() => {
         updateUI();
         ticking = false;
       });
       ticking = true;
     }
   });

   This ties updates to the browser's frame rate,
   not a timer. Smoother for scroll animations.

   Use throttle for logic that isn't frame-synced
   (API calls, analytics, localStorage writes).
   Use rAF for visual updates.