@tanstack/preact-query 5.102.2 → 5.102.4

package/src/useQuery.ts

@@ -12,6 +12,33 @@ import type {
 } from './types'
 import { useBaseQuery } from './useBaseQuery'
 
+/**
+ * This overload is selected when `initialData` is set, so the resulting `data` is never `undefined`.
+ *
+ * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`.
+ * @param options - The {@link DefinedInitialDataOptions} to use — everything you can pass to `useQuery`, with `initialData` set.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The current query result, typed so that `status` is `success` — or `error` if a fetch attempt
+ * fails while keeping the existing data (`status` never resolves to `pending` in this overload's type,
+ * since `initialData` guarantees data upfront). `isSuccess`/`isError` are derived booleans for convenience.
+ *
+ * @example
+ * ```tsx
+ * import { useQuery } from '@tanstack/preact-query'
+ *
+ * function Posts() {
+ *   // `data` is `Post[]`, never `undefined`, thanks to `initialData`.
+ *   const { data } = useQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *     initialData: [],
+ *   })
+ *
+ *   return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ * }
+ * ```
+ */
 export function useQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -22,6 +49,41 @@ export function useQuery<
   queryClient?: QueryClient,
 ): DefinedUseQueryResult<TData, TError>
 
+/**
+ * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`.
+ * @param options - The {@link UndefinedInitialDataOptions} to use — everything you can pass to `useQuery`.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
+ * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
+ * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ * })
+ *
+ * function Posts() {
+ *   const { status, data, error, isFetching } = useQuery(postsOptions)
+ *
+ *   if (status === 'pending') return 'Loading...'
+ *   if (status === 'error') return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <div>
+ *       {data.map((post) => (
+ *         <p key={post.id}>{post.title}</p>
+ *       ))}
+ *       <div>{isFetching ? 'Background Updating...' : ' '}</div>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 export function useQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -32,6 +94,78 @@ export function useQuery<
   queryClient?: QueryClient,
 ): UseQueryResult<TData, TError>
 
+/**
+ * @see {@link queryOptions} to share these options between `useQuery` and imperative APIs like `queryClient.query`.
+ * @param options - The {@link UseQueryOptions} to use — everything you can pass to `useQuery`.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns The current query result. `status` is `pending` if there is no cached data and no query attempt
+ * has finished yet, `error` if the query attempt resulted in an error, or `success` if the query has data to
+ * display. `isPending`/`isSuccess`/`isError` are derived booleans for convenience.
+ *
+ * @example
+ * ```tsx
+ * import { queryOptions, useQuery } from '@tanstack/preact-query'
+ *
+ * const postsOptions = queryOptions({
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ * })
+ *
+ * function Posts() {
+ *   const { status, data, error, isFetching } = useQuery(postsOptions)
+ *
+ *   if (status === 'pending') return 'Loading...'
+ *   if (status === 'error') return <span>Error: {error.message}</span>
+ *
+ *   return (
+ *     <div>
+ *       {data.map((post) => (
+ *         <p key={post.id}>{post.title}</p>
+ *       ))}
+ *       <div>{isFetching ? 'Background Updating...' : ' '}</div>
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * A dependent query, only enabled once `postId` is set:
+ * ```tsx
+ * import { useQuery } from '@tanstack/preact-query'
+ *
+ * function Post({ postId }: { postId: number | undefined }) {
+ *   const { data } = useQuery({
+ *     queryKey: ['post', postId],
+ *     queryFn: () => fetchPost(postId!),
+ *     enabled: postId != null,
+ *   })
+ *
+ *   return <h1>{data?.title}</h1>
+ * }
+ * ```
+ *
+ * @example
+ * Seeding a detail query from an already-cached list, to skip the loading state:
+ * ```tsx
+ * import { useQuery, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function Post({ postId }: { postId: number }) {
+ *   const queryClient = useQueryClient()
+ *
+ *   const { data } = useQuery({
+ *     queryKey: ['post', postId],
+ *     queryFn: () => fetchPost(postId),
+ *     initialData: () =>
+ *       queryClient
+ *         .getQueryData<Array<Post>>(['posts'])
+ *         ?.find((post) => post.id === postId),
+ *   })
+ *
+ *   return <h1>{data?.title}</h1>
+ * }
+ * ```
+ */
 export function useQuery<
   TQueryFnData = unknown,
   TError = DefaultError,

package/src/useSuspenseInfiniteQuery.ts

@@ -15,6 +15,54 @@ 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 } = 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}>
+ *         Load More
+ *       </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,133 @@ 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 results = useSuspenseQueries({
+ *     queries: ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *     })),
+ *   })
+ *
+ *   return (
+ *     <ul>
+ *       {results.map((result) => (
+ *         <li key={result.data.id}>{result.data.title}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading posts...</h1>}>
+ *       <Posts ids={[1, 2, 3]} />
+ *     </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 results = useSuspenseQueries({
+ *     queries: ids.map((id) => ({
+ *       queryKey: ['post', id],
+ *       queryFn: () => fetchPost(id),
+ *     })),
+ *   })
+ *
+ *   return (
+ *     <ul>
+ *       {results.map((result) => (
+ *         <li key={result.data.id}>{result.data.title}</li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<h1>Loading posts...</h1>}>
+ *       <Posts ids={[1, 2, 3]} />
+ *     </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,49 @@ 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.
+ *
+ * @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,

package/src/utils.ts

@@ -56,7 +56,6 @@ function didSnapshotChange(inst: {
   try {
     const nextValue = latestGetSnapshot()
     return !Object.is(prevValue, nextValue)
-    // eslint-disable-next-line no-unused-vars
   } catch (_error) {
     return true
   }