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

useQueries.ts

353 lines11.8 KB

1'use client'
2import * as React from 'react'
3​
4import {
5 QueriesObserver,
6 QueryObserver,
7 notifyManager,
8} from '@tanstack/query-core'
9import { useQueryClient } from './QueryClientProvider'
10import { useIsRestoring } from './isRestoring'
11import { useQueryErrorResetBoundary } from './QueryErrorResetBoundary'
12import {
13 ensurePreventErrorBoundaryRetry,
14 getHasError,
15 useClearResetErrorBoundary,
16} from './errorBoundaryUtils'
17import {
18 ensureSuspenseTimers,
19 fetchOptimistic,
20 shouldSuspend,
21 willFetch,
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'
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 : T extends Array<
206 UseQueryOptionsForUseQueries<
207 infer TQueryFnData,
208 infer TError,
209 infer TData,
210 any
211 >
212 >
213 ? // Dynamic-size (homogenous) UseQueryOptions array: map directly to array of results
214 Array<
215 UseQueryResult<
216 unknown extends TData ? TQueryFnData : TData,
217 unknown extends TError ? DefaultError : TError
218 >
219 >
220 : // Fallback
221 Array<UseQueryResult>
222​
223export function useQueries<
224 T extends Array<any>,
225 TCombinedResult = QueriesResults<T>,
226>(
227 {
228 queries,
229 ...options
230 }: {
231 queries: readonly [...QueriesOptions<T>]
232 combine?: (result: QueriesResults<T>) => TCombinedResult
233 },
234 queryClient?: QueryClient,
235): TCombinedResult {
236 const client = useQueryClient(queryClient)
237 const isRestoring = useIsRestoring()
238 const errorResetBoundary = useQueryErrorResetBoundary()
239​
240 const defaultedQueries = React.useMemo(
241 () =>
242 queries.map((opts) => {
243 const defaultedOptions = client.defaultQueryOptions(
244 opts as QueryObserverOptions,
245 )
246​
247 // Make sure the results are already in fetching state before subscribing or updating options
248 defaultedOptions._optimisticResults = isRestoring
249 ? 'isRestoring'
250 : 'optimistic'
251​
252 return defaultedOptions
253 }),
254 [queries, client, isRestoring],
255 )
256​
257 defaultedQueries.forEach((query) => {
258 ensureSuspenseTimers(query)
259 ensurePreventErrorBoundaryRetry(query, errorResetBoundary)
260 })
261​
262 useClearResetErrorBoundary(errorResetBoundary)
263​
264 const [observer] = React.useState(
265 () =>
266 new QueriesObserver<TCombinedResult>(
267 client,
268 defaultedQueries,
269 options as QueriesObserverOptions<TCombinedResult>,
270 ),
271 )
272​
273 const [optimisticResult, getCombinedResult, trackResult] =
274 observer.getOptimisticResult(
275 defaultedQueries,
276 (options as QueriesObserverOptions<TCombinedResult>).combine,
277 )
278​
279 React.useSyncExternalStore(
280 React.useCallback(
281 (onStoreChange) =>
282 isRestoring
283 ? () => undefined
284 : observer.subscribe(notifyManager.batchCalls(onStoreChange)),
285 [observer, isRestoring],
286 ),
287 () => observer.getCurrentResult(),
288 () => observer.getCurrentResult(),
289 )
290​
291 React.useEffect(() => {
292 // Do not notify on updates because of changes in the options because
293 // these changes should already be reflected in the optimistic result.
294 observer.setQueries(
295 defaultedQueries,
296 options as QueriesObserverOptions<TCombinedResult>,
297 {
298 listeners: false,
299 },
300 )
301 }, [defaultedQueries, options, observer])
302​
303 const shouldAtLeastOneSuspend = optimisticResult.some((result, index) =>
304 shouldSuspend(defaultedQueries[index], result),
305 )
306​
307 const suspensePromises = shouldAtLeastOneSuspend
308 ? optimisticResult.flatMap((result, index) => {
309 const opts = defaultedQueries[index]
310​
311 if (opts) {
312 const queryObserver = new QueryObserver(client, opts)
313 if (shouldSuspend(opts, result)) {
314 return fetchOptimistic(opts, queryObserver, errorResetBoundary)
315 } else if (willFetch(result, isRestoring)) {
316 void fetchOptimistic(opts, queryObserver, errorResetBoundary)
317 }
318 }
319 return []
320 })
321 : []
322​
323 if (suspensePromises.length > 0) {
324 observer.setQueries(
325 defaultedQueries,
326 options as QueriesObserverOptions<TCombinedResult>,
327 {
328 listeners: false,
329 },
330 )
331 throw Promise.all(suspensePromises)
332 }
333 const firstSingleResultWhichShouldThrow = optimisticResult.find(
334 (result, index) => {
335 const query = defaultedQueries[index]
336 return (
337 query &&
338 getHasError({
339 result,
340 errorResetBoundary,
341 throwOnError: query.throwOnError,
342 query: client.getQueryCache().get(query.queryHash),
343 })
344 )
345 },
346 )
347​
348 if (firstSingleResultWhichShouldThrow?.error) {
349 throw firstSingleResultWhichShouldThrow.error
350 }
351​
352 return getCombinedResult(trackResult())