tanstack-pacer

TanStack Pacer

概述

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

适用场景： 对搜索输入进行防抖处理、对滚动／调整大小处理程序进行节流、强制执行 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)	默认先进先出；支持后进先出、优先级和过期
异步队列	AsyncQueuer / asyncQueue(fn, opts)	并发控制、重试、错误回调
异步批处理	AsyncBatcher / asyncBatch(fn, opts)	收集项目，在等待时间到期或达到最大数量后批量处理
React 防抖	useDebouncer / useDebouncedCallback	实例 Hook 与简单回调 Hook
React 节流	useThrottler / useThrottledCallback	实例 Hook 与简单回调 Hook
React 速率限制	useRateLimiter / useRateLimitedCallback	实例 Hook 与简单回调 Hook
React 队列	useQueuer / useQueuedState	实例 Hook 与集成状态的 Hook
React 异步队列	useAsyncQueuer / useAsyncQueuedState	并发控制与状态管理
React 批处理	useBatcher / useAsyncBatcher	同步和异步批处理 Hook
状态 Hook	useDebouncedState、useThrottledState	直接与 React 状态集成
值 Hook	useDebouncedValue、useThrottledValue	创建派生的防抖／节流值

常见错误

错误	正确做法
在 Debouncer 上使用 maxWait	Debouncer 没有 maxWait；如需均匀间隔执行，请使用 Throttler
在渲染过程中创建实例	使用钩子（useDebouncer、useThrottler）创建实例，以管理其生命周期
忽略 maybeExecute 的返回值	限速器和 Throttler 可能会拒绝调用；请检查状态或使用回调
需要节流时使用防抖	防抖会等待操作暂停；节流可确保每个时间间隔最多执行一次
卸载时未清理	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 钩子和集成