Open History to see the last commit
1import { QueriesObserver, noop } from '@tanstack/query-core'
2import {
3 batch,
4 createComputed,
5 createMemo,
6 createRenderEffect,
7 createResource,
8 mergeProps,
9 on,
10 onCleanup,
11 onMount,
12} from 'solid-js'
13import { createStore, unwrap } from 'solid-js/store'
14import { useQueryClientResolver } from './QueryClientProvider'
15import { useIsRestoring } from './isRestoring'
16import type {
17 DefaultError,
18 OmitKeyof,
19 QueriesObserverOptions,
20 QueriesPlaceholderDataFunction,
21 QueryFunction,
22 QueryKey,
23 QueryObserverOptions,
24 QueryObserverResult,
25 ThrowOnError,
26} from '@tanstack/query-core'
27import type { Accessor } from 'solid-js'
28import type { QueryClient } from './QueryClient'
29import type { QueryOptions, UseQueryResult } from './types'
30β
31// This defines the `UseQueryOptions` that are accepted in `QueriesOptions` & `GetOptions`.
32// `placeholderData` function does not have a parameter
33type UseQueryOptionsForUseQueries<
34 TQueryFnData = unknown,
35 TError = DefaultError,
36 TData = TQueryFnData,
37 TQueryKey extends QueryKey = QueryKey,
38> = OmitKeyof<
39 QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
40 'placeholderData' | 'suspense'
41> & {
42 placeholderData?: TQueryFnData | QueriesPlaceholderDataFunction<TQueryFnData>
43 /**
44 * @deprecated The `suspense` option has been deprecated in v5 and will be removed in the next major version.
45 * The `data` property on useQueries is a plain object and not a SolidJS Resource.
46 * It will not suspend when the data is loading.
47 * Setting `suspense` to `true` will be a no-op.
48 */
49 suspense?: boolean
50}
51β
52// Avoid TS depth-limit error in case of large array literal
53type MAXIMUM_DEPTH = 20
54β
55// Widen the type of the symbol to enable type inference even if skipToken is not immutable.
56type SkipTokenForUseQueries = symbol
57β
58type GetOptions<T> =
59 // Part 1: responsible for applying explicit type parameter to function arguments, if object { queryFnData: TQueryFnData, error: TError, data: TData }
60 T extends {
61 queryFnData: infer TQueryFnData
62 error?: infer TError
63 data: infer TData
64 }
65 ? UseQueryOptionsForUseQueries<TQueryFnData, TError, TData>
66 : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
67 ? UseQueryOptionsForUseQueries<TQueryFnData, TError>
68 : T extends { data: infer TData; error?: infer TError }
69 ? UseQueryOptionsForUseQueries<unknown, TError, TData>
70 : // Part 2: responsible for applying explicit type parameter to function arguments, if tuple [TQueryFnData, TError, TData]
71 T extends [infer TQueryFnData, infer TError, infer TData]
72 ? UseQueryOptionsForUseQueries<TQueryFnData, TError, TData>
73 : T extends [infer TQueryFnData, infer TError]
74 ? UseQueryOptionsForUseQueries<TQueryFnData, TError>
75 : T extends [infer TQueryFnData]
76 ? UseQueryOptionsForUseQueries<TQueryFnData>
77 : // Part 3: responsible for inferring and enforcing type if no explicit parameter was provided
78 T extends {
79 queryFn?:
80 | QueryFunction<infer TQueryFnData, infer TQueryKey>
81 | SkipTokenForUseQueries
82 select?: (data: any) => infer TData
83 throwOnError?: ThrowOnError<any, infer TError, any, any>
84 }
85 ? UseQueryOptionsForUseQueries<
86 TQueryFnData,
87 unknown extends TError ? DefaultError : TError,
88 unknown extends TData ? TQueryFnData : TData,
89 TQueryKey
90 >
91 : // Fallback
92 UseQueryOptionsForUseQueries
93β
94type GetResults<T> =
95 // Part 1: responsible for mapping explicit type parameter to function result, if object
96 T extends { queryFnData: any; error?: infer TError; data: infer TData }
97 ? UseQueryResult<TData, TError>
98 : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
99 ? UseQueryResult<TQueryFnData, TError>
100 : T extends { data: infer TData; error?: infer TError }
101 ? UseQueryResult<TData, TError>
102 : // Part 2: responsible for mapping explicit type parameter to function result, if tuple
103 T extends [any, infer TError, infer TData]
104 ? UseQueryResult<TData, TError>
105 : T extends [infer TQueryFnData, infer TError]
106 ? UseQueryResult<TQueryFnData, TError>
107 : T extends [infer TQueryFnData]
108 ? UseQueryResult<TQueryFnData>
109 : // Part 3: responsible for mapping inferred type to results, if no explicit parameter was provided
110 T extends {
111 queryFn?:
112 | QueryFunction<infer TQueryFnData, any>
113 | SkipTokenForUseQueries
114 select?: (data: any) => infer TData
115 throwOnError?: ThrowOnError<any, infer TError, any, any>
116 }
117 ? UseQueryResult<
118 unknown extends TData ? TQueryFnData : TData,
119 unknown extends TError ? DefaultError : TError
120 >
121 : // Fallback
122 UseQueryResult
123β
124/**
125 * QueriesOptions reducer recursively unwraps function arguments to infer/enforce type param
126 */
127type QueriesOptions<
128 T extends Array<any>,
129 TResult extends Array<any> = [],
130 TDepth extends ReadonlyArray<number> = [],
131> = TDepth['length'] extends MAXIMUM_DEPTH
132 ? Array<UseQueryOptionsForUseQueries>
133 : T extends []
134 ? []
135 : T extends [infer Head]
136 ? [...TResult, GetOptions<Head>]
137 : T extends [infer Head, ...infer Tail]
138 ? QueriesOptions<
139 [...Tail],
140 [...TResult, GetOptions<Head>],
141 [...TDepth, 1]
142 >
143 : ReadonlyArray<unknown> extends T
144 ? T
145 : // If T is *some* array but we couldn't assign unknown[] to it, then it must hold some known/homogeneous type!
146 // use this to infer the param types in the case of Array.map() argument
147 T extends Array<
148 UseQueryOptionsForUseQueries<
149 infer TQueryFnData,
150 infer TError,
151 infer TData,
152 infer TQueryKey
153 >
154 >
155 ? Array<
156 UseQueryOptionsForUseQueries<
157 TQueryFnData,
158 TError,
159 TData,
160 TQueryKey
161 >
162 >
163 : // Fallback
164 Array<UseQueryOptionsForUseQueries>
165β
166/**
167 * QueriesResults reducer recursively maps type param to results
168 */
169type QueriesResults<
170 T extends Array<any>,
171 TResult extends Array<any> = [],
172 TDepth extends ReadonlyArray<number> = [],
173> = TDepth['length'] extends MAXIMUM_DEPTH
174 ? Array<UseQueryResult>
175 : T extends []
176 ? []
177 : T extends [infer Head]
178 ? [...TResult, GetResults<Head>]
179 : T extends [infer Head, ...infer Tail]
180 ? QueriesResults<
181 [...Tail],
182 [...TResult, GetResults<Head>],
183 [...TDepth, 1]
184 >
185 : { [K in keyof T]: GetResults<T[K]> }
186β
187/**
188 * The `useQueries` primitive can be used to fetch a variable number of queries.
189 *
190 * The `queries` key accepts an array with query option objects mostly identical to `useQuery` β see
191 * `placeholderData` below for the one difference. A custom `QueryClient` is supplied once, as `useQueries`'
192 * own top-level second argument, rather than per query.
193 *
194 * Having the same query key more than once in the array of query objects may cause some data to be shared
195 * between queries. To avoid this, consider de-duplicating the queries and map the results back to the desired
196 * structure.
197 *
198 * The `combine` option can be used to combine the results of the queries into a single value. The result will
199 * be structurally shared to be as referentially stable as possible.
200 *
201 * `placeholderData` is supported here too, but unlike `useQuery`, it doesn't receive information from
202 * previously rendered queries, because the number of queries can differ between renders.
203 * @param queriesOptions - An accessor returning the `queries` array to run, and an optional `combine`
204 * function.
205 * @param queryClient - An accessor for a custom `QueryClient`. Otherwise, the one from the nearest context
206 * will be used.
207 * @returns The combined result. Without `combine`, this is an array with all the query results, in the same
208 * order as the input. When `combine` is provided, this is the value returned by `combine` instead.
209 * @example
210 * ```tsx
211 * import { For } from 'solid-js'
212 * import { useQueries } from '@tanstack/solid-query'
213 *
214 * function Posts(props: { ids: Array<number> }) {
215 * const postQueries = useQueries(() => ({
216 * queries: props.ids.map((id) => ({
217 * queryKey: ['post', id],
218 * queryFn: () => fetchPost(id),
219 * staleTime: Infinity,
220 * })),
221 * }))
222 *
223 * return (
224 * <ul>
225 * <For each={postQueries}>
226 * {(postQuery) => {
227 * if (postQuery.isPending) return <li>Loading...</li>
228 * if (postQuery.isError) return <li>Error: {postQuery.error.message}</li>
229 * return <li>{postQuery.data.title}</li>
230 * }}
231 * </For>
232 * </ul>
233 * )
234 * }
235 * ```
236 * @example
237 * Combining results into a single value:
238 * ```tsx
239 * import { For, Match, Switch } from 'solid-js'
240 * import { useQueries } from '@tanstack/solid-query'
241 *
242 * function Posts(props: { ids: Array<number> }) {
243 * const combinedPostsQuery = useQueries(() => ({
244 * queries: props.ids.map((id) => ({
245 * queryKey: ['post', id],
246 * queryFn: () => fetchPost(id),
247 * })),
248 * combine: (postQueries) => {
249 * return {
250 * data: postQueries.map((postQuery) => postQuery.data),
251 * isPending: postQueries.some((postQuery) => postQuery.isPending),
252 * isError: postQueries.some((postQuery) => postQuery.isError),
253 * }
254 * },
255 * }))
256 *
257 * return (
258 * <Switch
259 * fallback={
260 * <ul>
261 * <For each={combinedPostsQuery.data}>{(post) => <li>{post?.title}</li>}</For>
262 * </ul>
263 * }
264 * >
265 * <Match when={combinedPostsQuery.isPending}>Loading...</Match>
266 * <Match when={combinedPostsQuery.isError}>Error loading posts</Match>
267 * </Switch>
268 * )
269 * }
270 * ```
271 */
272export function useQueries<
273 T extends Array<any>,
274 TCombinedResult extends QueriesResults<T> = QueriesResults<T>,
275>(
276 queriesOptions: Accessor<{
277 queries:
278 | readonly [...QueriesOptions<T>]
279 | readonly [...{ [K in keyof T]: GetOptions<T[K]> }]
280 combine?: (result: QueriesResults<T>) => TCombinedResult
281 }>,
282 queryClient?: Accessor<QueryClient>,
283): TCombinedResult {
284 const resolveClient = useQueryClientResolver(queryClient)
285 const client = createMemo(() => resolveClient())
286 const isRestoring = useIsRestoring()
287β
288 const defaultedQueries = createMemo(() =>
289 queriesOptions().queries.map((options) =>
290 mergeProps(
291 client().defaultQueryOptions(options as QueryObserverOptions),
292 {
293 get _optimisticResults() {
294 return isRestoring() ? 'isRestoring' : 'optimistic'
295 },
296 },
297 ),
298 ),
299 )
300β
301 const observer = new QueriesObserver(
302 client(),
303 defaultedQueries(),
304 queriesOptions().combine
305 ? ({
306 combine: queriesOptions().combine,
307 } as QueriesObserverOptions<TCombinedResult>)
308 : undefined,
309 )
310β
311 const [state, setState] = createStore<TCombinedResult>(
312 observer.getOptimisticResult(
313 defaultedQueries(),
314 (queriesOptions() as QueriesObserverOptions<TCombinedResult>).combine,
315 )[1](),
316 )
317β
318 createRenderEffect(
319 on(
320 () => queriesOptions().queries.length,
321 () =>
322 setState(
323 observer.getOptimisticResult(
324 defaultedQueries(),
325 (queriesOptions() as QueriesObserverOptions<TCombinedResult>)
326 .combine,
327 )[1](),
328 ),
329 ),
330 )
331β
332 const dataResources = createMemo(
333 on(
334 () => state.length,
335 () =>
336 state.map((queryRes) => {
337 const dataPromise = () =>
338 new Promise((resolve) => {
339 if (queryRes.isFetching && queryRes.isLoading) return
340 resolve(unwrap(queryRes.data))
341 })
342 return createResource(dataPromise)
343 }),
344 ),
345 )
346β
347 batch(() => {
348 const dataResources_ = dataResources()
349 for (let index = 0; index < dataResources_.length; index++) {
350 const dataResource = dataResources_[index]!
351 dataResource[1].mutate(() => unwrap(state[index]!.data))
352 dataResource[1].refetch()
353 }
354 })
355β
356 let taskQueue: Array<() => void> = []
357 const subscribeToObserver = () =>
358 observer.subscribe((result) => {
359 taskQueue.push(() => {
360 batch(() => {
361 const dataResources_ = dataResources()
362 for (let index = 0; index < dataResources_.length; index++) {
363 const dataResource = dataResources_[index]!
364 const unwrappedResult = { ...unwrap(result[index]) }
365 // @ts-expect-error typescript pedantry regarding the possible range of index
366 setState(index, unwrap(unwrappedResult))
367 dataResource[1].mutate(() => unwrap(state[index]!.data))
368 dataResource[1].refetch()
369 }
370 })
371 })
372β
373 queueMicrotask(() => {
374 const taskToRun = taskQueue.pop()
375 if (taskToRun) taskToRun()
376 taskQueue = []
377 })
378 })
379β
380 let unsubscribe: () => void = noop
381 createComputed<() => void>((cleanup) => {
382 cleanup?.()
383 unsubscribe = isRestoring() ? noop : subscribeToObserver()
384 // cleanup needs to be scheduled after synchronous effects take place
385 return () => queueMicrotask(unsubscribe)
386 })
387 onCleanup(unsubscribe)
388β
389 onMount(() => {
390 observer.setQueries(
391 defaultedQueries(),
392 queriesOptions().combine
393 ? ({
394 combine: queriesOptions().combine,
395 } as QueriesObserverOptions<TCombinedResult>)
396 : undefined,
397 )
398 })
399β
400 createComputed(() => {
401 observer.setQueries(
402 defaultedQueries(),
403 queriesOptions().combine
404 ? ({
405 combine: queriesOptions().combine,
406 } as QueriesObserverOptions<TCombinedResult>)
407 : undefined,
408 )
409 })
410β
411 const handler = (index: number) => ({
412 get(target: QueryObserverResult, prop: keyof QueryObserverResult): any {
413 if (prop === 'data') {
414 return dataResources()[index]![0]()
415 }
416 return Reflect.get(target, prop)
417 },
418 })
419β
420 const getProxies = () =>
421 state.map((s, index) => {
422 return new Proxy(s, handler(index))
423 })
424β
425 const [proxyState, setProxyState] = createStore(getProxies())
426 createRenderEffect(() => setProxyState(getProxies()))
427β
428 return proxyState as TCombinedResult
429}