useDebounceカスタムフックの実装

useDebounce フックは、値とミリ秒単位の遅延時間を受け取り、その値をデバウンスしたものを返します。function useDebounce(value, delay) のように記述します。返される debouncedValue は実際の値より遅れて更新され、別の変更がないまま指定した遅延時間が経過した後にだけ更新されます。

フック内で、状態変数を宣言します。const [debouncedValue, setDebouncedValue] = useState(value) のように記述します。この状態には、最後に確定した値が保持されます。初期値と同じ値で始まり、デバウンスタイマーが発火した後にだけ更新されます。debouncedValue を読み取るコンポーネントは、安定した確定済みの入力値を取得できます。

中心となる処理は useEffect に記述します。setTimeout(() => setDebouncedValue(value), delay) でタイマーを作成し、その ID を保存します。エフェクトは value または delay が変わるたびに実行されます。タイマーは最後の変更から delay ミリ秒後に発火し、デバウンスされた状態を更新します。

useEffect のクリーンアップ関数では、clearTimeout(timerId) を呼び出します。タイマーが発火する前に value が変わると、React はクリーンアップを実行して、保留中の更新をキャンセルします。その後、新しいタイマーが設定されます。これがデバウンスを機能させる重要な仕組みです。値が急速に変化すると、タイマーが繰り返しリセットされます。

useEffect の依存配列には [value, delay] を含める必要があります。入力値が変わるたびにエフェクトが再実行されて新しいタイマーが設定され、delay が変わった場合にも再実行されます。これにより、呼び出し側がデバウンス間隔を動的に調整できます。古いクロージャーの問題を避けるため、両方を含める必要があります。

使い方は簡単です。const debouncedSearch = useDebounce(searchInput, 300) のように記述します。[debouncedSearch] を依存配列とする別の useEffect で、API 呼び出しを実行します。入力の状態（searchInput）はすぐに更新されるため入力の応答性は保たれ、API 呼び出しだけがデバウンスによって遅延します。

標準的な実装では、デフォルトでトレーリングエッジでのみ実行されます。最初のトリガーでは関数を呼び出し、その後の呼び出しにはデバウンスを適用する「即時」モードでは、呼び出し済みかどうかを追跡し、タイムアウト後にリセットするための ref が必要です。これはより複雑ですが、送信ボタンなどに役立ちます。

型安全性を確保するため、フックをジェネリックにします。function useDebounce(value: T, delay: number): T のように記述します。これにより、TypeScript は value の型から debouncedValue の型を推論できます。ジェネリックパラメーター T は、内部状態と戻り値の型に自動的に引き継がれます。

よくある間違いは、useEffect からクリーンアップ関数を返し忘れることです。クリーンアップがないと、値が変わるたびに新しいタイマーが作成されますが、古いタイマーはキャンセルされません。その結果、複数のタイマーが発火し、古い値を使って setDebouncedValue が複数回呼び出されるため、デバウンスがまったく機能しなくなります。

別の方法として、lodash を使ってデバウンス関数自体を useRef に保存することもできます。状態ベースのアプローチとは異なり、ref ベースのアプローチでは値ではなくコールバック（関数）にデバウンスを適用します。派生値が必要な場合は状態ベースのフックを使い、イベントハンドラーにデバウンスを適用する場合はコールバックのアプローチを使います。

タイムアウトのコールバック内に console log を追加し、素早く入力している間のブラウザコンソールを確認して、フックが正しく動作することを検証します。キー入力ごとではなく、「入力を止めた」タイミングごとに 1 件のログが表示されるはずです。素早く入力したときのログ数は、キー入力数より大幅に少なくなるはずです。

useDebounce の useEffect では、なぜ clearTimeout を呼び出すクリーンアップ関数を返す必要があるのですか？

useDebounce(value, delay) フックは、delay ms の間イベントが発生しなかった後にだけ更新される、デバウンスされた状態を保持します。その useEffect はタイムアウトを設定し、クリーンアップ時にそれを消去して古いタイマーをキャンセルします。API を取得するエフェクトでは、デバウンスされた値を依存配列に指定します。完全な型安全性を得るには、TypeScript のジェネリックを追加します。