@kubb/plugin-client 5.12.0-canary.20261109T134631 → 6.0.0

package/src/generators/sdkGenerator.tsx

@@ -0,0 +1,209 @@
+import path from 'node:path'
+import { type OperationTypeSource, resolveOperationTypes, resultTypeName } from '@internals/client'
+import { isEventStream } from '@internals/shared'
+import { ensureValidVarName } from '@internals/utils'
+import { ast, defineGenerator, Diagnostics } from '@kubb/kit'
+import type { Generator } from '@kubb/kit'
+import { File, jsxRenderer } from '@kubb/renderer-jsx'
+import { type GeneratorContext, type OperationData, resolveOperationData } from '../builders/operationData.ts'
+import { buildEventStreamImports } from '../builders/returnStatement.ts'
+import { isValidatorEnabled } from '../builders/validatorOptions.ts'
+import { SdkClient } from '../components/SdkClient.tsx'
+import { ClientRuntime } from '../components/ClientRuntime.tsx'
+import { SdkFacade } from '../components/SdkFacade.tsx'
+import type { ContractClientFactory } from '../types.ts'
+
+type Controller = {
+  name: string
+  tag: string | undefined
+  file: ast.FileNode
+  operations: Array<OperationData>
+}
+
+/**
+ * Groups operations into one controller per tag. Operations without a tag fall back to a single
+ * `Client`/`ApiClient` controller, matching the resolver's default naming.
+ */
+function buildControllers(nodes: ReadonlyArray<ast.OperationNode>, ctx: GeneratorContext, types: OperationTypeSource): Array<Controller> {
+  const { resolver, root } = ctx
+  const { output, group } = ctx.options
+
+  return nodes.reduce((acc, operationNode) => {
+    if (!ast.http.isOperation(operationNode)) return acc
+    const tag = operationNode.tags[0]
+    const name = tag ? ensureValidVarName(resolver.groupName(tag)) : resolver.className('ApiClient')
+    // `group.name` names the folder and file, never the class.
+    const fileName = tag && group ? ensureValidVarName(path.basename(resolver.groupDir(group, tag))) : name
+    const file = resolver.file({ name: fileName, extname: '.ts', tag, root, output, group: group ?? undefined })
+    const operationData = resolveOperationData({ node: operationNode, ctx, types })
+    const previous = acc.find((item) => item.file.path === file.path)
+
+    if (previous) {
+      previous.operations.push(operationData)
+    } else {
+      acc.push({ name, tag, file, operations: [operationData] })
+    }
+
+    return acc
+  }, [] as Array<Controller>)
+}
+
+function collectImportsByFile(ops: Array<OperationData>, pick: (op: OperationData) => { file: ast.FileNode | null; names: Array<string> }) {
+  const namesByPath = new Map<string, Set<string>>()
+  const filesByPath = new Map<string, ast.FileNode>()
+
+  ops.forEach((op) => {
+    const { file, names } = pick(op)
+    if (!file || names.length === 0) return
+    if (!namesByPath.has(file.path)) namesByPath.set(file.path, new Set())
+    const set = namesByPath.get(file.path)!
+    names.forEach((n) => set.add(n))
+    filesByPath.set(file.path, file)
+  })
+
+  return { namesByPath, filesByPath }
+}
+
+/**
+ * Builds the class-based SDK generator for a client plugin (`@kubb/plugin-fetch`,
+ * `@kubb/plugin-axios`). Only registered when `sdk` is set; otherwise the plugin keeps its
+ * standalone per-operation functions.
+ *
+ * Every tag client is an instance class whose constructor takes a client config and builds its own
+ * client, or takes an existing client, so each environment is a separate instance. With `sdk.mode:
+ * 'tag'` (the default) it emits one class per tag, named by `resolver.groupName`, and, when `sdk.name`
+ * is set, a composed root that creates one client and shares it with every tag client. With
+ * `sdk.mode: 'flat'` it emits one class named by `sdk.name`, with every operation as a direct method.
+ *
+ * `templates` is the folder the optional runtime is copied from: `sse.ts` only for a document that streams, and each
+ * form media type only for a document with a body of that type.
+ */
+export function createSdkGenerator<TFactory extends ContractClientFactory>({ templates }: { templates?: string } = {}): Generator<TFactory> {
+  return defineGenerator<TFactory>({
+    name: 'sdk',
+    renderer: jsxRenderer,
+    operations(nodes, ctx) {
+      const { config, resolver, root } = ctx
+      const { output, group, validator, returnType, throwOnErrorDefault, sdk } = ctx.options
+
+      if (!sdk) return null
+
+      // `resolver.file(...)` resolves every tag to the same single `output.path` under `mode:
+      // 'file'`, so a tag-per-class split has nothing to split into: every tag would collapse
+      // into whichever controller `buildControllers` reduces first, silently dropping the rest.
+      if (sdk.mode === 'tag' && output.mode === 'file') {
+        throw new Diagnostics.Error({
+          code: Diagnostics.code.invalidPluginOptions,
+          severity: 'error',
+          message: `Plugin "${ctx.plugin.name}" resolves \`output.mode\` to 'file' but also configures \`sdk.mode: 'tag'\`.`,
+          help: "A single-file output has nothing to split tag classes into. Set `sdk.mode: 'flat'` to emit one class into that file, or give `output.path` an extensionless directory name (or set `output.mode: 'directory'` explicitly) so each tag gets its own file.",
+          location: { kind: 'config' },
+          plugin: ctx.plugin.name,
+        })
+      }
+
+      const types = resolveOperationTypes(ctx.driver, ctx.plugin.name)
+
+      const validatorEnabled = isValidatorEnabled(validator)
+      const controllers = buildControllers(nodes, ctx, types)
+      const clientPath = path.resolve(root, '.kubb/client.ts')
+      const standardSchemaPath = path.resolve(root, '.kubb/standardSchema.ts')
+
+      const banner = (file: ast.FileNode) => resolver.default.banner(ctx.meta, { output, config, file: { path: file.path, baseName: file.baseName } })
+      const footer = (file: ast.FileNode) => resolver.default.footer(ctx.meta, { output, config, file: { path: file.path, baseName: file.baseName } })
+
+      const renderClassFile = (className: string, file: ast.FileNode, ops: Array<OperationData>) => {
+        const { namesByPath: typeNamesByPath, filesByPath: typeFilesByPath } = collectImportsByFile(ops, (op) => ({
+          file: op.typeFile,
+          names: [op.types.response.options(op.node), op.types.response.responses(op.node), ...op.headerTypeNames],
+        }))
+        const { namesByPath: zodNamesByPath, filesByPath: zodFilesByPath } = validatorEnabled
+          ? collectImportsByFile(ops, (op) => ({ file: op.zodFile, names: op.validatorHooks.importedZodNames }))
+          : { namesByPath: new Map<string, Set<string>>(), filesByPath: new Map<string, ast.FileNode>() }
+        const resultOps = ops.filter((op) => !isEventStream(op.node))
+        const typedHeaders = (op: OperationData) => op.headerTypeNames.length > 0
+        const resultName = returnType === 'data' ? 'UnwrappedResult' : 'RequestResult'
+
+        return (
+          <File key={file.path} baseName={file.baseName} path={file.path} meta={file.meta} banner={banner(file)} footer={footer(file)}>
+            <File.Import
+              name={[
+                'createClient',
+                returnType === 'data' ? 'unwrapResult' : 'withUnwrap',
+                'resolveThrowOnError',
+                ...(ctx.options.importPath === undefined && ops.some((op) => op.security) ? ['securitySchemes'] : []),
+              ]}
+              root={file.path}
+              path={clientPath}
+            />
+            <File.Import
+              name={Array.from(
+                new Set([
+                  'ClientConfig',
+                  'ClientInstance',
+                  'Options',
+                  ...(returnType === 'data' ? [] : ['Unwrappable']),
+                  ...(resultOps.some((op) => !typedHeaders(op)) ? [resultName] : []),
+                  ...(resultOps.some(typedHeaders) ? [resultTypeName(resultName, true)] : []),
+                  ...ops.filter((op) => isEventStream(op.node)).flatMap((op) => buildEventStreamImports({ node: op.node, types: op.types, returnType })),
+                ]),
+              )}
+              root={file.path}
+              path={clientPath}
+              isTypeOnly
+            />
+
+            {validator === 'zod' && ops.some((op) => ast.http.requestBody.getSchema(op.node) != null) && <File.Import name={['z']} path="zod" isTypeOnly />}
+
+            {Array.from(typeNamesByPath.entries()).map(([filePath, set]) => (
+              <File.Import key={filePath} name={Array.from(set)} root={file.path} path={typeFilesByPath.get(filePath)!.path} isTypeOnly />
+            ))}
+
+            {validatorEnabled &&
+              Array.from(zodNamesByPath.entries()).map(([filePath, set]) => (
+                <File.Import key={filePath} name={Array.from(set)} root={file.path} path={zodFilesByPath.get(filePath)!.path} />
+              ))}
+
+            {ops.some((op) => op.validatorHooks.headers) && <File.Import name={['toHeadersStandardSchema']} root={file.path} path={standardSchemaPath} />}
+
+            <SdkClient name={className} operations={ops} returnType={returnType} throwOnErrorDefault={throwOnErrorDefault} />
+          </File>
+        )
+      }
+
+      // `flat` collapses every operation into one class named by `sdk.name`, so callers reach
+      // an operation as `new PetStore(config).getPetById(...)` without a per-tag sub-client.
+      const renderFacadeFile = (name: string) => {
+        const sdkFile = resolver.file({ name, extname: '.ts', root, output, group: group ?? undefined })
+        const members = controllers.map(({ name, tag }) => ({ className: name, propName: resolver.propertyName(tag ?? name) }))
+
+        return (
+          <File key={sdkFile.path} baseName={sdkFile.baseName} path={sdkFile.path} meta={sdkFile.meta} banner={banner(sdkFile)} footer={footer(sdkFile)}>
+            <File.Import name={['createClient']} root={sdkFile.path} path={clientPath} />
+            <File.Import name={['ClientConfig', 'ClientInstance']} root={sdkFile.path} path={clientPath} isTypeOnly />
+            {controllers.map(({ name, file }) => (
+              <File.Import key={name} name={[name]} root={sdkFile.path} path={file.path} />
+            ))}
+            <SdkFacade name={resolver.className(name)} members={members} />
+          </File>
+        )
+      }
+
+      const files =
+        sdk.mode === 'flat'
+          ? renderClassFile(
+              resolver.className(sdk.name ?? 'sdk'),
+              resolver.file({ name: sdk.name ?? 'sdk', extname: '.ts', root, output, group: group ?? undefined }),
+              controllers.flatMap((controller) => controller.operations),
+            )
+          : [...controllers.map(({ name, file, operations: ops }) => renderClassFile(name, file, ops)), sdk.name && renderFacadeFile(sdk.name)]
+
+      return (
+        <>
+          <ClientRuntime nodes={nodes} root={root} templates={templates} baseURL={ctx.options.baseURL} servers={ctx.meta.servers} auth={ctx.meta.auth} />
+          {files}
+        </>
+      )
+    },
+  })
+}

