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 从公开仓库中收录这些内容。

举报或申请下架