@tanstack/preact-query 5.102.3 → 5.102.5

package/src/useMutation.ts

@@ -17,6 +17,176 @@ import { useSyncExternalStore } from './utils'
 
 // HOOK
 
+/**
+ * Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
+ * `useMutation` is the hook for that.
+ *
+ * @see {@link mutationOptions} to share these options across multiple `useMutation` call sites.
+ * @param options - The {@link UseMutationOptions} to use — everything you can pass to `useMutation`.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns `mutate`/`mutateAsync` also accept per-call `onSuccess`/`onError`/`onSettled` callbacks as a second
+ * argument, useful for triggering call-site side effects (e.g. navigation) without coupling them to the shared
+ * mutation definition. If you make multiple requests, `onSuccess` will fire only after the latest call you've
+ * made.
+ *
+ * @example
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ *
+ *   return (
+ *     <button
+ *       onClick={() =>
+ *         addMutation.mutate('Item', {
+ *           onError: (error) => console.error('Failed to add item:', error),
+ *         })
+ *       }
+ *     >
+ *       Add
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Rendering the mutation's own state, rather than just firing it off:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       {addMutation.isPending ? (
+ *         'Adding todo...'
+ *       ) : (
+ *         <>
+ *           {addMutation.isError ? (
+ *             <div>An error occurred: {addMutation.error.message}</div>
+ *           ) : null}
+ *           <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *         </>
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Optimistic update via `onMutate`, rolling back on `onError`:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onMutate: async (newTodo) => {
+ *       await queryClient.cancelQueries({ queryKey: ['todos'] })
+ *       const previousTodos = queryClient.getQueryData<Array<string>>(['todos'])
+ *
+ *       queryClient.setQueryData<Array<string>>(['todos'], (old) => [
+ *         ...(old ?? []),
+ *         newTodo,
+ *       ])
+ *
+ *       // Passed to `onError` as `context` if the mutation fails.
+ *       return { previousTodos }
+ *     },
+ *     onError: (_err, _newTodo, context) => {
+ *       queryClient.setQueryData(['todos'], context?.previousTodos)
+ *     },
+ *     onSettled: () => {
+ *       queryClient.invalidateQueries({ queryKey: ['todos'] })
+ *     },
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Callbacks passed per call to `mutate` only fire for the last call — `mutateAsync` gives you a
+ * promise per call instead, so you can wait for all of them:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodos() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ *
+ *   async function handleAddAll(todos: Array<string>) {
+ *     try {
+ *       await Promise.all(todos.map((todo) => addMutation.mutateAsync(todo)))
+ *     } catch (error) {
+ *       console.error('Failed to add todos:', error)
+ *     }
+ *   }
+ *
+ *   return (
+ *     <button onClick={() => handleAddAll(['Todo 1', 'Todo 2', 'Todo 3'])}>
+ *       Add all
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * If some of the mutations above can fail independently of the others, and you want to know which ones
+ * did — rather than losing that information the moment the first one rejects — swap `Promise.all` for
+ * `Promise.allSettled`:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodos() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ *
+ *   async function handleAddAll(todos: Array<string>) {
+ *     const results = await Promise.allSettled(
+ *       todos.map((todo) => addMutation.mutateAsync(todo)),
+ *     )
+ *
+ *     results.forEach((result, index) => {
+ *       if (result.status === 'rejected') {
+ *         console.error(`Failed to add "${todos[index]}":`, result.reason)
+ *       }
+ *     })
+ *   }
+ *
+ *   return (
+ *     <button onClick={() => handleAddAll(['Todo 1', 'Todo 2', 'Todo 3'])}>
+ *       Add all
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
 export function useMutation<
   TData = unknown,
   TError = DefaultError,

package/src/useMutationState.ts

@@ -11,6 +11,25 @@ import { useCallback, useEffect, useRef } from 'preact/hooks'
 import { useQueryClient } from './QueryClientProvider'
 import { useSyncExternalStore } from './utils'
 
+/**
+ * `useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching
+ * (useful for app-wide loading indicators).
+ *
+ * @param filters - The {@link MutationFilters} to narrow down the matched mutations.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns Will be the `number` of the mutations that your application is currently fetching.
+ *
+ * @example
+ * ```tsx
+ * import { useIsMutating } from '@tanstack/preact-query'
+ *
+ * // How many mutations are fetching?
+ * const isMutating = useIsMutating()
+ * // How many mutations matching the posts prefix are fetching?
+ * const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+ * ```
+ */
 export function useIsMutating(
   filters?: MutationFilters,
   queryClient?: QueryClient,
@@ -60,6 +79,61 @@ function getResult<
     )
 }
 