package/src/index.ts

@@ -1,2 +1,4 @@
 export { default, pluginClient, pluginClientName } from './plugin.ts'
-export type { Options, PluginClient, ResolvedOptions, ResolverClient } from './types.ts'
+export { resolverClient } from './resolver.ts'
+export { clientDependencies, resolveClientOptions, setupClient } from './setup.ts'
+export type { ClientOptions, ClientResolvedOptions, Options, PluginClient, ResolvedOptions, ResolverClient } from './types.ts'

package/src/macros.ts

@@ -0,0 +1,9 @@
+import { macroDedupeUnion } from '@kubb/kit'
+import type { ast } from '@kubb/kit'
+
+/**
+ * Macros the client plugins apply by default, ahead of any user macros. `macroDedupeUnion`
+ * drops repeated union members, keeping the generated response and error
+ * unions tidy. A plugin wires them with `ctx.setMacros([...defaultMacros, ...userMacros])`.
+ */
+export const defaultMacros: ReadonlyArray<ast.Macro> = [macroDedupeUnion]

package/src/plugin.ts

@@ -1,11 +1,10 @@
-import { createGroupConfig } from '@internals/shared'
 import { addGenerator, defineExtension, Resolver, setMacros, setResolver } from '@kubb/kit'
 import { compatibility } from '../kubb-extension.json'
 import { version } from '../package.json'
