@kubb/core 5.0.0-beta.4 → 5.0.0-beta.40

package/src/defineMiddleware.ts

@@ -1,20 +1,19 @@
-import type { KubbHooks } from './Kubb.ts'
+import type { KubbHooks } from './types.ts'
 
 /**
- * A middleware instance produced by calling a factory created with `defineMiddleware`.
- * It declares event handlers under a `hooks` object which are registered on the
- * shared emitter after all plugin hooks, so middleware handlers for any event
- * always fire last.
+ * A middleware instance. Subscribes to lifecycle events via `hooks`. Middleware
+ * handlers always fire after every plugin handler for the same event, so they
+ * see the full set of generated files.
  */
 export type Middleware = {
   /**
-   * Unique identifier for this middleware.
+   * Unique name. Use a `middleware-<feature>` convention (e.g.
+   * `middleware-barrel`).
    */
   name: string
   /**
-   * Lifecycle event handlers for this middleware.
-   * Any event from the global `KubbHooks` map can be subscribed to here.
-   * Handlers are registered after all plugin handlers, so they always fire last.
+   * Lifecycle event handlers. Any event from the global `KubbHooks` map can be
+   * subscribed to here. Handlers run after all plugin handlers for that event.
    */
   hooks: {
     [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void>
@@ -22,18 +21,17 @@ export type Middleware = {
 }
 
 /**
- * Creates a middleware factory using the hook-style `hooks` API.
+ * Creates a middleware factory. Middleware fires after every plugin handler
+ * for the same event, which makes it the natural place for post-processing
+ * (barrel files, lint runs, audit logs).
  *
- * Middleware handlers fire after all plugin handlers for any given event, making them ideal for post-processing, logging, and auditing.
- * Per-build state (such as accumulators) belongs inside the factory closure so each `createKubb` invocation gets its own isolated instance.
+ * Per-build state belongs inside the factory closure so each `createKubb`
+ * invocation gets its own isolated instance.
  *
- * @note The factory can accept typed options. See examples for using options and per-build state patterns.
- *
- * @example
+ * @example Stateless middleware
  * ```ts
  * import { defineMiddleware } from '@kubb/core'
  *
- * // Stateless middleware
  * export const logMiddleware = defineMiddleware(() => ({
  *   name: 'log-middleware',
  *   hooks: {
@@ -42,8 +40,12 @@ export type Middleware = {
  *     },
  *   },
  * }))
+ * ```
+ *
+ * @example Middleware with options and per-build state
+ * ```ts
+ * import { defineMiddleware } from '@kubb/core'
  *
- * // Middleware with options and per-build state
  * export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
  *   const seen = new Set<string>()
  *   return {

package/src/defineParser.ts

@@ -4,41 +4,58 @@ type PrintOptions = {
   extname?: FileNode['extname']
 }
 
-export type Parser<TMeta extends object = any> = {
+/**
+ * Converts a resolved {@link FileNode} into the final source string that gets
+ * written to disk. Kubb ships with TypeScript and TSX parsers. Add your own
+ * for new file types (JSON, Markdown, ...).
+ */
+export type Parser<TMeta extends object = object, TNode = unknown> = {
+  /**
+   * Display name used in diagnostics and the parser registry.
+   */
   name: string
   /**
-   * File extensions this parser handles.
-   * Use `undefined` to create a catch-all fallback parser.
+   * File extensions this parser handles. Set to `undefined` to define a
+   * catch-all fallback used when no other parser claims the extension.
    *
-   * @example Handled extensions
+   * @example
    * `['.ts', '.js']`
    */
   extNames: Array<FileNode['extname']> | undefined
   /**
-   * Convert a resolved file to a string.
+   * Serialise the file's AST into source code.
    */
-  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | string
+  parse(file: FileNode<TMeta>, options?: PrintOptions): string
+  /**
+   * Render compiler AST nodes for this parser's language into source text.
+   * Plugins call this to format the nodes they assemble before handing them
+   * back to the parser as `FileNode.sources`.
+   */
+  print(...nodes: Array<TNode>): string
 }
 
 /**
- * Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
- *
- * @note Call the returned factory with optional options to instantiate the parser.
+ * Defines a parser with type-safe `this`. Used to register handlers for new
+ * file extensions or to plug a non-TypeScript output into the build.
  *
  * @example
  * ```ts
- * import { defineParser } from '@kubb/core'
+ * import { defineParser, ast } from '@kubb/core'
  *
  * export const jsonParser = defineParser({
  *   name: 'json',
  *   extNames: ['.json'],
  *   parse(file) {
- *     const { extractStringsFromNodes } = await import('@kubb/ast')
- *     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
+ *     return file.sources
+ *       .map((source) => ast.extractStringsFromNodes(source.nodes ?? []))
+ *       .join('\n')
+ *   },
+ *   print(...nodes) {
+ *     return nodes.map(String).join('\n')
  *   },
  * })
  * ```
  */
-export function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta> {
+export function defineParser<T extends Parser>(parser: T): T {
   return parser
 }

package/src/definePlugin.ts

@@ -1,5 +1,262 @@
-import type { KubbHooks } from './Kubb.ts'
-import type { KubbPluginSetupContext, PluginFactoryOptions } from './types.ts'
+import { extname } from 'node:path'
+import type { FileNode, HttpMethod, UserFileNode, Visitor } from '@kubb/ast'
+import type { Generator } from './defineGenerator.ts'
+import type { BannerMeta, 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 shared by every plugin. Each plugin extends this with
+ * its own keys via the `Kubb.PluginOptionsRegistry.output` interface merge.
+ */
+export type Output<_TOptions = unknown> = {
+  /**
+   * Folder (or single file) where the plugin writes its generated code.
+   * Resolved against the global `output.path` set on `defineConfig`.
+   */
+  path: string
+  /**
+   * Text prepended to every generated file. Useful for license headers,
+   * lint disables, or `@ts-nocheck` directives.
+   *
+   * A string is applied to every file (including barrel and aggregation re-export files).
+   * Pass a function to compute the banner from the file's `BannerMeta` document metadata
+   * plus per-file context (`isBarrel`, `isAggregation`, `filePath`, `baseName`), so you can
+   * skip the banner on specific files.
+   *
+   * @example Add a directive to source files but not re-export files
+   * `banner: (meta) => (meta.isBarrel || meta.isAggregation) ? '' : "'use server'"`
+   */
+  banner?: string | ((meta: BannerMeta) => string)
+  /**
+   * Text appended at the end of every generated file. Mirror of `banner`.
+   * Pass a function to compute the footer from the file's `BannerMeta`.
+   */
+  footer?: string | ((meta: BannerMeta) => string)
+  /**
+   * Allows the plugin to overwrite hand-written files at the same path.
+   * Defaults to `false` to protect manual edits.
+   *
+   * @default false
+   */
+  override?: boolean
+} & ExtractRegistryKey<Kubb.PluginOptionsRegistry, 'output'>
+
+/**
+ * Groups generated files into subdirectories based on an OpenAPI tag or path
+ * segment.
+ */
+export type Group = {
+  /**
+   * Property used to assign each operation to a group.
+   * - `'tag'` uses the first tag (`operation.getTags().at(0)?.name`).
+   * - `'path'` uses the first segment of the operation's URL.
+   */
+  type: 'tag' | 'path'
+  /**
+   * Returns the subdirectory name from the group key. Defaults to
+   * `${camelCase(group)}Controller` for tags, or the first path segment.
+   */
+  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
+}
+
+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
+}
+
+/**
+ * Filter that skips matching operations or schemas during generation. Use it
+ * to drop deprecated endpoints, internal-only schemas, or anything you do
+ * not want code generated for.
+ *
+ * @example
+ * ```ts
+ * exclude: [
+ *   { type: 'tag', pattern: 'internal' },
+ *   { type: 'path', pattern: /^\/admin/ },
+ *   { type: 'operationId', pattern: /^deprecated_/ },
+ * ]
+ * ```
+ */
+export type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+
+/**
+ * Filter that restricts generation to operations or schemas matching at least
+ * one entry. Useful for partial builds (one tag, one API version).
+ *
+ * @example
+ * ```ts
+ * include: [
+ *   { type: 'tag', pattern: 'public' },
+ *   { type: 'path', pattern: /^\/api\/v1/ },
+ * ]
+ * ```
+ */
+export type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+
+/**
+ * Filter paired with a partial options object. When the filter matches, the
+ * options are merged on top of the plugin defaults for that operation only.
+ * Useful for "this one tag goes to a different folder" rules.
+ *
+ * Entries are evaluated top to bottom. The first matching entry wins.
+ *
+ * @example
+ * ```ts
+ * override: [
+ *   {
+ *     type: 'tag',
+ *     pattern: 'admin',
+ *     options: { output: { path: './src/gen/admin' } },
+ *   },
+ *   {
+ *     type: 'operationId',
+ *     pattern: 'listPets',
+ *     options: { enumType: 'literal' },
+ *   },
+ * ]
+ * ```
+ */
+export type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
+  options: Omit<Partial<TOptions>, 'override'>
+}
+
+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 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`.
@@ -21,9 +278,9 @@ export type Plugin<TFactory extends PluginFactoryOptions = PluginFactoryOptions>
   /**
    * Controls the execution order of this plugin relative to others.
    *
-   * - `'pre'`  — runs before all normal plugins.
-   * - `'post'` — runs after all normal plugins.
-   * - `undefined` (default) — runs in declaration order among normal plugins.
+   * - `'pre'` runs before all normal plugins.
+   * - `'post'` runs after all normal plugins.
+   * - `undefined` (default), runs in declaration order among normal plugins.
    *
    * Dependency constraints always take precedence over `enforce`.
    */
@@ -37,30 +294,61 @@ 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
+  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
 }
 
 /**
- * Wraps a factory function and returns a typed `Plugin` with lifecycle handlers grouped under `hooks`.
- *
- * Handlers live in a single `hooks` object (inspired by Astro integrations).
- * All lifecycle events from `KubbHooks` are available for subscription.
+ * Wraps a plugin factory and returns a function that accepts user options and
+ * yields a fully typed `Plugin`. Lifecycle handlers go inside a single
+ * `hooks` object (inspired by Astro integrations).
  *
- * @note For real plugins, use a `PluginFactoryOptions` type parameter to get type-safe context in `kubb:plugin:setup`.
- * Plugin names should follow the convention `plugin-<feature>` (e.g., `plugin-react-query`, `plugin-zod`).
+ * Pass a `PluginFactoryOptions` type parameter to get a typed `ctx` inside
+ * `kubb:plugin:setup`. Plugin names should follow the `plugin-<feature>`
+ * convention (`plugin-react-query`, `plugin-zod`, ...).
  *
  * @example
  * ```ts
@@ -81,3 +369,18 @@ export function definePlugin<TFactory extends PluginFactoryOptions = PluginFacto
 ): (options?: TFactory['options']) => Plugin<TFactory> {
   return (options) => factory(options ?? ({} as TFactory['options']))
 }
+
+/**
+ * Detects whether an output path points at a single file (`'single'`) or a
+ * directory (`'split'`). Decided purely from the presence of a file extension.
+ *
+ * @example Directory
+ * `getMode('./types') // 'split'`
+ *
+ * @example Single file
+ * `getMode('./api.ts') // 'single'`
+ */
+export function getMode(fileOrFolder: string | undefined | null): 'single' | 'split' {
+  if (!fileOrFolder) return 'split'
+  return extname(fileOrFolder) ? 'single' : 'split'
+}