useDebounce - Atrasar atualizações de valor ou execução de callback até que a entrada se estabilize

import { useState, useEffect, useRef, useCallback, useMemo } from "react";
 
/**
 * useDebouncedValue
 * Retorna uma cópia com debounce do `value` que só atualiza
 * após `delay` ms de inatividade.
 */
function useDebouncedValue<T>(value: T, delay: number): T {
  const [debounced, setDebounced] = useState(value);
 
  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);
 
  return debounced;
}
 
/**
 * useDebouncedCallback
 * Retorna uma versão estável e com debounce do `callback`.
 * Suporta invocação na borda inicial (leading edge) via `options.leading`.
 */
function useDebouncedCallback<T extends (...args: any[]) => void>(
  callback: T,
  delay: number,
  options: { leading?: boolean } = {}
): T & { cancel: () => void; flush: () => void } {
  const { leading = false } = options;
  const callbackRef = useRef(callback);
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const lastArgsRef = useRef<Parameters<T> | null>(null);
  const leadingFiredRef = useRef(false);
 
  // Sempre mantém o callback mais recente
  useEffect(() => {
    callbackRef.current = callback;
  }, [callback]);
 
  // Limpeza ao desmontar
  useEffect(() => {
    return () => {
      if (timerRef.current) clearTimeout(timerRef.current);
    };
  }, []);
 
  const cancel = useCallback(() => {
    if (timerRef.current) clearTimeout(timerRef.current);
    timerRef.current = null;
    lastArgsRef.current = null;
    leadingFiredRef.current = false;
  }, []);
 
  const flush = useCallback(() => {
    if (lastArgsRef.current) {
      callbackRef.current(...lastArgsRef.current);
    }
    cancel();
  }, [cancel]);
 
  const debounced = useCallback(
    (...args: Parameters<T>) => {
      lastArgsRef.current = args;
 
      if (leading && !leadingFiredRef.current) {
        leadingFiredRef.current = true;
        callbackRef.current(...args);
      }
 
      if (timerRef.current) clearTimeout(timerRef.current);
 
      timerRef.current = setTimeout(() => {
        if (!leading) {
          callbackRef.current(...args);
        }
        leadingFiredRef.current = false;
        timerRef.current = null;
        lastArgsRef.current = null;
      }, delay);
    },
    [delay, leading]
  ) as T & { cancel: () => void; flush: () => void };
 
  debounced.cancel = cancel;
  debounced.flush = flush;
 
  return debounced;
}

"use client";
 
import { useState } from "react";
 
function SearchInput() {
  const [query, setQuery] = useState("");
  const debouncedQuery = useDebouncedValue(query, 300);
 
  // Só dispara a requisição de rede quando debouncedQuery muda
  useEffect(() => {
    if (!debouncedQuery) return;
    fetch(`/api/search?q=${encodeURIComponent(debouncedQuery)}`)
      .then((res) => res.json())
      .then((data) => console.log(data));
  }, [debouncedQuery]);
 
  return (
    <input
      value={query}
      onChange={(e) => setQuery(e.target.value)}
      placeholder="Pesquisar..."
    />
  );
}
 
function SaveButton() {
  const debouncedSave = useDebouncedCallback(
    (content: string) => {
      fetch("/api/save", {
        method: "POST",
        body: JSON.stringify({ content }),
      });
    },
    1000,
    { leading: true }
  );
 
  return (
    <button onClick={() => debouncedSave("conteúdo rascunhado")}>
      Salvar (com debounce)
    </button>
  );
}

// Dispara nas bordas inicial e final (leading e trailing)
function useDebouncedCallback(callback, delay, { leading: true, trailing: true })

// Exemplo de produção: Padrão de debounce integrado com SWR
// Arquivo: src/hooks/use-search.ts
import { useState, useEffect, useMemo } from 'react';
import useSWR from 'swr';
 
const fetcher = (url: string) => fetch(url).then((r) => r.json());
 
export function useSearch(query: string, platform: string) {
  const [debouncedQuery, setDebouncedQuery] = useState(query);
 
  // Debounce: atualiza a consulta apenas após 300ms de inatividade
  useEffect(() => {
    const timer = setTimeout(() => setDebouncedQuery(query), 300);
    return () => clearTimeout(timer);
  }, [query]);
 
  const shouldFetch = debouncedQuery.length >= 3;
  const apiUrl = shouldFetch
    ? `/api/search?q=${encodeURIComponent(debouncedQuery)}&platform=${platform}`
    : null;
 
  const { data, isLoading, isValidating } = useSWR(apiUrl, fetcher, {
    keepPreviousData: true,
  });
 
  return useMemo(() => ({
    results: data?.results ?? [],
    isLoading: isLoading || (shouldFetch && isValidating),
  }), [data, isLoading, shouldFetch, isValidating]);
}