Tanstack Pacer

tanstack-skills/tanstack-skills/plugins/tanstack-pacer/skills/tanstack-pacer

作者 tanstack-skills6f5521ecbdfb無授權條款35 個星標收錄於 2026年10月8日更新於 2026年10月8日儲存庫8 個月前更新

Framework-agnostic debouncing, throttling, rate limiting, queuing, and batching utilities.

AI 產生的概覽

TanStack Pacer 的防抖、節流、限流、佇列與批次處理工具參考指南。

功能
此技能是 TanStack Pacer 函式庫的文件式參考,涵蓋函式執行的防抖、節流、限流、佇列與批次處理。它展示類別 API、工廠函式與 React Hooks,並提供 wait、leading、trailing、maxWait、limit、window、concurrency、批次大小等選項的程式碼範例。內容還包括工具選擇建議、前沿與後沿行為說明、最佳實務與常見陷阱。
適用情境
當你需要查詢如何在 JavaScript 或 TypeScript 中控制函式呼叫的時機或頻率時使用,例如對搜尋輸入做防抖、對捲動事件做節流、限制 API 呼叫或批次處理分析事件。在判斷某個情境適合哪種 Pacer 工具時也很有用。
執行需求
需要 @tanstack/pacer 套件,使用 React Hooks 時還需要 @tanstack/react-pacer。不含指令碼,僅為說明文件與程式碼範例。

Overview

TanStack Pacer provides a unified, type-safe toolkit for controlling function execution timing. It offers class-based APIs, factory functions, and React hooks for debouncing, throttling, rate limiting, queuing, and batching.

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

Installation

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

Debouncing

Delays execution until after a period of inactivity.

Class API

typescript
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

Factory Function

typescript
import { debounce } from '@tanstack/pacer'
const debouncedSearch = debounce(  (query: string) => fetchResults(query),  { wait: 300 })
debouncedSearch('term')debouncedSearch.cancel()

React Hooks

typescript
import {  useDebouncer,  useDebouncedCallback,  useDebouncedState,  useDebouncedValue,} from '@tanstack/react-pacer'
// Full debouncer instanceconst debouncer = useDebouncer(fn, { wait: 300 })
// Simple debounced functionconst debouncedFn = useDebouncedCallback(fn, { wait: 300 })
// Debounced state managementconst [debouncedValue, setValue] = useDebouncedState(initialValue, { wait: 300 })
// Debounced reactive valueconst debouncedValue = useDebouncedValue(reactiveValue, { wait: 300 })

Throttling

Limits execution to at most once per interval.

Class API

typescript
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

typescript
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

Controls execution with a maximum count within a time window.

Class API

typescript
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 exceededlimiter.getExecutionCount()limiter.getRejectionCount()

React Hooks

typescript
import {  useRateLimiter,  useRateLimitedCallback,  useRateLimitedState,  useRateLimitedValue,} from '@tanstack/react-pacer'
const rateLimitedFn = useRateLimitedCallback(apiCall, { limit: 5, window: 1000 })

Queuing

Sequential execution with configurable concurrency.

typescript
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 countqueue.getPending()        // Currently executing count

Batching

Groups calls for combined processing.

typescript
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)    // Accumulatesbatcher.flush()          // Manual flushbatcher.getSize()        // Current batch sizebatcher.clear()          // Discard batch

Async Variants

typescript
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 hooksimport { useAsyncDebouncer, useAsyncThrottler } from '@tanstack/react-pacer'

Choosing the Right Utility

ScenarioUtilityWhy
Search inputDebouncerWait for user to stop typing
Scroll eventsThrottlerPeriodic updates during activity
API protectionRateLimiterHard limit on call frequency
File uploadsQueueSequential processing
Analytics eventsBatcherGroup for efficiency
Network requestsAsyncDebouncerHandle abort/retry

Leading vs Trailing Edge

  • Leading (leading: true): Execute immediately, suppress until wait expires. Good for button clicks.
  • Trailing (trailing: true): Execute after activity stops. Good for search inputs.
  • Both: Execute immediately AND after final wait. Good for scroll throttling.

Best Practices

  1. Use maxWait with debouncing to guarantee execution during continuous activity
  2. Use async variants for network requests (handle abort/cancellation)
  3. React hooks handle cleanup automatically - no manual teardown needed
  4. Use setOptions for dynamic reconfiguration (e.g., reducing wait for power users)
  5. Compose utilities for complex scenarios (rate-limited queue)
  6. Use onReject on RateLimiter to inform users when they're rate limited

Common Pitfalls

  • Using debounce when you need throttle (debounce waits for inactivity, throttle guarantees periodic execution)
  • Not using maxWait with debounce for long-running continuous events
  • Creating new instances on every render (use hooks or module-level)
  • Forgetting cleanup in non-React environments (call cancel())

來源與署名

來源:tanstack-skills/tanstack-skills位於plugins/tanstack-pacer/skills/tanstack-pacer提交6f5521e

授權條款: 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架