@tanstack/preact-query 5.102.8 → 5.103.0

package/build/modern/useSuspenseQuery.d.ts

@@ -18,9 +18,14 @@ import { DefaultError, QueryClient, QueryKey } from "@tanstack/query-core";
  * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
  *
  * @example
+ * The query error is thrown if the fetch fails and no cached data exists yet, so an error boundary is
+ * required around `<Suspense>`. 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 'preact/compat'
- * import { useSuspenseQuery } from '@tanstack/preact-query'
+ * import { useErrorBoundary } from 'preact/hooks'
+ * import { QueryErrorResetBoundary, useSuspenseQuery } from '@tanstack/preact-query'
+ * import type { ComponentChildren } from 'preact'
  *
  * function Posts() {
  *   // `data` is guaranteed to be defined here — no `isPending` check needed.
@@ -31,21 +36,56 @@ import { DefaultError, QueryClient, QueryKey } from "@tanstack/query-core";
  *
  *   return (
  *     <div>
- *       <h1>Posts {isFetching ? <Spinner /> : null}</h1>
- *       {data.map((post) => (
- *         <p key={post.id}>{post.title}</p>
- *       ))}
+ *       <h1>Posts {isFetching ? '(refreshing...)' : null}</h1>
+ *       <ul>
+ *         {data.map((post) => (
+ *           <li key={post.id}>{post.title}</li>
+ *         ))}
+ *       </ul>
  *     </div>
  *   )
  * }
  *
  * function App() {
  *   return (
- *     <Suspense fallback={<h1>Loading posts...</h1>}>
- *       <Posts />
- *     </Suspense>
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary
+ *           onReset={reset}
+ *           fallbackRender={({ resetErrorBoundary }) => (
+ *             <div>
+ *               There was an error!
+ *               <button onClick={() => resetErrorBoundary()}>Try again</button>
+ *             </div>
+ *           )}
+ *         >
+ *           <Suspense fallback={<h1>Loading posts...</h1>}>
+ *             <Posts />
+ *           </Suspense>
+ *         </ErrorBoundary>
+ *       )}
+ *     </QueryErrorResetBoundary>
  *   )
  * }
