Debounce & Throttle

// ❌ No optimization — API call on EVERY keystroke

const searchInput = document.getElementById("search");

searchInput.addEventListener("input", (e) => {
  // This fires on EVERY character typed
  fetch(`/api/search?q=${e.target.value}`)
    .then(res => res.json())
    .then(results => renderResults(results));
});

// User types "react hooks":
// r        → fetch("/api/search?q=r")
// re       → fetch("/api/search?q=re")
// rea      → fetch("/api/search?q=rea")
// reac     → fetch("/api/search?q=reac")
// react    → fetch("/api/search?q=react")
// react    → fetch("/api/search?q=react ")
// react h  → fetch("/api/search?q=react h")
// react ho → fetch("/api/search?q=react ho")
// react hoo→ fetch("/api/search?q=react hoo")
// react hook→fetch("/api/search?q=react hook")
// react hooks→fetch("/api/search?q=react hooks")
//
// 11 API calls! 10 of them are useless.
// The server is overloaded. Results flicker as responses
// arrive out of order. The user only wanted ONE search.

User scrolls for 2 seconds:

Without throttle:
  ║ scroll ║ scroll ║ scroll ║ scroll ║ scroll ║ ...
  0ms      16ms     32ms     48ms     64ms     80ms
  
  → 120 handler executions in 2 seconds
  → If each handler reads DOM layout: 120 forced reflows
  → Result: janky, stuttering scroll

With throttle (200ms):
  ║ scroll ║                   ║ scroll ║                   ║ ...
  0ms                          200ms                        400ms
  
  → 10 handler executions in 2 seconds
  → Smooth scrolling, responsive UI

User types "react" with 300ms debounce delay:

Events:    r       e       a       c       t
Time:      0ms     150ms   280ms   400ms   520ms
Timer:     start   reset   reset   reset   reset
                                            │
                                            └─ 300ms of silence...
                                                    │
Execute:                                            820ms ← fires ONCE

What happens at each keystroke:
  "r"  → start 300ms timer
  "e"  → cancel old timer, start new 300ms timer
  "a"  → cancel old timer, start new 300ms timer
  "c"  → cancel old timer, start new 300ms timer
  "t"  → cancel old timer, start new 300ms timer
  ...300ms pass with no more keystrokes...
  → Timer fires! Execute function with value "react"

Result: 1 execution instead of 5. The function waits for the
user to finish, then runs with the final value.

Scroll events with 200ms throttle:

Events:    ↓  ↓  ↓  ↓  ↓  ↓  ↓  ↓  ↓  ↓  ↓  ↓  ↓  ↓  ↓
Time:      0  16 32 48 64 80 ... 200    ... 400    ... 600ms

Execute:   ✓                         ✓           ✓           ✓
           0ms                       200ms       400ms       600ms

What happens:
  0ms   → Execute immediately (first call always runs)
  16ms  → Ignored (within 200ms window)
  32ms  → Ignored
  ...
  200ms → 200ms passed since last execution → Execute
  216ms → Ignored
  ...
  400ms → Execute
  ...

Result: ~3 executions per second instead of ~60.
The function runs at a steady, predictable rate.
The user gets continuous feedback, not delayed feedback.

Events firing rapidly over 1 second (every ~50ms):

Input:     ╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎  (20 events)
           0ms                    1000ms

Debounce (300ms delay):
Execute:                              ╎
                                      1300ms
           → 1 execution (after events stop + 300ms)

Throttle (300ms interval):
Execute:   ╎         ╎         ╎      ╎
           0ms       300ms     600ms   900ms
           → 4 executions (one every 300ms)

No optimization:
Execute:   ╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎╎
           → 20 executions (every single event)

Do you need the FINAL value after the user stops?
    │
    ├─ YES → DEBOUNCE
    │   Examples:
    │   • Search input (want the complete query)
    │   • Form validation (want the final field value)
    │   • Auto-save (want the final document state)
    │   • Resize handler (want the final window size)
    │
    └─ NO, you need CONTINUOUS updates during the action?
        │
        └─ YES → THROTTLE
            Examples:
            • Scroll tracking (need position updates while scrolling)
            • Drag handler (need position updates while dragging)
            • Mouse move (need cursor position continuously)
            • Progress indicator (need updates during long operation)

function debounce(fn, delay) {
  let timeoutId;

  return function (...args) {
    // Cancel the previous timer (if any)
    clearTimeout(timeoutId);

    // Start a new timer
    timeoutId = setTimeout(() => {
      fn.apply(this, args);
    }, delay);
  };
}

