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

asyncRateLimit.md

154 lines6.2 KB

1---
2id: asyncRateLimit
3title: asyncRateLimit
4---
5​
6```ts
7function asyncRateLimit<TFn>(fn, initialOptions): (...args) => Promise<Awaited<ReturnType<TFn>> | undefined>;
8```
9​
10Defined in: [async-rate-limiter.ts:642](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/async-rate-limiter.ts#L642)
11​
12Creates an async rate-limited function that will execute the provided function up to a maximum number of times within a time window.
13​
14Async vs Sync Versions:
15The async version provides advanced features over the sync rate limit function:
16- Returns promises that can be awaited for rate-limited function results
17- Built-in retry support via AsyncRetryer integration
18- Abort support to cancel in-flight executions
19- Comprehensive error handling with onError callbacks and throwOnError control
20- Detailed execution tracking (success/error/settle counts, rejection counts)
21- More sophisticated window management with automatic cleanup
22​
23The sync rate limit function is lighter weight and simpler when you don't need async features,
24return values, or execution control.
25​
26What is Rate Limiting?
27Rate limiting allows a function to execute up to a limit within a time window,
28then blocks all subsequent calls until the window passes. This can lead to "bursty" behavior where
29all executions happen immediately, followed by a complete block.
30​
31Window Types:
32- 'fixed': A strict window that resets after the window period. All executions within the window count
33 towards the limit, and the window resets completely after the period.
34- 'sliding': A rolling window that allows executions as old ones expire. This provides a more
35 consistent rate of execution over time.
36​
37Configuration Options:
38- `limit`: Maximum number of executions allowed within the window (required)
39- `window`: Time window in milliseconds (required)
40- `windowType`: 'fixed' or 'sliding' (default: 'fixed')
41- `enabled`: Whether the rate limiter is enabled (default: true)
42- `asyncRetryerOptions`: Configure retry behavior for executions
43​
44When to Use Rate Limiting:
45Rate limiting is best used for hard API limits or resource constraints. For UI updates or
46smoothing out frequent events, throttling or debouncing usually provide better user experience.
47- A rate limiter will allow all executions until the limit is reached, then block all subsequent calls until the window resets
48- A throttler ensures even spacing between executions, which can be better for consistent performance
49- A debouncer collapses multiple calls into one, which is better for handling bursts of events
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​
59State Management:
60- Uses TanStack Store for reactive state management
61- Use `initialState` to provide initial state values when creating the rate limiter
62- `initialState` can be a partial state object
63- Use `onSuccess` callback to react to successful function execution and implement custom logic
64- Use `onError` callback to react to function execution errors and implement custom error handling
65- Use `onSettled` callback to react to function execution completion (success or error) and implement custom logic
66- Use `onReject` callback to react to executions being rejected when rate limit is exceeded
67- The state includes execution times, success/error counts, and current execution status
68- State can be accessed via the underlying AsyncRateLimiter instance's `store.state` property
69- When using framework adapters (React/Solid), state is accessed from the hook's state property
70​
71## Type Parameters
72​
73### TFn
74​
75`TFn` *extends* [`AnyAsyncFunction`](../type-aliases/AnyAsyncFunction.md)
76​
77## Parameters
78​
79### fn
80​
81`TFn`
82​
83### initialOptions
84​
85[`AsyncRateLimiterOptions`](../interfaces/AsyncRateLimiterOptions.md)\<`TFn`\>
86​
87## Returns
88​
89```ts
90(...args): Promise<Awaited<ReturnType<TFn>> | undefined>;
91```
92​
93Attempts to execute the rate-limited function if within the configured limits.
94Will reject execution if the number of calls in the current window exceeds the limit.
95​
96Error Handling:
97- If the rate-limited function throws and no `onError` handler is configured,
98 the error will be thrown from this method.
99- If an `onError` handler is configured, errors will be caught and passed to the handler,
100 and this method will return undefined.
101- The error state can be checked using `getErrorCount()` and `getIsExecuting()`.
102​
103### Parameters
104​
105#### args
106​
107...`Parameters`\<`TFn`\>
108​
109### Returns
110​
111`Promise`\<`Awaited`\<`ReturnType`\<`TFn`\>\> \| `undefined`\>
112​
113A promise that resolves with the function's return value, or undefined if an error occurred and was handled by onError
114​
115### Throws
116​
117The error from the rate-limited function if no onError handler is configured
118​
119### Example
120​
121```ts
122const rateLimiter = new AsyncRateLimiter(fn, { limit: 5, window: 1000 });
123​
124// First 5 calls will return a promise that resolves with the result
125const result = await rateLimiter.maybeExecute('arg1', 'arg2');
126​
127// Additional calls within the window will return undefined
128const result2 = await rateLimiter.maybeExecute('arg1', 'arg2'); // undefined
129```
130​
131## Example
132​
133```ts
134// Rate limit to 5 calls per minute with a sliding window
135const rateLimited = asyncRateLimit(makeApiCall, {
136 limit: 5,
137 window: 60000,
138 windowType: 'sliding',
139 onError: (error) => {
140 console.error('API call failed:', error);
141 },
142 onReject: (rateLimiter) => {
143 console.log(`Rate limit exceeded. Try again in ${rateLimiter.getMsUntilNextWindow()}ms`);
144 }
145});
146​
147// First 5 calls will execute immediately
148// Additional calls will be rejected until the minute window resets
149// Returns the API response directly
150const result = await rateLimited();
151​
152// For more even execution, consider using throttle instead:
153const throttled = throttle(makeApiCall, { wait: 12000 }); // One call every 12 seconds
154```