+ *
+ * function ErrorBoundary({
+ *   children,
+ *   onReset,
+ *   fallbackRender,
+ * }: {
+ *   children: ComponentChildren
+ *   onReset: () => void
+ *   fallbackRender: (props: {
+ *     error: Error
+ *     resetErrorBoundary: () => void
+ *   }) => ComponentChildren
+ * }) {
+ *   const [error, resetErrorBoundary] = useErrorBoundary(() => onReset())
+ *
+ *   if (error) return fallbackRender({ error, resetErrorBoundary })
+ *
+ *   return children
+ * }
  * ```
  */
 declare function useSuspenseQuery<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>, queryClient?: QueryClient): UseSuspenseQueryResult<TData, TError>;

package/build/modern/useSuspenseQuery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSuspenseQuery.d.ts","names":[],"sources":["../../src/useSuspenseQuery.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsDgB,iBACd,wBACA,SAAS,cACT,QAAQ,cACR,kBAAkB,WAAW,UAE7B,SAAS,wBAAwB,cAAc,QAAQ,OAAO,YAC9D,cAAc,cACb,uBAAuB,OAAO"}
+{"version":3,"file":"useSuspenseQuery.d.ts","names":[],"sources":["../../src/useSuspenseQuery.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8FgB,iBACd,wBACA,SAAS,cACT,QAAQ,cACR,kBAAkB,WAAW,UAE7B,SAAS,wBAAwB,cAAc,QAAQ,OAAO,YAC9D,cAAc,cACb,uBAAuB,OAAO"}

package/build/modern/useSuspenseQuery.js

@@ -19,9 +19,14 @@ import { QueryObserver, skipToken } from "@tanstack/query-core";
 * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).
 *
 * @example
+* The query error is thrown if the fetch fails and no cached data exists yet, so an error boundary is
+* required around `<Suspense>`. 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 'preact/compat'
-* import { useSuspenseQuery } from '@tanstack/preact-query'
+* import { useErrorBoundary } from 'preact/hooks'
+* import { QueryErrorResetBoundary, useSuspenseQuery } from '@tanstack/preact-query'
+* import type { ComponentChildren } from 'preact'
 *
 * function Posts() {
 *   // `data` is guaranteed to be defined here — no `isPending` check needed.
@@ -32,21 +37,56 @@ import { QueryObserver, skipToken } from "@tanstack/query-core";
 *
 *   return (
 *     <div>
-*       <h1>Posts {isFetching ? <Spinner /> : null}</h1>
-*       {data.map((post) => (
-*         <p key={post.id}>{post.title}</p>
-*       ))}
+*       <h1>Posts {isFetching ? '(refreshing...)' : null}</h1>
+*       <ul>
+*         {data.map((post) => (
+*           <li key={post.id}>{post.title}</li>
+*         ))}
+*       </ul>
 *     </div>
 *   )
 * }
 *
 * function App() {
 *   return (
-*     <Suspense fallback={<h1>Loading posts...</h1>}>
-*       <Posts />
-*     </Suspense>
+*     <QueryErrorResetBoundary>
+*       {({ reset }) => (
+*         <ErrorBoundary
+*           onReset={reset}
+*           fallbackRender={({ resetErrorBoundary }) => (
+*             <div>
+*               There was an error!
+*               <button onClick={() => resetErrorBoundary()}>Try again</button>
+*             </div>
+*           )}
+*         >
+*           <Suspense fallback={<h1>Loading posts...</h1>}>
+*             <Posts />
+*           </Suspense>
+*         </ErrorBoundary>
+*       )}
+*     </QueryErrorResetBoundary>
 *   )
 * }
+*
+* function ErrorBoundary({
+*   children,
+*   onReset,
+*   fallbackRender,
+* }: {
+*   children: ComponentChildren
+*   onReset: () => void
+*   fallbackRender: (props: {
+*     error: Error
+*     resetErrorBoundary: () => void
+*   }) => ComponentChildren
+* }) {
+*   const [error, resetErrorBoundary] = useErrorBoundary(() => onReset())
+*
+*   if (error) return fallbackRender({ error, resetErrorBoundary })
+*
+*   return children
+* }
 * ```
 */
 function useSuspenseQuery(options, queryClient) {

package/build/modern/useSuspenseQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSuspenseQuery.js","names":[],"sources":["../../src/useSuspenseQuery.ts"],"sourcesContent":["import { QueryObserver, skipToken } from '@tanstack/query-core'\nimport type { DefaultError, QueryClient, QueryKey } from '@tanstack/query-core'\n\nimport { defaultThrowOnError } from './suspense'\nimport type { UseSuspenseQueryOptions, UseSuspenseQueryResult } from './types'\nimport { useBaseQuery } from './useBaseQuery'\n\n/**\n * The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and\n * `placeholderData`.\n *\n * Caveat: cancellation does not work.\n *\n * @remarks Multiple `useSuspenseQuery` calls in the same component suspend serially, causing a request\n * waterfall — each one blocks rendering until it resolves, so the next doesn't even start fetching until then.\n * Use {@link useSuspenseQueries} instead when you have more than one suspenseful query in a component, so they\n * fetch in parallel.\n * @param options - The {@link UseSuspenseQueryOptions} to use — the same options as `useQuery`, minus the ones listed above.\n * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will\n * be used.\n * @returns The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`\n * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).\n *\n * @example\n * ```tsx\n * import { Suspense } from 'preact/compat'\n * import { useSuspenseQuery } from '@tanstack/preact-query'\n *\n * function Posts() {\n *   // `data` is guaranteed to be defined here — no `isPending` check needed.\n *   const { data, isFetching } = useSuspenseQuery({\n *     queryKey: ['posts'],\n *     queryFn: fetchPosts,\n *   })\n *\n *   return (\n *     <div>\n *       <h1>Posts {isFetching ? <Spinner /> : null}</h1>\n *       {data.map((post) => (\n *         <p key={post.id}>{post.title}</p>\n *       ))}\n *     </div>\n *   )\n * }\n *\n * function App() {\n *   return (\n *     <Suspense fallback={<h1>Loading posts...</h1>}>\n *       <Posts />\n *     </Suspense>\n *   )\n * }\n * ```\n */\nexport function useSuspenseQuery<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n  queryClient?: QueryClient,\n): UseSuspenseQueryResult<TData, TError> {\n  if (process.env.NODE_ENV !== 'production') {\n    if ((options.queryFn as any) === skipToken) {\n      console.error('skipToken is not allowed for useSuspenseQuery')\n    }\n  }\n\n  return useBaseQuery(\n    {\n      ...options,\n      enabled: true,\n      suspense: true,\n      throwOnError: defaultThrowOnError,\n      placeholderData: undefined,\n    },\n    QueryObserver,\n    queryClient,\n  ) as UseSuspenseQueryResult<TData, TError>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,SAAgB,iBAMd,SACA,aACuC;CACvC,IAAI,QAAQ,IAAI,aAAa,cACtB;MAAA,QAAQ,YAAoB,WAC/B,QAAQ,MAAM,+CAA+C;CAAA;CAIjE,OAAO,aACL;EACE,GAAG;EACH,SAAS;EACT,UAAU;EACV,cAAc;EACd,iBAAiB,KAAA;CACnB,GACA,eACA,WACF;AACF"}
+{"version":3,"file":"useSuspenseQuery.js","names":[],"sources":["../../src/useSuspenseQuery.ts"],"sourcesContent":["import { QueryObserver, skipToken } from '@tanstack/query-core'\nimport type { DefaultError, QueryClient, QueryKey } from '@tanstack/query-core'\n\nimport { defaultThrowOnError } from './suspense'\nimport type { UseSuspenseQueryOptions, UseSuspenseQueryResult } from './types'\nimport { useBaseQuery } from './useBaseQuery'\n\n/**\n * The options for `useSuspenseQuery` are the same as for `useQuery`, except for `throwOnError`, `enabled`, and\n * `placeholderData`.\n *\n * Caveat: cancellation does not work.\n *\n * @remarks Multiple `useSuspenseQuery` calls in the same component suspend serially, causing a request\n * waterfall — each one blocks rendering until it resolves, so the next doesn't even start fetching until then.\n * Use {@link useSuspenseQueries} instead when you have more than one suspenseful query in a component, so they\n * fetch in parallel.\n * @param options - The {@link UseSuspenseQueryOptions} to use — the same options as `useQuery`, minus the ones listed above.\n * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will\n * be used.\n * @returns The same object as `useQuery`, except that `data` is guaranteed to be defined, `isPlaceholderData`\n * is missing, and `status` is either `success` or `error` (with the derived flags set accordingly).\n *\n * @example\n * The query error is thrown if the fetch fails and no cached data exists yet, so an error boundary is\n * required around `<Suspense>`. A failed background refetch instead continues to render the cached data.\n * Use {@link QueryErrorResetBoundary} to let the user retry after such an error:\n * ```tsx\n * import { Suspense } from 'preact/compat'\n * import { useErrorBoundary } from 'preact/hooks'\n * import { QueryErrorResetBoundary, useSuspenseQuery } from '@tanstack/preact-query'\n * import type { ComponentChildren } from 'preact'\n *\n * function Posts() {\n *   // `data` is guaranteed to be defined here — no `isPending` check needed.\n *   const { data, isFetching } = useSuspenseQuery({\n *     queryKey: ['posts'],\n *     queryFn: fetchPosts,\n *   })\n *\n *   return (\n *     <div>\n *       <h1>Posts {isFetching ? '(refreshing...)' : null}</h1>\n *       <ul>\n *         {data.map((post) => (\n *           <li key={post.id}>{post.title}</li>\n *         ))}\n *       </ul>\n *     </div>\n *   )\n * }\n *\n * function App() {\n *   return (\n *     <QueryErrorResetBoundary>\n *       {({ reset }) => (\n *         <ErrorBoundary\n *           onReset={reset}\n *           fallbackRender={({ resetErrorBoundary }) => (\n *             <div>\n *               There was an error!\n *               <button onClick={() => resetErrorBoundary()}>Try again</button>\n *             </div>\n *           )}\n *         >\n *           <Suspense fallback={<h1>Loading posts...</h1>}>\n *             <Posts />\n *           </Suspense>\n *         </ErrorBoundary>\n *       )}\n *     </QueryErrorResetBoundary>\n *   )\n * }\n *\n * function ErrorBoundary({\n *   children,\n *   onReset,\n *   fallbackRender,\n * }: {\n *   children: ComponentChildren\n *   onReset: () => void\n *   fallbackRender: (props: {\n *     error: Error\n *     resetErrorBoundary: () => void\n *   }) => ComponentChildren\n * }) {\n *   const [error, resetErrorBoundary] = useErrorBoundary(() => onReset())\n *\n *   if (error) return fallbackRender({ error, resetErrorBoundary })\n *\n *   return children\n * }\n * ```\n */\nexport function useSuspenseQuery<\n  TQueryFnData = unknown,\n  TError = DefaultError,\n  TData = TQueryFnData,\n  TQueryKey extends QueryKey = QueryKey,\n>(\n  options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,\n  queryClient?: QueryClient,\n): UseSuspenseQueryResult<TData, TError> {\n  if (process.env.NODE_ENV !== 'production') {\n    if ((options.queryFn as any) === skipToken) {\n      console.error('skipToken is not allowed for useSuspenseQuery')\n    }\n  }\n\n  return useBaseQuery(\n    {\n      ...options,\n      enabled: true,\n      suspense: true,\n      throwOnError: defaultThrowOnError,\n      placeholderData: undefined,\n    },\n    QueryObserver,\n    queryClient,\n  ) as UseSuspenseQueryResult<TData, TError>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,SAAgB,iBAMd,SACA,aACuC;CACvC,IAAI,QAAQ,IAAI,aAAa,cACtB;MAAA,QAAQ,YAAoB,WAC/B,QAAQ,MAAM,+CAA+C;CAAA;CAIjE,OAAO,aACL;EACE,GAAG;EACH,SAAS;EACT,UAAU;EACV,cAAc;EACd,iBAAiB,KAAA;CACnB,GACA,eACA,WACF;AACF"}

package/build/query-codemods/eslint.config.js

@@ -15,4 +15,11 @@ export default [
       'sort-imports': 'off',
     },
   },
+  {
+    files: ['src/**/__testfixtures__/**'],
+    rules: {
+      // Codemod fixtures intentionally preserve historical QueryClient syntax.
+      'no-restricted-syntax': 'off',
+    },
+  },
 ]

