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