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

useAsyncRateLimitedCallback.md

83 lines2.9 KB

1---
2id: useAsyncRateLimitedCallback
3title: useAsyncRateLimitedCallback
4---
5​
6```ts
7function useAsyncRateLimitedCallback<TFn>(fn, options): (...args) => Promise<Awaited<ReturnType<TFn>> | undefined>;
8```
9​
10Defined in: [async-rate-limiter/useAsyncRateLimitedCallback.ts:59](https://github.com/TanStack/pacer/blob/main/packages/react-pacer/src/async-rate-limiter/useAsyncRateLimitedCallback.ts#L59)
11​
12A React hook that creates a rate-limited version of an async callback function.
13This hook is a convenient wrapper around the `useAsyncRateLimiter` hook,
14providing a stable, async rate-limited function reference for use in React components.
15​
16Async rate limiting is a "hard limit" approach for async functions: it allows all calls
17until the limit is reached, then blocks (rejects) subsequent calls until the window resets.
18Unlike throttling or debouncing, it does not attempt to space out or collapse calls.
19This can lead to bursts of rapid executions followed by periods where all calls are blocked.
20​
21The async rate limiter supports two types of windows:
22- 'fixed': A strict window that resets after the window period. All executions within the window count
23 towards the limit, and the window resets completely after the period.
24- 'sliding': A rolling window that allows executions as old ones expire. This provides a more
25 consistent rate of execution over time.
26​
27For smoother execution patterns, consider:
28- useAsyncThrottledCallback: When you want consistent spacing between executions (e.g. UI updates)
29- useAsyncDebouncedCallback: When you want to collapse rapid calls into a single execution (e.g. search input)
30​
31Async rate limiting should primarily be used when you need to enforce strict limits
32on async operations, like API rate limits or other scenarios requiring hard caps
33on execution frequency.
34​
35This hook provides a simpler API compared to `useAsyncRateLimiter`, making it ideal for basic
36async rate limiting needs. However, it does not expose the underlying AsyncRateLimiter instance.
37​
38For advanced usage requiring features like:
39- Manual cancellation
40- Access to execution counts
41- Custom useCallback dependencies
42​
43Consider using the `useAsyncRateLimiter` hook instead.
44​
45## Type Parameters
46​
47### TFn
48​
49`TFn` *extends* `AnyAsyncFunction`
50​
51## Parameters
52​
53### fn
54​
55`TFn`
56​
57### options
58​
59[`ReactAsyncRateLimiterOptions`](../interfaces/ReactAsyncRateLimiterOptions.md)\<`TFn`, \{
60\}\>
61​
62## Returns
63​
64(...`args`) => `Promise`\<`Awaited`\<`ReturnType`\<`TFn`\>\> \| `undefined`\>
65​
66## Example
67​
68```tsx
69// Rate limit async API calls to maximum 5 calls per minute with a sliding window
70const makeApiCall = useAsyncRateLimitedCallback(
71 async (data: ApiData) => {
72 return fetch('/api/endpoint', { method: 'POST', body: JSON.stringify(data) });
73 },
74 {
75 limit: 5,
76 window: 60000, // 1 minute
77 windowType: 'sliding',
78 onReject: () => {
79 console.warn('API rate limit reached. Please wait before trying again.');
80 }
81 }
82);
83```