@kubb/core 5.0.0-alpha.69 → 5.0.0-alpha.70

package/dist/{types-mW3-Ihuf.d.ts → types-DWtkW2RX.d.ts}

@@ -1,5 +1,5 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
-import { FileNode, HttpMethod, ImportNode, InputNode, Node, OperationNode, SchemaNode, Visitor } from "@kubb/ast";
+import { FileNode, HttpMethod, ImportNode, InputNode, Node, OperationNode, SchemaNode, UserFileNode, Visitor } from "@kubb/ast";
 
 //#region ../../internals/utils/src/asyncEventEmitter.d.ts
 /**
@@ -853,28 +853,10 @@ declare global {
 //#endregion
 //#region src/defineMiddleware.d.ts
 /**
- * A middleware observes and post-processes the build output produced by plugins.
- * It attaches listeners to the shared `hooks` emitter before the plugin execution loop
- * begins and reacts to lifecycle events (e.g. `kubb:plugin:end`, `kubb:build:end`) to
- * inject barrel files or perform other cross-cutting concerns.
- *
- * Middleware listeners are always registered **after** all plugin listeners, because
- * `createKubb` installs middleware only after the `PluginDriver` has registered every
- * plugin's hooks.  This means middleware hooks for any event always fire last.
- *
- * @example
- * ```ts
- * import { defineMiddleware } from '@kubb/core'
- *
- * export const myMiddleware = defineMiddleware({
- *   name: 'my-middleware',
- *   install(hooks) {
- *     hooks.on('kubb:build:end', ({ files }) => {
- *       console.log(`Build complete with ${files.length} files`)
- *     })
- *   },
- * })
- * ```
+ * 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.
  */
 type Middleware = {
   /**
@@ -882,29 +864,51 @@ type Middleware = {
    */
   name: string;
   /**
-   * Called during `createKubb` after `setup()` but before the plugin
-   * execution loop starts. Attach listeners to `hooks` here.
+   * 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.
    */
-  install(hooks: AsyncEventEmitter<KubbHooks>): void;
+  hooks: { [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void> };
 };
 /**
- * Identity factory for middleware.
- * Returns the middleware object unchanged but provides a typed entry-point
- * to define middleware with proper inference.
+ * Creates a middleware factory using the hook-style (`hooks:`) API.
+ *
+ * Mirrors `definePlugin`: the factory is called with optional options and returns a
+ * fresh `Middleware` instance. Placing per-build state (e.g. accumulators) inside the
+ * factory closure ensures each `createKubb` invocation gets its own isolated instance.
  *
  * @example
  * ```ts
- * export const myMiddleware = defineMiddleware({
- *   name: 'my-middleware',
- *   install(hooks) {
- *     hooks.on('kubb:build:end', ({ files }) => {
+ * // Stateless middleware
+ * export const logMiddleware = defineMiddleware(() => ({
+ *   name: 'log-middleware',
+ *   hooks: {
+ *     'kubb:build:end'({ files }) {
  *       console.log(`Build complete with ${files.length} files`)
- *     })
+ *     },
  *   },
+ * }))
+ *
+ * // Middleware with options and per-build state
+ * export const myMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
+ *   const seen = new Set<string>()
+ *   return {
+ *     name: 'my-middleware',
+ *     hooks: {
+ *       'kubb:plugin:end'({ plugin }) {
+ *         seen.add(`${options.prefix}${plugin.name}`)
+ *       },
+ *     },
+ *   }
+ * })
+ *
+ * // Usage in kubb.config.ts:
+ * export default defineConfig({
+ *   middleware: [logMiddleware(), myMiddleware({ prefix: 'pfx:' })],
  * })
  * ```
  */
-declare function defineMiddleware(middleware: Middleware): Middleware;
+declare function defineMiddleware<TOptions extends object = object>(factory: (options: TOptions) => Middleware): (options?: TOptions) => Middleware;
 //#endregion
 //#region src/defineParser.d.ts
 type PrintOptions = {
@@ -1125,19 +1129,6 @@ type Config<TInput = Input> = {
      * @deprecated Use `storage` to control where files are written.
      */
     write?: boolean;
-    /**
-     * Storage backend for generated files.
-     * Defaults to `fsStorage()` — the built-in filesystem driver.
-     * Accepts any object implementing the {@link Storage} interface.
-     * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
-     * @default fsStorage()
-     * @example
-     * ```ts
-     * import { memoryStorage } from '@kubb/core'
-     * storage: memoryStorage()
-     * ```
-     */
-    storage?: Storage;
     /**
      * Specifies the formatting tool to be used.
      * - 'auto' automatically detects and uses oxfmt, biome, or prettier (in that order of preference).
@@ -1179,6 +1170,19 @@ type Config<TInput = Input> = {
      */
     override?: boolean;
   } & ExtractRegistryKey<Kubb.ConfigOptionsRegistry, 'output'>;
+  /**
+   * Storage backend for generated files.
+   * Defaults to `fsStorage()` — the built-in filesystem driver.
+   * Accepts any object implementing the {@link Storage} interface.
+   * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
+   * @default fsStorage()
+   * @example
+   * ```ts
+   * import { memoryStorage } from '@kubb/core'
+   * storage: memoryStorage()
+   * ```
+   */
+  storage?: Storage;
   /**
    * An array of Kubb plugins used for code generation.
    * Each plugin may declare additional configurable options.
@@ -1562,9 +1566,7 @@ type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactor
   /**
    * Inject a raw file into the build output, bypassing the normal generation pipeline.
    */
-  injectFile(file: Pick<FileNode, 'baseName' | 'path'> & {
-    sources?: FileNode['sources'];
-  }): void;
+  injectFile(userFileNode: UserFileNode): void;
   /**
    * Merge a partial config update into the current build configuration.
    */
@@ -1724,6 +1726,16 @@ type KubbPluginEndContext = {
   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;
 };
 type KubbHookStartContext = {
   id?: string;
@@ -1900,4 +1912,4 @@ type CLIOptions = {
 type PossibleConfig<TCliOptions = undefined> = PossiblePromise<Config | Config[]> | ((...args: [TCliOptions] extends [undefined] ? [] : [TCliOptions]) => PossiblePromise<Config | Config[]>);
 //#endregion
 export { defineParser as $, KubbPluginStartContext as A, Override as B, KubbGenerationSummaryContext as C, KubbLifecycleStartContext as D, KubbInfoContext as E, Logger as F, ResolveOptionsContext as G, PossibleConfig as H, LoggerContext as I, ResolverFileParams as J, Resolver as K, LoggerOptions as L, KubbSuccessContext as M, KubbVersionNewContext as N, KubbPluginEndContext as O, KubbWarnContext as P, Parser as Q, NormalizedPlugin as R, KubbGenerationStartContext as S, KubbHookStartContext as T, ResolveBannerContext as U, PluginFactoryOptions as V, ResolveNameParams as W, UserConfig as X, ResolverPathParams as Y, UserLogger as Z, KubbErrorContext as _, logLevel as _t, Config as a, createKubb as at, KubbFilesProcessingStartContext as b, GeneratorContext as c, Plugin as ct, InputData as d, defineGenerator as dt, Middleware as et, InputPath as f, Storage as ft, KubbDebugContext as g, createRenderer as gt, KubbConfigEndContext as h, RendererFactory as ht, CLIOptions as i, BuildOutput as it, KubbPluginsEndContext as j, KubbPluginSetupContext as k, Group as l, definePlugin as lt, KubbBuildStartContext as m, Renderer as mt, AdapterFactoryOptions as n, Kubb$1 as nt, DevtoolsOptions as o, PluginDriver as ot, KubbBuildEndContext as p, createStorage as pt, ResolverContext as q, AdapterSource as r, KubbHooks as rt, Exclude$1 as s, FileManager as st, Adapter as t, defineMiddleware as tt, Include as u, Generator as ut, KubbFileProcessingUpdateContext as v, AsyncEventEmitter as vt, KubbHookEndContext as w, KubbGenerationEndContext as x, KubbFilesProcessingEndContext as y, Output as z };
-//# sourceMappingURL=types-mW3-Ihuf.d.ts.map
+//# sourceMappingURL=types-DWtkW2RX.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "5.0.0-alpha.69",
+  "version": "5.0.0-alpha.70",
   "description": "Core functionality for Kubb's plugin-based code generation system, providing the foundation for transforming OpenAPI specifications.",
   "keywords": [
     "ast",
@@ -65,15 +65,15 @@
   "dependencies": {
     "fflate": "^0.8.2",
     "tinyexec": "^1.1.1",
-    "@kubb/ast": "5.0.0-alpha.69"
+    "@kubb/ast": "5.0.0-alpha.70"
   },
   "devDependencies": {
     "p-limit": "^7.3.0",
     "@internals/utils": "0.0.0",
-    "@kubb/renderer-jsx": "5.0.0-alpha.69"
+    "@kubb/renderer-jsx": "5.0.0-alpha.70"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-alpha.69"
+    "@kubb/renderer-jsx": "5.0.0-alpha.70"
   },
   "size-limit": [
     {

package/src/FileManager.ts

@@ -4,6 +4,11 @@ import { createFile } from '@kubb/ast'
 function mergeFile<TMeta extends object = object>(a: FileNode<TMeta>, b: FileNode<TMeta>): FileNode<TMeta> {
   return {
     ...a,
+    // Incoming file (b) takes precedence for banner/footer so that barrel files,
+    // which never carry a banner, can clear banners set by plugin-generated files
+    // at the same path.
+    banner: b.banner,
+    footer: b.footer,
     sources: [...(a.sources || []), ...(b.sources || [])],
     imports: [...(a.imports || []), ...(b.imports || [])],
     exports: [...(a.exports || []), ...(b.exports || [])],

package/src/PluginDriver.ts

@@ -161,8 +161,8 @@ export class PluginDriver {
           setOptions: (opts) => {
             normalizedPlugin.options = { ...normalizedPlugin.options, ...opts }
           },
-          injectFile: ({ sources = [], ...rest }) => {
-            this.fileManager.add(createFile({ imports: [], exports: [], sources, ...rest }))
+          injectFile: (userFileNode) => {
+            this.fileManager.add(createFile(userFileNode))
           },
         }
         return hooks['kubb:plugin:setup']!(pluginCtx)

package/src/createKubb.ts

@@ -12,7 +12,7 @@ import type { Kubb } from './Kubb.ts'
 import { PluginDriver } from './PluginDriver.ts'
 import { applyHookResult } from './renderNode.ts'
 import { fsStorage } from './storages/fsStorage.ts'
-import type { AdapterSource, Config, GeneratorContext, KubbHooks, NormalizedPlugin, Storage, UserConfig } from './types.ts'
+import type { AdapterSource, Config, GeneratorContext, KubbHooks, Middleware, NormalizedPlugin, Storage, UserConfig } from './types.ts'
 import { getDiagnosticInfo } from './utils/diagnostics.ts'
 import { isInputPath } from './utils/isInputPath.ts'
 
@@ -68,7 +68,7 @@ async function setup(userConfig: UserConfig, options: SetupOptions = {}): Promis
       `  • Output: ${userConfig.output?.path || 'not specified'}`,
       `  • Plugins: ${userConfig.plugins?.length || 0}`,
       'Output Settings:',
-      `  • Storage: ${userConfig.output?.storage ? `custom(${userConfig.output.storage.name})` : userConfig.output?.write === false ? 'disabled' : 'filesystem (default)'}`,
+      `  • Storage: ${userConfig.storage ? `custom(${userConfig.storage.name})` : userConfig.output?.write === false ? 'disabled' : 'filesystem (default)'}`,
       `  • Formatter: ${userConfig.output?.format || 'none'}`,
       `  • Linter: ${userConfig.output?.lint || 'none'}`,
       'Environment:',
@@ -124,7 +124,7 @@ async function setup(userConfig: UserConfig, options: SetupOptions = {}): Promis
     plugins: userConfig.plugins as unknown as Config['plugins'],
   }
 
-  const storage: Storage | null = config.output.write === false ? null : (config.output.storage ?? fsStorage())
+  const storage: Storage | null = config.output.write === false ? null : (config.storage ?? fsStorage())
 
   if (config.output.clean) {
     await hooks.emit('kubb:debug', {
@@ -138,11 +138,20 @@ async function setup(userConfig: UserConfig, options: SetupOptions = {}): Promis
     hooks,
   })
 
-  // Install middleware listeners after all plugin hooks are registered.
+  // Register middleware hooks after all plugin hooks are registered.
   // Because AsyncEventEmitter calls listeners in registration order,
   // middleware hooks for any event fire after all plugin hooks for that event.
+  function registerMiddlewareHook<K extends keyof KubbHooks & string>(event: K, middlewareHooks: Middleware['hooks']) {
+    const handler = middlewareHooks[event]
+    if (handler) {
+      hooks.on(event, handler)
+    }
+  }
+
   for (const middleware of config.middleware ?? []) {
-    middleware.install(hooks)
+    for (const event of Object.keys(middleware.hooks) as Array<keyof KubbHooks & string>) {
+      registerMiddlewareHook(event, middleware.hooks)
+    }
   }
 
   const adapter = config.adapter
@@ -308,6 +317,11 @@ async function safeBuild(setupResult: SetupResult): Promise<BuildOutput> {
           plugin,
           duration,
           success: true,
+          config,
+          get files() {
+            return driver.fileManager.files
+          },
+          upsertFile: (...files) => driver.fileManager.upsert(...files),
         })
 
         await hooks.emit('kubb:debug', {
@@ -324,6 +338,11 @@ async function safeBuild(setupResult: SetupResult): Promise<BuildOutput> {
           duration,
           success: false,
           error,
+          config,
+          get files() {
+            return driver.fileManager.files
+          },
+          upsertFile: (...files) => driver.fileManager.upsert(...files),
         })
 
         await hooks.emit('kubb:debug', {

package/src/defineMiddleware.ts

@@ -1,29 +1,10 @@
-import type { AsyncEventEmitter } from '@internals/utils'
 import type { KubbHooks } from './Kubb.ts'
 
 /**
- * A middleware observes and post-processes the build output produced by plugins.
- * It attaches listeners to the shared `hooks` emitter before the plugin execution loop
- * begins and reacts to lifecycle events (e.g. `kubb:plugin:end`, `kubb:build:end`) to
- * inject barrel files or perform other cross-cutting concerns.
- *
- * Middleware listeners are always registered **after** all plugin listeners, because
- * `createKubb` installs middleware only after the `PluginDriver` has registered every
- * plugin's hooks.  This means middleware hooks for any event always fire last.
- *
- * @example
- * ```ts
- * import { defineMiddleware } from '@kubb/core'
- *
- * export const myMiddleware = defineMiddleware({
- *   name: 'my-middleware',
- *   install(hooks) {
- *     hooks.on('kubb:build:end', ({ files }) => {
- *       console.log(`Build complete with ${files.length} files`)
- *     })
- *   },
- * })
- * ```
+ * 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.
  */
 export type Middleware = {
   /**
@@ -31,29 +12,53 @@ export type Middleware = {
    */
   name: string
   /**
-   * Called during `createKubb` after `setup()` but before the plugin
-   * execution loop starts. Attach listeners to `hooks` here.
+   * 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.
    */
-  install(hooks: AsyncEventEmitter<KubbHooks>): void
+  hooks: {
+    [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void>
+  }
 }
 
 /**
- * Identity factory for middleware.
- * Returns the middleware object unchanged but provides a typed entry-point
- * to define middleware with proper inference.
+ * Creates a middleware factory using the hook-style (`hooks:`) API.
+ *
+ * Mirrors `definePlugin`: the factory is called with optional options and returns a
+ * fresh `Middleware` instance. Placing per-build state (e.g. accumulators) inside the
+ * factory closure ensures each `createKubb` invocation gets its own isolated instance.
  *
  * @example
  * ```ts
- * export const myMiddleware = defineMiddleware({
- *   name: 'my-middleware',
- *   install(hooks) {
- *     hooks.on('kubb:build:end', ({ files }) => {
+ * // Stateless middleware
+ * export const logMiddleware = defineMiddleware(() => ({
+ *   name: 'log-middleware',
+ *   hooks: {
+ *     'kubb:build:end'({ files }) {
  *       console.log(`Build complete with ${files.length} files`)
- *     })
+ *     },
  *   },
+ * }))
+ *
+ * // Middleware with options and per-build state
+ * export const myMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
+ *   const seen = new Set<string>()
+ *   return {
+ *     name: 'my-middleware',
+ *     hooks: {
+ *       'kubb:plugin:end'({ plugin }) {
+ *         seen.add(`${options.prefix}${plugin.name}`)
+ *       },
+ *     },
+ *   }
+ * })
+ *
+ * // Usage in kubb.config.ts:
+ * export default defineConfig({
+ *   middleware: [logMiddleware(), myMiddleware({ prefix: 'pfx:' })],
  * })
  * ```
  */
-export function defineMiddleware(middleware: Middleware): Middleware {
-  return middleware
+export function defineMiddleware<TOptions extends object = object>(factory: (options: TOptions) => Middleware): (options?: TOptions) => Middleware {
+  return (options) => factory(options ?? ({} as TOptions))
 }

package/src/storages/fsStorage.ts

@@ -14,7 +14,7 @@ function isMissingPathError(error: unknown): error is NodeJS.ErrnoException {
 /**
  * Built-in filesystem storage driver.
  *
- * This is the default storage when no `storage` option is configured in `output`.
+ * This is the default storage when no `storage` option is configured in the root config.
  * Keys are resolved against `process.cwd()`, so root-relative paths such as
  * `src/gen/api/getPets.ts` are written to the correct location without extra configuration.
  *
@@ -31,7 +31,8 @@ function isMissingPathError(error: unknown): error is NodeJS.ErrnoException {
  *
  * export default defineConfig({
  *   input:  { path: './petStore.yaml' },
- *   output: { path: './src/gen', storage: fsStorage() },
+ *   output: { path: './src/gen' },
+ *   storage: fsStorage(),
  * })
  * ```
  */

package/src/storages/memoryStorage.ts

@@ -14,7 +14,8 @@ import { createStorage } from '../createStorage.ts'
  *
  * export default defineConfig({
  *   input:  { path: './petStore.yaml' },
- *   output: { path: './src/gen', storage: memoryStorage() },
+ *   output: { path: './src/gen' },
+ *   storage: memoryStorage(),
  * })
  * ```
  */

package/src/types.ts

@@ -1,5 +1,5 @@
 import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
-import type { FileNode, HttpMethod, ImportNode, InputNode, Node, SchemaNode, Visitor } from '@kubb/ast'
+import type { FileNode, HttpMethod, ImportNode, InputNode, Node, SchemaNode, UserFileNode, Visitor } from '@kubb/ast'
 import type { DEFAULT_STUDIO_URL, logLevel } from './constants.ts'
 import type { RendererFactory } from './createRenderer.ts'
 import type { Storage } from './createStorage.ts'
@@ -190,19 +190,6 @@ export type Config<TInput = Input> = {
      * @deprecated Use `storage` to control where files are written.
      */
     write?: boolean
-    /**
-     * Storage backend for generated files.
-     * Defaults to `fsStorage()` — the built-in filesystem driver.
-     * Accepts any object implementing the {@link Storage} interface.
-     * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
-     * @default fsStorage()
-     * @example
-     * ```ts
-     * import { memoryStorage } from '@kubb/core'
-     * storage: memoryStorage()
-     * ```
-     */
-    storage?: Storage
     /**
      * Specifies the formatting tool to be used.
      * - 'auto' automatically detects and uses oxfmt, biome, or prettier (in that order of preference).
@@ -244,6 +231,19 @@ export type Config<TInput = Input> = {
      */
     override?: boolean
   } & ExtractRegistryKey<Kubb.ConfigOptionsRegistry, 'output'>
+  /**
+   * Storage backend for generated files.
+   * Defaults to `fsStorage()` — the built-in filesystem driver.
+   * Accepts any object implementing the {@link Storage} interface.
+   * Keys are root-relative paths (e.g. `src/gen/api/getPets.ts`).
+   * @default fsStorage()
+   * @example
+   * ```ts
+   * import { memoryStorage } from '@kubb/core'
+   * storage: memoryStorage()
+   * ```
+   */
+  storage?: Storage
   /**
    * An array of Kubb plugins used for code generation.
    * Each plugin may declare additional configurable options.
@@ -648,11 +648,7 @@ export type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = Plugi
   /**
    * Inject a raw file into the build output, bypassing the normal generation pipeline.
    */
-  injectFile(
-    file: Pick<FileNode, 'baseName' | 'path'> & {
-      sources?: FileNode['sources']
-    },
-  ): void
+  injectFile(userFileNode: UserFileNode): void
   /**
    * Merge a partial config update into the current build configuration.
    */
@@ -828,6 +824,16 @@ export type KubbPluginEndContext = {
   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
 }
 
 export type KubbHookStartContext = {