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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-vue-query",
-  "version": "5.0.0-beta.22",
+  "version": "5.0.0-beta.25",
   "description": "Generate type-safe TanStack Query (Vue Query) composables from your OpenAPI specification. Covers useQuery, useMutation, useInfiniteQuery, and queryOptions with Vue 3 Composition API support.",
   "keywords": [
     "code-generation",
@@ -70,12 +70,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",
@@ -83,7 +83,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

@@ -38,7 +38,7 @@ function buildInfiniteQueryParamsNode(
 ): 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/InfiniteQueryOptions.tsx

@@ -73,11 +73,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 })
@@ -96,15 +96,15 @@ export function InfiniteQueryOptions({
         .join(' && ')},`
     : ''
 
-  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

@@ -65,7 +65,7 @@ function buildMutationParamsNode(
         type: ast.createParamsType({
           variant: 'reference',
           name: `{
-  mutation?: MutationObserverOptions<${[TData, TError, TRequestWrapped ? `{${TRequestWrapped}}` : 'void', 'TContext'].join(', ')}> & { client?: QueryClient },
+  mutation?: MutationObserverOptions<${[TData, TError, TRequestWrapped ? `{${TRequestWrapped}}` : 'undefined', 'TContext'].join(', ')}> & { client?: QueryClient },
   client?: ${buildRequestConfigType(node, resolver)},
 }`,
         }),
@@ -100,7 +100,7 @@ export function Mutation({
   const TRequest = hasMutationParams ? (declarationPrinter.print(mutationArgParamsNode) ?? '') : ''
   const argKeysStr = hasMutationParams ? (keysPrinter.print(mutationArgParamsNode) ?? '') : ''
 
-  const generics = [TData, TError, TRequest ? `{${TRequest}}` : 'void', 'TContext'].join(', ')
+  const generics = [TData, TError, TRequest ? `{${TRequest}}` : 'undefined', 'TContext'].join(', ')
 
   const mutationKeyParamsNode = ast.createFunctionParameters({ params: [] })
   const mutationKeyParamsCall = callPrinter.print(mutationKeyParamsNode) ?? ''

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/QueryKey.tsx

@@ -14,7 +14,7 @@ type Props = {
   tsResolver: ResolverTs
   paramsCasing: 'camelcase' | undefined
   pathParamsType: 'object' | 'inline'
-  transformer: Transformer | undefined
+  transformer: Transformer | null | undefined
 }
 
 const declarationPrinter = functionPrinter({ mode: 'declaration' })
@@ -26,10 +26,10 @@ export function buildQueryKeyParamsNode(
   return wrapWithMaybeRefOrGetter(buildQueryKeyParams(node, options))
 }
 
-export function QueryKey({ name, node, tsResolver, paramsCasing, pathParamsType, typeName, transformer = queryKeyTransformer }: Props): KubbReactNode {
+export function QueryKey({ name, node, tsResolver, paramsCasing, pathParamsType, typeName, transformer }: Props): KubbReactNode {
   const paramsNode = buildQueryKeyParamsNode(node, { pathParamsType, paramsCasing, resolver: tsResolver })
   const paramsSignature = declarationPrinter.print(paramsNode) ?? ''
-  const keys = transformer({
+  const keys = (transformer ?? queryKeyTransformer)({
     node,
     casing: paramsCasing,
   })

package/src/components/QueryOptions.tsx

@@ -33,7 +33,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
 
   const baseParams = ast.createOperationParams(node, {
     paramsType,

package/src/generators/infiniteQueryGenerator.tsx

@@ -10,6 +10,12 @@ import { difference } from 'remeda'
 import { InfiniteQuery, InfiniteQueryOptions, QueryKey } from '../components'
 import type { PluginVueQuery } from '../types'
 
+/**
+ * Built-in generator for `useInfiniteQuery` composables. Enabled when
+ * `pluginVueQuery({ infinite: { ... } })`. Emits one `useFooInfiniteQuery`
+ * composable per query operation, wiring the configured cursor path into
+ * TanStack Query's cursor-based pagination.
+ */
 export const infiniteQueryGenerator = defineGenerator<PluginVueQuery>({
   name: 'vue-query-infinite',
   renderer: jsxRendererSync,
@@ -26,7 +32,7 @@ export const infiniteQueryGenerator = defineGenerator<PluginVueQuery>({
       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<PluginVueQuery>({
     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<PluginVueQuery>({
       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<PluginVueQuery>({
           {
             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 } from '../components'
 import type { PluginVueQuery } from '../types'
 
+/**
+ * Built-in generator for `useMutation` composables. Emits one
+ * `useFooMutation` composable per POST/PUT/DELETE operation (configurable
+ * via `mutation.methods`) plus the matching `fooMutationKey` helper.
+ */
 export const mutationGenerator = defineGenerator<PluginVueQuery>({
   name: 'vue-query-mutation',
   renderer: jsxRendererSync,
@@ -37,29 +42,32 @@ export const mutationGenerator = defineGenerator<PluginVueQuery>({
     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(
@@ -67,10 +75,10 @@ export const mutationGenerator = defineGenerator<PluginVueQuery>({
           {
             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 { PluginVueQuery } from '../types'
 
+/**
+ * Built-in generator for `useQuery` composables. Emits one `useFooQuery`
+ * composable per GET operation (configurable via `query.methods`) plus the
+ * matching `fooQueryKey` / `fooQueryOptions` helpers.
+ */
 export const queryGenerator = defineGenerator<PluginVueQuery>({
   name: 'vue-query',
   renderer: jsxRendererSync,
@@ -38,10 +43,13 @@ export const queryGenerator = defineGenerator<PluginVueQuery>({
     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 },
       ),
     }
 
@@ -51,20 +59,20 @@ export const queryGenerator = defineGenerator<PluginVueQuery>({
       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(
@@ -72,10 +80,10 @@ export const queryGenerator = defineGenerator<PluginVueQuery>({
           {
             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/plugin.ts

@@ -13,8 +13,36 @@ import { infiniteQueryGenerator, mutationGenerator, queryGenerator } from './gen
 import { resolverVueQuery } from './resolvers/resolverVueQuery.ts'
 import type { PluginVueQuery } from './types.ts'
 
+/**
+ * Canonical plugin name for `@kubb/plugin-vue-query`. Used for driver lookups
+ * and cross-plugin dependency references.
+ */
 export const pluginVueQueryName = 'plugin-vue-query' satisfies PluginVueQuery['name']
 
+/**
+ * Generates one TanStack Query composable per OpenAPI operation for Vue's
+ * Composition API. Queries become `useFooQuery` (and optionally
+ * `useFooInfiniteQuery`); mutations become `useFooMutation`. Each composable
+ * is fully typed end to end.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'kubb'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginVueQuery } from '@kubb/plugin-vue-query'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginVueQuery({
+ *       output: { path: './hooks' },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
 export const pluginVueQuery = definePlugin<PluginVueQuery>((options) => {
   const {
     output = { path: 'hooks', barrelType: 'named' },
@@ -56,7 +84,7 @@ export const pluginVueQuery = definePlugin<PluginVueQuery>((options) => {
               return `${camelCase(ctx.group)}Controller`
             },
       } satisfies Group)
-    : undefined
+    : null
 
   return {
     name: pluginVueQueryName,
@@ -99,9 +127,9 @@ export const pluginVueQuery = definePlugin<PluginVueQuery>((options) => {
             ? {
                 queryParam: 'id',
                 initialPageParam: 0,
-                cursorParam: undefined,
-                nextParam: undefined,
-                previousParam: undefined,
+                cursorParam: null,
+                nextParam: null,
+                previousParam: null,
                 ...infinite,
               }
             : false,

package/src/resolvers/resolverVueQuery.ts

@@ -7,9 +7,20 @@ function capitalize(name: string): string {
 }
 
 /**
- * Naming convention resolver for Vue Query plugin.
+ * Default resolver used by `@kubb/plugin-vue-query`. Decides the names and
+ * file paths for every generated TanStack Query composable (`useFooQuery`,
+ * `useFooMutation`, `useFooInfiniteQuery`) and its companion helpers.
  *
- * Provides default naming helpers using camelCase for functions and file paths.
+ * Functions and files use camelCase; composables get the `use` prefix.
+ *
+ * @example Resolve composable and helper names
+ * ```ts
+ * import { resolverVueQuery } from '@kubb/plugin-vue-query'
+ *
+ * resolverVueQuery.resolveQueryName(operationNode)       // 'useGetPetById'
+ * resolverVueQuery.resolveQueryKeyName(operationNode)    // 'getPetByIdQueryKey'
+ * resolverVueQuery.resolveQueryOptionsName(operationNode) // 'getPetByIdQueryOptions'
+ * ```
  */
 export const resolverVueQuery = defineResolver<PluginVueQuery>(() => ({
   name: 'default',