+/**
+ * `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
+ * `filters` ({@link MutationFilters}) to narrow down your mutations, and `select` to transform the mutation
+ * state.
+ *
+ * @param options - The `filters` to narrow down matched mutations, and an optional `select` to transform the
+ * mutation state.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns Will be an Array of whatever `select` returns for each matching mutation.
+ *
+ * @example
+ * Get all variables of all running mutations:
+ * ```tsx
+ * import { useMutationState } from '@tanstack/preact-query'
+ *
+ * const variables = useMutationState({
+ *   filters: { status: 'pending' },
+ *   select: (mutation) => mutation.state.variables,
+ * })
+ * ```
+ *
+ * @example
+ * Get all data for specific mutations via the `mutationKey`:
+ * ```tsx
+ * import { useMutation, useMutationState } from '@tanstack/preact-query'
+ *
+ * const mutationKey = ['posts']
+ *
+ * // Some mutation that we want to get the state for
+ * const mutation = useMutation({
+ *   mutationKey,
+ *   mutationFn: createPosts,
+ * })
+ *
+ * const data = useMutationState({
+ *   // this mutation key needs to match the mutation key of the given mutation (see above)
+ *   filters: { mutationKey },
+ *   select: (mutation) => mutation.state.data,
+ * })
+ * ```
+ *
+ * @example
+ * Access the latest mutation data via the `mutationKey`. Each invocation of `mutate` adds a new entry to the
+ * mutation cache for `gcTime` milliseconds — check the last item that `useMutationState` returns to get the
+ * latest invocation:
+ * ```tsx
+ * const data = useMutationState({
+ *   filters: { mutationKey: ['posts'] },
+ *   select: (mutation) => mutation.state.data,
+ * })
+ *
+ * const latest = data[data.length - 1]
+ * ```
+ */
 export function useMutationState<
   TResult = MutationState,
   TMutation extends Mutation<any, any, any, any> =

package/src/usePrefetchInfiniteQuery.tsx

@@ -4,6 +4,50 @@ import { useQueryClient } from './QueryClientProvider'
 import type { DefaultError, QueryClient, QueryKey } from '@tanstack/query-core'
 import type { UsePrefetchInfiniteQueryOptions } from './types'
 
+/**
+ * `usePrefetchInfiniteQuery` does not return anything, it should be used just to fire a prefetch during render,
+ * before a suspense boundary that wraps a component that uses `useSuspenseInfiniteQuery`. You can pass
+ * everything to `usePrefetchInfiniteQuery` that you can pass to `queryClient.infiniteQuery`, though
+ * `queryKey`, `initialPageParam`, and `getNextPageParam` are always required, and `queryFn` is required unless
+ * a default query function has been defined.
+ *
+ * `getNextPageParam` receives both the last page of the infinite list of data and the full array of all pages,
+ * as well as pageParam information, and should return a single variable that will be passed to your query
+ * function as `context.pageParam`. Return `undefined` or `null` to indicate there is no next page available.
+ *
+ * The prefetch is skipped if the query already has any cached state — including a `pending`/`error` state left
+ * over from a previous attempt — so calling this on every render is cheap and won't refetch data that's
+ * already there or already in flight.
+ *
+ * @param options - The {@link UsePrefetchInfiniteQueryOptions} to use — everything you can pass to `queryClient.infiniteQuery`.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns `void` — nothing is returned.
+ *
+ * @example
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { infiniteQueryOptions, usePrefetchInfiniteQuery } from '@tanstack/preact-query'
+ *
+ * const projectsOptions = infiniteQueryOptions({
+ *   queryKey: ['projects'],
+ *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextId,
+ * })
+ *
+ * function App() {
+ *   // Fire the prefetch during render, before the suspense boundary below.
+ *   usePrefetchInfiniteQuery(projectsOptions)
+ *
+ *   return (
+ *     <Suspense fallback={<h1>Loading projects...</h1>}>
+ *       <Projects />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
+ */
 export function usePrefetchInfiniteQuery<
   TQueryFnData = unknown,
   TError = DefaultError,

