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

useQueries.ts

328 lines11.2 KB

1'use client'
2import * as React from 'react'
3​
4import {
5 QueriesObserver,
6 QueryObserver,
7 noop,
8 notifyManager,
9} from '@tanstack/query-core'
10import { useQueryClient } from './QueryClientProvider'
11import { useIsRestoring } from './IsRestoringProvider'
12import { useQueryErrorResetBoundary } from './QueryErrorResetBoundary'
13import {
14 ensurePreventErrorBoundaryRetry,
15 getHasError,
16 useClearResetErrorBoundary,
17} from './errorBoundaryUtils'
18import {
19 ensureSuspenseTimers,
20 fetchOptimistic,
21 shouldSuspend,
22} from './suspense'
23import type {
24 DefinedUseQueryResult,
25 UseQueryOptions,
26 UseQueryResult,
27} from './types'
28import type {
29 DefaultError,
30 OmitKeyof,
31 QueriesObserverOptions,
32 QueriesPlaceholderDataFunction,
33 QueryClient,
34 QueryFunction,
35 QueryKey,
36 QueryObserverOptions,
37 ThrowOnError,
38} from '@tanstack/query-core'
39​
40// This defines the `UseQueryOptions` that are accepted in `QueriesOptions` & `GetOptions`.
41// `placeholderData` function always gets undefined passed
42type UseQueryOptionsForUseQueries<
43 TQueryFnData = unknown,
44 TError = DefaultError,
45 TData = TQueryFnData,
46 TQueryKey extends QueryKey = QueryKey,
47> = OmitKeyof<
48 UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
49 'placeholderData' | 'subscribed'
50> & {
51 placeholderData?: TQueryFnData | QueriesPlaceholderDataFunction<TQueryFnData>
53​
54// Avoid TS depth-limit error in case of large array literal
55type MAXIMUM_DEPTH = 20
56​
57// Widen the type of the symbol to enable type inference even if skipToken is not immutable.
58type SkipTokenForUseQueries = symbol
59​
60type GetUseQueryOptionsForUseQueries<T> =
61 // Part 1: responsible for applying explicit type parameter to function arguments, if object { queryFnData: TQueryFnData, error: TError, data: TData }
62 T extends {
63 queryFnData: infer TQueryFnData
64 error?: infer TError
65 data: infer TData
66 }
67 ? UseQueryOptionsForUseQueries<TQueryFnData, TError, TData>
68 : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
69 ? UseQueryOptionsForUseQueries<TQueryFnData, TError>
70 : T extends { data: infer TData; error?: infer TError }
71 ? UseQueryOptionsForUseQueries<unknown, TError, TData>
72 : // Part 2: responsible for applying explicit type parameter to function arguments, if tuple [TQueryFnData, TError, TData]
73 T extends [infer TQueryFnData, infer TError, infer TData]
74 ? UseQueryOptionsForUseQueries<TQueryFnData, TError, TData>
75 : T extends [infer TQueryFnData, infer TError]
76 ? UseQueryOptionsForUseQueries<TQueryFnData, TError>
77 : T extends [infer TQueryFnData]
78 ? UseQueryOptionsForUseQueries<TQueryFnData>
79 : // Part 3: responsible for inferring and enforcing type if no explicit parameter was provided
80 T extends {
81 queryFn?:
82 | QueryFunction<infer TQueryFnData, infer TQueryKey>
83 | SkipTokenForUseQueries
84 select?: (data: any) => infer TData
85 throwOnError?: ThrowOnError<any, infer TError, any, any>
86 }
87 ? UseQueryOptionsForUseQueries<
88 TQueryFnData,
89 unknown extends TError ? DefaultError : TError,
90 unknown extends TData ? TQueryFnData : TData,
91 TQueryKey
92 >
93 : // Fallback
94 UseQueryOptionsForUseQueries
95​
96// A defined initialData setting should return a DefinedUseQueryResult rather than UseQueryResult
97type GetDefinedOrUndefinedQueryResult<T, TData, TError = unknown> = T extends {
98 initialData?: infer TInitialData
100 ? unknown extends TInitialData
101 ? UseQueryResult<TData, TError>
102 : TInitialData extends TData
103 ? DefinedUseQueryResult<TData, TError>
104 : TInitialData extends () => infer TInitialDataResult
105 ? unknown extends TInitialDataResult
106 ? UseQueryResult<TData, TError>
107 : TInitialDataResult extends TData
108 ? DefinedUseQueryResult<TData, TError>
109 : UseQueryResult<TData, TError>
110 : UseQueryResult<TData, TError>
111 : UseQueryResult<TData, TError>
112​
113type GetUseQueryResult<T> =
114 // Part 1: responsible for mapping explicit type parameter to function result, if object
115 T extends { queryFnData: any; error?: infer TError; data: infer TData }
116 ? GetDefinedOrUndefinedQueryResult<T, TData, TError>
117 : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
118 ? GetDefinedOrUndefinedQueryResult<T, TQueryFnData, TError>
119 : T extends { data: infer TData; error?: infer TError }
120 ? GetDefinedOrUndefinedQueryResult<T, TData, TError>
121 : // Part 2: responsible for mapping explicit type parameter to function result, if tuple
122 T extends [any, infer TError, infer TData]
123 ? GetDefinedOrUndefinedQueryResult<T, TData, TError>
124 : T extends [infer TQueryFnData, infer TError]
125 ? GetDefinedOrUndefinedQueryResult<T, TQueryFnData, TError>
126 : T extends [infer TQueryFnData]
127 ? GetDefinedOrUndefinedQueryResult<T, TQueryFnData>
128 : // Part 3: responsible for mapping inferred type to results, if no explicit parameter was provided
129 T extends {
130 queryFn?:
131 | QueryFunction<infer TQueryFnData, any>
132 | SkipTokenForUseQueries
133 select?: (data: any) => infer TData
134 throwOnError?: ThrowOnError<any, infer TError, any, any>
135 }
136 ? GetDefinedOrUndefinedQueryResult<
137 T,
138 unknown extends TData ? TQueryFnData : TData,
139 unknown extends TError ? DefaultError : TError
140 >
141 : // Fallback
142 UseQueryResult
143​
144/**
145 * QueriesOptions reducer recursively unwraps function arguments to infer/enforce type param
146 */
147export type QueriesOptions<
148 T extends Array<any>,
149 TResults extends Array<any> = [],
150 TDepth extends ReadonlyArray<number> = [],
151> = TDepth['length'] extends MAXIMUM_DEPTH
152 ? Array<UseQueryOptionsForUseQueries>
153 : T extends []
154 ? []
155 : T extends [infer Head]
156 ? [...TResults, GetUseQueryOptionsForUseQueries<Head>]
157 : T extends [infer Head, ...infer Tails]
158 ? QueriesOptions<
159 [...Tails],
160 [...TResults, GetUseQueryOptionsForUseQueries<Head>],
161 [...TDepth, 1]
162 >
163 : ReadonlyArray<unknown> extends T
164 ? T
165 : // If T is *some* array but we couldn't assign unknown[] to it, then it must hold some known/homogenous type!
166 // use this to infer the param types in the case of Array.map() argument
167 T extends Array<
168 UseQueryOptionsForUseQueries<
169 infer TQueryFnData,
170 infer TError,
171 infer TData,
172 infer TQueryKey
173 >
174 >
175 ? Array<
176 UseQueryOptionsForUseQueries<
177 TQueryFnData,
178 TError,
179 TData,
180 TQueryKey
181 >
182 >
183 : // Fallback
184 Array<UseQueryOptionsForUseQueries>
185​
186/**
187 * QueriesResults reducer recursively maps type param to results
188 */
189export type QueriesResults<
190 T extends Array<any>,
191 TResults extends Array<any> = [],
192 TDepth extends ReadonlyArray<number> = [],
193> = TDepth['length'] extends MAXIMUM_DEPTH
194 ? Array<UseQueryResult>
195 : T extends []
196 ? []
197 : T extends [infer Head]
198 ? [...TResults, GetUseQueryResult<Head>]
199 : T extends [infer Head, ...infer Tails]
200 ? QueriesResults<
201 [...Tails],
202 [...TResults, GetUseQueryResult<Head>],
203 [...TDepth, 1]
204 >
205 : { [K in keyof T]: GetUseQueryResult<T[K]> }
206​
207export function useQueries<
208 T extends Array<any>,
209 TCombinedResult = QueriesResults<T>,
210>(
211 {
212 queries,
213 ...options
214 }: {
215 queries:
216 | readonly [...QueriesOptions<T>]
217 | readonly [...{ [K in keyof T]: GetUseQueryOptionsForUseQueries<T[K]> }]
218 combine?: (result: QueriesResults<T>) => TCombinedResult
219 subscribed?: boolean
220 },
221 queryClient?: QueryClient,
222): TCombinedResult {
223 const client = useQueryClient(queryClient)
224 const isRestoring = useIsRestoring()
225 const errorResetBoundary = useQueryErrorResetBoundary()
226​
227 const defaultedQueries = React.useMemo(
228 () =>
229 queries.map((opts) => {
230 const defaultedOptions = client.defaultQueryOptions(
231 opts as QueryObserverOptions,
232 )
233​
234 // Make sure the results are already in fetching state before subscribing or updating options
235 defaultedOptions._optimisticResults = isRestoring
236 ? 'isRestoring'
237 : 'optimistic'
238​
239 return defaultedOptions
240 }),
241 [queries, client, isRestoring],
242 )
243​
244 defaultedQueries.forEach((queryOptions) => {
245 ensureSuspenseTimers(queryOptions)
246 const query = client.getQueryCache().get(queryOptions.queryHash)
247 ensurePreventErrorBoundaryRetry(queryOptions, errorResetBoundary, query)
248 })
249​
250 useClearResetErrorBoundary(errorResetBoundary)
251​
252 const [observer] = React.useState(
253 () =>
254 new QueriesObserver<TCombinedResult>(
255 client,
256 defaultedQueries,
257 options as QueriesObserverOptions<TCombinedResult>,
258 ),
259 )
260​
261 // note: this must be called before useSyncExternalStore
262 const [optimisticResult, getCombinedResult, trackResult] =
263 observer.getOptimisticResult(
264 defaultedQueries,
265 (options as QueriesObserverOptions<TCombinedResult>).combine,
266 )
267​
268 const shouldSubscribe = !isRestoring && options.subscribed !== false
269 React.useSyncExternalStore(
270 React.useCallback(
271 (onStoreChange) =>
272 shouldSubscribe
273 ? observer.subscribe(notifyManager.batchCalls(onStoreChange))
274 : noop,
275 [observer, shouldSubscribe],
276 ),
277 () => observer.getCurrentResult(),
278 () => observer.getCurrentResult(),
279 )
280​
281 React.useEffect(() => {
282 observer.setQueries(
283 defaultedQueries,
284 options as QueriesObserverOptions<TCombinedResult>,
285 )
286 }, [defaultedQueries, options, observer])
287​
288 const shouldAtLeastOneSuspend = optimisticResult.some((result, index) =>
289 shouldSuspend(defaultedQueries[index], result),
290 )
291​
292 const suspensePromises = shouldAtLeastOneSuspend
293 ? optimisticResult.flatMap((result, index) => {
294 const opts = defaultedQueries[index]
295​
296 if (opts && shouldSuspend(opts, result)) {
297 const queryObserver = new QueryObserver(client, opts)
298 return fetchOptimistic(opts, queryObserver, errorResetBoundary)
299 }
300 return []
301 })
302 : []
303​
304 if (suspensePromises.length > 0) {
305 throw Promise.all(suspensePromises)
306 }
307 const firstSingleResultWhichShouldThrow = optimisticResult.find(
308 (result, index) => {
309 const query = defaultedQueries[index]
310 return (
311 query &&
312 getHasError({
313 result,
314 errorResetBoundary,
315 throwOnError: query.throwOnError,
316 query: client.getQueryCache().get(query.queryHash),
317 suspense: query.suspense,
318 })
319 )
320 },
321 )
322​
323 if (firstSingleResultWhichShouldThrow?.error) {
324 throw firstSingleResultWhichShouldThrow.error
325 }
326​
327 return getCombinedResult(trackResult())