tanstack-pacer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TanStack Pacer

Overview

概述

TanStack Pacer is a lightweight, type-safe library for controlling function execution timing through debouncing, throttling, rate limiting, queuing, and batching. It provides framework-agnostic core classes with dedicated React hooks at multiple abstraction levels (instance, callback, state, value).

When to use: Debouncing search input, throttling scroll/resize handlers, enforcing API rate limits, queuing async tasks with concurrency control, batching multiple operations into single requests.

When NOT to use: Simple one-off delays (use

setTimeout

), server-side rate limiting at the infrastructure level (use middleware/API gateway), complex job scheduling (use a task queue like BullMQ).

TanStack Pacer 是一个轻量、类型安全的库，可通过防抖、节流、速率限制、排队和批处理来控制函数的执行时机。它提供了与框架无关的核心类，以及多个抽象层级的专属React钩子（实例、回调、状态、值层面）。

适用场景： 防抖搜索输入、节流滚动/ resize 事件处理器、强制API速率限制、对异步任务进行并发控制排队、将多个操作批量处理为单个请求。

不适用场景： 简单的一次性延迟（使用

setTimeout

即可）、基础设施层面的服务端速率限制（使用中间件/API网关）、复杂的作业调度（使用BullMQ等任务队列）。

Quick Reference

快速参考

Pattern	API	Key Points
Debounce function	`Debouncer` / `debounce(fn, opts)`	Waits for inactivity; no `maxWait` option by design
Throttle function	`Throttler` / `throttle(fn, opts)`	Even spacing; `leading` and `trailing` both default `true`
Rate limit	`RateLimiter` / `rateLimit(fn, opts)`	Fixed or sliding window; rejects calls over limit
Queue items	`Queuer` / `queue(fn, opts)`	FIFO default; supports LIFO, priority, expiration
Async queue	`AsyncQueuer` / `asyncQueue(fn, opts)`	Concurrency control, retry, error callbacks
Async batch	`AsyncBatcher` / `asyncBatch(fn, opts)`	Collects items, processes as batch after wait/maxSize
React debounce	`useDebouncer` / `useDebouncedCallback`	Instance hook vs simple callback hook
React throttle	`useThrottler` / `useThrottledCallback`	Instance hook vs simple callback hook
React rate limit	`useRateLimiter` / `useRateLimitedCallback`	Instance hook vs simple callback hook
React queue	`useQueuer` / `useQueuedState`	Instance hook vs state-integrated hook
React async queue	`useAsyncQueuer` / `useAsyncQueuedState`	Concurrency + state management
React batch	`useBatcher` / `useAsyncBatcher`	Sync and async batching hooks
State hooks	`useDebouncedState` , `useThrottledState`	Integrate with React state directly
Value hooks	`useDebouncedValue` , `useThrottledValue`	Create derived debounced/throttled values

模式	API	核心要点
防抖函数	`Debouncer` / `debounce(fn, opts)`	等待无活动状态；设计上默认无 `maxWait` 选项
节流函数	`Throttler` / `throttle(fn, opts)`	均匀间隔执行； `leading` 和 `trailing` 默认均为 `true`
速率限制	`RateLimiter` / `rateLimit(fn, opts)`	固定或滑动窗口；超出限制时拒绝调用
任务排队	`Queuer` / `queue(fn, opts)`	默认先进先出；支持后进先出、优先级、过期机制
异步任务队列	`AsyncQueuer` / `asyncQueue(fn, opts)`	并发控制、重试、错误回调
异步批处理	`AsyncBatcher` / `asyncBatch(fn, opts)`	收集任务项，在等待超时或达到最大数量后批量处理
React 防抖	`useDebouncer` / `useDebouncedCallback`	实例钩子 vs 简单回调钩子
React 节流	`useThrottler` / `useThrottledCallback`	实例钩子 vs 简单回调钩子
React 速率限制	`useRateLimiter` / `useRateLimitedCallback`	实例钩子 vs 简单回调钩子
React 任务队列	`useQueuer` / `useQueuedState`	实例钩子 vs 集成状态的钩子
React 异步任务队列	`useAsyncQueuer` / `useAsyncQueuedState`	并发控制 + 状态管理
React 批处理	`useBatcher` / `useAsyncBatcher`	同步和异步批处理钩子
状态钩子	`useDebouncedState` , `useThrottledState`	直接与React状态集成
值钩子	`useDebouncedValue` , `useThrottledValue`	创建派生的防抖/节流值

Common Mistakes

常见错误

Mistake	Correct Pattern
Using `maxWait` on Debouncer	Debouncer has no `maxWait` ; use Throttler for evenly spaced execution
Creating instances inside render	Create with hooks ( `useDebouncer` , `useThrottler` ) to manage lifecycle
Ignoring `maybeExecute` return	Rate limiter and throttler may reject calls; check state or use callbacks
Using debounce when throttle is needed	Debounce waits for pause; throttle guarantees max-once-per-interval
Not cleaning up on unmount	React hooks handle cleanup automatically; manual instances need `cancel()`
Using Queuer when items can be dropped	Queuers process every item; use throttle/debounce if dropping is acceptable
Fixed window when sliding is needed	Fixed windows allow bursts at boundaries; sliding window gives smoother rate
Forgetting `onReject` on RateLimiter	Rejected calls are silent by default; add `onReject` for user feedback
Not passing `enabled: false` to disable	All utilities support `enabled` option to temporarily disable processing

错误操作	正确做法
在Debouncer中使用 `maxWait`	Debouncer 无 `maxWait` 选项；如需均匀间隔执行，请使用Throttler
在渲染内部创建实例	使用钩子（ `useDebouncer` 、 `useThrottler` ）来管理生命周期
忽略 `maybeExecute` 的返回值	速率限制器和节流器可能会拒绝调用；请检查状态或使用回调函数
需要节流时使用了防抖	防抖会等待操作暂停；节流可保证每间隔最多执行一次
组件卸载时未清理资源	React钩子会自动处理清理；手动创建的实例需要调用 `cancel()`
可丢弃任务时使用Queuer	Queuer会处理每个任务项；若可丢弃任务，请使用节流/防抖
需要滑动窗口时使用了固定窗口	固定窗口允许在边界处出现突发请求；滑动窗口可提供更平滑的速率控制
忘记为RateLimiter添加 `onReject`	默认情况下被拒绝的调用无提示；请添加 `onReject` 以向用户反馈
未通过 `enabled: false` 禁用功能	所有工具均支持 `enabled` 选项，可临时禁用处理逻辑

Delegation

任务委托

If the
tanstack-query
skill is available, delegate data fetching and cache management tasks to it. TanStack Pacer complements Query for controlling request frequency. Otherwise, recommend:
npx skills add oakoss/agent-skills --skill tanstack-query

Execution timing patterns: Use this skill
Data fetching and caching: Delegate to
```
tanstack-query
```
Component architecture: Delegate to framework-specific skills

若
tanstack-query
技能可用，请将数据获取和缓存管理任务委托给它。TanStack Pacer 可与Query配合使用，控制请求频率。否则，推荐执行：
npx skills add oakoss/agent-skills --skill tanstack-query

执行时机模式：使用本技能
数据获取与缓存：委托给
```
tanstack-query
```
组件架构：委托给框架专属技能

References

参考资料

Throttle and debounce patterns
Rate limiting patterns
Queuing and async queuing
React hooks and integration

节流与防抖模式
速率限制模式
任务排队与异步队列
React钩子与集成