Implementowanie własnego hooka useDebounce

Hook useDebounce przyjmuje wartość oraz opóźnienie w milisekundach i zwraca opóźnioną wersję tej wartości: function useDebounce(value, delay). Zwracana wartość debouncedValue jest opóźniona względem rzeczywistej wartości i aktualizuje się dopiero po upływie określonego czasu bez kolejnej zmiany.

Wewnątrz hooka należy zadeklarować zmienną stanu: const [debouncedValue, setDebouncedValue] = useState(value). Stan ten przechowuje ostatnią zatwierdzoną wartość. Początkowo jest równy wartości początkowej i aktualizuje się dopiero po uruchomieniu timera debounce. Komponenty odczytujące debouncedValue otrzymują stabilną, ustaloną wartość wejściową.

Główna logika znajduje się w useEffect: należy utworzyć timer za pomocą setTimeout(() => setDebouncedValue(value), delay) i zapisać jego identyfikator. Efekt uruchamia się za każdym razem, gdy zmieni się value lub delay. Timer zostaje uruchomiony delay milisekund po ostatniej zmianie i aktualizuje stan objęty debounce.

Funkcja cleanup hooka useEffect wywołuje clearTimeout(timerId). Gdy value zmieni się przed uruchomieniem timera, React wykonuje cleanup i anuluje oczekującą aktualizację. Następnie planowany jest nowy timer. To kluczowy mechanizm działania debounce: szybkie zmiany stale resetują timer.

Tablica zależności useEffect powinna zawierać [value, delay]. Efekt uruchamia się ponownie za każdym razem, gdy zmieni się wartość wejściowa (dzięki czemu planowany jest nowy timer) oraz gdy zmieni się delay (na wypadek dynamicznego dostosowania interwału debounce przez wywołujący kod). Obie wartości muszą zostać uwzględnione, aby uniknąć problemów z nieaktualnym domknięciem.

Użycie jest proste: const debouncedSearch = useDebounce(searchInput, 300). Osobny useEffect z [debouncedSearch] jako zależnością wykonuje wywołanie API. Stan wejściowy (searchInput) aktualizuje się natychmiast, dzięki czemu pole pozostaje responsywne; tylko wywołanie API czeka na debounce.

Domyślnie standardowa implementacja działa tylko na trailing edge. W trybie „immediate”, który wywołuje funkcję przy pierwszym zdarzeniu, a kolejne wywołania obejmuje debounce, potrzebny jest ref śledzący, czy wywołanie już nastąpiło, oraz resetujący tę informację po upływie czasu oczekiwania. Jest to bardziej złożone rozwiązanie, ale przydatne w przypadku przycisków wysyłania.

W celu zapewnienia bezpieczeństwa typów hook należy zdefiniować jako generyczny: function useDebounce(value: T, delay: number): T. Dzięki temu TypeScript może wywnioskować typ debouncedValue na podstawie typu value. Parametr generyczny T automatycznie propaguje się przez stan wewnętrzny i typ zwracany.

Częstym błędem jest zapomnienie o zwróceniu funkcji cleanup z useEffect. Bez cleanup każda zmiana wartości tworzy nowy timer, ale nigdy nie anuluje poprzedniego. W rezultacie uruchamia się wiele timerów, które wielokrotnie wywołują setDebouncedValue z nieaktualnymi wartościami, całkowicie niwecząc działanie debounce.

Alternatywą jest przechowywanie samej funkcji debounce w useRef z użyciem lodash. W przeciwieństwie do podejścia opartego na stanie podejście z refem obejmuje debounce callbacków (funkcji), a nie wartości. Podejście oparte na stanie należy wybrać, gdy potrzebna jest wartość pochodna, a podejście z callbackiem — gdy debounce ma dotyczyć handlera zdarzenia.

Działanie hooka można zweryfikować, dodając logowanie konsolowe wewnątrz callbacku timera i obserwując konsolę przeglądarki podczas szybkiego pisania. Powinno pojawić się jedno logowanie na każde zdarzenie „stop”, a nie jedno na każde naciśnięcie klawisza. Podczas szybkiego pisania liczba logów powinna być znacznie mniejsza niż liczba naciśnięć klawiszy.

Dlaczego useEffect w useDebounce musi zwracać funkcję cleanup, która wywołuje clearTimeout?

Hook useDebounce(value, delay) przechowuje stan objęty debounce, który aktualizuje się dopiero po delay ms ciszy. Jego useEffect ustawia timer i usuwa go podczas cleanup, aby anulować nieaktualne timery. Wartość objętą debounce należy wykorzystać jako zależność efektów pobierających dane z API. Dodanie generycznego typu TypeScript zapewnia pełne bezpieczeństwo typów.