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

AsyncRateLimiter.md

338 lines9.2 KB

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 }
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`