package/src/usePrefetchQuery.tsx

@@ -4,6 +4,41 @@ import { useQueryClient } from './QueryClientProvider'
 import type { DefaultError, QueryClient, QueryKey } from '@tanstack/query-core'
 import type { UsePrefetchQueryOptions } from './types'
 
+/**
+ * `usePrefetchQuery` does not return anything, it should be used just to fire a prefetch during render, before
+ * a suspense boundary that wraps a component that uses `useSuspenseQuery`. You can pass everything to
+ * `usePrefetchQuery` that you can pass to `queryClient.query`, though `queryKey` is always required, and
+ * `queryFn` is required unless a default query function has been defined.
+ *
+ * The prefetch is skipped if the query already has any cached state — including a `pending`/`error` state left
+ * over from a previous attempt — so calling this on every render is cheap and won't refetch data that's
+ * already there or already in flight.
+ *
+ * @param options - The {@link UsePrefetchQueryOptions} to use — everything you can pass to `queryClient.query`.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns `void` — nothing is returned.
+ *
+ * @example
+ * ```tsx
+ * import { Suspense } from 'preact/compat'
+ * import { usePrefetchQuery } from '@tanstack/preact-query'
+ *
+ * function App() {
+ *   // Fire the prefetch during render, before the suspense boundary below.
+ *   usePrefetchQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   })
+ *
+ *   return (
+ *     <Suspense fallback={<h1>Loading posts...</h1>}>
+ *       <Posts />
+ *     </Suspense>
+ *   )
+ * }
+ * ```
+ */
 export function usePrefetchQuery<
   TQueryFnData = unknown,
   TError = DefaultError,

package/src/useQueries.ts

@@ -142,7 +142,16 @@ type GetUseQueryResult<T> =
                   UseQueryResult
 
 /**
- * QueriesOptions reducer recursively unwraps function arguments to infer/enforce type param
+ * The `queries` array accepted by `useQueries`. Recursively unwraps each tuple element so every entry's
+ * `queryFn`/`select`/`throwOnError` 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 options 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 QueriesOptions<
   T extends Array<any>,
@@ -184,7 +193,16 @@ export type QueriesOptions<
               Array<UseQueryOptionsForUseQueries>
 
 /**
- * QueriesResults reducer recursively maps type param to results
+ * The result type returned by `useQueries`, when no `combine` is provided. Mirrors {@link QueriesOptions}: 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 UseQueryResult} type.
+ *
+ * @template T - The type of the `queries` array, as inferred by {@link QueriesOptions}.
+ * @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 QueriesResults<
   T extends Array<any>,
@@ -204,6 +222,56 @@ export type QueriesResults<
           >
         : { [K in keyof T]: GetUseQueryResult<T[K]> }
 
+/**
+ * The `useQueries` hook can be used to fetch a variable number of queries.
+ *
+ * The `queries` key accepts an array with query option objects identical to `useQuery` (excluding the
+ * `queryClient` option - because the `QueryClient` can be passed in on the top level).
+ *
+ * Having the same query key more than once in the array of query objects may cause some data to be shared
+ * between queries. To avoid this, consider de-duplicating the queries and map the results back to the desired
+ * structure.
+ *
+ * The `combine` option can be used to combine the results of the queries into a single value. The result will
+ * be structurally shared to be as referentially stable as possible.
+ *
+ * @param queryClient - Use this to provide a custom `QueryClient`. Otherwise, the one from the nearest context
+ * will be used.
+ * @returns The combined result. Without `combine`, this is an array with all the query results, in the same
+ * order as the input. When `combine` is provided, this is the value returned by `combine` instead.
+ *
+ * @example
+ * ```tsx
+ * import { useQueries } from '@tanstack/preact-query'
+ *
+ * const ids = [1, 2, 3]
+ * const results = useQueries({
+ *   queries: ids.map((id) => ({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *     staleTime: Infinity,
+ *   })),
+ * })
+ * ```
+ *
+ * @example
+ * Combining results into a single value:
+ * ```tsx
+ * const ids = [1, 2, 3]
+ * const combinedQueries = useQueries({
+ *   queries: ids.map((id) => ({
+ *     queryKey: ['post', id],
+ *     queryFn: () => fetchPost(id),
+ *   })),
+ *   combine: (results) => {
+ *     return {
+ *       data: results.map((result) => result.data),
+ *       pending: results.some((result) => result.isPending),
+ *     }
+ *   },
+ * })
+ * ```
+ */
 export function useQueries<
   T extends Array<any>,
   TCombinedResult = QueriesResults<T>,
