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

useQueries.ts

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