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

TimeoutManager.md

272 lines6.1 KB

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