'use client' import { skipToken } from '@tanstack/query-core' import { useQueries } from './useQueries' import { defaultThrowOnError } from './suspense' import type { UseSuspenseQueryOptions, UseSuspenseQueryResult } from './types' import type { DefaultError, QueryClient, QueryFunction, ThrowOnError, } from '@tanstack/query-core' // Avoid TS depth-limit error in case of large array literal type MAXIMUM_DEPTH = 20 // Widen the type of the symbol to enable type inference even if skipToken is not immutable. type SkipTokenForUseQueries = symbol type GetUseSuspenseQueryOptions = // Part 1: responsible for applying explicit type parameter to function arguments, if object { queryFnData: TQueryFnData, error: TError, data: TData } T extends { queryFnData: infer TQueryFnData error?: infer TError data: infer TData } ? UseSuspenseQueryOptions : T extends { queryFnData: infer TQueryFnData; error?: infer TError } ? UseSuspenseQueryOptions : T extends { data: infer TData; error?: infer TError } ? UseSuspenseQueryOptions : // Part 2: responsible for applying explicit type parameter to function arguments, if tuple [TQueryFnData, TError, TData] T extends [infer TQueryFnData, infer TError, infer TData] ? UseSuspenseQueryOptions : T extends [infer TQueryFnData, infer TError] ? UseSuspenseQueryOptions : T extends [infer TQueryFnData] ? UseSuspenseQueryOptions : // Part 3: responsible for inferring and enforcing type if no explicit parameter was provided T extends { queryFn?: | QueryFunction | SkipTokenForUseQueries select?: (data: any) => infer TData throwOnError?: ThrowOnError } ? UseSuspenseQueryOptions< TQueryFnData, TError, TData, TQueryKey > : T extends { queryFn?: | QueryFunction | SkipTokenForUseQueries throwOnError?: ThrowOnError } ? UseSuspenseQueryOptions< TQueryFnData, TError, TQueryFnData, TQueryKey > : // Fallback UseSuspenseQueryOptions type GetUseSuspenseQueryResult = // Part 1: responsible for mapping explicit type parameter to function result, if object T extends { queryFnData: any; error?: infer TError; data: infer TData } ? UseSuspenseQueryResult : T extends { queryFnData: infer TQueryFnData; error?: infer TError } ? UseSuspenseQueryResult : T extends { data: infer TData; error?: infer TError } ? UseSuspenseQueryResult : // Part 2: responsible for mapping explicit type parameter to function result, if tuple T extends [any, infer TError, infer TData] ? UseSuspenseQueryResult : T extends [infer TQueryFnData, infer TError] ? UseSuspenseQueryResult : T extends [infer TQueryFnData] ? UseSuspenseQueryResult : // Part 3: responsible for mapping inferred type to results, if no explicit parameter was provided T extends { queryFn?: | QueryFunction | SkipTokenForUseQueries select?: (data: any) => infer TData throwOnError?: ThrowOnError } ? UseSuspenseQueryResult< unknown extends TData ? TQueryFnData : TData, unknown extends TError ? DefaultError : TError > : T extends { queryFn?: | QueryFunction | SkipTokenForUseQueries throwOnError?: ThrowOnError } ? UseSuspenseQueryResult< TQueryFnData, unknown extends TError ? DefaultError : TError > : // Fallback UseSuspenseQueryResult /** * The `queries` array accepted by `useSuspenseQueries`. Recursively unwraps each tuple element so every * entry's `queryFn`/`select` are inferred individually, up to 20 elements. An opaque array (e.g. `unknown[]`) * is returned as-is; a non-tuple array of a known element type, or a tuple past 20 elements, falls back to a * single homogeneous {@link UseSuspenseQueryOptions} type. * * @template T - The type of the `queries` array as written at the call site. * @template TResults - The internal accumulator that this type builds during recursion. It is not meant * to be set explicitly. * @template TDepth - The internal recursion-depth counter, checked against the 20-element limit. It is not * meant to be set explicitly. */ export type SuspenseQueriesOptions< T extends Array, TResults extends Array = [], TDepth extends ReadonlyArray = [], > = TDepth['length'] extends MAXIMUM_DEPTH ? Array : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseSuspenseQueryOptions] : T extends [infer Head, ...infer Tails] ? SuspenseQueriesOptions< [...Tails], [...TResults, GetUseSuspenseQueryOptions], [...TDepth, 1] > : Array extends T ? T : // If T is *some* array but we couldn't assign unknown[] to it, then it must hold some known/homogeneous type! // use this to infer the param types in the case of Array.map() argument T extends Array< UseSuspenseQueryOptions< infer TQueryFnData, infer TError, infer TData, infer TQueryKey > > ? Array< UseSuspenseQueryOptions > : // Fallback Array /** * The result type returned by `useSuspenseQueries`, when no `combine` is provided. Mirrors * {@link SuspenseQueriesOptions}: each tuple element's result type is inferred individually, up to 20 elements. * A non-tuple array is mapped per-element instead, still inferring each entry individually; only past 20 * elements does this fall back to a single homogeneous {@link UseSuspenseQueryResult} type. * * @template T - The type of the `queries` array, as inferred by {@link SuspenseQueriesOptions}. * @template TResults - The internal accumulator that this type builds during recursion. It is not meant * to be set explicitly. * @template TDepth - The internal recursion-depth counter, checked against the 20-element limit. It is not * meant to be set explicitly. */ export type SuspenseQueriesResults< T extends Array, TResults extends Array = [], TDepth extends ReadonlyArray = [], > = TDepth['length'] extends MAXIMUM_DEPTH ? Array : T extends [] ? [] : T extends [infer Head] ? [...TResults, GetUseSuspenseQueryResult] : T extends [infer Head, ...infer Tails] ? SuspenseQueriesResults< [...Tails], [...TResults, GetUseSuspenseQueryResult], [...TDepth, 1] > : { [K in keyof T]: GetUseSuspenseQueryResult } /** * The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` * option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. * * @param options - The `queries` array to run in Suspense, and an optional `combine` function. * @param queryClient - Use this to provide a custom `QueryClient`. Otherwise, the one from the nearest context * will be used. * @returns The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be * defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived * flags set accordingly). * * Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone * stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid * this, make sure to set a high enough `staleTime`. Cancellation does not work. * * @example * The query error is thrown if a fetch fails and no cached data exists yet, so an error boundary is * required around ``. A failed background refetch instead continues to render the cached data. * Use {@link QueryErrorResetBoundary} to let the user retry after such an error: * ```tsx * import { Suspense } from 'react' * import { ErrorBoundary } from 'react-error-boundary' * import { * QueryErrorResetBoundary, * useSuspenseQueries, * } from '@tanstack/react-query' * * function Posts({ ids }: { ids: Array }) { * // Every result is guaranteed to be defined — no per-query `isPending` check needed. * const postQueries = useSuspenseQueries({ * queries: ids.map((id) => ({ * queryKey: ['post', id], * queryFn: () => fetchPost(id), * })), * }) * * return ( *
    * {postQueries.map((query) => ( *
  • {query.data.title}
  • * ))} *