@@ -212,10 +280,25 @@ export function useQueries<
     queries,
     ...options
   }: {
+    /**
+     * An array with query option objects, mostly identical to `useQuery` — except that `queryClient` and
+     * `subscribed` aren't accepted per-query (`subscribed` is a top-level option here instead), and
+     * `placeholderData` accepts a {@link QueriesPlaceholderDataFunction}, which is called with `previousData`
+     * and `previousQuery` always `undefined`, rather than `useQuery`'s placeholder function.
+     */
     queries:
       | readonly [...QueriesOptions<T>]
       | readonly [...{ [K in keyof T]: GetUseQueryOptionsForUseQueries<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: QueriesResults<T>) => TCombinedResult
+    /**
+     * Set this to `false` to unsubscribe this observer from updates to the query cache.
+     *
+     * @defaultValue true
+     */
     subscribed?: boolean
   },
   queryClient?: QueryClient,

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,59 @@ 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>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * The same query, checking `isPending`/`isError` instead of `status` — pick whichever reads better to you:
+ * ```tsx
+ * import { useQuery } from '@tanstack/preact-query'
+ *
+ * function Posts() {
+ *   const { isPending, isError, data, error } = useQuery({
+ *     queryKey: ['posts'],
+ *     queryFn: fetchPosts,
+ *   })
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   return <>{data.map((post) => <p key={post.id}>{post.title}</p>)}</>
+ * }
+ * ```
+ */
 export function useQuery<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -32,6 +112,112 @@ 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 — use `isLoading`, not `isPending`, so the
+ * loading state doesn't show while the query is disabled:
+ * ```tsx
+ * import { useQuery } from '@tanstack/preact-query'
+ *
+ * function Post({ postId }: { postId: number | undefined }) {
+ *   const { data, isLoading, isError, error } = useQuery({
+ *     queryKey: ['post', postId],
+ *     queryFn: () => fetchPost(postId!),
+ *     enabled: postId != null,
+ *   })
+ *
+ *   if (postId == null) return 'Select a post'
+ *   if (isLoading) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
+ *   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>
+ * }
+ * ```
+ *
+ * @example
+ * Paginated data, keeping the previous page's data visible while the next page loads:
+ * ```tsx
+ * import { keepPreviousData, useQuery } from '@tanstack/preact-query'
+ * import { useState } from 'preact/hooks'
+ *
+ * function Posts() {
+ *   const [page, setPage] = useState(0)
+ *
+ *   const { data, isPlaceholderData } = useQuery({
+ *     queryKey: ['posts', page],
+ *     queryFn: () => fetchPosts(page),
+ *     placeholderData: keepPreviousData,
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       {data?.map((post) => <p key={post.id}>{post.title}</p>)}
+ *       <button
+ *         disabled={isPlaceholderData}
+ *         onClick={() => setPage((old) => old + 1)}
+ *       >
+ *         Next Page
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
 export function useQuery<
   TQueryFnData = unknown,
   TError = DefaultError,