Implementando o hook personalizado useDebounce

O gancho useDebounce aceita um valor e um atraso em milissegundos e retorna uma versão desse valor com atraso após a pausa: function useDebounce(value, delay). O debouncedValue retornado fica atrasado em relação ao valor real e só é atualizado depois que o atraso especificado tiver transcorrido sem outra alteração.

Dentro do gancho, declare uma variável de estado: const [debouncedValue, setDebouncedValue] = useState(value). Esse estado armazena o último valor confirmado. Ele começa igual ao valor inicial e só é atualizado depois que o temporizador do atraso é disparado. Os componentes que leem debouncedValue veem uma entrada estável e consolidada.

A lógica principal fica em um useEffect: crie um temporizador com setTimeout(() => setDebouncedValue(value), delay) e armazene o ID. O efeito é executado sempre que value ou delay mudar. O temporizador é disparado delay milissegundos depois da última alteração, atualizando o estado com atraso.

A função de limpeza de useEffect chama clearTimeout(timerId). Quando value muda antes de o temporizador ser disparado, o React executa a limpeza e cancela a atualização pendente. Em seguida, um novo temporizador é agendado. Esse é o mecanismo essencial que faz o atraso após a pausa funcionar: alterações rápidas continuam reiniciando o temporizador.

A matriz de dependências de useEffect deve conter [value, delay]. O efeito é executado novamente sempre que o valor de entrada muda, para que um novo temporizador seja agendado, e sempre que o atraso muda, caso o chamador ajuste dinamicamente o intervalo do atraso após a pausa. Ambos devem ser incluídos para evitar problemas com fechamentos obsoletos.

O uso é simples: const debouncedSearch = useDebounce(searchInput, 300). Um useEffect separado, com [debouncedSearch] como dependência, dispara a chamada à API. O estado de entrada (searchInput) é atualizado imediatamente, mantendo a entrada responsiva; somente a chamada à API aguarda o atraso após a pausa.

Por padrão, a implementação padrão só é executada na borda final. Para um modo "imediato", que chama a função no primeiro acionamento, mas aplica o atraso às chamadas seguintes, você precisa de uma referência para acompanhar se a chamada já foi feita e redefini-la depois do temporizador. Isso é mais complexo, mas útil para botões de envio.

Deixe o gancho genérico para obter segurança de tipos: function useDebounce(value: T, delay: number): T. Isso permite que o TypeScript infira o tipo de debouncedValue a partir do tipo de value. O parâmetro genérico T é propagado automaticamente pelo estado interno e pelo tipo retornado.

Um erro frequente é esquecer de retornar a função de limpeza de useEffect. Sem a limpeza, cada alteração de valor cria um novo temporizador, mas nunca cancela o anterior. O resultado é que vários temporizadores são disparados, fazendo com que setDebouncedValue seja chamado várias vezes com valores obsoletos, anulando completamente o atraso após a pausa.

Uma alternativa é armazenar a própria função de atraso em um useRef usando o lodash. Diferentemente da abordagem baseada em estado, a abordagem baseada em referência aplica o atraso a funções de retorno, e não a valores. Use o gancho baseado em estado quando precisar de um valor derivado; use a abordagem baseada em função de retorno quando precisar aplicar o atraso a um manipulador de eventos.

Verifique se o gancho funciona adicionando um registro no console dentro da função de retorno do temporizador e observando o console do navegador enquanto digita rapidamente. Você deve ver um registro por evento de parada, não um por tecla pressionada. A quantidade de registros deve ser muito menor que a quantidade de teclas pressionadas durante uma digitação rápida.

Por que o useEffect em useDebounce precisa retornar uma função de limpeza que chama clearTimeout?

O gancho useDebounce(value, delay) mantém um estado com atraso após a pausa, atualizado somente depois de delay ms de silêncio. Seu useEffect define um tempo limite e o limpa durante a limpeza para cancelar temporizadores obsoletos. Use o valor com atraso como dependência dos efeitos que buscam dados na API. Adicione um tipo genérico do TypeScript para obter segurança de tipos completa.