* ) * } * * function App() { * return ( * * {({ reset }) => ( * ( *
* There was an error! * *
* )} * > * Loading posts...}> * * *
* )} *
* ) * } * ``` * * @example * Several different queries — use `useSuspenseQueries` instead of multiple `useSuspenseQuery` calls, so * they fetch in parallel rather than suspending one after another: * ```tsx * import { Suspense } from 'react' * import { ErrorBoundary } from 'react-error-boundary' * import { * QueryErrorResetBoundary, * useSuspenseQueries, * } from '@tanstack/react-query' * * function Dashboard() { * const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({ * queries: [ * { queryKey: ['users'], queryFn: fetchUsers }, * { queryKey: ['teams'], queryFn: fetchTeams }, * { queryKey: ['projects'], queryFn: fetchProjects }, * ], * }) * * return ( *
* * * *
* ) * } * * function App() { * return ( * * {({ reset }) => ( * ( *
* There was an error! * *
* )} * > * Loading dashboard...}> * * *
* )} *
* ) * } * ``` * * @example * `combine`s the results into a single boolean, so `Refresh` only re-renders when that boolean changes, * not on every individual query update. This overload is the only one that accepts `combine`: * ```tsx * import { Suspense } from 'react' * import { ErrorBoundary } from 'react-error-boundary' * import { * QueryErrorResetBoundary, * useSuspenseQueries, * } from '@tanstack/react-query' * * function Refresh() { * const anyFetching = useSuspenseQueries({ * queries: [ * { queryKey: ['users'], queryFn: fetchUsers }, * { queryKey: ['teams'], queryFn: fetchTeams }, * ], * combine: (results) => results.some((result) => result.isFetching), * }) * * return anyFetching ? Refreshing… : null * } * * function App() { * return ( * * {({ reset }) => ( * ( *
* There was an error! * *
* )} * > * Loading dashboard...}> * * *
* )} *
* ) * } * ``` */ export function useSuspenseQueries< T extends Array, TCombinedResult = SuspenseQueriesResults, >( options: { /** * An array with query option objects identical to `useSuspenseQuery`. */ queries: | readonly [...SuspenseQueriesOptions] | readonly [...{ [K in keyof T]: GetUseSuspenseQueryOptions }] /** * Use this to combine the results of the queries into a single value. The result will be structurally * shared to be as referentially stable as possible. */ combine?: (result: SuspenseQueriesResults) => TCombinedResult }, queryClient?: QueryClient, ): TCombinedResult /** * The options for `useSuspenseQueries` are the same as for `useQueries`, except that the top-level `subscribed` * option isn't supported, and each `query` can't have `throwOnError`, `enabled`, or `placeholderData`. * * @param options - The `queries` array to run in Suspense, and an optional `combine` function. * @param queryClient - Use this to provide a custom `QueryClient`. Otherwise, the one from the nearest context * will be used. * @returns The same structure as `useQueries`, except that for each `query`, `data` is guaranteed to be * defined, `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived * flags set accordingly). * * Caveat: the component will only re-mount after all queries have finished loading. Hence, if a query has gone * stale in the time it took for all the queries to complete, it will be fetched again at re-mount. To avoid * this, make sure to set a high enough `staleTime`. Cancellation does not work. * * @example * The query error is thrown if a fetch fails and no cached data exists yet, so an error boundary is * required around ``. A failed background refetch instead continues to render the cached data. * Use {@link QueryErrorResetBoundary} to let the user retry after such an error: * ```tsx * import { Suspense } from 'react' * import { ErrorBoundary } from 'react-error-boundary' * import { * QueryErrorResetBoundary, * useSuspenseQueries, * } from '@tanstack/react-query' * * function Posts({ ids }: { ids: Array }) { * // Every result is guaranteed to be defined — no per-query `isPending` check needed. * const postQueries = useSuspenseQueries({ * queries: ids.map((id) => ({ * queryKey: ['post', id], * queryFn: () => fetchPost(id), * })), * }) * * return ( *
    * {postQueries.map((query) => ( *
  • {query.data.title}
  • * ))} *
* ) * } * * function App() { * return ( * * {({ reset }) => ( * ( *
* There was an error! * *
* )} * > * Loading posts...}> * * *
* )} *
* ) * } * ``` * * @example * Several different queries — use `useSuspenseQueries` instead of multiple `useSuspenseQuery` calls, so * they fetch in parallel rather than suspending one after another: * ```tsx * import { Suspense } from 'react' * import { ErrorBoundary } from 'react-error-boundary' * import { * QueryErrorResetBoundary, * useSuspenseQueries, * } from '@tanstack/react-query' * * function Dashboard() { * const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({ * queries: [ * { queryKey: ['users'], queryFn: fetchUsers }, * { queryKey: ['teams'], queryFn: fetchTeams }, * { queryKey: ['projects'], queryFn: fetchProjects }, * ], * }) * * return ( *
* * * *
* ) * } * * function App() { * return ( * * {({ reset }) => ( * ( *
* There was an error! * *
* )} * > * Loading dashboard...}> * * *
* )} *
* ) * } * ``` */ export function useSuspenseQueries< T extends Array, TCombinedResult = SuspenseQueriesResults, >( options: { /** * An array with query option objects identical to `useSuspenseQuery`. */ queries: readonly [...SuspenseQueriesOptions] /** * Use this to combine the results of the queries into a single value. The result will be structurally * shared to be as referentially stable as possible. */ combine?: (result: SuspenseQueriesResults) => TCombinedResult }, queryClient?: QueryClient, ): TCombinedResult export function useSuspenseQueries(options: any, queryClient?: QueryClient) { return useQueries( { ...options, queries: options.queries.map((query: any) => { if (process.env.NODE_ENV !== 'production') { if (query.queryFn === skipToken) { console.error('skipToken is not allowed for useSuspenseQueries') } } return { ...query, suspense: true, throwOnError: defaultThrowOnError, enabled: true, placeholderData: undefined, } }), }, queryClient, ) }