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

Throttler.md

230 lines4.9 KB

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`