@kubb/plugin-client 5.0.0-alpha.3 → 5.0.0-alpha.31

package/src/plugin.ts

@@ -1,130 +1,173 @@
 import path from 'node:path'
 import { camelCase } from '@internals/utils'
-import { definePlugin, type Group, getBarrelFiles, getMode } from '@kubb/core'
-import { OperationGenerator, pluginOasName } from '@kubb/plugin-oas'
+import { createPlugin, type Group, getPreset, mergeGenerators } from '@kubb/core'
+import { pluginTsName } from '@kubb/plugin-ts'
 import { pluginZodName } from '@kubb/plugin-zod'
-import { classClientGenerator, operationsGenerator } from './generators'
+import { version } from '../package.json'
+import { classClientGenerator } from './generators/classClientGenerator.tsx'
 import { clientGenerator } from './generators/clientGenerator.tsx'
 import { groupedClientGenerator } from './generators/groupedClientGenerator.tsx'
+import { operationsGenerator } from './generators/operationsGenerator.tsx'
 import { staticClassClientGenerator } from './generators/staticClassClientGenerator.tsx'
+import { presets } from './presets.ts'
 import { source as axiosClientSource } from './templates/clients/axios.source.ts'
 import { source as fetchClientSource } from './templates/clients/fetch.source.ts'
 import { source as configSource } from './templates/config.source.ts'
 import type { PluginClient } from './types.ts'
 
+/**
+ * Canonical plugin name for `@kubb/plugin-client`, used to identify the plugin
+ * in driver lookups and warnings.
+ */
 export const pluginClientName = 'plugin-client' satisfies PluginClient['name']
 
