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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-react-query",
-  "version": "5.0.0-beta.22",
+  "version": "5.0.0-beta.25",
   "description": "Generate type-safe TanStack Query (React Query) hooks from your OpenAPI specification. Covers useQuery, useMutation, useInfiniteQuery, and queryOptions with full TypeScript support.",
   "keywords": [
     "code-generation",
@@ -68,12 +68,12 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.22",
-    "@kubb/renderer-jsx": "5.0.0-beta.22",
+    "@kubb/core": "5.0.0-beta.25",
+    "@kubb/renderer-jsx": "5.0.0-beta.25",
     "remeda": "^2.34.1",
-    "@kubb/plugin-client": "5.0.0-beta.22",
-    "@kubb/plugin-ts": "5.0.0-beta.22",
-    "@kubb/plugin-zod": "5.0.0-beta.22"
+    "@kubb/plugin-client": "5.0.0-beta.25",
+    "@kubb/plugin-ts": "5.0.0-beta.25",
+    "@kubb/plugin-zod": "5.0.0-beta.25"
   },
   "devDependencies": {
     "@internals/shared": "0.0.0",
@@ -81,7 +81,7 @@
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.22"
+    "@kubb/renderer-jsx": "5.0.0-beta.25"
   },
   "size-limit": [
     {

package/src/components/InfiniteQuery.tsx

@@ -39,7 +39,7 @@ function buildInfiniteQueryParamsNode(
   },
 ): ast.FunctionParametersNode {
   const { paramsType, paramsCasing, pathParamsType, resolver, pageParamGeneric } = options
-  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : undefined
+  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null
 
   const optionsParam = ast.createFunctionParameter({
     name: 'options',
@@ -104,11 +104,11 @@ export function InfiniteQuery({
       ? (() => {
           const groupName = tsResolver.resolveQueryParamsName(node, rawQueryParams[0]!)
           const individualName = tsResolver.resolveParamName(node, rawQueryParams[0]!)
-          return groupName !== individualName ? groupName : undefined
+          return groupName !== individualName ? groupName : null
         })()
-      : undefined
+      : null
 
-  const queryParamType = queryParam && queryParamsTypeName ? `${queryParamsTypeName}['${queryParam}']` : undefined
+  const queryParamType = queryParam && queryParamsTypeName ? `${queryParamsTypeName}['${queryParam}']` : null
   const pageParamType = queryParamType ? (isInitialPageParamDefined ? `NonNullable<${queryParamType}>` : queryParamType) : fallbackPageParamType
 
   const returnType = 'UseInfiniteQueryResult<TData, TError> & { queryKey: TQueryKey }'

package/src/components/InfiniteQueryOptions.tsx

@@ -72,11 +72,11 @@ export function InfiniteQueryOptions({
       ? (() => {
           const groupName = tsResolver.resolveQueryParamsName(node, rawQueryParams[0]!)
           const individualName = tsResolver.resolveParamName(node, rawQueryParams[0]!)
-          return groupName !== individualName ? groupName : undefined
+          return groupName !== individualName ? groupName : null
         })()
-      : undefined
+      : null
 
-  const queryParamType = queryParam && queryParamsTypeName ? `${queryParamsTypeName}['${queryParam}']` : undefined
+  const queryParamType = queryParam && queryParamsTypeName ? `${queryParamsTypeName}['${queryParam}']` : null
   const pageParamType = queryParamType ? (isInitialPageParamDefined ? `NonNullable<${queryParamType}>` : queryParamType) : fallbackPageParamType
 
   const paramsNode = getQueryOptionsParams(node, { paramsType, paramsCasing, pathParamsType, resolver: tsResolver })
@@ -90,15 +90,15 @@ export function InfiniteQueryOptions({
   const enabledSource = buildEnabledCheck(queryKeyParamsNode)
   const enabledText = enabledSource ? `enabled: !!(${enabledSource}),` : ''
 
-  const hasNewParams = nextParam !== undefined || previousParam !== undefined
+  const hasNewParams = nextParam != null || previousParam != null
 
   const [getNextPageParamExpr, getPreviousPageParamExpr] = (() => {
     if (hasNewParams) {
-      const nextAccessor = nextParam ? getNestedAccessor(nextParam, 'lastPage') : undefined
-      const prevAccessor = previousParam ? getNestedAccessor(previousParam, 'firstPage') : undefined
+      const nextAccessor = nextParam ? getNestedAccessor(nextParam, 'lastPage') : null
+      const prevAccessor = previousParam ? getNestedAccessor(previousParam, 'firstPage') : null
       return [
-        nextAccessor ? `getNextPageParam: (lastPage) => ${nextAccessor}` : undefined,
-        prevAccessor ? `getPreviousPageParam: (firstPage) => ${prevAccessor}` : undefined,
+        nextAccessor ? `getNextPageParam: (lastPage) => ${nextAccessor}` : null,
+        prevAccessor ? `getPreviousPageParam: (firstPage) => ${prevAccessor}` : null,
       ] as const
     }
     if (cursorParam) {

package/src/components/Mutation.tsx

@@ -58,7 +58,7 @@ function buildMutationParamsNode(
     resolver,
   })
   const TRequest = mutationArgParamsNode.params.length > 0 ? (declarationPrinter.print(mutationArgParamsNode) ?? '') : ''
-  const generics = [TData, TError, TRequest ? `{${TRequest}}` : 'void', 'TContext'].join(', ')
+  const generics = [TData, TError, TRequest ? `{${TRequest}}` : 'undefined', 'TContext'].join(', ')
 
   return ast.createFunctionParameters({
     params: [
@@ -89,7 +89,7 @@ export function Mutation({ name, mutationOptionsName, paramsCasing, dataReturnTy
     resolver: tsResolver,
   })
   const TRequest = mutationArgParamsNode.params.length > 0 ? (declarationPrinter.print(mutationArgParamsNode) ?? '') : ''
-  const generics = [TData, TError, TRequest ? `{${TRequest}}` : 'void', 'TContext'].join(', ')
+  const generics = [TData, TError, TRequest ? `{${TRequest}}` : 'undefined', 'TContext'].join(', ')
   const returnType = `UseMutationResult<${generics}>`
 
   const mutationOptionsConfigNode = buildMutationConfigParamsNode(node, tsResolver)

package/src/components/MutationOptions.tsx

@@ -90,7 +90,7 @@ export function MutationOptions({
       <Function name={name} export params={paramsSignature} generics={['TContext = unknown']}>
         {`
       const mutationKey = ${mutationKeyName}()
-      return mutationOptions<${TData}, ${TError}, ${TRequest ? `{${TRequest}}` : 'void'}, TContext>({
+      return mutationOptions<${TData}, ${TError}, ${TRequest ? `{${TRequest}}` : 'undefined'}, TContext>({
         mutationKey,
         mutationFn: async(${hasMutationParams ? `{ ${argKeysStr} }` : '_'}) => {
           return ${clientName}(${clientCallStr})

package/src/components/Query.tsx

@@ -36,7 +36,7 @@ function buildQueryParamsNode(
 ): ast.FunctionParametersNode {
   const { paramsType, paramsCasing, pathParamsType, dataReturnType, resolver } = options
   const responseName = resolver.resolveResponseName(node)
-  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : undefined
+  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null
   const errorNames = resolveErrorNames(node, resolver)
 
   const TData = dataReturnType === 'data' ? responseName : `ResponseConfig<${responseName}>`

package/src/components/QueryOptions.tsx

@@ -32,7 +32,7 @@ export function getQueryOptionsParams(
   },
 ): ast.FunctionParametersNode {
   const { paramsType, paramsCasing, pathParamsType, resolver } = options
-  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : undefined
+  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null
 
   return ast.createOperationParams(node, {
     paramsType,

package/src/components/SuspenseInfiniteQuery.tsx

@@ -39,7 +39,7 @@ function buildSuspenseInfiniteQueryParamsNode(
   },
 ): ast.FunctionParametersNode {
   const { paramsType, paramsCasing, pathParamsType, resolver, pageParamGeneric } = options
-  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : undefined
+  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null
 
   const optionsParam = ast.createFunctionParameter({
     name: 'options',
@@ -104,11 +104,11 @@ export function SuspenseInfiniteQuery({
       ? (() => {
           const groupName = tsResolver.resolveQueryParamsName(node, rawQueryParams[0]!)
           const individualName = tsResolver.resolveParamName(node, rawQueryParams[0]!)
-          return groupName !== individualName ? groupName : undefined
+          return groupName !== individualName ? groupName : null
         })()
-      : undefined
+      : null
 
-  const queryParamType = queryParam && queryParamsTypeName ? `${queryParamsTypeName}['${queryParam}']` : undefined
+  const queryParamType = queryParam && queryParamsTypeName ? `${queryParamsTypeName}['${queryParam}']` : null
   const pageParamType = queryParamType ? (isInitialPageParamDefined ? `NonNullable<${queryParamType}>` : queryParamType) : fallbackPageParamType
 
   const returnType = 'UseSuspenseInfiniteQueryResult<TData, TError> & { queryKey: TQueryKey }'

package/src/components/SuspenseInfiniteQueryOptions.tsx

@@ -72,11 +72,11 @@ export function SuspenseInfiniteQueryOptions({
       ? (() => {
           const groupName = tsResolver.resolveQueryParamsName(node, rawQueryParams[0]!)
           const individualName = tsResolver.resolveParamName(node, rawQueryParams[0]!)
-          return groupName !== individualName ? groupName : undefined
+          return groupName !== individualName ? groupName : null
         })()
-      : undefined
+      : null
 
-  const queryParamType = queryParam && queryParamsTypeName ? `${queryParamsTypeName}['${queryParam}']` : undefined
+  const queryParamType = queryParam && queryParamsTypeName ? `${queryParamsTypeName}['${queryParam}']` : null
   const pageParamType = queryParamType ? (isInitialPageParamDefined ? `NonNullable<${queryParamType}>` : queryParamType) : fallbackPageParamType
 
   const paramsNode = getQueryOptionsParams(node, { paramsType, paramsCasing, pathParamsType, resolver: tsResolver })
@@ -90,15 +90,15 @@ export function SuspenseInfiniteQueryOptions({
   const enabledSource = buildEnabledCheck(queryKeyParamsNode)
   const enabledText = enabledSource ? `enabled: !!(${enabledSource}),` : ''
 
-  const hasNewParams = nextParam !== undefined || previousParam !== undefined
+  const hasNewParams = nextParam != null || previousParam != null
 
   const [getNextPageParamExpr, getPreviousPageParamExpr] = (() => {
     if (hasNewParams) {
-      const nextAccessor = nextParam ? getNestedAccessor(nextParam, 'lastPage') : undefined
-      const prevAccessor = previousParam ? getNestedAccessor(previousParam, 'firstPage') : undefined
+      const nextAccessor = nextParam ? getNestedAccessor(nextParam, 'lastPage') : null
+      const prevAccessor = previousParam ? getNestedAccessor(previousParam, 'firstPage') : null
       return [
-        nextAccessor ? `getNextPageParam: (lastPage) => ${nextAccessor}` : undefined,
-        prevAccessor ? `getPreviousPageParam: (firstPage) => ${prevAccessor}` : undefined,
+        nextAccessor ? `getNextPageParam: (lastPage) => ${nextAccessor}` : null,
+        prevAccessor ? `getPreviousPageParam: (firstPage) => ${prevAccessor}` : null,
       ] as const
     }
     if (cursorParam) {

package/src/components/SuspenseQuery.tsx

@@ -36,7 +36,7 @@ function buildSuspenseQueryParamsNode(
 ): ast.FunctionParametersNode {
   const { paramsType, paramsCasing, pathParamsType, dataReturnType, resolver } = options
   const responseName = resolver.resolveResponseName(node)
-  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : undefined
+  const requestName = node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null
   const errorNames = resolveErrorNames(node, resolver)
 
   const TData = dataReturnType === 'data' ? responseName : `ResponseConfig<${responseName}>`

package/src/generators/customHookOptionsFileGenerator.tsx

@@ -5,6 +5,12 @@ import { defineGenerator } from '@kubb/core'
 import { File, Function, jsxRendererSync } from '@kubb/renderer-jsx'
 import type { PluginReactQuery } from '../types'
 
+/**
+ * Scaffolds the user-editable `useCustomHookOptions` file when
+ * `pluginReactQuery({ customOptions: { ... } })` is configured. The file is
+ * only created when it does not already exist, so user edits persist across
+ * regeneration.
+ */
 export const customHookOptionsFileGenerator = defineGenerator<PluginReactQuery>({
   name: 'react-query-custom-hook-options-file',
   renderer: jsxRendererSync,
@@ -27,7 +33,7 @@ export const customHookOptionsFileGenerator = defineGenerator<PluginReactQuery>(
       const hookName = resolver.resolveQueryName(firstNode)
       const hookFile = resolver.resolveFile(
         { name: hookName, extname: '.ts', tag: firstNode.tags[0] ?? 'default', path: firstNode.path },
-        { root, output, group },
+        { root, output, group: group ?? undefined },
       )
       hookFilePath = hookFile.path
     } else {

package/src/generators/hookOptionsGenerator.tsx

@@ -9,6 +9,12 @@ import { resolveOperationOverrides } from '../utils.ts'
 type QueryOption = PluginReactQuery['resolvedOptions']['query']
 type MutationOption = PluginReactQuery['resolvedOptions']['mutation']
 
+/**
+ * Emits the `HookOptions` type used by `customOptions`. Enabled when
+ * `pluginReactQuery({ customOptions: { ... } })`. The generated type lists
+ * every hook keyed by name so user-supplied options stay in sync with the
+ * generated hooks at compile time.
+ */
 export const hookOptionsGenerator = defineGenerator<PluginReactQuery>({
   name: 'react-query-hook-options',
   renderer: jsxRendererSync,
@@ -19,14 +25,14 @@ export const hookOptionsGenerator = defineGenerator<PluginReactQuery>({
     if (!customOptions) return null
 
     const name = resolver.resolveHookOptionsName()
-    const resolvedFile = resolver.resolveFile({ name, extname: '.ts' }, { root, output, group })
+    const resolvedFile = resolver.resolveFile({ name, extname: '.ts' }, { root, output, group: group ?? undefined })
     const hookOptionsFile = {
       ...resolvedFile,
       baseName: `${name}.ts` as const,
       path: resolvedFile.path.replace(/[^/\\]+\.ts$/, `${name}.ts`),
     }
 
-    const imports: KubbReactNode[] = []
+    const imports: Array<KubbReactNode> = []
     const hookOptions: Record<string, string> = {}
 
     for (const node of nodes) {
@@ -34,7 +40,7 @@ export const hookOptionsGenerator = defineGenerator<PluginReactQuery>({
       const nodeQuery: QueryOption = 'query' in opOverrides ? (opOverrides.query as QueryOption) : query
       const nodeMutation: MutationOption = 'mutation' in opOverrides ? (opOverrides.mutation as MutationOption) : mutation
       const nodeInfinite = 'infinite' in opOverrides ? opOverrides.infinite : infinite
-      const nodeInfiniteOptions = nodeInfinite && typeof nodeInfinite === 'object' ? nodeInfinite : undefined
+      const nodeInfiniteOptions = nodeInfinite && typeof nodeInfinite === 'object' ? nodeInfinite : null
 
       // query: false means "still a query but skip the useQuery hook"
       const isQueryOp =
@@ -53,7 +59,7 @@ export const hookOptionsGenerator = defineGenerator<PluginReactQuery>({
         const queryHookName = resolver.resolveQueryName(node)
         const queryHookFile = resolver.resolveFile(
           { name: queryHookName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-          { root, output, group },
+          { root, output, group: group ?? undefined },
         )
         imports.push(<File.Import name={[queryOptionsName]} root={hookOptionsFile.path} path={queryHookFile.path} />)
         hookOptions[queryHookName] = `Partial<ReturnType<typeof ${queryOptionsName}>>`
@@ -63,7 +69,7 @@ export const hookOptionsGenerator = defineGenerator<PluginReactQuery>({
           const suspenseHookName = resolver.resolveSuspenseQueryName(node)
           const suspenseHookFile = resolver.resolveFile(
             { name: suspenseHookName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-            { root, output, group },
+            { root, output, group: group ?? undefined },
           )
           imports.push(<File.Import name={[suspenseOptionsName]} root={hookOptionsFile.path} path={suspenseHookFile.path} />)
           hookOptions[suspenseHookName] = `Partial<ReturnType<typeof ${suspenseOptionsName}>>`
@@ -80,7 +86,7 @@ export const hookOptionsGenerator = defineGenerator<PluginReactQuery>({
             const infiniteHookName = resolver.resolveInfiniteQueryName(node)
             const infiniteHookFile = resolver.resolveFile(
               { name: infiniteHookName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-              { root, output, group },
+              { root, output, group: group ?? undefined },
             )
             imports.push(<File.Import name={[infiniteOptionsName]} root={hookOptionsFile.path} path={infiniteHookFile.path} />)
             hookOptions[infiniteHookName] = `Partial<ReturnType<typeof ${infiniteOptionsName}>>`
@@ -90,7 +96,7 @@ export const hookOptionsGenerator = defineGenerator<PluginReactQuery>({
               const suspenseInfiniteHookName = resolver.resolveSuspenseInfiniteQueryName(node)
               const suspenseInfiniteHookFile = resolver.resolveFile(
                 { name: suspenseInfiniteHookName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-                { root, output, group },
+                { root, output, group: group ?? undefined },
               )
               imports.push(<File.Import name={[suspenseInfiniteOptionsName]} root={hookOptionsFile.path} path={suspenseInfiniteHookFile.path} />)
               hookOptions[suspenseInfiniteHookName] = `Partial<ReturnType<typeof ${suspenseInfiniteOptionsName}>>`
@@ -104,7 +110,7 @@ export const hookOptionsGenerator = defineGenerator<PluginReactQuery>({
         const mutationHookName = resolver.resolveMutationName(node)
         const mutationHookFile = resolver.resolveFile(
           { name: mutationHookName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
-          { root, output, group },
+          { root, output, group: group ?? undefined },
         )
         imports.push(<File.Import name={[mutationOptionsName]} root={hookOptionsFile.path} path={mutationHookFile.path} />)
         hookOptions[mutationHookName] = `Partial<ReturnType<typeof ${mutationOptionsName}>>`

package/src/generators/infiniteQueryGenerator.tsx

@@ -10,6 +10,12 @@ import { difference } from 'remeda'
 import { InfiniteQuery, InfiniteQueryOptions, QueryKey } from '../components'
 import type { PluginReactQuery } from '../types'
 
+/**
+ * Built-in generator for `useInfiniteQuery` hooks. Enabled when
+ * `pluginReactQuery({ infinite: { ... } })`. Emits one `useFooInfiniteQuery`
+ * hook per query operation, wiring the configured `nextParam` /
+ * `previousParam` paths into TanStack Query's cursor-based pagination.
+ */
 export const infiniteQueryGenerator = defineGenerator<PluginReactQuery>({
   name: 'react-infinite-query',
   renderer: jsxRendererSync,
@@ -26,7 +32,7 @@ export const infiniteQueryGenerator = defineGenerator<PluginReactQuery>({
       mutation !== false &&
       !isQuery &&
       difference(mutation ? mutation.methods : [], query ? query.methods : []).some((method) => node.method.toLowerCase() === method.toLowerCase())
-    const infiniteOptions = infinite && typeof infinite === 'object' ? infinite : undefined
+    const infiniteOptions = infinite && typeof infinite === 'object' ? infinite : null
 
     if (!isQuery || isMutation || !infiniteOptions) return null
 
@@ -48,10 +54,13 @@ export const infiniteQueryGenerator = defineGenerator<PluginReactQuery>({
     const clientBaseName = resolver.resolveInfiniteClientName(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 },
       ),
     }
 
@@ -61,20 +70,20 @@ export const infiniteQueryGenerator = 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(
@@ -82,10 +91,10 @@ export const infiniteQueryGenerator = 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
 

package/src/generators/mutationGenerator.tsx

@@ -10,6 +10,11 @@ import { difference } from 'remeda'
 import { Mutation, MutationKey, MutationOptions } from '../components'
 import type { PluginReactQuery } from '../types'
 
+/**
+ * Built-in generator for `useMutation` hooks. Emits one `useFooMutation` hook
+ * per POST/PUT/DELETE operation (configurable via `mutation.methods`) plus
+ * the matching `fooMutationKey` / `fooMutationOptions` helpers.
+ */
 export const mutationGenerator = defineGenerator<PluginReactQuery>({
   name: 'react-query-mutation',
   renderer: jsxRendererSync,
@@ -38,29 +43,32 @@ export const mutationGenerator = defineGenerator<PluginReactQuery>({
     const clientName = resolver.resolveClientName(node)
 
     const meta = {
-      file: resolver.resolveFile({ name: mutationHookName, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      file: resolver.resolveFile(
+        { name: mutationHookName, 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(
@@ -68,10 +76,10 @@ export const mutationGenerator = 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
 

package/src/generators/queryGenerator.tsx

@@ -10,6 +10,11 @@ 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,
@@ -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
 

package/src/generators/suspenseInfiniteQueryGenerator.tsx

@@ -10,6 +10,12 @@ 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,
@@ -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