@kubb/plugin-react-query 5.0.0-beta.4 → 5.0.0-beta.56

package/src/resolvers/resolverReactQuery.ts

@@ -1,22 +1,118 @@
-import { camelCase } from '@internals/utils'
+import { camelCase, toFilePath } from '@internals/utils'
 import { defineResolver } from '@kubb/core'
 import type { PluginReactQuery } from '../types.ts'
 
+function capitalize(name: string): string {
+  return `${name.charAt(0).toUpperCase()}${name.slice(1)}`
+}
+
 /**
- * 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`).
+ *
+ * Functions and files use camelCase; hooks get the `use` prefix; suspense and
+ * infinite variants are suffixed with `Suspense`/`Infinite`.
  *
- * Provides default naming helpers using camelCase for functions and file paths.
+ * @example Resolve hook and helper names
+ * ```ts
+ * import { resolverReactQuery } from '@kubb/plugin-react-query'
  *
- * @example
- * `resolverReactQuery.default('list pets', 'function')  // → 'listPets'`
+ * resolverReactQuery.resolveQueryName(operationNode)       // 'useGetPetById'
+ * resolverReactQuery.resolveMutationName(operationNode)    // 'useUpdatePet'
+ * resolverReactQuery.resolveQueryKeyName(operationNode)    // 'getPetByIdQueryKey'
+ * resolverReactQuery.resolveQueryOptionsName(operationNode) // 'getPetByIdQueryOptions'
+ * ```
  */
