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

throttle.md

100 lines2.7 KB

1---
2id: throttle
3title: throttle
4---
5​
6```ts
7function throttle<TFn>(fn, initialOptions): (...args) => void;
8```
9​
10Defined in: [throttler.ts:374](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L374)
11​
12Creates a throttled function that limits how often the provided function can execute.
13​
14This synchronous version is lighter weight and often all you need - upgrade to asyncThrottle when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
15​
16Throttling ensures a function executes at most once within a specified time window,
17regardless of how many times it is called. This is useful for rate-limiting
18expensive operations or UI updates.
19​
20The throttled function can be configured to execute on the leading and/or trailing
21edge of the throttle window via options.
22​
23For handling bursts of events, consider using debounce() instead. For hard execution
24limits, consider using rateLimit().
25​
26State Management:
27- Uses TanStack Store for reactive state management
28- Use `initialState` to provide initial state values when creating the throttler
29- Use `onExecute` callback to react to function execution and implement custom logic
30- The state includes execution count, last execution time, pending status, and more
31- State can be accessed via the underlying Throttler instance's `store.state` property
32- When using framework adapters (React/Solid), state is accessed from the hook's state property
33​
34## Type Parameters
35​
36### TFn
37​
38`TFn` *extends* [`AnyFunction`](../type-aliases/AnyFunction.md)
39​
40## Parameters
41​
42### fn
43​
44`TFn`
45​
46### initialOptions
47​
48[`ThrottlerOptions`](../interfaces/ThrottlerOptions.md)\<`TFn`\>
49​
50## Returns
51​
52```ts
53(...args): void;
54```
55​
56Attempts to execute the throttled function. The execution behavior depends on the throttler options:
57​
58- If enough time has passed since the last execution (>= wait period):
59 - With leading=true: Executes immediately
60 - With leading=false: Waits for the next trailing execution
61​
62- If within the wait period:
63 - With trailing=true: Schedules execution for end of wait period
64 - With trailing=false: Drops the execution
65​
66### Parameters
67​
68#### args
69​
70...`Parameters`\<`TFn`\>
71​
72### Returns
73​
74`void`
75​
76### Example
77​
78```ts
79const throttled = new Throttler(fn, { wait: 1000 });
80​
81// First call executes immediately
82throttled.maybeExecute('a', 'b');
83​
84// Call during wait period - gets throttled
85throttled.maybeExecute('c', 'd');
86```
87​
88## Example
89​
90```ts
91// Basic throttling - max once per second
92const throttled = throttle(updateUI, { wait: 1000 });
93​
94// Configure leading/trailing execution
95const throttled = throttle(saveData, {
96 wait: 2000,
97 leading: true, // Execute immediately on first call
98 trailing: true // Execute again after delay if called during wait
99});
100```