-export const pluginClient = definePlugin<PluginClient>((options) => {
+/**
+ * The `@kubb/plugin-client` plugin factory.
+ *
+ * Generates type-safe HTTP client functions (or classes) from an OpenAPI/AST `RootNode`.
+ * Walks operations, delegates rendering to the active generators,
+ * and writes barrel files based on `output.barrelType`.
+ *
+ * @example
+ * ```ts
+ * import { pluginClient } from '@kubb/plugin-client'
+ *
+ * export default defineConfig({
+ *   plugins: [pluginClient({ output: { path: 'clients' } })],
+ * })
+ * ```
+ */
+export const pluginClient = createPlugin<PluginClient>((options) => {
   const {
     output = { path: 'clients', barrelType: 'named' },
     group,
-    urlType = false,
     exclude = [],
     include,
     override = [],
-    transformers = {},
+    urlType = false,
     dataReturnType = 'data',
     paramsType = 'inline',
     pathParamsType = paramsType === 'object' ? 'object' : options.pathParamsType || 'inline',
     operations = false,
-    baseURL,
     paramsCasing,
     clientType = 'function',
     parser = 'client',
     client = 'axios',
     importPath,
-    contentType,
     bundle = false,
     wrapper,
+    baseURL,
+    compatibilityPreset = 'default',
+    resolver: userResolver,
+    transformer: userTransformer,
   } = options
 
   const resolvedImportPath = importPath ?? (!bundle ? `@kubb/plugin-client/clients/${client}` : undefined)
 
-  const defaultGenerators = [
-    clientType === 'staticClass' ? staticClassClientGenerator : clientType === 'class' ? classClientGenerator : clientGenerator,
-    group && clientType === 'function' ? groupedClientGenerator : undefined,
-    operations ? operationsGenerator : undefined,
-  ].filter((x): x is NonNullable<typeof x> => Boolean(x))
+  const selectedGenerators =
+    options.generators ??
+    [
+      clientType === 'staticClass' ? staticClassClientGenerator : clientType === 'class' ? classClientGenerator : clientGenerator,
+      group && clientType === 'function' ? groupedClientGenerator : undefined,
+      operations ? operationsGenerator : undefined,
+    ].filter((x): x is NonNullable<typeof x> => Boolean(x))
 
-  const generators = options.generators ?? defaultGenerators
+  const preset = getPreset({
+    preset: compatibilityPreset,
+    presets,
+    resolver: userResolver,
+    transformer: userTransformer,
+    generators: selectedGenerators,
+  })
+
+  const generators = preset.generators ?? []
+  const mergedGenerator = mergeGenerators(generators)
+
+  let resolveNameWarning = false
+  let resolvePathWarning = false
 
   return {
     name: pluginClientName,
-    options: {
-      client,
-      clientType,
-      bundle,
-      output,
-      group,
-      parser,
-      dataReturnType,
-      importPath: resolvedImportPath,
-      paramsType,
-      paramsCasing,
-      pathParamsType,
-      baseURL,
-      urlType,
-      wrapper,
+    version,
+    get resolver() {
+      return preset.resolver
     },
-    pre: [pluginOasName, 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)
+    get transformer() {
+      return preset.transformer
+    },
+    get options() {
+      return {
+        client,
+        clientType,
+        bundle,
+        output,
+        exclude,
+        include,
+        override,
+        group: group
+          ? ({
+              ...group,
+              name: group.name
+                ? group.name
+                : (ctx: { group: string }) => {
+                    if (group.type === 'path') {
+                      return `${ctx.group.split('/')[1]}`
+                    }
+                    return `${camelCase(ctx.group)}Controller`
+                  },
+            } satisfies Group)
+          : undefined,
+        parser,
+        dataReturnType,
+        importPath: resolvedImportPath,
+        baseURL,
+        paramsType,
+        paramsCasing,
+        pathParamsType,
+        urlType,
+        wrapper,
+        resolver: preset.resolver,
       }
-
-      if (group && (options?.group?.path || options?.group?.tag)) {
-        const groupName: Group['name'] = group?.name
-          ? group.name
-          : (ctx) => {
-              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,
-        )
+    },
+    pre: [pluginTsName, parser === 'zod' ? pluginZodName : undefined].filter(Boolean),
+    resolvePath(baseName, pathMode, options) {
+      if (!resolvePathWarning) {
+        this.warn('Do not use resolvePath for pluginClient, use resolverClient.resolvePath instead')
+        resolvePathWarning = true
       }
 
-      return path.resolve(root, output.path, baseName)
+      return this.plugin.resolver.resolvePath(
+        { baseName, pathMode, tag: options?.group?.tag, path: options?.group?.path },
+        { root: this.root, output, group: this.plugin.options.group },
+      )
     },
     resolveName(name, type) {
-      const resolvedName = camelCase(name, { isFile: type === 'file' })
-
-      if (type) {
-        return transformers?.name?.(resolvedName, type) || resolvedName
+      if (!resolveNameWarning) {
+        this.warn('Do not use resolveName for pluginClient, use resolverClient.default instead')
+        resolveNameWarning = true
       }
 
-      return resolvedName
+      return this.plugin.resolver.default(name, type)
+    },
+    async operation(node, options) {
+      return mergedGenerator.operation?.call(this, node, options)
     },
-    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()
+    async operations(nodes, options) {
+      return mergedGenerator.operations?.call(this, nodes, options)
+    },
+    async buildStart() {
+      const { plugin } = this
+      const root = this.root
 
       // pre add bundled fetch
-      if (bundle && !this.plugin.options.importPath) {
+      if (bundle && !plugin.options.importPath) {
         await this.addFile({
           baseName: 'fetch.ts',
           path: path.resolve(root, '.kubb/fetch.ts'),
           sources: [
             {
               name: 'fetch',
-              value: this.plugin.options.client === 'fetch' ? fetchClientSource : axiosClientSource,
+              value: plugin.options.client === 'fetch' ? fetchClientSource : axiosClientSource,
               isExportable: true,
               isIndexable: true,
             },
@@ -148,42 +191,6 @@ export const pluginClient = definePlugin<PluginClient>((options) => {
         imports: [],
         exports: [],
       })
-
-      const operationGenerator = new OperationGenerator(
-        baseURL
-          ? {
-              ...this.plugin.options,
-              baseURL,
-            }
-          : this.plugin.options,
-        {
-          fabric: this.fabric,
-          oas,
-          pluginManager: this.pluginManager,
-          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)
     },
   }
 })

package/src/presets.ts

@@ -0,0 +1,25 @@
+import { definePresets } from '@kubb/core'
+import { resolverClient } from './resolvers/resolverClient.ts'
+import { resolverClientLegacy } from './resolvers/resolverClientLegacy.ts'
+import type { ResolverClient } from './types.ts'
+
+/**
+ * Built-in preset registry for `@kubb/plugin-client`.
+ *
+ * - `default` — uses `resolverClient` with v5 naming conventions.
+ * - `kubbV4`  — uses `resolverClientLegacy` with backward-compatible naming.
+ *
+ * Note: Unlike plugin-ts/plugin-zod, generators are not defined here because
+ * plugin-client selects generators dynamically based on `clientType`, `group`,
+ * and `operations` options. Generator selection happens in `plugin.ts`.
+ */
+export const presets = definePresets<ResolverClient>({
+  default: {
+    name: 'default',
+    resolver: resolverClient,
+  },
+  kubbV4: {
+    name: 'kubbV4',
+    resolver: resolverClientLegacy,
+  },
+})

package/src/resolvers/resolverClient.ts

@@ -0,0 +1,26 @@
+import { camelCase } from '@internals/utils'
+import { defineResolver } from '@kubb/core'
+import type { PluginClient } from '../types.ts'
+
+/**
+ * Resolver for `@kubb/plugin-client` that provides the default naming
+ * and path-resolution helpers used by the plugin.
+ *
+ * @example
+ * ```ts
+ * import { resolverClient } from '@kubb/plugin-client'
+ *
+ * resolverClient.default('list pets', 'function') // -> 'listPets'
+ * resolverClient.resolveName('show pet by id')    // -> 'showPetById'
+ * ```
+ */
+export const resolverClient = defineResolver<PluginClient>(() => ({
+  name: 'default',
+  pluginName: 'plugin-client',
+  default(name, type) {
+    return camelCase(name, { isFile: type === 'file' })
+  },
+  resolveName(name) {
+    return this.default(name, 'function')
+  },
+}))

package/src/resolvers/resolverClientLegacy.ts

@@ -0,0 +1,26 @@
+import { camelCase } from '@internals/utils'
+import { defineResolver } from '@kubb/core'
+import type { PluginClient } from '../types.ts'
+
+/**
+ * Legacy resolver for `@kubb/plugin-client` that provides backward-compatible
+ * naming conventions matching the v4 behavior.
+ *
+ * @example
+ * ```ts
+ * import { resolverClientLegacy } from '@kubb/plugin-client'
+ *
+ * resolverClientLegacy.default('list pets', 'function') // -> 'listPets'
+ * resolverClientLegacy.resolveName('show pet by id')    // -> 'showPetById'
+ * ```
+ */
+export const resolverClientLegacy = defineResolver<PluginClient>(() => ({
+  name: 'kubbV4',
+  pluginName: 'plugin-client',
+  default(name, type) {
+    return camelCase(name, { isFile: type === 'file' })
+  },
+  resolveName(name) {
+    return this.default(name, 'function')
+  },
+}))

package/src/types.ts

@@ -1,8 +1,30 @@
-import type { Group, Output, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
+import type { Visitor } from '@kubb/ast/types'
+import type {
+  CompatibilityPreset,
+  Exclude,
+  Generator,
+  Group,
+  Include,
+  Output,
+  Override,
+  PluginFactoryOptions,
+  ResolvePathOptions,
+  Resolver,
+  UserGroup,
+} from '@kubb/core'
 
-import type { contentType, Oas } from '@kubb/oas'
-import type { Exclude, Include, Override, ResolvePathOptions } from '@kubb/plugin-oas'
-import type { Generator } from '@kubb/plugin-oas/generators'
+/**
+ * The concrete resolver type for `@kubb/plugin-client`.
+ * Extends the base `Resolver` with a `resolveName` helper for client function names.
+ */
+export type ResolverClient = Resolver & {
+  /**
+   * Resolves the function name for a given raw operation name.
+   * @example
+   * resolver.resolveName('show pet by id') // -> 'showPetById'
+   */
+  resolveName(this: ResolverClient, name: string): string
+}
 
 /**
  * Use either a preset `client` type OR a custom `importPath`, not both.
@@ -36,21 +58,56 @@ export type ClientImportPath =
       bundle?: never
     }
 
+/**
+ * Discriminated union that ties `pathParamsType` to the `paramsType` values where it is meaningful.
+ *
+ * - `paramsType: 'object'` — all parameters (including path params) are merged into a single
+ *   destructured object. `pathParamsType` is never reached in this code path and has no effect.
+ * - `paramsType?: 'inline'` (or omitted) — each parameter group is a separate function argument.
+ *   `pathParamsType` controls whether the path-param group itself is destructured (`'object'`)
+ *   or spread as individual arguments (`'inline'`).
+ */
+type ParamsTypeOptions =
+  | {
+      /**
+       * All parameters — path, query, headers, and body — are merged into a single
+       * destructured object argument.
+       * - 'object' returns the params and pathParams as an object.
+       * @default 'inline'
+       */
+      paramsType: 'object'
+      /**
+       * `pathParamsType` has no effect when `paramsType` is `'object'`.
+       * Path params are already inside the single destructured object.
+       */
+      pathParamsType?: never
+    }
+  | {
+      /**
+       * Each parameter group is emitted as a separate function argument.
+       * - 'inline' returns the params as comma separated params.
+       * @default 'inline'
+       */
+      paramsType?: 'inline'
+      /**
+       * Controls how path parameters are arranged within the inline argument list.
+       * - 'object' groups path params into a destructured object: `{ petId }: PathParams`.
+       * - 'inline' emits each path param as its own argument: `petId: string`.
+       * @default 'inline'
+       */
+      pathParamsType?: 'object' | 'inline'
+    }
+
 export type Options = {
   /**
-   * Specify the export location for the files and define the behavior of the output
+   * Specify the export location for the files and define the behavior of the output.
    * @default { path: 'clients', 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 clients based on the provided name.
    */
-  group?: Group
+  group?: UserGroup
   /**
    * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
    */
@@ -88,25 +145,11 @@ export type Options = {
    */
   dataReturnType?: 'data' | 'full'
   /**
-   * How to style your params, by default no casing is applied
+   * How to style your params, by default no casing is applied.
    * - 'camelcase' uses camelCase for pathParams, queryParams and headerParams names
    * @note response types (data/body) are not affected by this option
    */
   paramsCasing?: 'camelcase'
-  /**
-   * How to pass your params.
-   * - 'object' returns the params and pathParams as an object.
-   * - 'inline' returns the params as comma separated params.
-   * @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.
-   * @default 'inline'
-   */
-  pathParamsType?: 'object' | 'inline'
   /**
    * Which parser can be used before returning the data.
    * - 'client' returns the data as-is from the client.
@@ -138,33 +181,55 @@ export type Options = {
      */
     className: string
   }
-  transformers?: {
-    /**
-     * Customize the names based on the type that is provided by the plugin.
-     */
-    name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
-  }
   /**
-   * Define some generators next to the client generators
+   * Apply a compatibility naming preset.
+   * @default 'default'
+   */
+  compatibilityPreset?: CompatibilityPreset
+  /**
+   * Override individual resolver methods. Any method you omit falls back to the
+   * preset resolver's implementation. Use `this.default(...)` to call it.
+   */
+  resolver?: Partial<ResolverClient> & ThisType<ResolverClient>
+  /**
+   * Single AST visitor applied to each node before printing.
+   * Return `null` or `undefined` from a method to leave the node unchanged.
+   */
+  transformer?: Visitor
+  /**
+   * Define some generators next to the client generators.
    */
   generators?: Array<Generator<PluginClient>>
-} & ClientImportPath
+} & ClientImportPath &
+  ParamsTypeOptions
 
 type ResolvedOptions = {
-  output: Output<Oas>
-  group?: Options['group']
-  baseURL: string | undefined
+  output: Output
+  exclude: Array<Exclude>
+  include: Array<Include> | undefined
+  override: Array<Override<ResolvedOptions>>
+  group: Group | undefined
   client: Options['client']
   clientType: NonNullable<Options['clientType']>
   bundle: NonNullable<Options['bundle']>
   parser: NonNullable<Options['parser']>
   urlType: NonNullable<Options['urlType']>
   importPath: Options['importPath']
+  baseURL: Options['baseURL']
   dataReturnType: NonNullable<Options['dataReturnType']>
-  pathParamsType: NonNullable<Options['pathParamsType']>
+  pathParamsType: NonNullable<NonNullable<Options['pathParamsType']>>
   paramsType: NonNullable<Options['paramsType']>
   paramsCasing: Options['paramsCasing']
   wrapper: Options['wrapper']
+  resolver: ResolverClient
 }
 
-export type PluginClient = PluginFactoryOptions<'plugin-client', Options, ResolvedOptions, never, ResolvePathOptions>
+export type PluginClient = PluginFactoryOptions<'plugin-client', Options, ResolvedOptions, never, ResolvePathOptions, ResolverClient>
+
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-client': PluginClient
+    }
+  }
+}