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

Debouncer.md

201 lines4.0 KB

1---
2id: Debouncer
3title: Debouncer
4---
5​
6Defined in: [debouncer.ts:142](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L142)
7​
8A class that creates a debounced function.
9​
10Debouncing ensures that a function is only executed after a certain amount of time has passed
11since its last invocation. This is useful for handling frequent events like window resizing,
12scroll events, or input changes where you want to limit the rate of execution.
13This synchronous version is lighter weight and often all you need - upgrade to AsyncDebouncer when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
14​
15The debounced function can be configured to execute either at the start of the delay period
16(leading edge) or at the end (trailing edge, default). Each new call during the wait period
17will reset the timer.
18​
19State Management:
20- Uses TanStack Store for reactive state management
21- Use `initialState` to provide initial state values when creating the debouncer
22- Use `onExecute` callback to react to function execution and implement custom logic
23- The state includes canLeadingExecute, execution count, and isPending status
24- State can be accessed via `debouncer.store.state` when using the class directly
25- When using framework adapters (React/Solid), state is accessed from `debouncer.state`
26​
27## Example
28​
29```ts
30const debouncer = new Debouncer((value: string) => {
31 saveToDatabase(value);
32}, { wait: 500 });
33​
34// Will only save after 500ms of no new input
35inputElement.addEventListener('input', () => {
36 debouncer.maybeExecute(inputElement.value);
37});
38```
39​
40## Type Parameters
41​
42### TFn
43​
44`TFn` *extends* [`AnyFunction`](../type-aliases/AnyFunction.md)
45​
46## Constructors
47​
48### Constructor
49​
50```ts
51new Debouncer<TFn>(fn, initialOptions): Debouncer<TFn>;
52```
53​
54Defined in: [debouncer.ts:150](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L150)
55​
56#### Parameters
57​
58##### fn
59​
60`TFn`
61​
62##### initialOptions
63​
64[`DebouncerOptions`](../interfaces/DebouncerOptions.md)\<`TFn`\>
65​
66#### Returns
67​
68`Debouncer`\<`TFn`\>
69​
70## Properties
71​
72### fn
73​
74```ts
75fn: TFn;
76```
77​
78Defined in: [debouncer.ts:151](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L151)
79​
80***
81​
82### key
83​
84```ts
85key: string | undefined;
86```
87​
88Defined in: [debouncer.ts:146](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L146)
89​
90***
91​
92### options
93​
94```ts
95options: DebouncerOptions<TFn>;
96```
97​
98Defined in: [debouncer.ts:147](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L147)
99​
100***
101​
102### store
103​
104```ts
105readonly store: Store<Readonly<DebouncerState<TFn>>>;
106```
107​
108Defined in: [debouncer.ts:143](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L143)
109​
110## Methods
111​
112### cancel()
113​
114```ts
115cancel(): void;
116```
117​
118Defined in: [debouncer.ts:285](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L285)
119​
120Cancels any pending execution
121​
122#### Returns
123​
124`void`
125​
126***
127​
128### flush()
129​
130```ts
131flush(): void;
132```
133​
134Defined in: [debouncer.ts:268](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L268)
135​
136Processes the current pending execution immediately
137​
138#### Returns
139​
140`void`
141​
142***
143​
144### maybeExecute()
145​
146```ts
147maybeExecute(...args): void;
148```
149​
150Defined in: [debouncer.ts:221](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L221)
151​
152Attempts to execute the debounced function
153If a call is already in progress, it will be queued
154​
155#### Parameters
156​
157##### args
158​
159...`Parameters`\<`TFn`\>
160​
161#### Returns
162​
163`void`
164​
165***
166​
167### reset()
168​
169```ts
170reset(): void;
171```
172​
173Defined in: [debouncer.ts:296](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L296)
174​
175Resets the debouncer state to its default values
176​
177#### Returns
178​
179`void`
180​
181***
182​
183### setOptions()
184​
185```ts
186setOptions(newOptions): void;
187```
188​
189Defined in: [debouncer.ts:175](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/debouncer.ts#L175)
190​
191Updates the debouncer options
192​
193#### Parameters
194​
195##### newOptions
196​
197`Partial`\<[`DebouncerOptions`](../interfaces/DebouncerOptions.md)\<`TFn`\>\>
198​
199#### Returns
200​
201`void`