@kubb/core 5.0.0-beta.2 → 5.0.0-beta.21

package/src/createRenderer.ts

@@ -3,53 +3,64 @@ import type { FileNode } from '@kubb/ast'
 /**
  * Minimal interface any Kubb renderer must satisfy.
  *
- * The generic `TElement` is the type of the element the renderer accepts —
- * e.g. `KubbReactElement` for `@kubb/renderer-jsx`, or a custom type for
- * your own renderer.  Defaults to `unknown` so that generators which do not
- * care about the element type continue to work without specifying it.
- *
- * This allows core to drive rendering without a hard dependency on
- * `@kubb/renderer-jsx` or any specific renderer implementation.
+ * `TElement` is the type the renderer accepts, for example `KubbReactElement`
+ * for `@kubb/renderer-jsx` or a custom type for your own renderer. Defaults to
+ * `unknown` so generators that don't care about the element type work without
+ * specifying it.
  */
 export type Renderer<TElement = unknown> = {
+  /**
+   * Renders `element` and populates {@link files} with the resulting {@link FileNode} objects.
+   * Called once per render cycle; must resolve before {@link files} is read.
+   */
   render(element: TElement): Promise<void>
+  /**
+   * Tears down the renderer and releases any held resources.
+   * Pass an `Error` to signal a failure, a number for an exit code, or omit for a clean shutdown.
+   */
   unmount(error?: Error | number | null): void
+  /**
+   * Releases any held resources. `[Symbol.dispose]` delegates here.
+   */
+  dispose(): void
+  /**
+   * Accumulated {@link FileNode} results produced by the last {@link render} call.
+   * Not populated when {@link stream} is implemented.
+   */
   readonly files: Array<FileNode>
+  /**
+   * When present, core calls this instead of {@link render} and {@link files},
+   * forwarding each file to `FileManager` as soon as it is ready.
+   */
+  stream?(element: TElement): Iterable<FileNode>
+  /**
+   * Disposer hook so renderers participate in `using` blocks: `using r = rendererFactory()`
+   * guarantees {@link dispose} runs on every exit path, including thrown errors.
+   */
+  [Symbol.dispose](): void
 }
 
 /**
- * A factory function that produces a fresh {@link Renderer} per render.
+ * A factory function that produces a fresh {@link Renderer} per render cycle.
  *
  * Generators use this to declare which renderer handles their output.
  */
 export type RendererFactory<TElement = unknown> = () => Renderer<TElement>
 
 /**
- * Creates a renderer factory for use in generator definitions.
- *
- * Wrap your renderer factory function with this helper to register it as the
- * renderer for a generator. Core will call this factory once per render cycle
- * to obtain a fresh renderer instance.
+ * Wraps a renderer factory for use in generator definitions.
  *
  * @example
  * ```ts
- * // packages/renderer-jsx/src/index.ts
  * export const jsxRenderer = createRenderer(() => {
  *   const runtime = new Runtime()
  *   return {
  *     async render(element) { await runtime.render(element) },
  *     get files() { return runtime.nodes },
+ *     dispose() { runtime.unmount() },
  *     unmount(error) { runtime.unmount(error) },
  *   }
  * })
- *
- * // packages/plugin-zod/src/generators/zodGenerator.tsx
- * import { jsxRenderer } from '@kubb/renderer-jsx'
- * export const zodGenerator = defineGenerator<PluginZod>({
- *   name: 'zod',
- *   renderer: jsxRenderer,
- *   schema(node, options) { return <File ...>...</File> },
- * })
  * ```
  */
 export function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement> {

package/src/defineGenerator.ts

@@ -1,9 +1,98 @@
-import type { PossiblePromise } from '@internals/utils'
-import type { FileNode, OperationNode, SchemaNode } from '@kubb/ast'
+import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
+import type { FileNode, InputMeta, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
+import type { Adapter } from './createAdapter.ts'
 import type { RendererFactory } from './createRenderer.ts'
-import type { GeneratorContext, PluginFactoryOptions } from './types.ts'
+import type { KubbHooks } from './types.ts'
+import type { KubbDriver } from './KubbDriver.ts'
+import type { Plugin, PluginFactoryOptions } from './definePlugin.ts'
+import type { Resolver } from './defineResolver.ts'
+import type { Config, DevtoolsOptions } from './types.ts'
 
-export type { GeneratorContext } from './types.ts'
+/**
+ * Context object passed to generator `schema`, `operation`, and `operations` methods.
+ *
+ * The adapter is always defined (guaranteed by `runPluginAstHooks`) so no runtime checks
+ * are needed. `ctx.options` carries resolved per-node options after exclude/include/override
+ * filtering for individual schema/operation calls, or plugin-level options for operations.
+ */
+export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config
+  /**
+   * Absolute path to the current plugin's output directory.
+   */
+  root: string
+  /**
+   * Determine output mode based on the output config.
+   * Returns `'single'` when `output.path` is a file, `'split'` for a directory.
+   */
+  getMode: (output: { path: string }) => 'single' | 'split'
+  driver: KubbDriver
+  /**
+   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
+   */
+  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined
+  getPlugin(name: string): Plugin | undefined
+  /**
+   * Get a plugin by name, throws an error if not found.
+   */
+  requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>
+  requirePlugin(name: string): Plugin
+  /**
+   * Get a resolver by plugin name, typed via `Kubb.PluginRegistry` when registered.
+   */
+  getResolver<TName extends keyof Kubb.PluginRegistry>(name: TName): Kubb.PluginRegistry[TName]['resolver']
+  getResolver(name: string): Resolver
+  /**
+   * Add files only if they don't exist.
+   */
+  addFile: (...file: Array<FileNode>) => Promise<void>
+  /**
+   * Merge sources into the same output file.
+   */
+  upsertFile: (...file: Array<FileNode>) => Promise<void>
+  hooks: AsyncEventEmitter<KubbHooks>
+  /**
+   * The current plugin instance.
+   */
+  plugin: Plugin<TOptions>
+  /**
+   * The current plugin's resolver.
+   */
+  resolver: TOptions['resolver']
+  /**
+   * The current plugin's transformer.
+   */
+  transformer: Visitor | undefined
+  /**
+   * Emit a warning.
+   */
+  warn: (message: string) => void
+  /**
+   * Emit an error.
+   */
+  error: (error: string | Error) => void
+  /**
+   * Emit an info message.
+   */
+  info: (message: string) => void
+  /**
+   * Open the current input node in Kubb Studio.
+   */
+  openInStudio: (options?: DevtoolsOptions) => Promise<void>
+  /**
+   * The configured adapter instance.
+   */
+  adapter: Adapter
+  /**
+   * Document metadata from the adapter — title, version, base URL, and pre-computed
+   * schema index fields (`circularNames`, `enumNames`).
+   */
+  meta: InputMeta
+  /**
+   * Resolved options after exclude/include/override filtering.
+   */
+  options: TOptions['resolvedOptions']
+}
 
 /**
  * Declares a named generator unit that walks the AST and emits files.
@@ -57,19 +146,19 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
   renderer?: RendererFactory<TElement> | null
   /**
    * Called for each schema node in the AST walk.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
    */
   schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
   /**
    * Called for each operation node in the AST walk.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
    */
   operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
   /**
    * Called once after all operations have been walked.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the plugin-level options for the batch call.
    */
   operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>

package/src/defineLogger.ts

@@ -1,9 +1,35 @@
-import type { Logger, LoggerOptions, UserLogger } from './types.ts'
+import type { AsyncEventEmitter } from '@internals/utils'
+import type { logLevel } from './constants.ts'
+import type { KubbHooks } from './types.ts'
+
+export type LoggerOptions = {
+  /**
+   * Log level for output verbosity.
+   * @default 3
+   */
+  logLevel: (typeof logLevel)[keyof typeof logLevel]
+}
+
+/**
+ * Shared context passed to plugins, parsers, and other internals.
+ */
+export type LoggerContext = AsyncEventEmitter<KubbHooks>
+
+export type Logger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = {
+  name: string
+  install: (context: LoggerContext, options?: TOptions) => TInstallReturn | Promise<TInstallReturn>
+}
+
+export type UserLogger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = Logger<TOptions, TInstallReturn>
 
 /**
  * Wraps a logger definition into a typed {@link Logger}.
  *
- * @example
+ * The optional second type parameter `TInstallReturn` allows loggers to return
+ * a value from `install` — for example, a sink factory that the caller can
+ * forward to hook execution.
+ *
+ * @example Basic logger
  * ```ts
  * export const myLogger = defineLogger({
  *   name: 'my-logger',
@@ -13,7 +39,20 @@ import type { Logger, LoggerOptions, UserLogger } from './types.ts'
  *   },
  * })
  * ```
+ *
+ * @example Logger that returns a hook sink factory
+ * ```ts
+ * export const myLogger = defineLogger<LoggerOptions, HookSinkFactory>({
+ *   name: 'my-logger',
+ *   install(context, options) {
+ *     // … register event handlers …
+ *     return (commandWithArgs) => ({ onStdout: console.log })
+ *   },
+ * })
+ * ```
  */
-export function defineLogger<Options extends LoggerOptions = LoggerOptions>(logger: UserLogger<Options>): Logger<Options> {
+export function defineLogger<Options extends LoggerOptions = LoggerOptions, TInstallReturn = void>(
+  logger: UserLogger<Options, TInstallReturn>,
+): Logger<Options, TInstallReturn> {
   return logger
 }

package/src/defineMiddleware.ts

@@ -1,4 +1,4 @@
-import type { KubbHooks } from './Kubb.ts'
+import type { KubbHooks } from './types.ts'
 
 /**
  * A middleware instance produced by calling a factory created with `defineMiddleware`.

package/src/defineParser.ts

@@ -17,7 +17,7 @@ export type Parser<TMeta extends object = any> = {
   /**
    * Convert a resolved file to a string.
    */
-  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string
+  parse(file: FileNode<TMeta>, options?: PrintOptions): string
 }
 
 /**

package/src/definePlugin.ts

@@ -1,5 +1,260 @@
-import type { KubbHooks } from './Kubb.ts'
-import type { KubbPluginSetupContext, PluginFactoryOptions } from './types.ts'
+import { extname } from 'node:path'
+import type { FileNode, HttpMethod, InputMeta, UserFileNode, Visitor } from '@kubb/ast'
+import type { RendererFactory } from './createRenderer.ts'
+import type { Generator } from './defineGenerator.ts'
+import type { Resolver } from './defineResolver.ts'
+import type { Config, KubbHooks } from './types.ts'
+
+/**
+ * Safely extracts a type from a registry, returning `{}` if the key doesn't exist.
+ * Enables optional interface augmentation for `Kubb.ConfigOptionsRegistry` and `Kubb.PluginOptionsRegistry`
+ * without requiring changes to core.
+ *
+ * @internal
+ */
+type ExtractRegistryKey<T, K extends PropertyKey> = K extends keyof T ? T[K] : {}
+
+/**
+ * Output configuration for generated files.
+ */
+export type Output<_TOptions = unknown> = {
+  /**
+   * Output folder or file path for generated code.
+   */
+  path: string
+  /**
+   * Text or function prepended to every generated file.
+   * When a function, receives the document metadata and returns a string.
+   */
+  banner?: string | ((meta?: InputMeta) => string)
+  /**
+   * Text or function appended to every generated file.
+   * When a function, receives the document metadata and returns a string.
+   */
+  footer?: string | ((meta?: InputMeta) => string)
+  /**
+   * Whether to override existing external files if they already exist.
+   * @default false
+   */
+  override?: boolean
+} & ExtractRegistryKey<Kubb.PluginOptionsRegistry, 'output'>
+
+export type Group = {
+  /**
+   * How to group files into subdirectories.
+   * - `'tag'` — group by OpenAPI tags
+   * - `'path'` — group by OpenAPI paths
+   */
+  type: 'tag' | 'path'
+  /**
+   * Function that returns the subdirectory name for a group value.
+   * Defaults to `${camelCase(group)}Controller` for tags, first path segment for paths.
+   */
+  name?: (context: { group: string }) => string
+}
+
+type ByTag = {
+  /**
+   * Filter by OpenAPI `tags` field. Matches one or more tags assigned to operations.
+   */
+  type: 'tag'
+  /**
+   * Tag name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp
+}
+
+type ByOperationId = {
+  /**
+   * Filter by OpenAPI `operationId` field. Each operation (GET, POST, etc.) has a unique identifier.
+   */
+  type: 'operationId'
+  /**
+   * Operation ID to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp
+}
+
+type ByPath = {
+  /**
+   * Filter by OpenAPI `path` (URL endpoint). Useful to group or filter by service segments like `/pets`, `/users`, etc.
+   */
+  type: 'path'
+  /**
+   * URL path to match (case-sensitive). Can be a literal string or regex pattern. Matches against the full path.
+   */
+  pattern: string | RegExp
+}
+
+type ByMethod = {
+  /**
+   * Filter by HTTP method: `'get'`, `'post'`, `'put'`, `'delete'`, `'patch'`, `'head'`, `'options'`.
+   */
+  type: 'method'
+  /**
+   * HTTP method to match (case-insensitive when using string, or regex for dynamic matching).
+   */
+  pattern: HttpMethod | RegExp
+}
+// TODO implement as alternative for ByMethod
+// type ByMethods = {
+//   type: 'methods'
+//   pattern: Array<HttpMethod>
+// }
+
+type BySchemaName = {
+  /**
+   * Filter by schema component name (TypeScript or JSON schema). Matches schemas in `#/components/schemas`.
+   */
+  type: 'schemaName'
+  /**
+   * Schema name to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp
+}
+
+type ByContentType = {
+  /**
+   * Filter by response or request content type: `'application/json'`, `'application/xml'`, etc.
+   */
+  type: 'contentType'
+  /**
+   * Content type to match (case-sensitive). Can be a literal string or regex pattern.
+   */
+  pattern: string | RegExp
+}
+
+/**
+ * A pattern filter that prevents matching nodes from being generated.
+ *
+ * Use to skip code generation for specific operations or schemas. For example, exclude deprecated endpoints
+ * or internal-only schemas. Can filter by tag, operationId, path, HTTP method, content type, or schema name.
+ *
+ * @example
+ * ```ts
+ * exclude: [
+ *   { type: 'tag', pattern: 'internal' },          // skip "internal" tag
+ *   { type: 'path', pattern: /^\/admin/ },          // skip all /admin endpoints
+ *   { type: 'operationId', pattern: 'deprecated_*' }  // skip operationIds matching pattern
+ * ]
+ * ```
+ */
+export type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+
+/**
+ * A pattern filter that restricts generation to only matching nodes.
+ *
+ * Use to generate code for a subset of operations or schemas. For example, only generate for a specific service
+ * tag or only for "production" endpoints. Can filter by tag, operationId, path, HTTP method, content type, or schema name.
+ *
+ * @example
+ * ```ts
+ * include: [
+ *   { type: 'tag', pattern: 'public' },        // generate only "public" tag
+ *   { type: 'path', pattern: /^\/api\/v1/ },   // generate only v1 endpoints
+ * ]
+ * ```
+ */
+export type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+
+/**
+ * A pattern filter paired with partial option overrides applied when the pattern matches.
+ *
+ * Use to customize generation for specific operations or schemas. For example, apply different output paths
+ * for different tags, or use custom resolver functions per operation. Can filter by tag, operationId, path,
+ * HTTP method, schema name, or content type.
+ *
+ * @example
+ * ```ts
+ * override: [
+ *   {
+ *     type: 'tag',
+ *     pattern: 'admin',
+ *     options: { output: { path: './src/gen/admin' } }  // admin APIs go to separate folder
+ *   },
+ *   {
+ *     type: 'operationId',
+ *     pattern: 'listPets',
+ *     options: { exclude: true }  // skip this specific operation
+ *   }
+ * ]
+ * ```
+ */
+export type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
+  //TODO should be options: Omit<Partial<TOptions>, 'override'>
+  options: Partial<TOptions>
+}
+
+export type PluginFactoryOptions<
+  /**
+   * Unique plugin name.
+   */
+  TName extends string = string,
+  /**
+   * User-facing plugin options.
+   */
+  TOptions extends object = object,
+  /**
+   * Plugin options after defaults are applied.
+   */
+  TResolvedOptions extends object = TOptions,
+  /**
+   * Resolver that encapsulates naming and path-resolution helpers.
+   * Define with `defineResolver` and export alongside the plugin.
+   */
+  TResolver extends Resolver = Resolver,
+> = {
+  name: TName
+  options: TOptions
+  resolvedOptions: TResolvedOptions
+  resolver: TResolver
+}
+
+/**
+ * Context for hook-style plugin `kubb:plugin:setup` handler.
+ * Provides methods to register generators, configure resolvers, transformers, and renderers.
+ */
+export type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactoryOptions> = {
+  /**
+   * Register a generator dynamically. Generators fire during the AST walk (schema/operation/operations)
+   * just like generators declared statically on `createPlugin`.
+   */
+  addGenerator<TElement = unknown>(generator: Generator<TFactory, TElement>): void
+  /**
+   * Set or override the resolver for this plugin.
+   * The resolver controls file naming and path resolution.
+   */
+  setResolver(resolver: Partial<TFactory['resolver']>): void
+  /**
+   * Set the AST transformer to pre-process nodes before they reach generators.
+   */
+  setTransformer(visitor: Visitor): void
+  /**
+   * Set the renderer factory to process JSX elements from generators.
+   */
+  setRenderer(renderer: RendererFactory): void
+  /**
+   * Set resolved options merged into the normalized plugin's `options`.
+   * Call this in `kubb:plugin:setup` to provide options generators need.
+   */
+  setOptions(options: TFactory['resolvedOptions']): void
+  /**
+   * Inject a raw file into the build output, bypassing the generation pipeline.
+   */
+  injectFile(userFileNode: UserFileNode): void
+  /**
+   * Merge a partial config update into the current build configuration.
+   */
+  updateConfig(config: Partial<Config>): void
+  /**
+   * The resolved build configuration at setup time.
+   */
+  config: Config
+  /**
+   * The plugin's user-provided options.
+   */
+  options: TFactory['options']
+}
 
 /**
  * A plugin object produced by `definePlugin`.
@@ -37,20 +292,52 @@ export type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>
    * Any event from the global `KubbHooks` map can be subscribed to here.
    */
   hooks: {
-    [K in Exclude<keyof KubbHooks, 'kubb:plugin:setup'>]?: (...args: KubbHooks[K]) => void | Promise<void>
+    [K in keyof KubbHooks as K extends 'kubb:plugin:setup' ? never : K]?: (...args: KubbHooks[K]) => void | Promise<void>
   } & {
     'kubb:plugin:setup'?(ctx: KubbPluginSetupContext<TFactory>): void | Promise<void>
   }
 }
 
 /**
- * Returns `true` when `plugin` is a hook-style plugin created with `definePlugin`.
+ * Normalized plugin after setup, with runtime fields populated.
+ * For internal use only — plugins use the public `Plugin` type externally.
  *
- * Used by `PluginDriver` to distinguish hook-style plugins from legacy `createPlugin` plugins
- * so it can normalize them and register their handlers on the `AsyncEventEmitter`.
+ * @internal
  */