// How it works:
// 1. Each call clears the previous setTimeout
// 2. A new setTimeout is set for 'delay' ms
// 3. If no new call comes within 'delay', the function executes
// 4. If a new call comes, step 1 cancels the pending timer

// Usage:
const debouncedSearch = debounce((query) => {
  fetch(`/api/search?q=${query}`);
}, 300);

input.addEventListener("input", (e) => {
  debouncedSearch(e.target.value);
});

function throttle(fn, interval) {
  let lastTime = 0;

  return function (...args) {
    const now = Date.now();

    // Only execute if enough time has passed
    if (now - lastTime >= interval) {
      lastTime = now;
      fn.apply(this, args);
    }
  };
}

// How it works:
// 1. Track the timestamp of the last execution
// 2. On each call, check if 'interval' ms have passed
// 3. If yes → execute and update lastTime
// 4. If no → ignore the call (do nothing)

// Usage:
const throttledScroll = throttle(() => {
  const scrollPercent = window.scrollY / document.body.scrollHeight;
  updateProgressBar(scrollPercent);
}, 200);

window.addEventListener("scroll", throttledScroll);

// Enhanced throttle that also fires on the trailing edge
// Ensures the last event is always captured

function throttle(fn, interval) {
  let lastTime = 0;
  let timeoutId = null;

  return function (...args) {
    const now = Date.now();
    const remaining = interval - (now - lastTime);

    if (remaining <= 0) {
      // Enough time passed → execute immediately
      clearTimeout(timeoutId);
      timeoutId = null;
      lastTime = now;
      fn.apply(this, args);
    } else if (!timeoutId) {
      // Schedule a trailing call for when the interval ends
      timeoutId = setTimeout(() => {
        lastTime = Date.now();
        timeoutId = null;
        fn.apply(this, args);
      }, remaining);
    }
  };
}

// Why trailing matters:
// Without trailing: if the last event falls within the throttle window,
// it's silently dropped. The final scroll position is never captured.
// With trailing: the last event always fires after the interval,
// ensuring the final state is processed.

import { useState, useCallback, useEffect, useRef } from "react";

// Approach 1: Custom useDebouncedCallback hook
function useDebouncedCallback(fn, delay) {
  const timeoutRef = useRef(null);

  // Cleanup on unmount
  useEffect(() => {
    return () => clearTimeout(timeoutRef.current);
  }, []);

  return useCallback((...args) => {
    clearTimeout(timeoutRef.current);
    timeoutRef.current = setTimeout(() => {
      fn(...args);
    }, delay);
  }, [fn, delay]);
}

// Usage in a search component
function SearchBar() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState([]);

  const searchAPI = useCallback(async (searchQuery) => {
    const res = await fetch(`/api/search?q=${searchQuery}`);
    const data = await res.json();
    setResults(data);
  }, []);

  const debouncedSearch = useDebouncedCallback(searchAPI, 300);

  const handleChange = (e) => {
    const value = e.target.value;
    setQuery(value);              // Update input immediately (responsive)
    debouncedSearch(value);       // Debounce the API call (efficient)
  };

  return (
    <div>
      <input value={query} onChange={handleChange} placeholder="Search..." />
      <ResultsList results={results} />
    </div>
  );
}

// Key insight: the INPUT updates on every keystroke (responsive UX),
// but the API call only fires after 300ms of silence (efficient).

import { useState, useEffect, useRef, useCallback } from "react";

// Custom useThrottledCallback hook
function useThrottledCallback(fn, interval) {
  const lastTimeRef = useRef(0);
  const timeoutRef = useRef(null);

  useEffect(() => {
    return () => clearTimeout(timeoutRef.current);
  }, []);

  return useCallback((...args) => {
    const now = Date.now();
    const remaining = interval - (now - lastTimeRef.current);

    if (remaining <= 0) {
      clearTimeout(timeoutRef.current);
      lastTimeRef.current = now;
      fn(...args);
    } else if (!timeoutRef.current) {
      timeoutRef.current = setTimeout(() => {
        lastTimeRef.current = Date.now();
        timeoutRef.current = null;
        fn(...args);
      }, remaining);
    }
  }, [fn, interval]);
}

