Implementando o hook personalizado useThrottle

O atraso após a pausa simplesmente reinicia um temporizador a cada evento. A limitação de frequência precisa acompanhar ativamente quando ocorreu a última execução e decidir se já passou tempo suficiente para outra. Isso exige manter um registro de data e hora entre as novas renderizações, tornando a implementação um pouco mais complexa que a do atraso após a pausa.

O registro de data e hora da última execução precisa persistir entre as novas renderizações sem acioná-las, o que faz de useRef a ferramenta adequada. Armazene o registro de data e hora como const lastRunTime = useRef(Date.now()). Diferentemente do estado, atualizar uma referência não causa uma nova renderização; assim, a lógica de limitação de frequência é executada com eficiência, sem ciclos extras.

O gancho useThrottle(value, delay) retorna uma versão do valor de entrada com frequência limitada. Seu contrato é semelhante ao de useDebounce: aceitar qualquer valor e um atraso em ms e retornar o valor com frequência limitada. Os componentes o utilizam da mesma forma, tornando-o uma alternativa substituta direta para diferentes semânticas de temporização.

Uma limitação de frequência de borda final atualiza o valor ao fim de cada intervalo. Quando um novo valor chega, agende um setTimeout para o tempo restante do intervalo: delay - (Date.now() - lastRunTime.current). Quando o temporizador dispara, atualize o estado e registre o novo lastRunTime. Cancele os temporizadores anteriores durante a limpeza.

Uma limitação de frequência de borda inicial aplica o primeiro valor imediatamente e ignora os seguintes até o intervalo expirar. Verifique: se Date.now() - lastRunTime.current >= delay, atualize o estado e registre o horário. Caso contrário, ignore a atualização. Isso fornece uma resposta imediata à primeira ação, seguida de um período de espera.

A melhor experiência do usuário geralmente combina as duas: responda imediatamente ao primeiro evento (borda inicial) e, em seguida, garanta que o estado final também seja aplicado depois do intervalo (borda final). Assim, o usuário vê uma resposta inicial rápida, e o valor final é sempre aplicado depois que o movimento termina, evitando um estado final desatualizado.

Armazene o ID do tempo limite pendente em um useRef: const timeoutRef = useRef(null). Antes de agendar um novo tempo limite, chame clearTimeout(timeoutRef.current) para cancelar qualquer tempo limite existente. Isso evita vários temporizadores sobrepostos, que causariam várias atualizações dentro de um único intervalo de limitação de frequência.

A limpeza do useEffect deve chamar clearTimeout(timeoutRef.current) para cancelar qualquer atualização final pendente quando o componente for desmontado. Sem isso, um tempo limite pendente é acionado depois da desmontagem, tentando definir o estado em um componente desmontado e podendo causar avisos do React.

Em vez de um gancho baseado em valor, você pode criar um gancho de limitação de frequência baseado em useCallback: useThrottledCallback(fn, delay) retorna uma versão limitada de uma função. Essa opção é mais flexível quando a operação que você deseja limitar é uma chamada de função, como um rastreador de análises, e não um valor reativo.

Nos testes do Jest, use jest.useFakeTimers() para controlar o tempo. Configure uma limitação de frequência com atraso de 1000 ms, dispare 10 mudanças rápidas de valor, avance o tempo falso em 500 ms e verifique se ocorreram apenas 1 ou 2 atualizações. Avance mais 500 ms e verifique se a atualização final é acionada. Isso valida o comportamento da limitação de frequência de forma determinística.

O React processa atualizações de estado em lotes durante as renderizações. Uma limitação de frequência que opera sobre atualizações de estado funciona de forma adequada dentro desse modelo. No entanto, observe que, no Modo concorrente do React 18, as renderizações podem ser interrompidas. A própria lógica de limitação de frequência, baseada no tempo real do relógio por meio de Date.now(), não é afetada pelo agendamento do React.

Em qual borda uma limitação de frequência de borda final é acionada?

A limitação de frequência exige acompanhar o horário da última execução com useRef. O gancho pode implementar a borda inicial (imediata), a borda final (adiada) ou ambas. Sempre armazene o ID do tempo limite em uma referência e cancele-o durante a limpeza. Para casos de uso baseados em funções, prefira um padrão de useThrottledCallback. Use testes com temporizadores falsos para garantir a confiabilidade.