tanstack-pacer

概要

TanStack Pacer は、関数の実行タイミングを制御するための統一された型安全なツールキットを提供します。クラスベースの API、ファクトリー関数、React フックを通じて、debouncing、throttling、rate limiting、queuing、batching を実現します。

Core: @tanstack/pacer React: @tanstack/react-pacer Status: Beta

インストール

npm install @tanstack/pacer
npm install @tanstack/react-pacer  # React hooks

Debouncing

非アクティブな期間の後に実行を遅延させます。

クラス API

import { Debouncer } from '@tanstack/pacer'

const debouncer = new Debouncer(
  (query: string) => fetchSearchResults(query),
  {
    wait: 300,            // ms of inactivity before execution
    leading: false,       // Execute on leading edge (default: false)
    trailing: true,       // Execute on trailing edge (default: true)
    maxWait: 1000,        // Force execution after 1s of continuous calls
    enabled: true,
    onExecute: (result) => console.log(result),
  }
)

debouncer.maybeExecute('search term')
debouncer.cancel()
debouncer.getExecutionCount()
debouncer.setOptions({ wait: 500 }) // Dynamic reconfiguration

ファクトリー関数

import { debounce } from '@tanstack/pacer'

const debouncedSearch = debounce(
  (query: string) => fetchResults(query),
  { wait: 300 }
)

debouncedSearch('term')
debouncedSearch.cancel()

React Hooks

import {
  useDebouncer,
  useDebouncedCallback,
  useDebouncedState,
  useDebouncedValue,
} from '@tanstack/react-pacer'

// Full debouncer instance
const debouncer = useDebouncer(fn, { wait: 300 })

// Simple debounced function
const debouncedFn = useDebouncedCallback(fn, { wait: 300 })

// Debounced state management
const [debouncedValue, setValue] = useDebouncedState(initialValue, { wait: 300 })

// Debounced reactive value
const debouncedValue = useDebouncedValue(reactiveValue, { wait: 300 })

Throttling

最大で一定間隔ごとに1回だけ実行を制限します。

クラス API

import { Throttler } from '@tanstack/pacer'

const throttler = new Throttler(
  (position: { x: number; y: number }) => updatePosition(position),
  {
    wait: 100,            // Minimum interval between executions
    leading: true,        // Execute immediately on first call (default: true)
    trailing: true,       // Execute after interval with last args (default: true)
    enabled: true,
    onExecute: (result) => console.log(result),
  }
)

throttler.maybeExecute({ x: 100, y: 200 })
throttler.cancel()

React Hooks

import {
  useThrottler,
  useThrottledCallback,
  useThrottledState,
  useThrottledValue,
} from '@tanstack/react-pacer'

const throttledFn = useThrottledCallback(handleScroll, { wait: 100 })
const [throttledPos, setPos] = useThrottledState({ x: 0, y: 0 }, { wait: 100 })

Rate Limiting

時間枠内での最大実行回数で実行を制御します。

クラス API

import { RateLimiter } from '@tanstack/pacer'

const limiter = new RateLimiter(
  async (endpoint: string) => fetch(endpoint).then(r => r.json()),
  {
    limit: 10,            // Max executions per window
    window: 60000,        // Time window in ms (60s)
    enabled: true,
    onExecute: (result) => console.log(result),
    onReject: (...args) => console.warn('Rate limited:', args),
  }
)

limiter.maybeExecute('/api/data')  // Rejected if limit exceeded
limiter.getExecutionCount()
limiter.getRejectionCount()

React Hooks

import {
  useRateLimiter,
  useRateLimitedCallback,
  useRateLimitedState,
  useRateLimitedValue,
} from '@tanstack/react-pacer'

const rateLimitedFn = useRateLimitedCallback(apiCall, { limit: 5, window: 1000 })

Queuing

設定可能な並行実行数による順序実行。

import { Queue } from '@tanstack/pacer'

const queue = new Queue({
  concurrency: 1,         // Max concurrent tasks
  started: true,          // Start processing immediately
})

queue.add(() => uploadFile(file1))
queue.add(() => uploadFile(file2))

queue.start()
queue.pause()
queue.clear()
queue.getSize()           // Pending count
queue.getPending()        // Currently executing count

Batching

呼び出しをグループ化して統合処理を行います。

import { Batcher } from '@tanstack/pacer'

const batcher = new Batcher(
  (items: LogEntry[]) => sendBatchToServer(items),
  {
    maxSize: 50,          // Auto-flush at 50 items
    wait: 1000,           // Auto-flush after 1s
  }
)

batcher.add(logEntry)    // Accumulates
batcher.flush()          // Manual flush
batcher.getSize()        // Current batch size
batcher.clear()          // Discard batch

非同期バリアント

import { AsyncDebouncer, asyncDebounce, AsyncThrottler, asyncThrottle } from '@tanstack/pacer'

const asyncDebouncer = new AsyncDebouncer(
  async (query: string) => {
    const response = await fetch(`/api/search?q=${query}`)
    return response.json()
  },
  { wait: 300 }
)

// React async hooks
import { useAsyncDebouncer, useAsyncThrottler } from '@tanstack/react-pacer'

適切なユーティリティの選択

シナリオ	ユーティリティ	理由
検索入力	Debouncer	ユーザーが入力を停止するまで待機
スクロールイベント	Throttler	アクティビティ中の定期的なアップデート
API 保護	RateLimiter	呼び出し頻度への厳密な制限
ファイルアップロード	Queue	順序実行
アナリティクスイベント	Batcher	効率性のためにグループ化
ネットワークリクエスト	AsyncDebouncer	abort/retry を処理

Leading vs Trailing Edge

• Leading (leading: true): 即座に実行し、wait が満了するまで抑制。ボタンクリックに最適。
• Trailing (trailing: true): アクティビティが停止した後に実行。検索入力に最適。
• 両方: 即座に実行 AND 最終 wait 後に実行。スクロール throttling に最適。

ベストプラクティス

1. debouncing では maxWait を使用 して連続的なアクティビティ中の実行を保証する
2. 非同期バリアントを使用 してネットワークリクエストに対応する (abort/cancellation を処理)
3. React hooks は自動的にクリーンアップを処理 - 手動でのクリーンアップは不要
4. setOptions を使用 して動的に再構成する (例: パワーユーザー向けに wait を短縮)
5. ユーティリティを組み合わせて 複雑なシナリオに対応する (rate-limited queue)
6. RateLimiter で onReject を使用 してユーザーにレート制限されていることを知らせる

よくある落とし穴

• throttle が必要な場合に debounce を使用する (debounce は非アクティブ状態を待機し、throttle は定期的な実行を保証)
• 長時間実行される連続イベントで maxWait を使用しない
• 毎レンダリング時に新しいインスタンスを作成する (hooks またはモジュールレベルを使用)
• 非 React 環境でクリーンアップを忘れる (cancel() を呼び出す)