-import { pluginTsName } from '@kubb/plugin-ts'
-import { pluginZodName } from '@kubb/plugin-zod'
-import { clientGenerator } from './generators/clientGenerator.tsx'
-import { defaultMacros, isValidatorEnabled, resolverClient } from '@internals/client'
+import { createClientGenerator } from './generators/clientGenerator.tsx'
+import { defaultMacros } from './macros.ts'
+import { resolverClient } from './resolver.ts'
+import { clientDependencies } from './setup.ts'
 import type { PluginClient, ResolverClient } from './types.ts'
 
 /**
@@ -26,7 +25,7 @@ export const pluginClientName = 'plugin-client' satisfies PluginClient['name']
 export const pluginClient = defineExtension<PluginClient>({
   kind: 'plugin',
   meta: { name: pluginClientName, version, compatibility },
-  dependencies: (options) => ({ [pluginTsName]: { optional: true }, [pluginZodName]: { optional: !isValidatorEnabled(options.validator) } }),
+  dependencies: clientDependencies,
   setup(options) {
     const {
       output = { path: 'clients', barrel: { type: 'named' } },
@@ -36,6 +35,7 @@ export const pluginClient = defineExtension<PluginClient>({
       importPath,
       throwOnErrorDefault = true,
       validator = false,
+      returnType = 'plain',
       group,
       resolver: userResolver,
     } = options
@@ -44,19 +44,19 @@ export const pluginClient = defineExtension<PluginClient>({
 
     setResolver(resolver)
     setMacros([...defaultMacros, ...(options.macros ?? [])])
-    addGenerator(clientGenerator)
+    addGenerator(createClientGenerator<PluginClient>('client'))
 
     return {
       output,
       exclude,
       include,
       override,
-      group: createGroupConfig(group),
+      group: group ?? null,
       importPath,
       baseURL: undefined,
       throwOnErrorDefault,
       validator,
-      returnType: 'plain',
+      returnType,
       sdk: undefined,
       resolver,
     }

package/src/resolver.ts

@@ -0,0 +1,28 @@
+import { resolveOperationName } from '@internals/shared'
+import { ensureValidVarName } from '@internals/utils'
+import { casing, createResolver } from '@kubb/kit'
+import type { PluginContractClient, ResolverClient } from './types.ts'
+
+/**
+ * Default resolver shared by the client plugins. Functions use safe camelCase identifiers and
+ * files inherit the built-in casing; classes and tag groups use PascalCase.
+ *
+ * @example
+ * ```ts
+ * resolverClient.name('show pet by id')  // 'showPetById'
+ * resolverClient.groupName('pet')        // 'PetClient'
+ * ```
+ */
+export const resolverClient: ResolverClient = createResolver<PluginContractClient>({
+  pluginName: 'plugin-contract-client',
+  name: resolveOperationName,
+  className(name) {
+    return ensureValidVarName(casing.pascal(name))
+  },
+  groupName(name) {
+    return ensureValidVarName(casing.pascal(`${name} Client`))
+  },
+  propertyName(name) {
+    return ensureValidVarName(casing.camel(name))
+  },
+})

