@kubb/plugin-react-query 5.0.0-alpha.9 → 5.0.0-beta.3

package/src/plugin.ts

@@ -1,14 +1,13 @@
 import path from 'node:path'
-import { camelCase, pascalCase } from '@internals/utils'
-import { createPlugin, type Group, getBarrelFiles, getMode } from '@kubb/core'
+import { camelCase } from '@internals/utils'
+import { ast, definePlugin, type Group } from '@kubb/core'
 import { pluginClientName } from '@kubb/plugin-client'
 import { source as axiosClientSource } from '@kubb/plugin-client/templates/clients/axios.source'
 import { source as fetchClientSource } from '@kubb/plugin-client/templates/clients/fetch.source'
 import { source as configSource } from '@kubb/plugin-client/templates/config.source'
-import { OperationGenerator, pluginOasName } from '@kubb/plugin-oas'
 import { pluginTsName } from '@kubb/plugin-ts'
 import { pluginZodName } from '@kubb/plugin-zod'
-import { MutationKey } from './components'
+import { MutationKey } from './components/MutationKey.tsx'
 import { QueryKey } from './components/QueryKey.tsx'
 import {
   customHookOptionsFileGenerator,
@@ -19,11 +18,12 @@ import {
   suspenseInfiniteQueryGenerator,
   suspenseQueryGenerator,
 } from './generators'
+import { resolverReactQuery } from './resolvers/resolverReactQuery.ts'
 import type { PluginReactQuery } from './types.ts'
 
 export const pluginReactQueryName = 'plugin-react-query' satisfies PluginReactQuery['name']
 
-export const pluginReactQuery = createPlugin<PluginReactQuery>((options) => {
+export const pluginReactQuery = definePlugin<PluginReactQuery>((options) => {
   const {
     output = { path: 'hooks', barrelType: 'named' },
     group,
@@ -36,204 +36,154 @@ export const pluginReactQuery = createPlugin<PluginReactQuery>((options) => {
     transformers = {},
     paramsType = 'inline',
     pathParamsType = paramsType === 'object' ? 'object' : options.pathParamsType || 'inline',
-    generators = [
-      queryGenerator,
-      suspenseQueryGenerator,
-      infiniteQueryGenerator,
-      suspenseInfiniteQueryGenerator,
-      mutationGenerator,
-      hookOptionsGenerator,
-      customHookOptionsFileGenerator,
-    ].filter(Boolean),
     mutation = {},
     query = {},
     mutationKey = MutationKey.getTransformer,
     queryKey = QueryKey.getTransformer,
     customOptions,
     paramsCasing,
-    contentType,
     client,
+    resolver: userResolver,
+    transformer: userTransformer,
+    generators: userGenerators = [],
   } = options
 
   const clientName = client?.client ?? 'axios'
   const clientImportPath = client?.importPath ?? (!client?.bundle ? `@kubb/plugin-client/clients/${clientName}` : undefined)
 
-  return {
-    name: pluginReactQueryName,
-    options: {
-      output,
-      client: {
-        bundle: client?.bundle,
-        baseURL: client?.baseURL,
-        client: clientName,
-        clientType: client?.clientType ?? 'function',
-        dataReturnType: client?.dataReturnType ?? 'data',
-        pathParamsType,
-        importPath: clientImportPath,
-        paramsCasing,
-      },
-      infinite: infinite
-        ? {
-            queryParam: 'id',
-            initialPageParam: 0,
-            cursorParam: undefined,
-            nextParam: undefined,
-            previousParam: undefined,
-            ...infinite,
-          }
-        : false,
-      suspense,
-      queryKey,
-      query:
-        query === false
-          ? false
-          : {
-              methods: ['get'],
-              importPath: '@tanstack/react-query',
-              ...query,
-            },
-      mutationKey,
-      mutation:
-        mutation === false
-          ? false
-          : {
-              methods: ['post', 'put', 'patch', 'delete'],
-              importPath: '@tanstack/react-query',
-              ...mutation,
-            },
-      customOptions: customOptions ? { name: 'useCustomHookOptions', ...customOptions } : undefined,
-      paramsType,
-      pathParamsType,
-      parser,
-      paramsCasing,
-      group,
-    },
-    pre: [pluginOasName, pluginTsName, parser === 'zod' ? pluginZodName : undefined].filter(Boolean),
-    resolvePath(baseName, pathMode, options) {
-      const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = pathMode ?? getMode(path.resolve(root, output.path))
-
-      if (mode === 'single') {
-        /**
-         * when output is a file then we will always append to the same file(output file), see fileManager.addOrAppend
-         * Other plugins then need to call addOrAppend instead of just add from the fileManager class
-         */
-        return path.resolve(root, output.path)
-      }
+  const selectedGenerators =
+    options.generators ??
+    [
+      queryGenerator,
+      suspenseQueryGenerator,
+      infiniteQueryGenerator,
+      suspenseInfiniteQueryGenerator,
+      mutationGenerator,
+      hookOptionsGenerator,
+      customHookOptionsFileGenerator,
+    ].filter(Boolean)
 
-      if (group && (options?.group?.path || options?.group?.tag)) {
-        const groupName: Group['name'] = group?.name
+  const groupConfig = group
+    ? ({
+        ...group,
+        name: group.name
           ? group.name
-          : (ctx) => {
-              if (group?.type === 'path') {
+          : (ctx: { group: string }) => {
+              if (group.type === 'path') {
                 return `${ctx.group.split('/')[1]}`
               }
               return `${camelCase(ctx.group)}Controller`
-            }
-
-        return path.resolve(
-          root,
-          output.path,
-          groupName({
-            group: group.type === 'path' ? options.group.path! : options.group.tag!,
-          }),
-          baseName,
-        )
-      }
-
-      return path.resolve(root, output.path, baseName)
-    },
-    resolveName(name, type) {
-      let resolvedName = camelCase(name)
-
-      if (type === 'file' || type === 'function') {
-        resolvedName = camelCase(name, {
-          isFile: type === 'file',
-        })
-      }
-      if (type === 'type') {
-        resolvedName = pascalCase(name)
-      }
-
-      if (type) {
-        return transformers?.name?.(resolvedName, type) || resolvedName
-      }
-
-      return resolvedName
-    },
-    async install() {
-      const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = getMode(path.resolve(root, output.path))
-      const oas = await this.getOas()
-      const baseURL = await this.getBaseURL()
-
-      if (baseURL) {
-        this.plugin.options.client.baseURL = baseURL
-      }
-
-      const hasClientPlugin = !!this.driver.getPluginByName(pluginClientName)
-
-      if (this.plugin.options.client.bundle && !hasClientPlugin && !this.plugin.options.client.importPath) {
-        // pre add bundled fetch
-        await this.upsertFile({
-          baseName: 'fetch.ts',
-          path: path.resolve(root, '.kubb/fetch.ts'),
-          sources: [
-            {
-              name: 'fetch',
-              value: this.plugin.options.client.client === 'fetch' ? fetchClientSource : axiosClientSource,
-              isExportable: true,
-              isIndexable: true,
             },
-          ],
-          imports: [],
-          exports: [],
-        })
-      }
+      } satisfies Group)
+    : undefined
 
-      if (!hasClientPlugin) {
-        await this.upsertFile({
-          baseName: 'config.ts',
-          path: path.resolve(root, '.kubb/config.ts'),
-          sources: [
-            {
-              name: 'config',
-              value: configSource,
-              isExportable: false,
-              isIndexable: false,
-            },
-          ],
-          imports: [],
-          exports: [],
+  return {
+    name: pluginReactQueryName,
+    options,
+    dependencies: [pluginTsName, parser === 'zod' ? pluginZodName : undefined].filter(Boolean),
+    hooks: {
+      'kubb:plugin:setup'(ctx) {
+        const resolver = userResolver ? { ...resolverReactQuery, ...userResolver } : resolverReactQuery
+
+        ctx.setOptions({
+          output,
+          transformers,
+          client: {
+            bundle: client?.bundle,
+            baseURL: client?.baseURL,
+            client: clientName,
+            clientType: client?.clientType ?? 'function',
+            importPath: clientImportPath,
+            dataReturnType: client?.dataReturnType ?? 'data',
+            paramsCasing,
+          },
+          queryKey,
+          query:
+            query === false
+              ? false
+              : {
+                  importPath: '@tanstack/react-query',
+                  methods: ['get'],
+                  ...query,
+                },
+          mutationKey,
+          mutation:
+            mutation === false
+              ? false
+              : {
+                  importPath: '@tanstack/react-query',
+                  methods: ['post', 'put', 'patch', 'delete'],
+                  ...mutation,
+                },
+          infinite: infinite
+            ? {
+                queryParam: 'id',
+                initialPageParam: 0,
+                cursorParam: undefined,
+                nextParam: undefined,
+                previousParam: undefined,
+                ...infinite,
+              }
+            : false,
+          suspense,
+          customOptions: customOptions ? { name: 'useCustomHookOptions', ...customOptions } : undefined,
+          parser,
+          paramsType,
+          pathParamsType,
+          paramsCasing,
+          group: groupConfig,
+          exclude,
+          include,
+          override,
+          resolver,
         })
-      }
-
-      const operationGenerator = new OperationGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        driver: this.driver,
-        events: this.events,
-        plugin: this.plugin,
-        contentType,
-        exclude,
-        include,
-        override,
-        mode,
-      })
-
-      const files = await operationGenerator.build(...generators)
-      await this.upsertFile(...files)
-
-      const barrelFiles = await getBarrelFiles(this.fabric.files, {
-        type: output.barrelType ?? 'named',
-        root,
-        output,
-        meta: {
-          pluginName: this.plugin.name,
-        },
-      })
-
-      await this.upsertFile(...barrelFiles)
+        ctx.setResolver(resolver)
+        if (userTransformer) {
+          ctx.setTransformer(userTransformer)
+        }
+
+        for (const gen of selectedGenerators) {
+          ctx.addGenerator(gen)
+        }
+        for (const gen of userGenerators) {
+          ctx.addGenerator(gen)
+        }
+
+        const root = path.resolve(ctx.config.root, ctx.config.output.path)
+        const hasClientPlugin = !!ctx.config.plugins?.some((p) => (p as { name?: string }).name === pluginClientName)
+
+        if (client?.bundle && !hasClientPlugin && !clientImportPath) {
+          ctx.injectFile({
+            baseName: 'fetch.ts',
+            path: path.resolve(root, '.kubb/fetch.ts'),
+            sources: [
+              ast.createSource({
+                name: 'fetch',
+                nodes: [ast.createText(clientName === 'fetch' ? fetchClientSource : axiosClientSource)],
+                isExportable: true,
+                isIndexable: true,
+              }),
+            ],
+          })
+        }
+
+        if (!hasClientPlugin) {
+          ctx.injectFile({
+            baseName: 'config.ts',
+            path: path.resolve(root, '.kubb/config.ts'),
+            sources: [
+              ast.createSource({
+                name: 'config',
+                nodes: [ast.createText(configSource)],
+                isExportable: false,
+                isIndexable: false,
+              }),
+            ],
+          })
+        }
+      },
     },
   }
 })
+
+export default pluginReactQuery

package/src/resolvers/resolverReactQuery.ts

@@ -0,0 +1,22 @@
+import { camelCase } from '@internals/utils'
+import { defineResolver } from '@kubb/core'
+import type { PluginReactQuery } from '../types.ts'
+
+/**
+ * Naming convention resolver for React Query plugin.
+ *
+ * Provides default naming helpers using camelCase for functions and file paths.
+ *
+ * @example
+ * `resolverReactQuery.default('list pets', 'function')  // → 'listPets'`
+ */
+export const resolverReactQuery = defineResolver<PluginReactQuery>((ctx) => ({
+  name: 'default',
+  pluginName: 'plugin-react-query',
+  default(name, type) {
+    return camelCase(name, { isFile: type === 'file' })
+  },
+  resolveName(name) {
+    return ctx.default(name, 'function')
+  },
+}))

package/src/types.ts

@@ -1,30 +1,41 @@
 import type { Transformer } from '@internals/tanstack-query'
-import type { Group, Output, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
-import type { contentType, HttpMethod, Oas } from '@kubb/oas'
+import type { ast, Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver } from '@kubb/core'
 import type { ClientImportPath, PluginClient } from '@kubb/plugin-client'
-import type { Exclude, Include, Override, ResolvePathOptions } from '@kubb/plugin-oas'
-import type { Generator } from '@kubb/plugin-oas/generators'
 
 export type { Transformer } from '@internals/tanstack-query'
 
+/**
+ * Resolver for React Query that provides naming methods for hook functions.
+ */
+export type ResolverReactQuery = Resolver & {
+  /**
+   * Resolves the hook function name for an operation.
+   *
+   * @example Resolving hook names
+   * `resolver.resolveName('show pet by id') // -> 'showPetById'`
+   */
+  resolveName(this: ResolverReactQuery, name: string): string
+}
+
 type Suspense = object
 
 /**
- * Customize the queryKey
+ * Customize the queryKey.
  */
 type QueryKey = Transformer
 
 /**
- * Customize the mutationKey
+ * Customize the mutationKey.
  */
 type MutationKey = Transformer
 
 type Query = {
   /**
-   * Define which HttpMethods can be used for queries
+   * HTTP methods to use for queries.
+   *
    * @default ['get']
    */
-  methods: Array<HttpMethod>
+  methods?: Array<string>
   /**
    * Path to the useQuery hook for useQuery functionality.
    * Used as `import { useQuery } from '${importPath}'`.
@@ -37,13 +48,14 @@ type Query = {
 
 type Mutation = {
   /**
-   * Define which HttpMethods can be used for mutations
+   * HTTP methods to use for mutations.
+   *
    * @default ['post', 'put', 'delete']
    */
-  methods: Array<HttpMethod>
+  methods?: Array<string>
   /**
-   * Path to the useQuery hook for useQuery functionality.
-   * Used as `import { useQuery } from '${importPath}'`.
+   * 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.
    * @default '@tanstack/react-query'
@@ -99,99 +111,99 @@ export type Options = {
    * Specify the export location for the files and define the behavior of the output
    * @default { path: 'hooks', barrelType: 'named' }
    */
-  output?: Output<Oas>
-  /**
-   * Define which contentType should be used.
-   * By default, the first JSON valid mediaType is used
-   */
-  contentType?: contentType
+  output?: Output
   /**
    * Group the @tanstack/query hooks based on the provided name.
    */
   group?: Group
   client?: ClientImportPath & Pick<PluginClient['options'], 'clientType' | 'dataReturnType' | 'baseURL' | 'bundle' | 'paramsCasing'>
   /**
-   * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
+   * Tags, operations, or paths to exclude from generation.
    */
   exclude?: Array<Exclude>
   /**
-   * Array containing include parameters to include tags/operations/methods/paths.
+   * Tags, operations, or paths to include in generation.
    */
   include?: Array<Include>
   /**
-   * Array containing override parameters to override `options` based on tags/operations/methods/paths.
+   * Override options for specific tags, operations, or paths.
    */
   override?: Array<Override<ResolvedOptions>>
   /**
-   * How to style your params, by default no casing is applied
-   * - 'camelcase' uses camelcase for the params names
+   * Apply casing to parameter names.
    */
   paramsCasing?: 'camelcase'
   /**
-   * How to pass your params.
-   * - 'object' returns the params and pathParams as an object.
-   * - 'inline' returns the params as comma separated params.
+   * How parameters are passed: grouped in an object or spread inline.
+   *
    * @default 'inline'
    */
   paramsType?: 'object' | 'inline'
   /**
-   * How to pass your pathParams.
-   * - 'object' returns the pathParams as an object.
-   * - 'inline': returns the pathParams as comma separated params.
+   * How path parameters are passed: grouped in an object or spread inline.
+   *
    * @default 'inline'
    */
   pathParamsType?: PluginClient['options']['pathParamsType']
-
   /**
-   * When set, an infiniteQuery hooks is added.
+   * Add infinite query hooks.
    */
   infinite?: Partial<Infinite> | false
   /**
-   * When set, a suspenseQuery hooks is added.
+   * Add suspense query hooks.
    */
   suspense?: Partial<Suspense> | false
   queryKey?: QueryKey
   /**
-   * Override some useQuery behaviors.
+   * Configure useQuery behavior.
    */
   query?: Partial<Query> | false
   mutationKey?: MutationKey
   /**
-   * Override some useMutation behaviors.
+   * Configure useMutation behavior.
    */
   mutation?: Partial<Mutation> | false
   /**
-   * When set, a custom hook is used to customize the options of the generated hooks.
-   * It will also generate a `HookOptions` type that can be used to type the custom options of each hook for type-safety.
+   * Use a custom hook to customize hook options and generate a HookOptions type.
    */
   customOptions?: CustomOptions
   /**
-   * Which parser should be used before returning the data to `@tanstack/query`.
-   * `'zod'` uses `@kubb/plugin-zod` to parse the data.
+   * Parser to use for validating response data.
    */
   parser?: PluginClient['options']['parser']
   transformers?: {
     /**
-     * Customize the names based on the type that is provided by the plugin.
+     * Override the default naming for hooks.
      */
-    name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
+    name?: (name: string, type?: string) => string
   }
   /**
-   * Define some generators next to the react-query generators
+   * Override naming conventions for function names and types.
+   */
+  resolver?: Partial<ResolverReactQuery> & ThisType<ResolverReactQuery>
+  /**
+   * AST visitor to transform generated nodes.
+   */
+  transformer?: ast.Visitor
+  /**
+   * Additional generators alongside the default generators.
    */
   generators?: Array<Generator<PluginReactQuery>>
 }
 
 type ResolvedOptions = {
-  output: Output<Oas>
-  group: Options['group']
+  output: Output
+  group: Group | undefined
+  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']>>
   pathParamsType: NonNullable<Options['pathParamsType']>
   paramsCasing: Options['paramsCasing']
   paramsType: NonNullable<Options['paramsType']>
   /**
-   * Only used of infinite
+   * Only used for infinite
    */
   infinite: NonNullable<Infinite> | false
   suspense: Suspense | false
@@ -200,6 +212,16 @@ type ResolvedOptions = {
   mutationKey: MutationKey | undefined
   mutation: NonNullable<Required<Mutation>> | false
   customOptions: NonNullable<Required<CustomOptions>> | undefined
+  resolver: ResolverReactQuery
+  transformers: NonNullable<Options['transformers']>
 }
 
-export type PluginReactQuery = PluginFactoryOptions<'plugin-react-query', Options, ResolvedOptions, never, ResolvePathOptions>
+export type PluginReactQuery = PluginFactoryOptions<'plugin-react-query', Options, ResolvedOptions, ResolverReactQuery>
+
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-react-query': PluginReactQuery
+    }
+  }
+}

package/src/utils.ts

@@ -0,0 +1,40 @@
+import type { ast } from '@kubb/core'
+import type { PluginReactQuery } from './types.ts'
+
+export {
+  buildGroupParam,
+  buildMutationArgParams,
+  buildQueryKeyParams,
+  getComments,
+  resolveErrorNames,
+  resolveHeaderGroupType,
+  resolvePathParamType,
+  resolveQueryGroupType,
+  resolveStatusCodeNames,
+} 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 ?? {}
+}