Open History to see the last commit
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```