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

queryClient.ts

732 lines18.3 KB

1import {
2 functionalUpdate,
3 hashKey,
4 hashQueryKeyByOptions,
5 noop,
6 partialMatchKey,
7 resolveStaleTime,
8 skipToken,
9} from './utils'
10import { QueryCache } from './queryCache'
11import { MutationCache } from './mutationCache'
12import { focusManager } from './focusManager'
13import { onlineManager } from './onlineManager'
14import { notifyManager } from './notifyManager'
15import { infiniteQueryBehavior } from './infiniteQueryBehavior'
16import type {
17 CancelOptions,
18 DefaultError,
19 DefaultOptions,
20 DefaultedQueryObserverOptions,
21 EnsureInfiniteQueryDataOptions,
22 EnsureQueryDataOptions,
23 FetchInfiniteQueryOptions,
24 FetchQueryOptions,
25 InferDataFromTag,
26 InferErrorFromTag,
27 InfiniteData,
28 InvalidateOptions,
29 InvalidateQueryFilters,
30 MutationKey,
31 MutationObserverOptions,
32 MutationOptions,
33 NoInfer,
34 OmitKeyof,
35 QueryClientConfig,
36 QueryKey,
37 QueryObserverOptions,
38 QueryOptions,
39 RefetchOptions,
40 RefetchQueryFilters,
41 ResetOptions,
42 SetDataOptions,
43} from './types'
44import type { QueryState } from './query'
45import type { MutationFilters, QueryFilters, Updater } from './utils'
46​
47// TYPES
48​
49interface QueryDefaults {
50 queryKey: QueryKey
51 defaultOptions: OmitKeyof<QueryOptions<any, any, any>, 'queryKey'>
53​
54interface MutationDefaults {
55 mutationKey: MutationKey
56 defaultOptions: MutationOptions<any, any, any, any>
58​
59// CLASS
60​
61export class QueryClient {
62 #queryCache: QueryCache
63 #mutationCache: MutationCache
64 #defaultOptions: DefaultOptions
65 #queryDefaults: Map<string, QueryDefaults>
66 #mutationDefaults: Map<string, MutationDefaults>
67 #mountCount: number
68 #unsubscribeFocus?: () => void
69 #unsubscribeOnline?: () => void
70​
71 constructor(config: QueryClientConfig = {}) {
72 this.#queryCache = config.queryCache || new QueryCache()
73 this.#mutationCache = config.mutationCache || new MutationCache()
74 this.#defaultOptions = config.defaultOptions || {}
75 this.#queryDefaults = new Map()
76 this.#mutationDefaults = new Map()
77 this.#mountCount = 0
78 }
79​
80 mount(): void {
81 this.#mountCount++
82 if (this.#mountCount !== 1) return
83​
84 this.#unsubscribeFocus = focusManager.subscribe(async (focused) => {
85 if (focused) {
86 await this.resumePausedMutations()
87 this.#queryCache.onFocus()
88 }
89 })
90 this.#unsubscribeOnline = onlineManager.subscribe(async (online) => {
91 if (online) {
92 await this.resumePausedMutations()
93 this.#queryCache.onOnline()
94 }
95 })
96 }
97​
98 unmount(): void {
99 this.#mountCount--
100 if (this.#mountCount !== 0) return
101​
102 this.#unsubscribeFocus?.()
103 this.#unsubscribeFocus = undefined
104​
105 this.#unsubscribeOnline?.()
106 this.#unsubscribeOnline = undefined
107 }
108​
109 isFetching<
110 TQueryFilters extends QueryFilters<any, any, any, any> = QueryFilters,
111 >(filters?: TQueryFilters): number {
112 return this.#queryCache.findAll({ ...filters, fetchStatus: 'fetching' })
113 .length
114 }
115​
116 isMutating<
117 TMutationFilters extends MutationFilters<any, any> = MutationFilters,
118 >(filters?: TMutationFilters): number {
119 return this.#mutationCache.findAll({ ...filters, status: 'pending' }).length
120 }
121​
122 /**
123 * Imperative (non-reactive) way to retrieve data for a QueryKey.
124 * Should only be used in callbacks or functions where reading the latest data is necessary, e.g. for optimistic updates.
125 *
126 * Hint: Do not use this function inside a component, because it won't receive updates.
127 * Use `useQuery` to create a `QueryObserver` that subscribes to changes.
128 */
129 getQueryData<
130 TQueryFnData = unknown,
131 TTaggedQueryKey extends QueryKey = QueryKey,
132 TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>,
133 >(queryKey: TTaggedQueryKey): TInferredQueryFnData | undefined {
134 const options = this.defaultQueryOptions({ queryKey })
135​
136 return this.#queryCache.get(options.queryHash)?.state.data as
137 | TInferredQueryFnData
138 | undefined
139 }
140​
141 ensureQueryData<
142 TQueryFnData,
143 TError = DefaultError,
144 TData = TQueryFnData,
145 TQueryKey extends QueryKey = QueryKey,
146 >(
147 options: EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>,
148 ): Promise<TData> {
149 const defaultedOptions = this.defaultQueryOptions(options)
150 const query = this.#queryCache.build(this, defaultedOptions)
151 const cachedData = query.state.data
152​
153 if (cachedData === undefined) {
154 return this.fetchQuery(options)
155 }
156​
157 if (
158 options.revalidateIfStale &&
159 query.isStaleByTime(resolveStaleTime(defaultedOptions.staleTime, query))
160 ) {
161 void this.prefetchQuery(defaultedOptions)
162 }
163​
164 return Promise.resolve(cachedData)
165 }
166​
167 getQueriesData<
168 TQueryFnData = unknown,
169 TQueryFilters extends QueryFilters<
170 any,
171 any,
172 any,
173 any
174 > = QueryFilters<TQueryFnData>,
175 TInferredQueryFnData = TQueryFilters extends QueryFilters<
176 infer TData,
177 any,
178 any,
179 any
180 >
181 ? TData
182 : TQueryFnData,
183 >(
184 filters: TQueryFilters,
185 ): Array<[QueryKey, TInferredQueryFnData | undefined]> {
186 return this.#queryCache.findAll(filters).map(({ queryKey, state }) => {
187 const data = state.data as TInferredQueryFnData | undefined
188 return [queryKey, data]
189 })
190 }
191​
192 setQueryData<
193 TQueryFnData = unknown,
194 TTaggedQueryKey extends QueryKey = QueryKey,
195 TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>,
196 >(
197 queryKey: TTaggedQueryKey,
198 updater: Updater<
199 NoInfer<TInferredQueryFnData> | undefined,
200 NoInfer<TInferredQueryFnData> | undefined
201 >,
202 options?: SetDataOptions,
203 ): TInferredQueryFnData | undefined {
204 const defaultedOptions = this.defaultQueryOptions<
205 any,
206 any,
207 unknown,
208 any,
209 QueryKey
210 >({ queryKey })
211​
212 const query = this.#queryCache.get<TInferredQueryFnData>(
213 defaultedOptions.queryHash,
214 )
215 const prevData = query?.state.data
216 const data = functionalUpdate(updater, prevData)
217​
218 if (data === undefined) {
219 return undefined
220 }
221​
222 return this.#queryCache
223 .build(this, defaultedOptions)
224 .setData(data, { ...options, manual: true })
225 }
226​
227 setQueriesData<
228 TQueryFnData,
229 TQueryFilters extends QueryFilters<
230 any,
231 any,
232 any,
233 any
234 > = QueryFilters<TQueryFnData>,
235 TInferredQueryFnData = TQueryFilters extends QueryFilters<
236 infer TData,
237 any,
238 any,
239 any
240 >
241 ? TData
242 : TQueryFnData,
243 >(
244 filters: TQueryFilters,
245 updater: Updater<
246 NoInfer<TInferredQueryFnData> | undefined,
247 NoInfer<TInferredQueryFnData> | undefined
248 >,
249 options?: SetDataOptions,
250 ): Array<[QueryKey, TInferredQueryFnData | undefined]> {
251 return notifyManager.batch(() =>
252 this.#queryCache
253 .findAll(filters)
254 .map(({ queryKey }) => [
255 queryKey,
256 this.setQueryData<TInferredQueryFnData>(queryKey, updater, options),
257 ]),
258 )
259 }
260​
261 getQueryState<
262 TQueryFnData = unknown,
263 TError = DefaultError,
264 TTaggedQueryKey extends QueryKey = QueryKey,
265 TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>,
266 TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>,
267 >(
268 queryKey: TTaggedQueryKey,
269 ): QueryState<TInferredQueryFnData, TInferredError> | undefined {
270 const options = this.defaultQueryOptions({ queryKey })
271 return this.#queryCache.get<TInferredQueryFnData, TInferredError>(
272 options.queryHash,
273 )?.state
274 }
275​
276 removeQueries<
277 TQueryFnData = unknown,
278 TError = DefaultError,
279 TTaggedQueryKey extends QueryKey = QueryKey,
280 TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>,
281 TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>,
282 >(
283 filters?: QueryFilters<
284 TInferredQueryFnData,
285 TInferredError,
286 TInferredQueryFnData,
287 TTaggedQueryKey
288 >,
289 ): void {
290 const queryCache = this.#queryCache
291 notifyManager.batch(() => {
292 queryCache.findAll(filters).forEach((query) => {
293 queryCache.remove(query)
294 })
295 })
296 }
297​
298 resetQueries<
299 TQueryFnData = unknown,
300 TError = DefaultError,
301 TTaggedQueryKey extends QueryKey = QueryKey,
302 TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>,
303 TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>,
304 >(
305 filters?: QueryFilters<
306 TInferredQueryFnData,
307 TInferredError,
308 TInferredQueryFnData,
309 TTaggedQueryKey
310 >,
311 options?: ResetOptions,
312 ): Promise<void> {
313 const queryCache = this.#queryCache
314​
315 return notifyManager.batch(() => {
316 queryCache.findAll(filters).forEach((query) => {
317 query.reset()
318 })
319 return this.refetchQueries(
320 {
321 type: 'active',
322 ...filters,
323 },
324 options,
325 )
326 })
327 }
328​
329 cancelQueries<
330 TQueryFnData = unknown,
331 TError = DefaultError,
332 TTaggedQueryKey extends QueryKey = QueryKey,
333 TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>,
334 TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>,
335 >(
336 filters?: QueryFilters<
337 TInferredQueryFnData,
338 TInferredError,
339 TInferredQueryFnData,
340 TTaggedQueryKey
341 >,
342 cancelOptions: CancelOptions = {},
343 ): Promise<void> {
344 const defaultedCancelOptions = { revert: true, ...cancelOptions }
345​
346 const promises = notifyManager.batch(() =>
347 this.#queryCache
348 .findAll(filters)
349 .map((query) => query.cancel(defaultedCancelOptions)),
350 )
351​
352 return Promise.all(promises).then(noop).catch(noop)
353 }
354​
355 invalidateQueries<
356 TQueryFnData = unknown,
357 TError = DefaultError,
358 TTaggedQueryKey extends QueryKey = QueryKey,
359 TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>,
360 TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>,
361 >(
362 filters?: InvalidateQueryFilters<
363 TInferredQueryFnData,
364 TInferredError,
365 TInferredQueryFnData,
366 TTaggedQueryKey
367 >,
368 options: InvalidateOptions = {},
369 ): Promise<void> {
370 return notifyManager.batch(() => {
371 this.#queryCache.findAll(filters).forEach((query) => {
372 query.invalidate()
373 })
374​
375 if (filters?.refetchType === 'none') {
376 return Promise.resolve()
377 }
378 return this.refetchQueries(
379 {
380 ...filters,
381 type: filters?.refetchType ?? filters?.type ?? 'active',
382 },
383 options,
384 )
385 })
386 }
387​
388 refetchQueries<
389 TQueryFnData = unknown,
390 TError = DefaultError,
391 TTaggedQueryKey extends QueryKey = QueryKey,
392 TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>,
393 TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>,
394 >(
395 filters?: RefetchQueryFilters<
396 TInferredQueryFnData,
397 TInferredError,
398 TInferredQueryFnData,
399 TTaggedQueryKey
400 >,
401 options: RefetchOptions = {},
402 ): Promise<void> {
403 const fetchOptions = {
404 ...options,
405 cancelRefetch: options.cancelRefetch ?? true,
406 }
407 const promises = notifyManager.batch(() =>
408 this.#queryCache
409 .findAll(filters)
410 .filter((query) => !query.isDisabled())
411 .map((query) => {
412 let promise = query.fetch(undefined, fetchOptions)
413 if (!fetchOptions.throwOnError) {
414 promise = promise.catch(noop)
415 }
416 return query.state.fetchStatus === 'paused'
417 ? Promise.resolve()
418 : promise
419 }),
420 )
421​
422 return Promise.all(promises).then(noop)
423 }
424​
425 fetchQuery<
426 TQueryFnData,
427 TError = DefaultError,
428 TData = TQueryFnData,
429 TQueryKey extends QueryKey = QueryKey,
430 TPageParam = never,
431 >(
432 options: FetchQueryOptions<
433 TQueryFnData,
434 TError,
435 TData,
436 TQueryKey,
437 TPageParam
438 >,
439 ): Promise<TData> {
440 const defaultedOptions = this.defaultQueryOptions(options)
441​
442 // https://github.com/tannerlinsley/react-query/issues/652
443 if (defaultedOptions.retry === undefined) {
444 defaultedOptions.retry = false
445 }
446​
447 const query = this.#queryCache.build(this, defaultedOptions)
448​
449 return query.isStaleByTime(
450 resolveStaleTime(defaultedOptions.staleTime, query),
451 )
452 ? query.fetch(defaultedOptions)
453 : Promise.resolve(query.state.data as TData)
454 }
455​
456 prefetchQuery<
457 TQueryFnData = unknown,
458 TError = DefaultError,
459 TData = TQueryFnData,
460 TQueryKey extends QueryKey = QueryKey,
461 >(
462 options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
463 ): Promise<void> {
464 return this.fetchQuery(options).then(noop).catch(noop)
465 }
466​
467 fetchInfiniteQuery<
468 TQueryFnData,
469 TError = DefaultError,
470 TData = TQueryFnData,
471 TQueryKey extends QueryKey = QueryKey,
472 TPageParam = unknown,
473 >(
474 options: FetchInfiniteQueryOptions<
475 TQueryFnData,
476 TError,
477 TData,
478 TQueryKey,
479 TPageParam
480 >,
481 ): Promise<InfiniteData<TData, TPageParam>> {
482 options.behavior = infiniteQueryBehavior<
483 TQueryFnData,
484 TError,
485 TData,
486 TPageParam
487 >(options.pages)
488 return this.fetchQuery(options as any)
489 }
490​
491 prefetchInfiniteQuery<
492 TQueryFnData,
493 TError = DefaultError,
494 TData = TQueryFnData,
495 TQueryKey extends QueryKey = QueryKey,
496 TPageParam = unknown,
497 >(
498 options: FetchInfiniteQueryOptions<
499 TQueryFnData,
500 TError,
501 TData,
502 TQueryKey,
503 TPageParam
504 >,
505 ): Promise<void> {
506 return this.fetchInfiniteQuery(options).then(noop).catch(noop)
507 }
508​
509 ensureInfiniteQueryData<
510 TQueryFnData,
511 TError = DefaultError,
512 TData = TQueryFnData,
513 TQueryKey extends QueryKey = QueryKey,
514 TPageParam = unknown,
515 >(
516 options: EnsureInfiniteQueryDataOptions<
517 TQueryFnData,
518 TError,
519 TData,
520 TQueryKey,
521 TPageParam
522 >,
523 ): Promise<InfiniteData<TData, TPageParam>> {
524 options.behavior = infiniteQueryBehavior<
525 TQueryFnData,
526 TError,
527 TData,
528 TPageParam
529 >(options.pages)
530​
531 return this.ensureQueryData(options as any)
532 }
533​
534 resumePausedMutations(): Promise<unknown> {
535 if (onlineManager.isOnline()) {
536 return this.#mutationCache.resumePausedMutations()
537 }
538 return Promise.resolve()
539 }
540​
541 getQueryCache(): QueryCache {
542 return this.#queryCache
543 }
544​
545 getMutationCache(): MutationCache {
546 return this.#mutationCache
547 }
548​
549 getDefaultOptions(): DefaultOptions {
550 return this.#defaultOptions
551 }
552​
553 setDefaultOptions(options: DefaultOptions): void {
554 this.#defaultOptions = options
555 }
556​
557 setQueryDefaults<
558 TQueryFnData = unknown,
559 TError = DefaultError,
560 TData = TQueryFnData,
561 TQueryData = TQueryFnData,
562 >(
563 queryKey: QueryKey,
564 options: Partial<
565 OmitKeyof<
566 QueryObserverOptions<TQueryFnData, TError, TData, TQueryData>,
567 'queryKey'
568 >
569 >,
570 ): void {
571 this.#queryDefaults.set(hashKey(queryKey), {
572 queryKey,
573 defaultOptions: options,
574 })
575 }
576​
577 getQueryDefaults(
578 queryKey: QueryKey,
579 ): OmitKeyof<QueryObserverOptions<any, any, any, any, any>, 'queryKey'> {
580 const defaults = [...this.#queryDefaults.values()]
581​
582 const result: OmitKeyof<
583 QueryObserverOptions<any, any, any, any, any>,
584 'queryKey'
585 > = {}
586​
587 defaults.forEach((queryDefault) => {
588 if (partialMatchKey(queryKey, queryDefault.queryKey)) {
589 Object.assign(result, queryDefault.defaultOptions)
590 }
591 })
592 return result
593 }
594​
595 setMutationDefaults<
596 TData = unknown,
597 TError = DefaultError,
598 TVariables = void,
599 TContext = unknown,
600 >(
601 mutationKey: MutationKey,
602 options: OmitKeyof<
603 MutationObserverOptions<TData, TError, TVariables, TContext>,
604 'mutationKey'
605 >,
606 ): void {
607 this.#mutationDefaults.set(hashKey(mutationKey), {
608 mutationKey,
609 defaultOptions: options,
610 })
611 }
612​
613 getMutationDefaults(
614 mutationKey: MutationKey,
615 ): OmitKeyof<MutationObserverOptions<any, any, any, any>, 'mutationKey'> {
616 const defaults = [...this.#mutationDefaults.values()]
617​
618 const result: OmitKeyof<
619 MutationObserverOptions<any, any, any, any>,
620 'mutationKey'
621 > = {}
622​
623 defaults.forEach((queryDefault) => {
624 if (partialMatchKey(mutationKey, queryDefault.mutationKey)) {
625 Object.assign(result, queryDefault.defaultOptions)
626 }
627 })
628​
629 return result
630 }
631​
632 defaultQueryOptions<
633 TQueryFnData = unknown,
634 TError = DefaultError,
635 TData = TQueryFnData,
636 TQueryData = TQueryFnData,
637 TQueryKey extends QueryKey = QueryKey,
638 TPageParam = never,
639 >(
640 options:
641 | QueryObserverOptions<
642 TQueryFnData,
643 TError,
644 TData,
645 TQueryData,
646 TQueryKey,
647 TPageParam
648 >
649 | DefaultedQueryObserverOptions<
650 TQueryFnData,
651 TError,
652 TData,
653 TQueryData,
654 TQueryKey
655 >,
656 ): DefaultedQueryObserverOptions<
657 TQueryFnData,
658 TError,
659 TData,
660 TQueryData,
661 TQueryKey
662 > {
663 if (options._defaulted) {
664 return options as DefaultedQueryObserverOptions<
665 TQueryFnData,
666 TError,
667 TData,
668 TQueryData,
669 TQueryKey
670 >
671 }
672​
673 const defaultedOptions = {
674 ...this.#defaultOptions.queries,
675 ...this.getQueryDefaults(options.queryKey),
676 ...options,
677 _defaulted: true,
678 }
679​
680 if (!defaultedOptions.queryHash) {
681 defaultedOptions.queryHash = hashQueryKeyByOptions(
682 defaultedOptions.queryKey,
683 defaultedOptions,
684 )
685 }
686​
687 // dependent default values
688 if (defaultedOptions.refetchOnReconnect === undefined) {
689 defaultedOptions.refetchOnReconnect =
690 defaultedOptions.networkMode !== 'always'
691 }
692 if (defaultedOptions.throwOnError === undefined) {
693 defaultedOptions.throwOnError = !!defaultedOptions.suspense
694 }
695​
696 if (!defaultedOptions.networkMode && defaultedOptions.persister) {
697 defaultedOptions.networkMode = 'offlineFirst'
698 }
699​
700 if (defaultedOptions.queryFn === skipToken) {
701 defaultedOptions.enabled = false
702 }
703​
704 return defaultedOptions as DefaultedQueryObserverOptions<
705 TQueryFnData,
706 TError,
707 TData,
708 TQueryData,
709 TQueryKey
710 >
711 }
712​
713 defaultMutationOptions<T extends MutationOptions<any, any, any, any>>(
714 options?: T,
715 ): T {
716 if (options?._defaulted) {
717 return options
718 }
719 return {
720 ...this.#defaultOptions.mutations,
721 ...(options?.mutationKey &&
722 this.getMutationDefaults(options.mutationKey)),
723 ...options,
724 _defaulted: true,
725 } as T
726 }
727​
728 clear(): void {
729 this.#queryCache.clear()
730 this.#mutationCache.clear()
731 }