tanstack-pacer

TanStack Pacer

概要

TanStack Pacer は、デバウンス、スロットリング、レート制限、キューイング、バッチ処理によって関数の実行タイミングを制御する、軽量で型安全なライブラリです。フレームワークに依存しないコアクラスと、複数の抽象化レベル（インスタンス、コールバック、状態、値）に対応した専用の React フックを提供します。

使用する場面： 検索入力のデバウンス、スクロールやリサイズのハンドラーのスロットリング、API のレート制限、並行制御を伴う非同期タスクのキューイング、複数の操作を単一のリクエストにまとめるバッチ処理。

使用しない場面： 単純な一時的遅延（setTimeout を使用）、インフラストラクチャレベルでのサーバー側レート制限（ミドルウェア／API ゲートウェイを使用）、複雑なジョブスケジューリング（BullMQ などのタスクキューを使用）。

クイックリファレンス

パターン	API	主なポイント
関数のデバウンス	Debouncer / debounce(fn, opts)	非アクティブな状態が続くのを待ちます。設計上、maxWait オプションはありません
関数のスロットリング	Throttler / throttle(fn, opts)	均等な間隔で実行します。leading と trailing はどちらもデフォルトで true です
レート制限	RateLimiter / rateLimit(fn, opts)	固定またはスライディングウィンドウに対応し、上限を超えた呼び出しを拒否します
アイテムのキューイング	Queuer / queue(fn, opts)	デフォルトは FIFO で、LIFO、優先度、有効期限にも対応します
非同期キュー	AsyncQueuer / asyncQueue(fn, opts)	並行制御、再試行、エラーコールバックに対応します
非同期バッチ	AsyncBatcher / asyncBatch(fn, opts)	アイテムを収集し、待機時間または最大サイズに達した後、バッチとして処理します
React のデバウンス	useDebouncer / useDebouncedCallback	インスタンスフックとシンプルなコールバックフック
React のスロットリング	useThrottler / useThrottledCallback	インスタンスフックとシンプルなコールバックフック
React のレート制限	useRateLimiter / useRateLimitedCallback	インスタンスフックとシンプルなコールバックフック
React のキュー	useQueuer / useQueuedState	インスタンスフックと状態統合フック
React の非同期キュー	useAsyncQueuer / useAsyncQueuedState	並行制御と状態管理
React のバッチ処理	useBatcher / useAsyncBatcher	同期・非同期のバッチ処理フック
状態フック	useDebouncedState、useThrottledState	React の状態と直接統合します
値フック	useDebouncedValue、useThrottledValue	デバウンス／スロットリングされた派生値を作成します

よくある間違い

間違い	正しいパターン
Debouncer で maxWait を使用する	Debouncer に maxWait はありません。一定間隔で実行するには Throttler を使用します
レンダリング中にインスタンスを作成する	フック（useDebouncer、useThrottler）を使用して作成し、ライフサイクルを管理します
maybeExecute の戻り値を無視する	レートリミッターとスロットラーは呼び出しを拒否する場合があります。状態を確認するか、コールバックを使用してください
スロットルが必要な場面でデバウンスを使用する	デバウンスは一時停止を待ちます。スロットルは各間隔で最大 1 回の実行を保証します
アンマウント時にクリーンアップしない	React フックはクリーンアップを自動的に処理します。手動で作成したインスタンスでは cancel() が必要です
アイテムを破棄してもよい場面で Queuer を使用する	Queuer はすべてのアイテムを処理します。破棄してもよい場合は、スロットルまたはデバウンスを使用してください
スライディングウィンドウが必要な場面で固定ウィンドウを使用する	固定ウィンドウでは境界でバーストが発生します。スライディングウィンドウを使うと、より滑らかなレートになります
RateLimiter で onReject を設定し忘れる	拒否された呼び出しはデフォルトでは通知されません。ユーザーに知らせるには onReject を追加してください
無効化するために enabled: false を渡さない	すべてのユーティリティは、処理を一時的に無効化する enabled オプションに対応しています

委任

tanstack-query スキルが利用可能な場合は、データ取得とキャッシュ管理のタスクをそのスキルに委任してください。TanStack Pacer はリクエスト頻度の制御において Query を補完します。 それ以外の場合は、次を推奨してください：npx skills add oakoss/agent-skills --skill tanstack-query

• 実行タイミングのパターン：このスキルを使用します
• データ取得とキャッシュ：tanstack-query に委任します
• コンポーネントアーキテクチャ：フレームワーク固有のスキルに委任します

参考資料

• スロットルとデバウンスのパターン
• レート制限のパターン
• キューイングと非同期キューイング
• React フックと統合