Open History to see the last commit
1---
2id: AsyncRateLimiter
3title: AsyncRateLimiter
4---
5
6Defined in: [async-rate-limiter.ts:245](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L245)
7
8A class that creates an async rate-limited function.
9
10Async vs Sync Versions:
11The async version provides advanced features over the sync RateLimiter:
12- Returns promises that can be awaited for rate-limited function results
13- Built-in retry support via AsyncRetryer integration
14- Abort support to cancel in-flight executions
15- Comprehensive error handling with onError callbacks and throwOnError control
16- Detailed execution tracking (success/error/settle counts, rejection counts)
17- More sophisticated window management with automatic cleanup
18
19The sync RateLimiter is lighter weight and simpler when you don't need async features,
20return values, or execution control.
21
22What is Rate Limiting?
23Rate limiting allows a function to execute up to a limit within a time window,
24then blocks all subsequent calls until the window passes. This can lead to "bursty" behavior where
25all executions happen immediately, followed by a complete block.
26
27Window Types:
28- 'fixed': A strict window that resets after the window period. All executions within the window count
29 towards the limit, and the window resets completely after the period.
30- 'sliding': A rolling window that allows executions as old ones expire. This provides a more
31 consistent rate of execution over time.
32
33When to Use Rate Limiting:
34Rate limiting is best used for hard API limits or resource constraints. For UI updates or
35smoothing out frequent events, throttling or debouncing usually provide better user experience.
36- Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)
37- Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)
38
39State Management:
40- Uses TanStack Store for reactive state management
41- Use `initialState` to provide initial state values when creating the rate limiter
42- `initialState` can be a partial state object
43- Use `onSuccess` callback to react to successful function execution and implement custom logic
44- Use `onError` callback to react to function execution errors and implement custom error handling
45- Use `onSettled` callback to react to function execution completion (success or error) and implement custom logic
46- Use `onReject` callback to react to executions being rejected when rate limit is exceeded
47- The state includes execution times, success/error counts, and current execution status
48- State can be accessed via `asyncRateLimiter.store.state` when using the class directly
49- When using framework adapters (React/Solid), state is accessed from `asyncRateLimiter.state`
50
51Error Handling:
52- If an `onError` handler is provided, it will be called with the error and rate limiter instance
53- If `throwOnError` is true (default when no onError handler is provided), the error will be thrown
54- If `throwOnError` is false (default when onError handler is provided), the error will be swallowed
55- Both onError and throwOnError can be used together - the handler will be called before any error is thrown
56- The error state can be checked using the underlying AsyncRateLimiter instance
57- Rate limit rejections (when limit is exceeded) are handled separately from execution errors via the `onReject` handler
58
59## Example
60
61```ts
62const rateLimiter = new AsyncRateLimiter(
63 async (id: string) => await api.getData(id),
64 {
65 limit: 5,
66 window: 1000,
67 windowType: 'sliding',
68 onError: (error) => {
69 console.error('API call failed:', error);
70 },
71 onReject: (limiter) => {
72 console.log(`Rate limit exceeded. Try again in ${limiter.getMsUntilNextWindow()}ms`);
73 }
74 }
75);
76
77// Will execute immediately until limit reached, then block
78// Returns the API response directly
79const data = await rateLimiter.maybeExecute('123');
80```
81
82## Type Parameters
83
84### TFn
85
86`TFn` *extends* [`AnyAsyncFunction`](../type-aliases/AnyAsyncFunction.md)
87
88## Constructors
89
90### Constructor
91
92```ts
93new AsyncRateLimiter<TFn>(fn, initialOptions): AsyncRateLimiter<TFn>;
94```
95
96Defined in: [async-rate-limiter.ts:254](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L254)
97
98#### Parameters
99
100##### fn
101
102`TFn`
103
104##### initialOptions
105
106[`AsyncRateLimiterOptions`](../interfaces/AsyncRateLimiterOptions.md)\<`TFn`\>
107
108#### Returns
109
110`AsyncRateLimiter`\<`TFn`\>
111
112## Properties
113
114### asyncRetryers
115
116```ts
117asyncRetryers: Map<number, AsyncRetryer<TFn>>;
118```
119
120Defined in: [async-rate-limiter.ts:251](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L251)
121
122***
123
124### fn
125
126```ts
127fn: TFn;
128```
129
130Defined in: [async-rate-limiter.ts:255](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L255)
131
132***
133
134### key
135
136```ts
137key: string | undefined;
138```
139
140Defined in: [async-rate-limiter.ts:249](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L249)
141
142***
143
144### options
145
146```ts
147options: AsyncRateLimiterOptions<TFn>;
148```
149
150Defined in: [async-rate-limiter.ts:250](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L250)
151
152***
153
154### store
155
156```ts
157readonly store: Store<Readonly<AsyncRateLimiterState<TFn>>>;
158```
159
160Defined in: [async-rate-limiter.ts:246](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L246)
161
162## Methods
163
164### abort()
165
166```ts
167abort(): void;
168```
169
170Defined in: [async-rate-limiter.ts:540](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L540)
171
172Aborts all ongoing executions with the internal abort controllers.
173Does NOT clear out the execution times or reset the rate limiter.
174
175#### Returns
176
177`void`
178
179***
180
181### getAbortSignal()
182
183```ts
184getAbortSignal(maybeExecuteCount?): AbortSignal | null;
185```
186
187Defined in: [async-rate-limiter.ts:530](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L530)
188
189Returns the AbortSignal for a specific execution.
190If no maybeExecuteCount is provided, returns the signal for the most recent execution.
191Returns null if no execution is found or not currently executing.
192
193#### Parameters
194
195##### maybeExecuteCount?
196
197`number`
198
199Optional specific execution to get signal for
200
201#### Returns
202
203`AbortSignal` \| `null`
204
205#### Example
206
207```typescript
208const rateLimiter = new AsyncRateLimiter(
209 async (userId: string) => {
210 const signal = rateLimiter.getAbortSignal()
211 if (signal) {
212 const response = await fetch(`/api/users/${userId}`, { signal })
213 return response.json()
214 }
215 },
216 { limit: 5, window: 1000 }
217)
218```
219
220***
221
222### getMsUntilNextWindow()
223
224```ts
225getMsUntilNextWindow(): number;
226```
227
228Defined in: [async-rate-limiter.ts:502](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L502)
229
230Returns the number of milliseconds until the next execution will be possible
231For fixed windows, this is the time until the current window resets
232For sliding windows, this is the time until the oldest execution expires
233
234#### Returns
235
236`number`
237
238***
239
240### getRemainingInWindow()
241
242```ts
243getRemainingInWindow(): number;
244```
245
246Defined in: [async-rate-limiter.ts:492](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L492)
247
248Returns the number of remaining executions allowed in the current window
249
250#### Returns
251
252`number`
253
254***
255
256### maybeExecute()
257
258```ts
259maybeExecute(...args): Promise<Awaited<ReturnType<TFn>> | undefined>;
260```
261
262Defined in: [async-rate-limiter.ts:358](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L358)
263
264Attempts to execute the rate-limited function if within the configured limits.
265Will reject execution if the number of calls in the current window exceeds the limit.
266
267Error Handling:
268- If the rate-limited function throws and no `onError` handler is configured,
269 the error will be thrown from this method.
270- If an `onError` handler is configured, errors will be caught and passed to the handler,
271 and this method will return undefined.
272- The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
273
274#### Parameters
275
276##### args
277
278...`Parameters`\<`TFn`\>
279
280#### Returns
281
282`Promise`\<`Awaited`\<`ReturnType`\<`TFn`\>\> \| `undefined`\>
283
284A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
285
286#### Throws
287
288The error from the rate-limited function if no onError handler is configured
289
290#### Example
291
292```ts
293const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
294
295// First 5 calls will return a promise that resolves with the result
296const result = await rateLimiter.maybeExecute('arg1', 'arg2');
297
298// Additional calls within the window will return undefined
299const result2 = await rateLimiter.maybeExecute('arg1', 'arg2'); // undefined
300```
301
302***
303
304### reset()
305
306```ts
307reset(): void;
308```
309
310Defined in: [async-rate-limiter.ts:551](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L551)
311
312Resets the rate limiter state
313
314#### Returns
315
316`void`
317
318***
319
320### setOptions()
321
322```ts
323setOptions(newOptions): void;
324```
325
326Defined in: [async-rate-limiter.ts:285](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L285)
327
328Updates the async rate limiter options
329
330#### Parameters
331
332##### newOptions
333
334`Partial`\<[`AsyncRateLimiterOptions`](../interfaces/AsyncRateLimiterOptions.md)\<`TFn`\>\>
335
336#### Returns
337
338`void`