package/src/setup.ts

@@ -0,0 +1,90 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { addGenerator, injectFile, Resolver, setMacros, setResolver, useConfig } from '@kubb/kit'
+import { pluginTsName } from '@kubb/plugin-ts'
+import { pluginZodName } from '@kubb/plugin-zod'
+import { isValidatorEnabled } from './builders/validatorOptions.ts'
+import { createClientGenerator } from './generators/clientGenerator.tsx'
+import { createSdkGenerator } from './generators/sdkGenerator.tsx'
+import { defaultMacros } from './macros.ts'
+import { resolverClient } from './resolver.ts'
+import type { ClientOptions, ClientResolvedOptions, ContractClientFactory, ResolverClient } from './types.ts'
+
+// Resolved from a file directly in `src/`, so the same `../templates/` path works from `dist/`.
+const templatePath = (name: string) => fileURLToPath(new URL(`../templates/${name}`, import.meta.url))
+
+/**
+ * Applies the client option defaults and merges a user `resolver` over the built-in one.
+ */
+export function resolveClientOptions(options: ClientOptions): ClientResolvedOptions {
+  const {
+    output = { path: 'clients', barrel: { type: 'named' } },
+    exclude = [],
+    include,
+    override = [],
+    baseURL,
+    throwOnErrorDefault = true,
+    validator = false,
+    returnType = 'full',
+    group,
+    sdk,
+    resolver: userResolver,
+  } = options
+
+  return {
+    output,
+    exclude,
+    include,
+    override,
+    group: group ?? null,
+    baseURL,
+    throwOnErrorDefault,
+    validator,
+    returnType,
+    sdk: sdk ? { mode: sdk.mode ?? 'tag', name: sdk.name } : undefined,
+    resolver: userResolver ? Resolver.merge<ResolverClient>(resolverClient, userResolver) : resolverClient,
+  }
+}
+
+/**
+ * Wires a client plugin in its `setup`: resolver, macros, client or SDK generator, and the `.kubb/` runtime with the plugin's own `client.ts`.
+ */
+export function setupClient({
+  name,
+  resolved,
+  macros = [],
+  client,
+}: {
+  name: string
+  resolved: ClientResolvedOptions
+  macros?: ClientOptions['macros']
+  client: string
+}): void {
+  const config = useConfig()
+
+  setResolver(resolved.resolver)
+  setMacros([...defaultMacros, ...macros])
+
+  const templates = templatePath('')
+  addGenerator<ContractClientFactory>(resolved.sdk ? createSdkGenerator({ templates }) : createClientGenerator(name, { templates }))
+
+  const root = path.resolve(config.root, config.output.path)
+  const files = [
+    ['serializers.ts', templatePath('serializers.ts')],
+    ['mediaTypes.ts', templatePath('mediaTypes.ts')],
+    ['core.ts', templatePath('core.ts')],
+    ['client.ts', client],
+    ['standardSchema.ts', templatePath('standardSchema.ts')],
+  ] as const
+
+  for (const [baseName, copy] of files) {
+    injectFile({ baseName, path: path.resolve(root, '.kubb', baseName), copy })
+  }
+}
+
+/**
+ * Declares `plugin-ts` as optional and `plugin-zod` as required once `validator` enables a direction.
+ */
+export function clientDependencies(options: Pick<ClientOptions, 'validator'>) {
+  return { [pluginTsName]: { optional: true }, [pluginZodName]: { optional: !isValidatorEnabled(options.validator) } }
+}