-export function isPlugin(plugin: unknown): plugin is Plugin {
-  return typeof plugin === 'object' && plugin !== null && 'hooks' in plugin
+export type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = Plugin<TOptions> & {
+  options: TOptions['resolvedOptions'] & {
+    output: Output
+    include?: Array<Include>
+    exclude: Array<Exclude>
+    override: Array<Override<TOptions['resolvedOptions']>>
+  }
+  resolver: TOptions['resolver']
+  transformer?: Visitor
+  renderer?: RendererFactory
+  generators?: Array<Generator>
+  apply?: (config: Config) => boolean
+  version?: string
+}
+
+export type KubbPluginStartContext = {
+  plugin: NormalizedPlugin
+}
+
+export type KubbPluginEndContext = {
+  plugin: NormalizedPlugin
+  duration: number
+  success: boolean
+  error?: Error
+  config: Config
+  /**
+   * Returns all files currently in the file manager (lazy snapshot).
+   * Includes files added by plugins that have already run.
+   */
+  readonly files: ReadonlyArray<FileNode>
+  /**
+   * Upsert one or more files into the file manager.
+   */
+  upsertFile: (...files: Array<FileNode>) => void
 }
 
 /**
@@ -81,3 +368,12 @@ export function definePlugin<TFactory extends PluginFactoryOptions = PluginFacto
 ): (options?: TFactory['options']) => Plugin<TFactory> {
   return (options) => factory(options ?? ({} as TFactory['options']))
 }
+
+/**
+ * Returns `'single'` when `fileOrFolder` has a file extension, `'split'` otherwise.
+ * Used to determine whether an output path targets a single file or a directory.
+ */
+export function getMode(fileOrFolder: string | undefined | null): 'single' | 'split' {
+  if (!fileOrFolder) return 'split'
+  return extname(fileOrFolder) ? 'single' : 'split'
+}