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

RateLimiter.md

226 lines5.2 KB

1---
2id: RateLimiter
3title: RateLimiter
4---
5​
6Defined in: [rate-limiter.ts:156](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L156)
7​
8A class that creates a rate-limited function.
9​
10Rate limiting is a simple approach that allows a function to execute up to a limit within a time window,
11then blocks all subsequent calls until the window passes. This can lead to "bursty" behavior where
12all executions happen immediately, followed by a complete block.
13This synchronous version is lighter weight and often all you need - upgrade to AsyncRateLimiter when you need promises, retry support, abort capabilities, or advanced error handling.
14​
15The rate limiter supports two types of windows:
16- 'fixed': A strict window that resets after the window period. All executions within the window count
17 towards the limit, and the window resets completely after the period.
18- 'sliding': A rolling window that allows executions as old ones expire. This provides a more
19 consistent rate of execution over time.
20​
21For smoother execution patterns, consider using:
22- Throttling: Ensures consistent spacing between executions (e.g. max once per 200ms)
23- Debouncing: Waits for a pause in calls before executing (e.g. after 500ms of no calls)
24​
25Rate limiting is best used for hard API limits or resource constraints. For UI updates or
26smoothing out frequent events, throttling or debouncing usually provide better user experience.
27​
28State Management:
29- Uses TanStack Store for reactive state management
30- Use `initialState` to provide initial state values when creating the rate limiter
31- Use `onExecute` callback to react to function execution and implement custom logic
32- Use `onReject` callback to react to executions being rejected when rate limit is exceeded
33- The state includes execution count, execution times, and rejection count
34- State can be accessed via `rateLimiter.store.state` when using the class directly
35- When using framework adapters (React/Solid), state is accessed from `rateLimiter.state`
36​
37## Example
38​
39```ts
40const rateLimiter = new RateLimiter(
41 (id: string) => api.getData(id),
42 {
43 limit: 5,
44 window: 1000,
45 windowType: 'sliding',
46 }
47);
48​
49// Will execute immediately until limit reached, then block
50rateLimiter.maybeExecute('123');
51```
52​
53## Type Parameters
54​
55### TFn
56​
57`TFn` *extends* [`AnyFunction`](../type-aliases/AnyFunction.md)
58​
59## Constructors
60​
61### Constructor
62​
63```ts
64new RateLimiter<TFn>(fn, initialOptions): RateLimiter<TFn>;
65```
66​
67Defined in: [rate-limiter.ts:163](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L163)
68​
69#### Parameters
70​
71##### fn
72​
73`TFn`
74​
75##### initialOptions
76​
77[`RateLimiterOptions`](../interfaces/RateLimiterOptions.md)\<`TFn`\>
78​
79#### Returns
80​
81`RateLimiter`\<`TFn`\>
82​
83## Properties
84​
85### fn
86​
87```ts
88fn: TFn;
89```
90​
91Defined in: [rate-limiter.ts:164](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L164)
92​
93***
94​
95### key
96​
97```ts
98key: string | undefined;
99```
100​
101Defined in: [rate-limiter.ts:159](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L159)
102​
103***
104​
105### options
106​
107```ts
108options: RateLimiterOptions<TFn>;
109```
110​
111Defined in: [rate-limiter.ts:160](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L160)
112​
113***
114​
115### store
116​
117```ts
118readonly store: Store<Readonly<RateLimiterState>>;
119```
120​
121Defined in: [rate-limiter.ts:157](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L157)
122​
123## Methods
124​
125### getMsUntilNextWindow()
126​
127```ts
128getMsUntilNextWindow(): number;
129```
130​
131Defined in: [rate-limiter.ts:358](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L358)
132​
133Returns the number of milliseconds until the next execution will be possible
134​
135#### Returns
136​
137`number`
138​
139***
140​
141### getRemainingInWindow()
142​
143```ts
144getRemainingInWindow(): number;
145```
146​
147Defined in: [rate-limiter.ts:350](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L350)
148​
149Returns the number of remaining executions allowed in the current window
150​
151#### Returns
152​
153`number`
154​
155***
156​
157### maybeExecute()
158​
159```ts
160maybeExecute(...args): boolean;
161```
162​
163Defined in: [rate-limiter.ts:252](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L252)
164​
165Attempts to execute the rate-limited function if within the configured limits.
166Will reject execution if the number of calls in the current window exceeds the limit.
167​
168#### Parameters
169​
170##### args
171​
172...`Parameters`\<`TFn`\>
173​
174#### Returns
175​
176`boolean`
177​
178#### Example
179​
180```ts
181const rateLimiter = new RateLimiter(fn, { limit: 5, window: 1000 });
182​
183// First 5 calls will return true
184rateLimiter.maybeExecute('arg1', 'arg2'); // true
185​
186// Additional calls within the window will return false
187rateLimiter.maybeExecute('arg1', 'arg2'); // false
188```
189​
190***
191​
192### reset()
193​
194```ts
195reset(): void;
196```
197​
198Defined in: [rate-limiter.ts:369](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L369)
199​
200Resets the rate limiter state
201​
202#### Returns
203​
204`void`
205​
206***
207​
208### setOptions()
209​
210```ts
211setOptions(newOptions): void;
212```
213​
214Defined in: [rate-limiter.ts:191](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/rate-limiter.ts#L191)
215​
216Updates the rate limiter options
217​
218#### Parameters
219​
220##### newOptions
221​
222`Partial`\<[`RateLimiterOptions`](../interfaces/RateLimiterOptions.md)\<`TFn`\>\>
223​
224#### Returns
225​
226`void`