package/build/query-codemods/root.eslint.config.js

@@ -44,6 +44,51 @@ export default [
       '@typescript-eslint/no-empty-function': 'off',
       '@typescript-eslint/no-unsafe-function-type': 'off',
       'no-case-declarations': 'off',
+      /**
+       * Disallows direct calls to deprecated imperative query methods of `QueryClient`
+       * for new tests and code
+       *
+       * Existing tests that directly test the methods from before the refactoring
+       * will be grandfathered in and allowed to continue using the deprecated methods.
+       * They should not be removed, but new tests should use the new methods instead.
+       */
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="fetchQuery"], [callee.computed=true][callee.property.value="fetchQuery"])',
+          message: 'Use queryClient.query(options) instead.',
+        },
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="prefetchQuery"], [callee.computed=true][callee.property.value="prefetchQuery"])',
+          message:
+            'Use queryClient.query(options).catch(noop) instead if errors should be swallowed.',
+        },
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="ensureQueryData"], [callee.computed=true][callee.property.value="ensureQueryData"])',
+          message:
+            "Use queryClient.query({ ...options, staleTime: 'static' }) instead.",
+        },
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="fetchInfiniteQuery"], [callee.computed=true][callee.property.value="fetchInfiniteQuery"])',
+          message: 'Use queryClient.infiniteQuery(options) instead.',
+        },
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="prefetchInfiniteQuery"], [callee.computed=true][callee.property.value="prefetchInfiniteQuery"])',
+          message:
+            'Use queryClient.infiniteQuery(options).catch(noop) instead if errors should be swallowed.',
+        },
+        {
+          selector:
+            'CallExpression[callee.type="MemberExpression"]:matches([callee.property.name="ensureInfiniteQueryData"], [callee.computed=true][callee.property.value="ensureInfiniteQueryData"])',
+          message:
+            "Use queryClient.infiniteQuery({ ...options, staleTime: 'static' }) instead.",
+        },
+      ],
       'prefer-const': 'off',
     },
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/preact-query",
-  "version": "5.102.8",
+  "version": "5.103.0",
   "description": "Hooks for managing, caching and syncing asynchronous and remote data in preact",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "!build/codemods/**/__tests__"
   ],
   "dependencies": {
-    "@tanstack/query-core": "5.102.8"
+    "@tanstack/query-core": "5.103.0"
   },
   "devDependencies": {
     "@preact/preset-vite": "^2.10.2",
@@ -55,23 +55,23 @@
     "preact-render-to-string": "^6.6.4",
     "typescript": "6.0.3",
     "typescript-eslint": "^8.54.0",
-    "@tanstack/query-persist-client-core": "5.102.8",
+    "@tanstack/query-persist-client-core": "5.103.0",
     "@tanstack/query-test-utils": "0.0.0"
   },
   "peerDependencies": {
     "preact": "^10.0.0"
   },
   "scripts": {
-    "clean": "premove ./build ./coverage ./dist-ts",
-    "compile": "tsc --build",
+    "clean": "premove ./build ./coverage ./dist-ts ./.cache/test-types",
+    "compile": "tsc --project tsconfig.json",
     "test:eslint": "eslint --concurrency=auto ./src",
     "test:types": "npm-run-all --serial test:types:*",
-    "test:types:ts56": "node ../../node_modules/typescript56/lib/tsc.js --build tsconfig.legacy.json",
-    "test:types:ts57": "node ../../node_modules/typescript57/lib/tsc.js --build tsconfig.legacy.json",
-    "test:types:ts58": "node ../../node_modules/typescript58/lib/tsc.js --build tsconfig.legacy.json",
-    "test:types:ts59": "node ../../node_modules/typescript59/lib/tsc.js --build tsconfig.legacy.json",
-    "test:types:tscurrent": "tsc --build",
-    "test:types:ts70": "node ../../node_modules/typescript70/lib/tsc.js --build",
+    "test:types:ts56": "node ../../node_modules/typescript56/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts56 --tsBuildInfoFile .cache/test-types/ts56.tsbuildinfo",
+    "test:types:ts57": "node ../../node_modules/typescript57/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts57 --tsBuildInfoFile .cache/test-types/ts57.tsbuildinfo",
+    "test:types:ts58": "node ../../node_modules/typescript58/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts58 --tsBuildInfoFile .cache/test-types/ts58.tsbuildinfo",
+    "test:types:ts59": "node ../../node_modules/typescript59/lib/tsc.js --project tsconfig.legacy.json --outDir .cache/test-types/ts59 --tsBuildInfoFile .cache/test-types/ts59.tsbuildinfo",
+    "test:types:tscurrent": "tsc --project tsconfig.json --outDir .cache/test-types/tscurrent --tsBuildInfoFile .cache/test-types/tscurrent.tsbuildinfo",
+    "test:types:ts70": "node ../../node_modules/typescript70/lib/tsc.js --project tsconfig.json --outDir .cache/test-types/ts70 --tsBuildInfoFile .cache/test-types/ts70.tsbuildinfo",
     "test:lib": "vitest",
     "test:lib:dev": "pnpm run test:lib --watch",
     "test:build": "publint --strict && attw --pack",

package/src/HydrationBoundary.tsx

@@ -138,7 +138,6 @@ export const HydrationBoundary = ({
             (dehydratedQuery.promise &&
               existingQuery.state.status !== 'pending' &&
               existingQuery.state.fetchStatus !== 'fetching' &&
-              dehydratedQuery.dehydratedAt !== undefined &&
               dehydratedQuery.dehydratedAt > existingQuery.state.dataUpdatedAt)
 
           if (hydrationIsNewer) {

package/src/QueryErrorResetBoundary.tsx

@@ -122,6 +122,18 @@ export interface QueryErrorResetBoundaryProps {
  * import type { ComponentChildren } from 'preact'
  * import { QueryErrorResetBoundary } from '@tanstack/preact-query'
  *
+ * function App() {
+ *   return (
+ *     <QueryErrorResetBoundary>
+ *       {({ reset }) => (
+ *         <ErrorBoundary reset={reset}>
+ *           <Page />
+ *         </ErrorBoundary>
+ *       )}
+ *     </QueryErrorResetBoundary>
+ *   )
+ * }
+ *
  * function ErrorBoundary({
  *   children,
  *   reset,
@@ -142,18 +154,6 @@ export interface QueryErrorResetBoundaryProps {
  *
  *   return children
  * }
- *
- * function App() {
- *   return (
- *     <QueryErrorResetBoundary>
- *       {({ reset }) => (
- *         <ErrorBoundary reset={reset}>
- *           <Page />
- *         </ErrorBoundary>
- *       )}
- *     </QueryErrorResetBoundary>
- *   )
- * }
  * ```
  */
 export const QueryErrorResetBoundary = ({

package/src/infiniteQueryOptions.ts

@@ -74,7 +74,9 @@ export type UnusedSkipTokenInfiniteOptions<
 > & {
   /**
    * `skipToken` is not allowed as a value here — this overload is selected when no `initialData` is set. If
-   * you don't intend to run the query yet, omit `queryFn` or use a default query function instead.
+   * you don't intend to run the query yet, set `enabled: false` — omitting `queryFn` alone still triggers a
+   * fetch that fails with "Missing queryFn" unless `enabled` is `false` or a default query function has been
+   * defined. A default query function only supplies `queryFn`; it doesn't defer the fetch on its own.
    */
   queryFn?: Exclude<
     UseInfiniteQueryOptions<
@@ -135,6 +137,8 @@ export type DefinedInitialDataInfiniteOptions<
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
  * @param options - The {@link DefinedInitialDataInfiniteOptions} to use — everything you can pass to `useInfiniteQuery`, with `initialData` set.
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ * @remarks See {@link useInfiniteQuery} for examples that fetch further pages, from a button click or
+ * automatically as the user scrolls.
  *
  * @example
  * ```tsx
@@ -149,8 +153,18 @@ export type DefinedInitialDataInfiniteOptions<
  * })
  *
  * function Projects() {
- *   const { data } = useInfiniteQuery(projectsOptions)
- *   return <>{data.pages.map((page) => page.projects.map((p) => <p key={p.id}>{p.name}</p>))}</>
+ *   // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the
+ *   // list stays visible alongside the error.
+ *   const { data, isError, error } = useInfiniteQuery(projectsOptions)
+ *
+ *   return (
+ *     <div>
+ *       {isError ? <span>Error: {error.message}</span> : null}
+ *       <ul>
+ *         {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}
+ *       </ul>
+ *     </div>
+ *   )
  * }
  * ```
  */
@@ -183,27 +197,13 @@ export function infiniteQueryOptions<
  * `options.queryKey` is required and is the query key to generate options for.
  *
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ * @remarks See {@link useInfiniteQuery} for examples that fetch further pages, from a button click or
+ * automatically as the user scrolls.
  *
  * @example
+ * A parameterized factory, so the same options object can be reused per `postId`:
  * ```tsx
- * import { infiniteQueryOptions } from '@tanstack/preact-query'
- *
- * export const projectsOptions = infiniteQueryOptions({
- *   queryKey: ['projects'],
- *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *   initialPageParam: 0,
- *   getNextPageParam: (lastPage) => lastPage.nextId,
- * })
- * ```
- *
- * @example
- * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
- * ```tsx
- * import {
- *   infiniteQueryOptions,
- *   noop,
- *   useInfiniteQuery,
- * } from '@tanstack/preact-query'
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
  *
  * export const commentsOptions = (postId: string) =>
  *   infiniteQueryOptions({
@@ -214,17 +214,17 @@ export function infiniteQueryOptions<
  *   })
  *
  * function Comments({ postId }: { postId: string }) {
- *   const result = useInfiniteQuery(commentsOptions(postId))
- *   if (!result.isSuccess) return 'Loading...'
+ *   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
- *     <>
- *       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
- *     </>
+ *     <ul>
+ *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *     </ul>
  *   )
  * }
- *
- * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
- * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
  * ```
  *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.
@@ -259,27 +259,13 @@ export function infiniteQueryOptions<
  * `options.queryKey` is required and is the query key to generate options for.
  *
  * @returns The same options object, typed so that `queryKey` carries the inferred data type.
+ * @remarks See {@link useInfiniteQuery} for examples that fetch further pages (from a button click or
+ * automatically as the user scrolls) and that use `skipToken` to disable the query until `postId` is set.
  *
  * @example
+ * A parameterized factory, so the same options object can be reused per `postId`:
  * ```tsx
- * import { infiniteQueryOptions } from '@tanstack/preact-query'
- *
- * export const projectsOptions = infiniteQueryOptions({
- *   queryKey: ['projects'],
- *   queryFn: ({ pageParam }) => fetchProjects(pageParam),
- *   initialPageParam: 0,
- *   getNextPageParam: (lastPage) => lastPage.nextId,
- * })
- * ```
- *
- * @example
- * A parameterized factory, reused across a hook and an imperative call with the same cache entry:
- * ```tsx
- * import {
- *   infiniteQueryOptions,
- *   noop,
- *   useInfiniteQuery,
- * } from '@tanstack/preact-query'
+ * import { infiniteQueryOptions, useInfiniteQuery } from '@tanstack/preact-query'
  *
  * export const commentsOptions = (postId: string) =>
  *   infiniteQueryOptions({
@@ -290,17 +276,17 @@ export function infiniteQueryOptions<
  *   })
  *
  * function Comments({ postId }: { postId: string }) {
- *   const result = useInfiniteQuery(commentsOptions(postId))
- *   if (!result.isSuccess) return 'Loading...'
+ *   const { data, isPending, isError, error } = useInfiniteQuery(commentsOptions(postId))
+ *
+ *   if (isPending) return 'Loading...'
+ *   if (isError) return <span>Error: {error.message}</span>
+ *
  *   return (
- *     <>
- *       {result.data.pages.map((page) => page.comments.map((c) => <p key={c.id}>{c.text}</p>))}
- *     </>
+ *     <ul>
+ *       {data.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}
+ *     </ul>
  *   )
  * }
- *
- * // Elsewhere, e.g. to warm the cache before rendering `<Comments>`:
- * queryClient.infiniteQuery(commentsOptions(postId)).catch(noop)
  * ```
  *
  * @see {@link useInfiniteQuery} to run an infinite query with these options.

package/src/mutationOptions.ts

@@ -13,21 +13,6 @@ import type { UseMutationOptions } from './types'
  * @returns The same options object, unchanged.
  *
  * @example
- * ```tsx
- * import { mutationOptions, useMutation } from '@tanstack/preact-query'
- *
- * export const createPostOptions = mutationOptions({
- *   mutationKey: ['posts', 'create'],
- *   mutationFn: createPost,
- * })
- *
- * function CreatePost() {
- *   const mutation = useMutation(createPostOptions)
- *   return <button onClick={() => mutation.mutate({ title: 'Hello' })}>Create</button>
- * }
- * ```
- *
- * @example
  * Looking the mutation up elsewhere via its `mutationKey`, e.g. for a global "saving…" indicator:
  * ```tsx
  * import { mutationOptions, useMutationState } from '@tanstack/preact-query'
@@ -62,13 +47,15 @@ export function mutationOptions<
 >
 /**
  * You can generally pass everything to `mutationOptions` that you can also pass to `useMutation`. No
- * `mutationKey` is required on this overload — use this when you don't need to look the mutation up later
- * (e.g. with `useMutationState`).
+ * `mutationKey` is required on this overload — use this when you don't need to target the mutation via a
+ * `mutationKey` filter later (e.g. with `useMutationState`); it can still be observed through other filters,
+ * such as `status`.
  *
  * @see {@link useMutation} to run the mutation these options describe.
  * @param options - The mutation options to use, identical to what you'd pass to `useMutation`, without a
  * `mutationKey`.
  * @returns The same options object, unchanged.
+ * @remarks See the other overload's example for looking a mutation up via `useMutationState`.
  *
  * @example
  * ```tsx