@kubb/plugin-react-query 5.0.0-beta.15 → 5.0.0-beta.25

package/src/generators/queryGenerator.tsx

@@ -10,11 +10,16 @@ import { difference } from 'remeda'
 import { Query, QueryKey, QueryOptions } from '../components'
 import type { PluginReactQuery } from '../types'
 
+/**
+ * Built-in generator for `useQuery` hooks. Emits one `useFooQuery` hook per
+ * GET operation (configurable via `query.methods`) plus the matching
+ * `fooQueryKey` / `fooQueryOptions` helpers.
+ */
 export const queryGenerator = defineGenerator<PluginReactQuery>({
   name: 'react-query',
   renderer: jsxRendererSync,
   operation(node, ctx) {
-    const { config, driver, resolver, root, inputNode } = ctx
+    const { config, driver, resolver, root } = ctx
     const { output, query, mutation, paramsCasing, paramsType, pathParamsType, parser, client: clientOptions, group, customOptions } = ctx.options
 
     const pluginTs = driver.getPlugin(pluginTsName)
@@ -39,10 +44,13 @@ export const queryGenerator = defineGenerator<PluginReactQuery>({
     const clientName = resolver.resolveClientName(node)
 
     const meta = {
-      file: resolver.resolveFile({ name: queryName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      file: resolver.resolveFile(
+        { name: queryName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      ),
       fileTs: tsResolver.resolveFile(
         { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-        { root, output: pluginTs.options?.output ?? output, group: pluginTs.options?.group },
+        { root, output: pluginTs.options?.output ?? output, group: pluginTs.options?.group ?? undefined },
       ),
     }
 
@@ -52,20 +60,20 @@ export const queryGenerator = defineGenerator<PluginReactQuery>({
       order: 'body-response-first',
     })
 
-    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : undefined
-    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : undefined
+    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : null
+    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : null
     const fileZod = zodResolver
       ? zodResolver.resolveFile(
           { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-          { root, output: pluginZod?.options?.output ?? output, group: pluginZod?.options?.group },
+          { root, output: pluginZod?.options?.output ?? output, group: pluginZod?.options?.group ?? undefined },
         )
-      : undefined
+      : null
     const zodSchemaNames = resolveZodSchemaNames(node, zodResolver)
 
     const clientPlugin = driver.getPlugin(pluginClientName)
     const hasClientPlugin = clientPlugin?.name === pluginClientName
     const shouldUseClientPlugin = hasClientPlugin && clientOptions.clientType !== 'class'
-    const clientResolver = shouldUseClientPlugin ? driver.getResolver(pluginClientName) : undefined
+    const clientResolver = shouldUseClientPlugin ? driver.getResolver(pluginClientName) : null
 
     const clientFile = shouldUseClientPlugin
       ? clientResolver?.resolveFile(
@@ -73,10 +81,10 @@ export const queryGenerator = defineGenerator<PluginReactQuery>({
           {
             root,
             output: clientPlugin?.options?.output ?? output,
-            group: clientPlugin?.options?.group,
+            group: clientPlugin?.options?.group ?? undefined,
           },
         )
-      : undefined
+      : null
 
     const resolvedClientName = shouldUseClientPlugin ? (clientResolver?.resolveName(node.operationId) ?? clientName) : clientName
 
@@ -85,8 +93,8 @@ export const queryGenerator = defineGenerator<PluginReactQuery>({
         baseName={meta.file.baseName}
         path={meta.file.path}
         meta={meta.file.meta}
-        banner={resolver.resolveBanner(inputNode, { output, config })}
-        footer={resolver.resolveFooter(inputNode, { output, config })}
+        banner={resolver.resolveBanner(ctx.meta, { output, config })}
+        footer={resolver.resolveFooter(ctx.meta, { output, config })}
       >
         {fileZod && zodSchemaNames.length > 0 && <File.Import name={zodSchemaNames} root={meta.file.path} path={fileZod.path} />}
         {clientOptions.importPath ? (

package/src/generators/suspenseInfiniteQueryGenerator.tsx

@@ -10,11 +10,17 @@ import { difference } from 'remeda'
 import { QueryKey, SuspenseInfiniteQuery, SuspenseInfiniteQueryOptions } from '../components'
 import type { PluginReactQuery } from '../types'
 
+/**
+ * Built-in generator for `useSuspenseInfiniteQuery` hooks. Enabled when both
+ * `suspense` and `infinite` are configured. Combines suspense semantics with
+ * cursor-based pagination — handlers throw promises while loading and pull
+ * additional pages on demand.
+ */
 export const suspenseInfiniteQueryGenerator = defineGenerator<PluginReactQuery>({
   name: 'react-suspense-infinite-query',
   renderer: jsxRendererSync,
   operation(node, ctx) {
-    const { config, driver, resolver, root, inputNode } = ctx
+    const { config, driver, resolver, root } = ctx
     const {
       output,
       query,
@@ -40,7 +46,7 @@ export const suspenseInfiniteQueryGenerator = defineGenerator<PluginReactQuery>(
       !isQuery &&
       difference(mutation ? mutation.methods : [], query ? query.methods : []).some((method) => node.method.toLowerCase() === method.toLowerCase())
     const isSuspense = !!suspense
-    const infiniteOptions = infinite && typeof infinite === 'object' ? infinite : undefined
+    const infiniteOptions = infinite && typeof infinite === 'object' ? infinite : null
 
     if (!isQuery || isMutation || !isSuspense || !infiniteOptions) return null
 
@@ -61,29 +67,32 @@ export const suspenseInfiniteQueryGenerator = defineGenerator<PluginReactQuery>(
     const clientBaseName = resolver.resolveSuspenseInfiniteClientName(node)
 
     const meta = {
-      file: resolver.resolveFile({ name: queryName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      file: resolver.resolveFile(
+        { name: queryName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      ),
       fileTs: tsResolver.resolveFile(
         { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-        { root, output: pluginTs.options?.output ?? output, group: pluginTs.options?.group },
+        { root, output: pluginTs.options?.output ?? output, group: pluginTs.options?.group ?? undefined },
       ),
     }
 
     const importedTypeNames = resolveOperationTypeNames(node, tsResolver, { paramsCasing, order: 'body-response-first' })
 
-    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : undefined
-    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : undefined
+    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : null
+    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : null
     const fileZod = zodResolver
       ? zodResolver.resolveFile(
           { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-          { root, output: pluginZod?.options?.output ?? output, group: pluginZod?.options?.group },
+          { root, output: pluginZod?.options?.output ?? output, group: pluginZod?.options?.group ?? undefined },
         )
-      : undefined
+      : null
     const zodSchemaNames = resolveZodSchemaNames(node, zodResolver)
 
     const clientPlugin = driver.getPlugin(pluginClientName)
     const hasClientPlugin = clientPlugin?.name === pluginClientName
     const shouldUseClientPlugin = hasClientPlugin && clientOptions.clientType !== 'class'
-    const clientResolver = shouldUseClientPlugin ? driver.getResolver(pluginClientName) : undefined
+    const clientResolver = shouldUseClientPlugin ? driver.getResolver(pluginClientName) : null
 
     const clientFile = shouldUseClientPlugin
       ? clientResolver?.resolveFile(
@@ -91,10 +100,10 @@ export const suspenseInfiniteQueryGenerator = defineGenerator<PluginReactQuery>(
           {
             root,
             output: clientPlugin?.options?.output ?? output,
-            group: clientPlugin?.options?.group,
+            group: clientPlugin?.options?.group ?? undefined,
           },
         )
-      : undefined
+      : null
 
     const resolvedClientName = shouldUseClientPlugin ? (clientResolver?.resolveName(node.operationId) ?? clientBaseName) : clientBaseName
 
@@ -103,8 +112,8 @@ export const suspenseInfiniteQueryGenerator = defineGenerator<PluginReactQuery>(
         baseName={meta.file.baseName}
         path={meta.file.path}
         meta={meta.file.meta}
-        banner={resolver.resolveBanner(inputNode, { output, config })}
-        footer={resolver.resolveFooter(inputNode, { output, config })}
+        banner={resolver.resolveBanner(ctx.meta, { output, config })}
+        footer={resolver.resolveFooter(ctx.meta, { output, config })}
       >
         {fileZod && zodSchemaNames.length > 0 && <File.Import name={zodSchemaNames} root={meta.file.path} path={fileZod.path} />}
         {clientOptions.importPath ? (

package/src/generators/suspenseQueryGenerator.tsx

@@ -10,11 +10,17 @@ import { difference } from 'remeda'
 import { QueryKey, QueryOptions, SuspenseQuery } from '../components'
 import type { PluginReactQuery } from '../types'
 
+/**
+ * Built-in generator for `useSuspenseQuery` hooks. Enabled when
+ * `pluginReactQuery({ suspense: {} })`. Emits one `useFooSuspenseQuery` hook
+ * per query operation. Suspense queries throw promises while loading and
+ * require a `<Suspense>` boundary in the React tree. TanStack Query v5+ only.
+ */
 export const suspenseQueryGenerator = defineGenerator<PluginReactQuery>({
   name: 'react-suspense-query',
   renderer: jsxRendererSync,
   operation(node, ctx) {
-    const { config, driver, resolver, root, inputNode } = ctx
+    const { config, driver, resolver, root } = ctx
     const { output, query, mutation, suspense, paramsCasing, paramsType, pathParamsType, parser, client: clientOptions, group, customOptions } = ctx.options
 
     const pluginTs = driver.getPlugin(pluginTsName)
@@ -40,10 +46,13 @@ export const suspenseQueryGenerator = defineGenerator<PluginReactQuery>({
     const clientName = resolver.resolveSuspenseClientName(node)
 
     const meta = {
-      file: resolver.resolveFile({ name: queryName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      file: resolver.resolveFile(
+        { name: queryName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      ),
       fileTs: tsResolver.resolveFile(
         { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-        { root, output: pluginTs.options?.output ?? output, group: pluginTs.options?.group },
+        { root, output: pluginTs.options?.output ?? output, group: pluginTs.options?.group ?? undefined },
       ),
     }
 
@@ -53,20 +62,20 @@ export const suspenseQueryGenerator = defineGenerator<PluginReactQuery>({
       order: 'body-response-first',
     })
 
-    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : undefined
-    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : undefined
+    const pluginZod = parser === 'zod' ? driver.getPlugin(pluginZodName) : null
+    const zodResolver = pluginZod ? driver.getResolver(pluginZodName) : null
     const fileZod = zodResolver
       ? zodResolver.resolveFile(
           { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-          { root, output: pluginZod?.options?.output ?? output, group: pluginZod?.options?.group },
+          { root, output: pluginZod?.options?.output ?? output, group: pluginZod?.options?.group ?? undefined },
         )
-      : undefined
+      : null
     const zodSchemaNames = resolveZodSchemaNames(node, zodResolver)
 
     const clientPlugin = driver.getPlugin(pluginClientName)
     const hasClientPlugin = clientPlugin?.name === pluginClientName
     const shouldUseClientPlugin = hasClientPlugin && clientOptions.clientType !== 'class'
-    const clientResolver = shouldUseClientPlugin ? driver.getResolver(pluginClientName) : undefined
+    const clientResolver = shouldUseClientPlugin ? driver.getResolver(pluginClientName) : null
 
     const clientFile = shouldUseClientPlugin
       ? clientResolver?.resolveFile(
@@ -74,10 +83,10 @@ export const suspenseQueryGenerator = defineGenerator<PluginReactQuery>({
           {
             root,
             output: clientPlugin?.options?.output ?? output,
-            group: clientPlugin?.options?.group,
+            group: clientPlugin?.options?.group ?? undefined,
           },
         )
-      : undefined
+      : null
 
     const resolvedClientName = shouldUseClientPlugin ? (clientResolver?.resolveName(node.operationId) ?? clientName) : clientName
 
@@ -86,8 +95,8 @@ export const suspenseQueryGenerator = defineGenerator<PluginReactQuery>({
         baseName={meta.file.baseName}
         path={meta.file.path}
         meta={meta.file.meta}
-        banner={resolver.resolveBanner(inputNode, { output, config })}
-        footer={resolver.resolveFooter(inputNode, { output, config })}
+        banner={resolver.resolveBanner(ctx.meta, { output, config })}
+        footer={resolver.resolveFooter(ctx.meta, { output, config })}
       >
         {fileZod && zodSchemaNames.length > 0 && <File.Import name={zodSchemaNames} root={meta.file.path} path={fileZod.path} />}
         {clientOptions.importPath ? (

package/src/plugin.ts

@@ -20,8 +20,37 @@ import {
 import { resolverReactQuery } from './resolvers/resolverReactQuery.ts'
 import type { PluginReactQuery } from './types.ts'
 
+/**
+ * Canonical plugin name for `@kubb/plugin-react-query`. Used for driver lookups
+ * and cross-plugin dependency references.
+ */
 export const pluginReactQueryName = 'plugin-react-query' satisfies PluginReactQuery['name']
 
+/**
+ * Generates one TanStack Query hook per OpenAPI operation for React. Queries
+ * become `useFooQuery`/`useFooSuspenseQuery`/`useFooInfiniteQuery`; mutations
+ * become `useFooMutation`. Each hook is fully typed: query keys, input
+ * variables, response data, and error shape all come from the spec.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginReactQuery } from '@kubb/plugin-react-query'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginReactQuery({
+ *       output: { path: './hooks' },
+ *       suspense: {},
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
 export const pluginReactQuery = definePlugin<PluginReactQuery>((options) => {
   const {
     output = { path: 'hooks', barrelType: 'named' },
@@ -73,7 +102,7 @@ export const pluginReactQuery = definePlugin<PluginReactQuery>((options) => {
               return `${camelCase(ctx.group)}Controller`
             },
       } satisfies Group)
-    : undefined
+    : null
 
   return {
     name: pluginReactQueryName,
@@ -116,14 +145,14 @@ export const pluginReactQuery = definePlugin<PluginReactQuery>((options) => {
             ? {
                 queryParam: 'id',
                 initialPageParam: 0,
-                cursorParam: undefined,
-                nextParam: undefined,
-                previousParam: undefined,
+                cursorParam: null,
+                nextParam: null,
+                previousParam: null,
                 ...infinite,
               }
             : false,
           suspense,
-          customOptions: customOptions ? { name: 'useCustomHookOptions', ...customOptions } : undefined,
+          customOptions: customOptions ? { name: 'useCustomHookOptions', ...customOptions } : null,
           parser,
           paramsType,
           pathParamsType,

package/src/resolvers/resolverReactQuery.ts

@@ -7,12 +7,23 @@ function capitalize(name: string): string {
 }
 
 /**
- * Naming convention resolver for React Query plugin.
+ * Default resolver used by `@kubb/plugin-react-query`. Decides the names and
+ * file paths for every generated TanStack Query hook (`useFooQuery`,
+ * `useFooMutation`, `useFooInfiniteQuery`, ...) and its companion helpers
+ * (`fooQueryKey`, `fooQueryOptions`).
  *
- * Provides default naming helpers using camelCase for functions and file paths.
+ * Functions and files use camelCase; hooks get the `use` prefix; suspense and
+ * infinite variants are suffixed with `Suspense`/`Infinite`.
  *
- * @example
- * `resolverReactQuery.default('list pets', 'function')  // → 'listPets'`
+ * @example Resolve hook and helper names
+ * ```ts
+ * import { resolverReactQuery } from '@kubb/plugin-react-query'
+ *
+ * resolverReactQuery.resolveQueryName(operationNode)       // 'useGetPetById'
+ * resolverReactQuery.resolveMutationName(operationNode)    // 'useUpdatePet'
+ * resolverReactQuery.resolveQueryKeyName(operationNode)    // 'getPetByIdQueryKey'
+ * resolverReactQuery.resolveQueryOptionsName(operationNode) // 'getPetByIdQueryOptions'
+ * ```
  */
 export const resolverReactQuery = defineResolver<PluginReactQuery>(() => ({
   name: 'default',

package/src/types.ts

@@ -128,27 +128,34 @@ export type ResolverReactQuery = Resolver & {
 type Suspense = object
 
 /**
- * Customize the queryKey.
+ * Builds the `queryKey` used by each generated query hook.
+ *
+ * @note String values are inlined verbatim into generated code. Wrap literal
+ * strings in `JSON.stringify(...)`.
  */
 type QueryKey = Transformer
 
 /**
- * Customize the mutationKey.
+ * Builds the `mutationKey` used by each generated mutation hook.
+ *
+ * @note String values are inlined verbatim into generated code. Wrap literal
+ * strings in `JSON.stringify(...)`.
  */
 type MutationKey = Transformer
 
 type Query = {
   /**
-   * HTTP methods to use for queries.
+   * HTTP methods treated as queries. Operations using these methods produce
+   * `useQuery`-style hooks.
    *
    * @default ['get']
    */
   methods?: Array<string>
   /**
-   * Path to the useQuery hook for useQuery functionality.
-   * Used as `import { useQuery } from '${importPath}'`.
-   * Accepts relative and absolute paths.
-   * Path is used as-is; relative paths are based on the generated file location.
+   * Module specifier used in the `import { useQuery } from '...'` statement at
+   * the top of every generated hook file. Useful for routing through a wrapper
+   * that injects a default `queryClient`.
+   *
    * @default '@tanstack/react-query'
    */
   importPath?: string
@@ -156,16 +163,16 @@ type Query = {
 
 type Mutation = {
   /**
-   * HTTP methods to use for mutations.
+   * HTTP methods treated as mutations. Operations using these methods produce
+   * `useMutation`-style hooks.
    *
    * @default ['post', 'put', 'delete']
    */
   methods?: Array<string>
   /**
-   * Path to the useMutation hook for useMutation functionality.
-   * Used as `import { useMutation } from '${importPath}'`.
-   * Accepts relative and absolute paths.
-   * Path is used as-is; relative paths are based on the generated file location.
+   * Module specifier used in the `import { useMutation } from '...'` statement
+   * at the top of every generated hook file.
+   *
    * @default '@tanstack/react-query'
    */
   importPath?: string
@@ -173,42 +180,45 @@ type Mutation = {
 
 export type Infinite = {
   /**
-   * Specify the params key used for `pageParam`.
+   * Name of the query parameter that holds the page cursor.
+   *
    * @default 'id'
    */
-  queryParam: string
+  queryParam?: string
   /**
-   * Which field of the data is used, set it to undefined when no cursor is known.
-   * @deprecated Use `nextParam` and `previousParam` instead for more flexible pagination handling.
+   * Path to the cursor field on the response. Leave undefined when the cursor
+   * is not known.
+   *
+   * @deprecated Use `nextParam` and `previousParam` for richer pagination control.
    */
-  cursorParam?: string | undefined
+  cursorParam?: string | null
   /**
-   * Which field of the data is used to get the cursor for the next page.
-   * Supports dot notation (e.g. 'pagination.next.id') or array path (e.g. ['pagination', 'next', 'id']) to access nested fields.
+   * Path to the next-page cursor on the response. Supports dot notation
+   * (`'pagination.next.id'`) or array form (`['pagination', 'next', 'id']`).
    */
-  nextParam?: string | string[] | undefined
+  nextParam?: string | Array<string> | null
   /**
-   * Which field of the data is used to get the cursor for the previous page.
-   * Supports dot notation (e.g. 'pagination.prev.id') or array path (e.g. ['pagination', 'prev', 'id']) to access nested fields.
+   * Path to the previous-page cursor on the response. Supports dot notation
+   * or array form.
    */
-  previousParam?: string | string[] | undefined
+  previousParam?: string | Array<string> | null
   /**
-   * The initial value, the value of the first page.
+   * Initial value for `pageParam` on the first fetch.
+   *
    * @default 0
    */
-  initialPageParam: unknown
+  initialPageParam?: unknown
 }
 
 type CustomOptions = {
   /**
-   * Path to the hook that is used to customize the hook options.
-   * It used as `import ${customOptions.name} from '${customOptions.importPath}'`.
-   * It allows both relative and absolute paths but be aware that we will not change the path.
+   * Module specifier of your custom-options hook. Imported as
+   * `import ${name} from '${importPath}'`.
    */
   importPath: string
   /**
-   * Name of the exported hook that is used to customize the hook options.
-   * It used as `import ${customOptions.name} from '${customOptions.importPath}'`.
+   * Exported function name of your custom-options hook.
+   *
    * @default 'useCustomHookOptions'
    */
   name?: string
@@ -216,86 +226,113 @@ type CustomOptions = {
 
 export type Options = {
   /**
-   * Specify the export location for the files and define the behavior of the output
-   * @default { path: 'hooks', barrelType: 'named' }
+   * Where the generated hooks are written and how they are exported.
+   *
+   * @default { path: 'hooks', barrel: { type: 'named' } }
    */
   output?: Output
   /**
-   * Group the @tanstack/query hooks based on the provided name.
+   * Split generated files into subfolders based on the operation's tag.
    */
   group?: Group
+  /**
+   * HTTP client used inside every generated hook. Mirrors a subset of
+   * `pluginClient` options.
+   */
   client?: ClientImportPath & Pick<PluginClient['options'], 'clientType' | 'dataReturnType' | 'baseURL' | 'bundle' | 'paramsCasing'>
   /**
-   * Tags, operations, or paths to exclude from generation.
+   * Skip operations matching at least one entry in the list.
    */
   exclude?: Array<Exclude>
   /**
-   * Tags, operations, or paths to include in generation.
+   * Restrict generation to operations matching at least one entry in the list.
    */
   include?: Array<Include>
   /**
-   * Override options for specific tags, operations, or paths.
+   * Apply a different options object to operations matching a pattern.
    */
   override?: Array<Override<ResolvedOptions>>
   /**
-   * Apply casing to parameter names.
+   * Rename parameter properties in the generated hooks.
+   *
+   * @note Must match the value of `paramsCasing` on `@kubb/plugin-ts`.
    */
   paramsCasing?: 'camelcase'
   /**
-   * How parameters are passed: grouped in an object or spread inline.
+   * How operation parameters appear in the generated hook signature.
+   * - `'inline'` — positional arguments.
+   * - `'object'` — single destructured object argument.
    *
    * @default 'inline'
    */
   paramsType?: 'object' | 'inline'
   /**
-   * How path parameters are passed: grouped in an object or spread inline.
+   * How URL path parameters are arranged inside the inline argument list.
    *
    * @default 'inline'
    */
   pathParamsType?: PluginClient['options']['pathParamsType']
   /**
-   * Add infinite query hooks.
+   * Enables `useInfiniteQuery` hooks for cursor- or page-based pagination.
+   * Pass an object to configure how the cursor is read; pass `false` to skip.
+   *
+   * @default false
    */
   infinite?: Partial<Infinite> | false
   /**
-   * Add suspense query hooks.
+   * Adds `useSuspenseQuery` hooks alongside the regular `useQuery` ones.
+   * Pass an empty object (`{}`) to enable. TanStack Query v5+ only.
    */
   suspense?: Partial<Suspense> | false
+  /**
+   * Custom `queryKey` builder. Use to add a version namespace, swap to
+   * operation IDs, or shape keys to match an existing invalidation strategy.
+   */
   queryKey?: QueryKey
   /**
-   * Configure useQuery behavior.
+   * Configures query hooks. Set to `false` to skip generating hooks entirely
+   * and emit only `queryOptions(...)` helpers.
    */
   query?: Partial<Query> | false
+  /**
+   * Custom `mutationKey` builder. Useful when you batch invalidations or read
+   * mutation state via `useMutationState`.
+   */
   mutationKey?: MutationKey
   /**
-   * Configure useMutation behavior.
+   * Configures mutation hooks. Set to `false` to skip mutation generation.
    */
   mutation?: Partial<Mutation> | false
   /**
-   * Use a custom hook to customize hook options and generate a HookOptions type.
+   * Wires every generated hook through a user-supplied function that returns
+   * extra options (`onSuccess`, `onError`, `select`, ...). Also emits a
+   * `HookOptions` type so the wrapper stays in sync with generated hooks.
    */
   customOptions?: CustomOptions
   /**
-   * Parser to use for validating response data.
+   * Validator applied to response bodies before they reach the caller.
+   * - `'client'` — no validation. Trusts the API.
+   * - `'zod'` — pipes responses through schemas from `@kubb/plugin-zod`.
    */
   parser?: PluginClient['options']['parser']
   /**
-   * Override naming conventions for function names and types.
+   * Override how hook names and file paths are built. Methods you omit fall
+   * back to the default `resolverReactQuery`.
    */
   resolver?: Partial<ResolverReactQuery> & ThisType<ResolverReactQuery>
   /**
-   * AST visitor to transform generated nodes.
+   * AST visitor applied to each operation node before printing.
    */
   transformer?: ast.Visitor
   /**
-   * Additional generators alongside the default generators.
+   * Custom generators that run alongside the built-in React Query generators.
    */
   generators?: Array<Generator<PluginReactQuery>>
 }
 
 type ResolvedOptions = {
   output: Output
-  group: Group | undefined
+  group: Group | null
   exclude: NonNullable<Options['exclude']>
   include: Options['include']
   override: NonNullable<Options['override']>
@@ -309,11 +346,11 @@ type ResolvedOptions = {
    */
   infinite: NonNullable<Infinite> | false
   suspense: Suspense | false
-  queryKey: QueryKey | undefined
+  queryKey: QueryKey | null
   query: NonNullable<Required<Query>> | false
-  mutationKey: MutationKey | undefined
+  mutationKey: MutationKey | null
   mutation: NonNullable<Required<Mutation>> | false
-  customOptions: NonNullable<Required<CustomOptions>> | undefined
+  customOptions: NonNullable<Required<CustomOptions>> | null
   resolver: ResolverReactQuery
 }