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