Open History to see the last commit
1---
2id: Throttler
3title: Throttler
4---
5
6Defined in: [throttler.ts:150](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L150)
7
8A class that creates a throttled function.
9
10Throttling ensures a function is called at most once within a specified time window.
11Unlike debouncing which waits for a pause in calls, throttling guarantees consistent
12execution timing regardless of call frequency.
13This synchronous version is lighter weight and often all you need - upgrade to AsyncThrottler when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
14
15Supports both leading and trailing edge execution:
16- Leading: Execute immediately on first call (default: true)
17- Trailing: Execute after wait period if called during throttle (default: true)
18
19For collapsing rapid-fire events where you only care about the last call, consider using Debouncer.
20
21State Management:
22- Uses TanStack Store for reactive state management
23- Use `initialState` to provide initial state values when creating the throttler
24- Use `onExecute` callback to react to function execution and implement custom logic
25- The state includes execution count, last execution time, pending status, and more
26- State can be accessed via `throttler.store.state` when using the class directly
27- When using framework adapters (React/Solid), state is accessed from `throttler.state`
28
29## Example
30
31```ts
32const throttler = new Throttler(
33 (id: string) => api.getData(id),
34 { wait: 1000 } // Execute at most once per second
35);
36
37// First call executes immediately
38throttler.maybeExecute('123');
39
40// Subsequent calls within 1000ms are throttled
41throttler.maybeExecute('123'); // Throttled
42```
43
44## Type Parameters
45
46### TFn
47
48`TFn` *extends* [`AnyFunction`](../type-aliases/AnyFunction.md)
49
50## Constructors
51
52### Constructor
53
54```ts
55new Throttler<TFn>(fn, initialOptions): Throttler<TFn>;
56```
57
58Defined in: [throttler.ts:158](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L158)
59
60#### Parameters
61
62##### fn
63
64`TFn`
65
66##### initialOptions
67
68[`ThrottlerOptions`](../interfaces/ThrottlerOptions.md)\<`TFn`\>
69
70#### Returns
71
72`Throttler`\<`TFn`\>
73
74## Properties
75
76### fn
77
78```ts
79fn: TFn;
80```
81
82Defined in: [throttler.ts:159](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L159)
83
84***
85
86### key
87
88```ts
89key: string | undefined;
90```
91
92Defined in: [throttler.ts:154](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L154)
93
94***
95
96### options
97
98```ts
99options: ThrottlerOptions<TFn>;
100```
101
102Defined in: [throttler.ts:155](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L155)
103
104***
105
106### store
107
108```ts
109readonly store: Store<Readonly<ThrottlerState<TFn>>>;
110```
111
112Defined in: [throttler.ts:151](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L151)
113
114## Methods
115
116### cancel()
117
118```ts
119cancel(): void;
120```
121
122Defined in: [throttler.ts:322](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L322)
123
124Cancels any pending trailing execution and clears internal state.
125
126If a trailing execution is scheduled (due to throttling with trailing=true),
127this will prevent that execution from occurring. The internal timeout and
128stored arguments will be cleared.
129
130Has no effect if there is no pending execution.
131
132#### Returns
133
134`void`
135
136***
137
138### flush()
139
140```ts
141flush(): void;
142```
143
144Defined in: [throttler.ts:300](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L300)
145
146Processes the current pending execution immediately
147
148#### Returns
149
150`void`
151
152***
153
154### maybeExecute()
155
156```ts
157maybeExecute(...args): void;
158```
159
160Defined in: [throttler.ts:241](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L241)
161
162Attempts to execute the throttled function. The execution behavior depends on the throttler options:
163
164- If enough time has passed since the last execution (>= wait period):
165 - With leading=true: Executes immediately
166 - With leading=false: Waits for the next trailing execution
167
168- If within the wait period:
169 - With trailing=true: Schedules execution for end of wait period
170 - With trailing=false: Drops the execution
171
172#### Parameters
173
174##### args
175
176...`Parameters`\<`TFn`\>
177
178#### Returns
179
180`void`
181
182#### Example
183
184```ts
185const throttled = new Throttler(fn, { wait: 1000 });
186
187// First call executes immediately
188throttled.maybeExecute('a', 'b');
189
190// Call during wait period - gets throttled
191throttled.maybeExecute('c', 'd');
192```
193
194***
195
196### reset()
197
198```ts
199reset(): void;
200```
201
202Defined in: [throttler.ts:333](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L333)
203
204Resets the throttler state to its default values
205
206#### Returns
207
208`void`
209
210***
211
212### setOptions()
213
214```ts
215setOptions(newOptions): void;
216```
217
218Defined in: [throttler.ts:183](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L183)
219
220Updates the throttler options
221
222#### Parameters
223
224##### newOptions
225
226`Partial`\<[`ThrottlerOptions`](../interfaces/ThrottlerOptions.md)\<`TFn`\>\>
227
228#### Returns
229
230`void`