// Usage: scroll progress indicator
function ScrollProgress() {
  const [progress, setProgress] = useState(0);

  const updateProgress = useCallback(() => {
    const scrolled = window.scrollY;
    const total = document.body.scrollHeight - window.innerHeight;
    setProgress(total > 0 ? (scrolled / total) * 100 : 0);
  }, []);

  const throttledUpdate = useThrottledCallback(updateProgress, 100);

  useEffect(() => {
    window.addEventListener("scroll", throttledUpdate);
    return () => window.removeEventListener("scroll", throttledUpdate);
  }, [throttledUpdate]);

  return (
    <div className="progress-bar" style={{ width: `${progress}%` }} />
  );
}

// Option 1: lodash (most common in production)
import { debounce, throttle } from "lodash";
import { useMemo, useEffect } from "react";

function SearchBar() {
  const [query, setQuery] = useState("");

  // useMemo ensures the debounced function is created once
  const debouncedFetch = useMemo(
    () => debounce((q) => fetch(`/api/search?q=${q}`), 300),
    []
  );

  // Cleanup on unmount
  useEffect(() => {
    return () => debouncedFetch.cancel();
  }, [debouncedFetch]);

  return (
    <input
      value={query}
      onChange={(e) => {
        setQuery(e.target.value);
        debouncedFetch(e.target.value);
      }}
    />
  );
}

// Option 2: use-debounce library (React-specific)
import { useDebouncedCallback } from "use-debounce";

function SearchBar() {
  const [query, setQuery] = useState("");

  const debouncedFetch = useDebouncedCallback((q) => {
    fetch(`/api/search?q=${q}`);
  }, 300);

  return (
    <input
      value={query}
      onChange={(e) => {
        setQuery(e.target.value);
        debouncedFetch(e.target.value);
      }}
    />
  );
}

function SearchPage() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState([]);
  const [loading, setLoading] = useState(false);

  const handleChange = async (e) => {
    const value = e.target.value;
    setQuery(value);

    // ❌ API call on EVERY keystroke
    setLoading(true);
    const res = await fetch(`/api/search?q=${value}`);
    const data = await res.json();
    setResults(data);
    setLoading(false);
  };

  return (
    <div>
      <input value={query} onChange={handleChange} />
      {loading && <Spinner />}
      <ResultsList results={results} />
    </div>
  );
}

// User types "javascript promises" (22 characters):
//
// Network tab:
// GET /api/search?q=j           → 200 OK (45ms)
// GET /api/search?q=ja          → 200 OK (52ms)
// GET /api/search?q=jav         → 200 OK (38ms)
// GET /api/search?q=java        → 200 OK (41ms)
// ... 18 more requests ...
// GET /api/search?q=javascript promises → 200 OK (67ms)
//
// Problems:
// 1. 22 API calls (21 are wasted)
// 2. Results flicker as responses arrive out of order
// 3. Server load: 22x more than necessary
// 4. Race condition: "java" response may arrive AFTER "javascript"
//    showing wrong results

function SearchPage() {
  const [query, setQuery] = useState("");
  const [results, setResults] = useState([]);
  const [loading, setLoading] = useState(false);

  // AbortController to cancel stale requests
  const abortRef = useRef(null);

  const searchAPI = useCallback(async (searchQuery) => {
    // Cancel previous in-flight request
    abortRef.current?.abort();
    abortRef.current = new AbortController();

    try {
      setLoading(true);
      const res = await fetch(`/api/search?q=${searchQuery}`, {
        signal: abortRef.current.signal,
      });
      const data = await res.json();
      setResults(data);
    } catch (err) {
      if (err.name !== "AbortError") throw err;
    } finally {
      setLoading(false);
    }
  }, []);

  // ✅ Debounced API call — fires 300ms after last keystroke
  const debouncedSearch = useDebouncedCallback(searchAPI, 300);

  const handleChange = (e) => {
    const value = e.target.value;
    setQuery(value);           // Input updates immediately
    debouncedSearch(value);    // API call is debounced
  };

  return (
    <div>
      <input value={query} onChange={handleChange} />
      {loading && <Spinner />}
      <ResultsList results={results} />
    </div>
  );
}

// User types "javascript promises" (22 characters):
//
// Network tab:
// GET /api/search?q=javascript promises → 200 OK (67ms)
//
// That's it. ONE request. The user typed at normal speed,
// paused for 300ms, and the debounce fired with the complete query.
//
// Improvements:
// 1. 1 API call instead of 22 (95% reduction)
// 2. No flickering results
// 3. No race conditions (AbortController cancels stale requests)
// 4. Server load reduced by 95%