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

TimeoutManager.md

276 lines6.2 KB

1---
2id: TimeoutManager
3title: TimeoutManager
4redirect_from:
5 - reference/timeoutManager
6---
7​
8<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
9​
10Defined in: [packages/query-core/src/timeoutManager.ts:82](https://github.com/TanStack/query/blob/main/packages/query-core/src/timeoutManager.ts#L82)
11​
12Allows customization of how timeouts are created.
13​
14`@tanstack/query-core` makes liberal use of timeouts to implement `staleTime`
15and `gcTime`. The default TimeoutManager provider uses the platform's global
16`setTimeout` implementation, which is known to have scalability issues with
17thousands of timeouts on the event loop.
18​
19If you hit this limitation, consider providing a custom TimeoutProvider that
20coalesces timeouts.
21​
22## Implements
23​
24- `Omit`\<[`TimeoutProvider`](../type-aliases/TimeoutProvider.md), `"name"`\>
25​
26## Methods
27​
28### clearInterval()
29​
30```ts
31clearInterval(intervalId: ManagedTimerId | undefined): void;
32```
33​
34Defined in: [packages/query-core/src/timeoutManager.ts:240](https://github.com/TanStack/query/blob/main/packages/query-core/src/timeoutManager.ts#L240)
35​
36`clearInterval` can be used to cancel an interval, like the global
37`clearInterval` function. It should be called with an interval ID
38returned by `setInterval`.
39​
40#### Parameters
41​
42##### intervalId
43​
44[`ManagedTimerId`](../type-aliases/ManagedTimerId.md) \| `undefined`
45​
46The timer ID returned by `setInterval`, or `undefined`.
47​
48#### Returns
49​
50`void`
51​
52#### Example
53​
54```ts
55import { timeoutManager } from '@tanstack/query-core'
56​
57const intervalId = timeoutManager.setInterval(
58 () => console.log('ran at:', new Date()),
59 1000,
61​
62timeoutManager.clearInterval(intervalId)
63```
64​
65#### Implementation of
66​
67```ts
68Omit.clearInterval
69```
70​
71***
72​
73### clearTimeout()
74​
75```ts
76clearTimeout(timeoutId: ManagedTimerId | undefined): void;
77```
78​
79Defined in: [packages/query-core/src/timeoutManager.ts:193](https://github.com/TanStack/query/blob/main/packages/query-core/src/timeoutManager.ts#L193)
80​
81`clearTimeout` cancels a timeout callback scheduled with `setTimeout`,
82like the global `clearTimeout` function. It should be called with a
83timer ID returned by `setTimeout`.
84​
85#### Parameters
86​
87##### timeoutId
88​
89[`ManagedTimerId`](../type-aliases/ManagedTimerId.md) \| `undefined`
90​
91The timer ID returned by `setTimeout`, or `undefined`.
92​
93#### Returns
94​
95`void`
96​
97#### Example
98​
99```ts
100import { timeoutManager } from '@tanstack/query-core'
101​
102const timeoutId = timeoutManager.setTimeout(
103 () => console.log('ran at:', new Date()),
104 1000,
106​
107timeoutManager.clearTimeout(timeoutId)
108```
109​
110#### Implementation of
111​
112```ts
113Omit.clearTimeout
114```
115​
116***
117​
118### setInterval()
119​
120```ts
121setInterval(callback: TimeoutCallback, delay: number): ManagedTimerId;
122```
123​
124Defined in: [packages/query-core/src/timeoutManager.ts:216](https://github.com/TanStack/query/blob/main/packages/query-core/src/timeoutManager.ts#L216)
125​
126`setInterval` schedules a callback to be called approximately every
127`delay` milliseconds, like the global `setInterval` function.
128​
129Like `setTimeout`, it returns a timer ID, which may be a number or an
130object that can be coerced to a number via `Symbol.toPrimitive`.
131​
132#### Parameters
133​
134##### callback
135​
136[`TimeoutCallback`](../type-aliases/TimeoutCallback.md)
137​
138The function to call on every interval.
139​
140##### delay
141​
142`number`
143​
144The time between calls, in milliseconds.
145​
146#### Returns
147​
148[`ManagedTimerId`](../type-aliases/ManagedTimerId.md)
149​
150The timer ID, to pass to [TimeoutManager#clearInterval](#clearinterval).
151​
152#### Example
153​
154```ts
155import { timeoutManager } from '@tanstack/query-core'
156​
157const intervalId = timeoutManager.setInterval(
158 () => console.log('ran at:', new Date()),
159 1000,
161```
162​
163#### Implementation of
164​
165```ts
166Omit.setInterval
167```
168​
169***
170​
171### setTimeout()
172​
173```ts
174setTimeout(callback: TimeoutCallback, delay: number): ManagedTimerId;
175```
176​
177Defined in: [packages/query-core/src/timeoutManager.ts:169](https://github.com/TanStack/query/blob/main/packages/query-core/src/timeoutManager.ts#L169)
178​
179`setTimeout` schedules a callback to run after approximately `delay`
180milliseconds, like the global `setTimeout` function. The callback can be
181canceled with `clearTimeout`.
182​
183It returns a timer ID, which may be a number or an object that can be
184coerced to a number via `Symbol.toPrimitive`.
185​
186#### Parameters
187​
188##### callback
189​
190[`TimeoutCallback`](../type-aliases/TimeoutCallback.md)
191​
192The function to call when the timeout elapses.
193​
194##### delay
195​
196`number`
197​
198The time to wait before calling `callback`, in milliseconds.
199​
200#### Returns
201​
202[`ManagedTimerId`](../type-aliases/ManagedTimerId.md)
203​
204The timer ID, to pass to [TimeoutManager#clearTimeout](#cleartimeout).
205​
206#### Example
207​
208```ts
209import { timeoutManager } from '@tanstack/query-core'
210​
211const timeoutId = timeoutManager.setTimeout(
212 () => console.log('ran at:', new Date()),
213 1000,
215​
216const timeoutIdNumber: number = Number(timeoutId)
217```
218​
219#### Implementation of
220​
221```ts
222Omit.setTimeout
223```
224​
225***
226​
227### setTimeoutProvider()
228​
229```ts
230setTimeoutProvider<TTimerId extends ManagedTimerId>(provider: TimeoutProvider<TTimerId>): void;
231```
232​
233Defined in: [packages/query-core/src/timeoutManager.ts:118](https://github.com/TanStack/query/blob/main/packages/query-core/src/timeoutManager.ts#L118)
234​
235`setTimeoutProvider` can be used to set a custom implementation of the
236`setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` functions,
237called a `TimeoutProvider`.
238​
239This may be useful if you notice event loop performance issues with
240thousands of queries. A custom TimeoutProvider could also support timer
241delays longer than the global `setTimeout` maximum delay value of about
24224 days.
243​
244It is important to call `setTimeoutProvider` before creating a
245QueryClient or queries, so that the same provider is used consistently
246for all timers in the application, since different TimeoutProviders
247cannot cancel each others' timers.
248​
249#### Type Parameters
250​
251##### TTimerId
252​
253`TTimerId` *extends* [`ManagedTimerId`](../type-aliases/ManagedTimerId.md)
254​
255#### Parameters
256​
257##### provider
258​
259[`TimeoutProvider`](../type-aliases/TimeoutProvider.md)\<`TTimerId`\>
260​
261The `TimeoutProvider` to use for all timers from now on.
262​
263#### Returns
264​
265`void`
266​
267#### Example
268​
269```ts
270import { timeoutManager, QueryClient } from '@tanstack/query-core'
271import { CustomTimeoutProvider } from './CustomTimeoutProvider'
272​
273timeoutManager.setTimeoutProvider(new CustomTimeoutProvider())
274​
275export const queryClient = new QueryClient()
276```