package/src/types.ts

@@ -1,7 +1,9 @@
 import type { Override, PluginType } from '@kubb/kit'
-import type { Options as ClientOptions, ResolvedOptions as ClientResolvedOptions, ResolverClient } from '@internals/client'
+import type { ReturnTypeOption } from '@internals/client'
+import type { ClientOptions, ClientResolvedOptions, ResolverClient } from './clientTypes.ts'
 
-export type { ResolverClient } from '@internals/client'
+export type * from './clientTypes.ts'
+export type { ReturnTypeOption } from '@internals/client'
 
 /**
  * Omits keys from every member of a union, where the built-in `Omit` would collapse the union into one shape.
@@ -18,6 +20,18 @@ type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K>
  * ```
  */
 export type Options = DistributiveOmit<ClientOptions, 'sdk' | 'returnType' | 'baseURL' | 'override'> & {
+  /**
+   * Shape of the value a generated operation resolves to. `'full'` and `'data'` import `withUnwrap` or `unwrapResult`
+   * and their types from your `importPath` module, so that module must export them.
+   *
+   * @default 'plain'
+   * @example
+   * ```ts
+   * pluginClient({ importPath: '../../client', returnType: 'full' })
+   * // await getPetById({ path: { petId: 1 } }).unwrap()
+   * ```
+   */
+  returnType?: ReturnTypeOption
   /**
    * Applies different options to operations that match a pattern.
    * `sdk`, `returnType`, and `baseURL` are not available, because this plugin generates standalone operations and your client module owns the base URL.

package/templates/client.ts

@@ -1,5 +1,6 @@
 // Stands in for the transport's `client.ts` next to `sse.ts`, so the shared templates typecheck on their own. In the
 // generated `.kubb/` folder, `sse.ts` reads these from the real client; this file is never copied.
-export type { DataShape, Options, RequestResult, SuccessOf } from './core.ts'
+export type * from './core.ts'
+export type NativeOptions = Record<string, unknown>
 export type NativeRequest = unknown
 export type NativeResponse = unknown