-export const resolverReactQuery = defineResolver<PluginReactQuery>((ctx) => ({
+export const resolverReactQuery = defineResolver<PluginReactQuery>(() => ({
   name: 'default',
   pluginName: 'plugin-react-query',
   default(name, type) {
-    return camelCase(name, { isFile: type === 'file' })
+    return type === 'file' ? toFilePath(name) : camelCase(name)
   },
   resolveName(name) {
-    return ctx.default(name, 'function')
+    return this.default(name, 'function')
+  },
+  resolvePathName(name, type) {
+    return this.default(name, type)
+  },
+  resolveQueryName(node) {
+    return `use${capitalize(this.resolveName(node.operationId))}`
+  },
+  resolveSuspenseQueryName(node) {
+    return `use${capitalize(this.resolveName(node.operationId))}Suspense`
+  },
+  resolveInfiniteQueryName(node) {
+    return `use${capitalize(this.resolveName(node.operationId))}Infinite`
+  },
+  resolveSuspenseInfiniteQueryName(node) {
+    return `use${capitalize(this.resolveName(node.operationId))}SuspenseInfinite`
+  },
+  resolveMutationName(node) {
+    return `use${capitalize(this.resolveName(node.operationId))}`
+  },
+  resolveQueryOptionsName(node) {
+    return `${this.resolveName(node.operationId)}QueryOptions`
+  },
+  resolveSuspenseQueryOptionsName(node) {
+    return `${this.resolveName(node.operationId)}SuspenseQueryOptions`
+  },
+  resolveInfiniteQueryOptionsName(node) {
+    return `${this.resolveName(node.operationId)}InfiniteQueryOptions`
+  },
+  resolveSuspenseInfiniteQueryOptionsName(node) {
+    return `${this.resolveName(node.operationId)}SuspenseInfiniteQueryOptions`
+  },
+  resolveMutationOptionsName(node) {
+    return `${this.resolveName(node.operationId)}MutationOptions`
+  },
+  resolveQueryKeyName(node) {
+    return `${this.resolveName(node.operationId)}QueryKey`
+  },
+  resolveSuspenseQueryKeyName(node) {
+    return `${this.resolveName(node.operationId)}SuspenseQueryKey`
+  },
+  resolveInfiniteQueryKeyName(node) {
+    return `${this.resolveName(node.operationId)}InfiniteQueryKey`
+  },
+  resolveSuspenseInfiniteQueryKeyName(node) {
+    return `${this.resolveName(node.operationId)}SuspenseInfiniteQueryKey`
+  },
+  resolveMutationKeyName(node) {
+    return `${this.resolveName(node.operationId)}MutationKey`
+  },
+  resolveQueryKeyTypeName(node) {
+    return `${capitalize(this.resolveName(node.operationId))}QueryKey`
+  },
+  resolveSuspenseQueryKeyTypeName(node) {
+    return `${capitalize(this.resolveName(node.operationId))}SuspenseQueryKey`
+  },
+  resolveInfiniteQueryKeyTypeName(node) {
+    return `${capitalize(this.resolveName(node.operationId))}InfiniteQueryKey`
+  },
+  resolveSuspenseInfiniteQueryKeyTypeName(node) {
+    return `${capitalize(this.resolveName(node.operationId))}SuspenseInfiniteQueryKey`
+  },
+  resolveMutationTypeName(node) {
+    return capitalize(this.resolveName(node.operationId))
+  },
+  resolveClientName(node) {
+    return this.resolveName(node.operationId)
+  },
+  resolveSuspenseClientName(node) {
+    return `${this.resolveName(node.operationId)}Suspense`
+  },
+  resolveInfiniteClientName(node) {
+    return `${this.resolveName(node.operationId)}Infinite`
+  },
+  resolveSuspenseInfiniteClientName(node) {
+    return `${this.resolveName(node.operationId)}SuspenseInfinite`
+  },
+  resolveHookOptionsName() {
+    return 'HookOptions'
+  },
+  resolveCustomHookOptionsName() {
+    return 'getCustomHookOptions'
   },
 }))

package/src/types.ts

@@ -1,5 +1,5 @@
 import type { Transformer } from '@internals/tanstack-query'
-import type { ast, Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver } from '@kubb/core'
+import type { ast, Exclude, Generator, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver } from '@kubb/core'
 import type { ClientImportPath, PluginClient } from '@kubb/plugin-client'
 
 export type { Transformer } from '@internals/tanstack-query'
@@ -9,38 +9,153 @@ export type { Transformer } from '@internals/tanstack-query'
  */
 export type ResolverReactQuery = Resolver & {
   /**
-   * Resolves the hook function name for an operation.
+   * Resolves the base function name for an operation.
    *
-   * @example Resolving hook names
+   * @example Resolving base operation names
    * `resolver.resolveName('show pet by id') // -> 'showPetById'`
    */
   resolveName(this: ResolverReactQuery, name: string): string
+  /**
+   * Resolves the output file name for a hook module.
+   */
+  resolvePathName(this: ResolverReactQuery, name: string, type?: 'file' | 'function' | 'type' | 'const'): string
+  /**
+   * Resolves a query hook function name.
+   */
+  resolveQueryName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves a suspense query hook function name.
+   */
+  resolveSuspenseQueryName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves an infinite query hook function name.
+   */
+  resolveInfiniteQueryName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves a suspense infinite query hook function name.
+   */
+  resolveSuspenseInfiniteQueryName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves a mutation hook function name.
+   */
+  resolveMutationName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the query options helper name.
+   */
+  resolveQueryOptionsName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the suspense query options helper name.
+   */
+  resolveSuspenseQueryOptionsName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the infinite query options helper name.
+   */
+  resolveInfiniteQueryOptionsName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the suspense infinite query options helper name.
+   */
+  resolveSuspenseInfiniteQueryOptionsName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the mutation options helper name.
+   */
+  resolveMutationOptionsName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the query key helper name.
+   */
+  resolveQueryKeyName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the suspense query key helper name.
+   */
+  resolveSuspenseQueryKeyName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the infinite query key helper name.
+   */
+  resolveInfiniteQueryKeyName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the suspense infinite query key helper name.
+   */
+  resolveSuspenseInfiniteQueryKeyName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the mutation key helper name.
+   */
+  resolveMutationKeyName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the query key type name.
+   */
+  resolveQueryKeyTypeName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the suspense query key type name.
+   */
+  resolveSuspenseQueryKeyTypeName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the infinite query key type name.
+   */
+  resolveInfiniteQueryKeyTypeName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the suspense infinite query key type name.
+   */
+  resolveSuspenseInfiniteQueryKeyTypeName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the mutation type name.
+   */
+  resolveMutationTypeName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the client function name generated inline by query hooks.
+   */
+  resolveClientName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the client function name generated inline by suspense query hooks.
+   */
+  resolveSuspenseClientName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the client function name generated inline by infinite query hooks.
+   */
+  resolveInfiniteClientName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the client function name generated inline by suspense infinite query hooks.
+   */
+  resolveSuspenseInfiniteClientName(this: ResolverReactQuery, node: ast.OperationNode): string
+  /**
+   * Resolves the generated custom hook options map type name.
+   */
+  resolveHookOptionsName(this: ResolverReactQuery): string
+  /**
+   * Resolves the helper function name used inside the custom hook options file.
+   */
+  resolveCustomHookOptionsName(this: ResolverReactQuery): string
 }
 
 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
@@ -48,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
@@ -65,140 +180,160 @@ 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
 }
 
-export type Options = {
-  /**
-   * Specify the export location for the files and define the behavior of the output
-   * @default { path: 'hooks', barrelType: 'named' }
-   */
-  output?: Output
+/**
+ * Where the generated hooks are written and how they are exported, plus the optional `group`
+ * strategy. The `group` option organizes `output.mode: 'directory'` output into per-tag or per-path subdirectories.
+ *
+ * @default { path: 'hooks', barrel: { type: 'named' } }
+ */
+export type Options = OutputOptions & {
   /**
-   * Group the @tanstack/query hooks based on the provided name.
+   * HTTP client used inside every generated hook. Mirrors a subset of
+   * `pluginClient` options.
    */
-  group?: Group
   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']
-  transformers?: {
-    /**
-     * Override the default naming for hooks.
-     */
-    name?: (name: string, type?: string) => string
-  }
   /**
-   * 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']>
   client: Pick<PluginClient['options'], 'client' | 'clientType' | 'dataReturnType' | 'importPath' | 'baseURL' | 'bundle' | 'paramsCasing'>
-  parser: Required<NonNullable<Options['parser']>>
+  parser: NonNullable<Options['parser']>
   pathParamsType: NonNullable<Options['pathParamsType']>
   paramsCasing: Options['paramsCasing']
   paramsType: NonNullable<Options['paramsType']>
@@ -207,13 +342,12 @@ 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
-  transformers: NonNullable<Options['transformers']>
 }
 
 export type PluginReactQuery = PluginFactoryOptions<'plugin-react-query', Options, ResolvedOptions, ResolverReactQuery>

package/src/utils.ts

@@ -1,40 +1,18 @@
-import type { ast } from '@kubb/core'
-import type { PluginReactQuery } from './types.ts'
-
 export {
   buildGroupParam,
-  buildMutationArgParams,
   buildQueryKeyParams,
-  getComments,
-  resolveErrorNames,
   resolveHeaderGroupType,
+  resolveOperationOverrides,
   resolvePathParamType,
   resolveQueryGroupType,
-  resolveStatusCodeNames,
+  resolveZodSchemaNames,
 } from '@internals/tanstack-query'
-
-export function transformName(name: string, type: string, transformers?: PluginReactQuery['resolvedOptions']['transformers']): string {
-  return transformers?.name?.(name, type) || name
-}
-
-function matchesPattern(node: ast.OperationNode, ov: { type: string; pattern: string | RegExp }): boolean {
-  const { type, pattern } = ov
-  const matches = (value: string) => (typeof pattern === 'string' ? value === pattern : pattern.test(value))
-  if (type === 'operationId') return matches(node.operationId)
-  if (type === 'tag') return node.tags.some((t) => matches(t))
-  if (type === 'path') return matches(node.path)
-  if (type === 'method') return matches(node.method)
-  return false
-}
-
-/**
- * Resolves per-operation overrides (first matching override wins), mirroring v4 OperationGenerator.getOptions().
- */
-export function resolveOperationOverrides(
-  node: ast.OperationNode,
-  override?: PluginReactQuery['resolvedOptions']['override'],
-): Partial<PluginReactQuery['resolvedOptions']> {
-  if (!override) return {}
-  const match = override.find((ov) => matchesPattern(node, ov as { type: string; pattern: string | RegExp }))
-  return (match as { options?: Partial<PluginReactQuery['resolvedOptions']> })?.options ?? {}
-}
+export {
+  buildOperationComments as getComments,
+  buildRequestConfigType,
+  buildStatusUnionType,
+  getContentTypeInfo,
+  resolveErrorNames,
+  resolveStatusCodeNames,
+  resolveSuccessNames,
+} from '@internals/shared'