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

TimeoutManager.md

274 lines6.1 KB

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