@tanstack/preact-query 5.102.3 → 5.102.5

package/src/useSuspenseInfiniteQuery.ts

@@ -15,6 +15,62 @@ import type {
 } from './types'
 import { useBaseQuery } from './useBaseQuery'
 
+/**
+ * The options for `useSuspenseInfiniteQuery` are the same as for `useInfiniteQuery`, except for `throwOnError`,
+ * `enabled`, and `placeholderData`.
+ *
+ * Caveat: cancellation does not work.
+ *
+ * @param options - The {@link UseSuspenseInfiniteQueryOptions} to use — the same options as `useInfiniteQuery`, minus the ones listed above.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The same object as `useInfiniteQuery`, except that `data` is guaranteed to be defined,
+ * `isPlaceholderData` is missing, and `status` is either `success` or `error` (with the derived flags set
+ * accordingly).
+ *
+ * @example
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * function Projects() {
+ *   // `data` is guaranteed to be defined here — no `isPending` check needed.
+ *   const { data, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =
+ *     useSuspenseInfiniteQuery({
+ *       queryKey: ['projects'],
+ *       queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *       initialPageParam: 0,
+ *       getNextPageParam: (lastPage) => lastPage.nextId,
+ *     })
+ *
+ *   return (
+ *     <div>
+ *       {data.pages.map((page) =>
+ *         page.projects.map((project) => <p key={project.id}>{project.name}</p>),
+ *       )}
+ *       <button
+ *         onClick={() => fetchNextPage()}
+ *         disabled={!hasNextPage || isFetching}
+ *       >
+ *         {isFetchingNextPage
+ *           ? 'Loading more...'
+ *           : hasNextPage
+ *             ? 'Load More'
+ *             : 'Nothing more to load'}
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading projects...</h1>}>
+ *       <Projects />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
+ */
 export function useSuspenseInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,

package/src/useSuspenseQueries.ts

@@ -105,7 +105,16 @@ type GetUseSuspenseQueryResult<T> =
                     UseSuspenseQueryResult
 
 /**
- * SuspenseQueriesOptions reducer recursively unwraps function arguments to infer/enforce type param
+ * 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<any>,
@@ -142,7 +151,16 @@ export type SuspenseQueriesOptions<
               Array<UseSuspenseQueryOptions>
 
 /**
- * SuspenseQueriesResults reducer recursively maps type param to results
+ * 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<any>,
@@ -162,25 +180,201 @@ export type SuspenseQueriesResults<
           >
         : { [K in keyof T]: GetUseSuspenseQueryResult<T[K]> }
 
+/**
+ * The options for `useSuspenseQueries` are the same as for `useQueries`, except that 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
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseQueries } from '@tanstack/preact-query'
+ *
+ * function Posts({ ids }: { ids: Array<number> }) {
+ *   // 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 (
+ *     <ul>
+ *       {postQueries.map((query) => (
+ *         <li key={query.data.id}>{query.data.title}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading posts...</h1>}>
+ *       <Posts ids={[1, 2, 3]} />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
+ *
+ * @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 'preact/compat'
+ * import { useSuspenseQueries } from '@tanstack/preact-query'
+ *
+ * function Dashboard() {
+ *   const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({
+ *     queries: [
+ *       { queryKey: ['users'], queryFn: fetchUsers },
+ *       { queryKey: ['teams'], queryFn: fetchTeams },
+ *       { queryKey: ['projects'], queryFn: fetchProjects },
+ *     ],
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <UserList users={usersQuery.data} />
+ *       <TeamList teams={teamsQuery.data} />
+ *       <ProjectList projects={projectsQuery.data} />
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading dashboard...</h1>}>
+ *       <Dashboard />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
+ */
 export function useSuspenseQueries<
   T extends Array<any>,
   TCombinedResult = SuspenseQueriesResults<T>,
 >(
   options: {
+    /**
+     * An array with query option objects identical to `useSuspenseQuery`.
+     */
     queries:
       | readonly [...SuspenseQueriesOptions<T>]
       | readonly [...{ [K in keyof T]: GetUseSuspenseQueryOptions<T[K]> }]
+    /**
+     * 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<T>) => TCombinedResult
   },
   queryClient?: QueryClient,
 ): TCombinedResult
 
+/**
+ * The options for `useSuspenseQueries` are the same as for `useQueries`, except that 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
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseQueries } from '@tanstack/preact-query'
+ *
+ * function Posts({ ids }: { ids: Array<number> }) {
+ *   // 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 (
+ *     <ul>
+ *       {postQueries.map((query) => (
+ *         <li key={query.data.id}>{query.data.title}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading posts...</h1>}>
+ *       <Posts ids={[1, 2, 3]} />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
+ *
+ * @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 'preact/compat'
+ * import { useSuspenseQueries } from '@tanstack/preact-query'
+ *
+ * function Dashboard() {
+ *   const [usersQuery, teamsQuery, projectsQuery] = useSuspenseQueries({
+ *     queries: [
+ *       { queryKey: ['users'], queryFn: fetchUsers },
+ *       { queryKey: ['teams'], queryFn: fetchTeams },
+ *       { queryKey: ['projects'], queryFn: fetchProjects },
+ *     ],
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <UserList users={usersQuery.data} />
+ *       <TeamList teams={teamsQuery.data} />
+ *       <ProjectList projects={projectsQuery.data} />
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading dashboard...</h1>}>
+ *       <Dashboard />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
+ */
 export function useSuspenseQueries<
   T extends Array<any>,
   TCombinedResult = SuspenseQueriesResults<T>,
 >(
   options: {
+    /**
+     * An array with query option objects identical to `useSuspenseQuery`.
+     */
     queries: readonly [...SuspenseQueriesOptions<T>]
+    /**
+     * 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<T>) => TCombinedResult
   },
   queryClient?: QueryClient,

package/src/useSuspenseQuery.ts

@@ -5,6 +5,53 @@ import { defaultThrowOnError } from './suspense'
 import type { UseSuspenseQueryOptions, UseSuspenseQueryResult } from './types'
 import { useBaseQuery } from './useBaseQuery'
 
+/**
+ * The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and
+ * `placeholderData`.
+ *
+ * Caveat: cancellation does not work.
+ *
+ * @remarks Multiple `useSuspenseQuery` calls in the same component suspend serially, causing a request
+ * waterfall — each one blocks rendering until it resolves, so the next doesn't even start fetching until then.
+ * Use {@link useSuspenseQueries} instead when you have more than one suspenseful query in a component, so they
+ * fetch in parallel.
+ * @param options - The {@link UseSuspenseQueryOptions} to use — the same options as `useQuery`, minus the ones listed above.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`
+ * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
+ *
+ * @example
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { useSuspenseQuery } from '@tanstack/preact-query'
+ *
+ * function Posts() {
+ *   // `data` is guaranteed to be defined here — no `isPending` check needed.
+ *   const { data, isFetching } = useSuspenseQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       <h1>Posts {isFetching ? <Spinner /> : null}</h1>
+ *       {data.map((post) => (
+ *         <p key={post.id}>{post.title}</p>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading posts...</h1>}>
+ *       <Posts />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
+ */
 export function useSuspenseQuery<
   TQueryFnData = unknown,
   TError = DefaultError,