Skip to content
Source
Sign inSign up
TanStack/pacer
Open History to see the last commit

rate-limiting.md

223 lines7.3 KB

1---
2title: React Rate Limiting Guide
3id: rate-limiting
4---
5​
6Rate limiting allows a configured number of executions within a time window. Calls run immediately while capacity remains. Once the limit is reached, later calls are rejected until capacity becomes available again.
7​
8TanStack Pacer provides an in-memory rate limiter intended primarily for client-side operations. It can run in server-side JavaScript, but it is not a distributed quota or enforcement system.
9​
10## How rate limiting works
11​
12This example allows three executions per window:
13​
14```text
15Rate Limiting (limit: 3 calls per window)
16Timeline: [1 second per tick]
17 Window 1 | Window 2
18Calls: ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️ ⬇️
19Executed: ✅ ✅ ✅ ❌ ❌ ✅ ✅
20 [=== 3 allowed ===][=== blocked until reset ===][=== new window ===]
21```
22​
23Rate limiting permits bursts. It does not space accepted calls evenly.
24​
25## When to use rate limiting
26​
27Choose rate limiting when:
28​
29- A client operation should follow a fixed quota.
30- Calls may run immediately until the quota is exhausted.
31- Rejected calls may be discarded or handled separately.
32- You need to measure remaining capacity or time until capacity returns.
33​
34Choose another utility when:
35​
36- Executions should be evenly spaced. Use [throttling](./throttling.md).
37- Only the final call matters. Use [debouncing](./debouncing.md).
38- Every operation must eventually run. Use [queuing](./queuing.md).
39- Items should run together. Use [batching](./batching.md).
40- You need Promise results, retries, or abort support. Use [async rate limiting](./async-rate-limiting.md).
41​
42## Window types
43​
44The `windowType` option controls when capacity returns.
45​
46### Fixed window
47​
48A fixed window starts when its first execution is accepted. All accepted executions remain counted until that window ends. Capacity then resets together.
49​
50```ts
51const limiter = useRateLimiter(sendEvent, {
52 limit: 3,
53 window: 1000,
54 windowType: 'fixed',
55})
56```
57​
58Fixed windows can allow bursts near a boundary because a full quota becomes available when the window resets.
59​
60### Sliding window
61​
62A sliding window tracks each accepted execution separately. Capacity returns one execution at a time as old timestamps leave the window.
63​
64```text
65Sliding Window (limit: 3 calls per window)
66Timeline: [1 second per tick]
67Calls: ⬇️ ⬇️ ⬇️ ⬇️ ⬇️
68Executed: ✅ ✅ ✅ ❌ ✅
69 [=== full ===][oldest execution expires][=== one available ===]
70```
71​
72```ts
73const limiter = useRateLimiter(sendEvent, {
74 limit: 3,
75 window: 1000,
76 windowType: 'sliding',
77})
78```
79​
80Use a sliding window when capacity should return gradually rather than all at once.
81​
82## Choose an API
83​
84- `useRateLimitedCallback` for a quota-controlled event handler
85- `useRateLimitedState` or `useRateLimitedValue` for React state
86- `useRateLimiter` for capacity helpers and selected state
87​
88Use the callback API for operations, the state or value API for quota-controlled UI updates, and the instance API when you need capacity helpers or rejection state.
89​
90## React example
91​
92```tsx
93import { useRateLimiter } from '@tanstack/react-pacer'
94​
95function SendButton() {
96 const limiter = useRateLimiter(
97 sendEvent,
98 { limit: 3, window: 10_000 },
99 (state) => ({
100 rejectionCount: state.rejectionCount,
101 }),
102 )
103​
104 return (
105 <button onClick={() => limiter.maybeExecute('clicked')}>
106 Send ({limiter.state.rejectionCount} rejected)
107 </button>
108 )
110```
111​
112The focused snippets later in this guide use `useRateLimiter` and assume they run inside a component or another hook.
113​
114## Handling rejected calls
115​
116Rejected calls do not run later. Use the boolean return value or `onReject` to provide feedback, retry elsewhere, or place work into a queue.
117​
118```ts
119const limiter = useRateLimiter(sendEvent, {
120 limit: 2,
121 window: 1000,
122 onReject: (limiter) => {
123 console.log('Rejected calls:', limiter.store.state.rejectionCount)
124 },
125})
126```
127​
128If rejected operations must eventually run, a [queuer](./queuing.md) is usually a better fit.
129​
130## Inspecting capacity
131​
132The instance API provides two computed helpers:
133​
134```ts
135limiter.getRemainingInWindow() // Accepted executions still available.
136limiter.getMsUntilNextWindow() // Time until at least one execution is available.
137```
138​
139Both helpers use the current `limit`, `window`, `windowType`, and execution history.
140​
141## Resetting and configuring the limiter
142​
143`reset()` clears execution timestamps, counters, and cleanup timers. The next call starts with full capacity.
144​
145```ts
146limiter.reset()
147```
148​
149Use `setOptions()` to update the configuration:
150​
151```ts
152limiter.setOptions({
153 limit: 10,
154 window: 30_000,
155})
156```
157​
158Changing options does not erase existing execution history. Call `reset()` when the new configuration should begin with a fresh window.
159​
160The `enabled`, `limit`, and `window` options may be functions that receive the limiter instance:
161​
162```ts
163const limiter = useRateLimiter(sendEvent, {
164 enabled: (limiter) => limiter.store.state.executionCount < 100,
165 limit: (limiter) => (limiter.store.state.rejectionCount > 10 ? 2 : 5),
166 window: 60_000,
167})
168```
169​
170Disabling the limiter prevents the wrapped function from executing. It does not delete existing execution history.
171​
172### Observing executions
173​
174`onExecute` receives the executed arguments and limiter instance. `onReject` receives the limiter instance.
175​
176```ts
177const limiter = useRateLimiter(sendEvent, {
178 limit: 5,
179 window: 1000,
180 onExecute: (args, limiter) => {
181 console.log('Sent:', args)
182 console.log('Remaining:', limiter.getRemainingInWindow())
183 },
184 onReject: (limiter) => {
185 console.log('Rejected:', limiter.store.state.rejectionCount)
186 },
187})
188```
189​
190## React lifecycle
191​
192The adapter has no default operation cleanup because a synchronous limiter has no pending or active work. Use `onUnmount` only when the component needs custom teardown related to the limiter.
193​
194## Reactive state
195​
196The adapter subscribes only to the state returned by the selector argument. Without a selector, the adapter state is empty. Create the utility at the top level of a component or another hook and select only fields used by the view:
197​
198```ts
199const limiter = useRateLimiter(
200 sendEvent,
201 { limit: 5, window: 60_000 },
202 (state) => ({
203 isExceeded: state.isExceeded,
204 rejectionCount: state.rejectionCount,
205 }),
207​
208console.log(limiter.state.isExceeded, limiter.state.rejectionCount)
209```
210​
211Option functions and lifecycle callbacks receive the underlying public utility instance. The `.store.state` reads inside those callbacks in the examples above are supported. Rendering code should read the selected adapter state shown here.
212​
213To restore selected state that your app has persisted, pass a partial snapshot through `initialState`. It is merged with the defaults. Restore only durable fields. Pending timers are not restored.
214​
215Commonly useful state includes:
216​
217- `executionCount`: Total accepted executions that completed.
218- `executionTimes`: Timestamps currently used for window calculations.
219- `isExceeded`: Whether the current limit has been reached.
220- `rejectionCount`: Calls rejected because the window was full.
221- `status`: `'disabled'`, `'exceeded'`, or `'idle'`.
222​
223See the [React API reference](../reference/index.md) for adapter signatures and the public core reference for complete option and state types.