@kubb/core 5.0.0-alpha.73 → 5.0.0-alpha.74

package/package.json

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

package/src/Kubb.ts

@@ -30,49 +30,45 @@ import type {
 } from './types'
 
 /**
- * The instance returned by {@link createKubb}.
+ * Kubb code generation instance returned by {@link createKubb}.
+ *
+ * Use this when orchestrating multiple builds, inspecting plugin timings, or integrating Kubb into a larger toolchain.
+ * For a single one-off build, chain directly: `await createKubb(config).build()`.
  */
 export type Kubb = {
   /**
-   * The shared event emitter. Attach listeners here before calling `setup()` or `build()`.
+   * Shared event emitter for lifecycle and status events. Attach listeners before calling `setup()` or `build()`.
    */
   readonly hooks: AsyncEventEmitter<KubbHooks>
   /**
-   * Raw generated source, keyed by absolute file path.
-   * Populated after a successful `build()` or `safeBuild()` call.
+   * Generated source code keyed by absolute file path. Available after `build()` or `safeBuild()` completes.
    */
   readonly sources: Map<string, string>
   /**
-   * The plugin driver. Available after `setup()` has been called.
+   * Plugin driver managing all plugins. Available after `setup()` completes.
    */
   readonly driver: PluginDriver | undefined
   /**
-   * The resolved config with applied defaults. Available after `setup()` has been called.
+   * Resolved configuration with defaults applied. Available after `setup()` completes.
    */
   readonly config: Config | undefined
   /**
-   * Initializes all Kubb infrastructure: validates input, applies config defaults,
-   * runs the adapter, and creates the PluginDriver.
-   *
-   * Calling `build()` or `safeBuild()` without calling `setup()` first will
-   * automatically invoke `setup()` before proceeding.
+   * Resolves config and initializes the driver. `build()` calls this automatically.
    */
   setup(): Promise<void>
   /**
-   * Runs a full Kubb build and throws on any error or plugin failure.
-   * Automatically calls `setup()` if it has not been called yet.
+   * Runs the full pipeline and throws on any plugin error. Automatically calls `setup()` if needed.
    */
   build(): Promise<BuildOutput>
   /**
-   * Runs a full Kubb build and captures errors instead of throwing.
-   * Automatically calls `setup()` if it has not been called yet.
+   * Runs the full pipeline and captures errors in `BuildOutput` instead of throwing. Automatically calls `setup()` if needed.
    */
   safeBuild(): Promise<BuildOutput>
 }
 
 /**
- * Events emitted during the Kubb code generation lifecycle.
- * These events can be listened to for logging, progress tracking, and custom integrations.
+ * Lifecycle events emitted during Kubb code generation.
+ * Use these for logging, progress tracking, and custom integrations.
  *
  * @example
  * ```typescript
@@ -92,76 +88,74 @@ export type Kubb = {
  */
 export interface KubbHooks {
   /**
-   * Emitted at the beginning of the Kubb lifecycle, before any code generation starts.
+   * Fires at the start of the Kubb lifecycle, before code generation begins.
    */
   'kubb:lifecycle:start': [ctx: KubbLifecycleStartContext]
   /**
-   * Emitted at the end of the Kubb lifecycle, after all code generation is complete.
+   * Fires at the end of the Kubb lifecycle, after all code generation completes.
    */
   'kubb:lifecycle:end': []
 
   /**
-   * Emitted when configuration loading starts.
+   * Fires when configuration loading starts.
    */
   'kubb:config:start': []
   /**
-   * Emitted when configuration loading is complete.
+   * Fires when configuration loading completes.
    */
   'kubb:config:end': [ctx: KubbConfigEndContext]
 
   /**
-   * Emitted when code generation phase starts.
+   * Fires when code generation starts.
    */
   'kubb:generation:start': [ctx: KubbGenerationStartContext]
   /**
-   * Emitted when code generation phase completes.
+   * Fires when code generation completes.
    */
   'kubb:generation:end': [ctx: KubbGenerationEndContext]
   /**
-   * Emitted with a summary of the generation results.
-   * Contains summary lines, title, and success status.
+   * Fires with a generation summary including summary lines, title, and success status.
    */
   'kubb:generation:summary': [ctx: KubbGenerationSummaryContext]
 
   /**
-   * Emitted when code formatting starts (e.g., running Biome or Prettier).
+   * Fires when code formatting starts (e.g., Biome or Prettier).
    */
   'kubb:format:start': []
   /**
-   * Emitted when code formatting completes.
+   * Fires when code formatting completes.
    */
   'kubb:format:end': []
 
   /**
-   * Emitted when linting starts.
+   * Fires when linting starts.
    */
   'kubb:lint:start': []
   /**
-   * Emitted when linting completes.
+   * Fires when linting completes.
    */
   'kubb:lint:end': []
 
   /**
-   * Emitted when plugin hooks execution starts.
+   * Fires when plugin hooks execution starts.
    */
   'kubb:hooks:start': []
   /**
-   * Emitted when plugin hooks execution completes.
+   * Fires when plugin hooks execution completes.
    */
   'kubb:hooks:end': []
 
   /**
-   * Emitted when a single hook execution starts (e.g., format or lint).
-   * The callback should be invoked when the command completes.
+   * Fires when a single hook executes (e.g., format or lint). The callback is invoked when the command finishes.
    */
   'kubb:hook:start': [ctx: KubbHookStartContext]
   /**
-   * Emitted when a single hook execution completes.
+   * Fires when a single hook execution completes.
    */
   'kubb:hook:end': [ctx: KubbHookEndContext]
 
   /**
-   * Emitted when a new version of Kubb is available.
+   * Fires when a new Kubb version is available.
    */
   'kubb:version:new': [ctx: KubbVersionNewContext]
 
@@ -170,7 +164,7 @@ export interface KubbHooks {
    */
   'kubb:info': [ctx: KubbInfoContext]
   /**
-   * Error event. Emitted when an error occurs during code generation.
+   * Error event, fired when an error occurs during generation.
    */
   'kubb:error': [ctx: KubbErrorContext]
   /**
@@ -182,81 +176,60 @@ export interface KubbHooks {
    */
   'kubb:warn': [ctx: KubbWarnContext]
   /**
-   * Debug event for detailed logging.
-   * Contains timestamp, log messages, and optional filename.
+   * Debug event for detailed logging with timestamp and optional filename.
    */
   'kubb:debug': [ctx: KubbDebugContext]
 
   /**
-   * Emitted when file processing starts.
-   * Contains the list of files to be processed.
+   * Fires when file processing starts with the list of files to process.
    */
   'kubb:files:processing:start': [ctx: KubbFilesProcessingStartContext]
   /**
-   * Emitted for each file being processed, providing progress updates.
-   * Contains processed count, total count, percentage, and file details.
+   * Fires for each file with progress updates: processed count, total, percentage, and file details.
    */
   'kubb:file:processing:update': [ctx: KubbFileProcessingUpdateContext]
   /**
-   * Emitted when file processing completes.
-   * Contains the list of processed files.
+   * Fires when file processing completes with the list of processed files.
    */
   'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext]
 
   /**
-   * Emitted when a plugin starts executing.
+   * Fires when a plugin starts execution.
    */
   'kubb:plugin:start': [ctx: KubbPluginStartContext]
   /**
-   * Emitted when a plugin completes execution.
-   * Duration in ms.
+   * Fires when a plugin completes execution. Duration measured in milliseconds.
    */
   'kubb:plugin:end': [ctx: KubbPluginEndContext]
 
   /**
-   * Fired once — before any plugin's `buildStart` runs — so that hook-style plugins
-   * can register generators, configure resolvers/transformers/renderers, or inject
-   * extra files.  All `kubb:plugin:setup` handlers registered via `definePlugin` receive
-   * a plugin-specific context (with the correct `addGenerator` closure).
-   * External tooling can observe this event via `hooks.on('kubb:plugin:setup', …)`.
+   * Fires once before plugins execute — allowing plugins to register generators, configure resolvers/transformers/renderers, or inject files.
    */
   'kubb:plugin:setup': [ctx: KubbPluginSetupContext]
   /**
-   * Fired immediately before the plugin execution loop begins.
-   * The adapter has already parsed the source and `inputNode` is available.
+   * Fires before the plugin execution loop begins. The adapter has already parsed the source and `inputNode` is available.
    */
   'kubb:build:start': [ctx: KubbBuildStartContext]
   /**
-   * Fired after all plugins have run and all per-plugin barrels have been generated,
-   * but BEFORE files are written to disk.
-   * Use this event to inject final files (e.g. a root barrel) that must be persisted
-   * in the same write pass as the plugin output.
+   * Fires after all plugins run and per-plugin barrels generate, but before files write to disk.
+   * Use this to inject final files that must persist in the same write pass as plugin output.
    */
   'kubb:plugins:end': [ctx: KubbPluginsEndContext]
   /**
-   * Fired after all files have been written to disk.
+   * Fires after all files write to disk.
    */
   'kubb:build:end': [ctx: KubbBuildEndContext]
 
   /**
-   * Emitted for each schema node during the AST walk.
-   * Generator listeners registered via `addGenerator()` in `kubb:plugin:setup` respond to this event.
-   * The `ctx.plugin.name` identifies which plugin is driving the current walk.
-   * `ctx.options` carries the per-node resolved options (after exclude/include/override).
+   * Fires for each schema node during AST traversal. Generator listeners respond to this.
    */
   'kubb:generate:schema': [node: SchemaNode, ctx: GeneratorContext]
   /**
-   * Emitted for each operation node during the AST walk.
-   * Generator listeners registered via `addGenerator()` in `kubb:plugin:setup` respond to this event.
-   * The `ctx.plugin.name` identifies which plugin is driving the current walk.
-   * `ctx.options` carries the per-node resolved options (after exclude/include/override).
+   * Fires for each operation node during AST traversal. Generator listeners respond to this.
    */
   'kubb:generate:operation': [node: OperationNode, ctx: GeneratorContext]
   /**
-   * Emitted once after all operations have been walked, with the full collected array.
-   * Generator listeners with an `operations()` method respond to this event.
-   * The `ctx.plugin.name` identifies which plugin is driving the current walk.
-   * `ctx.options` carries the plugin-level resolved options for the batch call.
+   * Fires once after all operations traverse with the full collected array. Batch generator listeners respond to this.
    */
   'kubb:generate:operations': [nodes: Array<OperationNode>, ctx: GeneratorContext]
 }

package/src/createAdapter.ts

@@ -1,24 +1,31 @@
 import type { Adapter, AdapterFactoryOptions } from './types.ts'
 
-/**
- * Builder type for an {@link Adapter} — takes options and returns the adapter instance.
- */
 type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>
 
 /**
- * Creates an adapter factory. Call the returned function with optional options to get the adapter instance.
+ * Factory for implementing custom adapters that translate non-OpenAPI specs into Kubb's AST.
+ *
+ * Use this to support GraphQL schemas, gRPC definitions, AsyncAPI, or custom domain-specific languages.
+ * Built-in adapters include `@kubb/adapter-oas` for OpenAPI and Swagger documents.
+ *
+ * @note Adapters must parse their input format to Kubb's `InputNode` structure.
  *
  * @example
+ * ```ts
  * export const myAdapter = createAdapter<MyAdapter>((options) => {
  *   return {
  *     name: 'my-adapter',
  *     options,
- *     async parse(source) { ... },
+ *     async parse(source) {
+ *       // Transform source format to InputNode
+ *       return { ... }
+ *     },
  *   }
  * })
  *
- * // instantiate
+ * // Instantiate:
  * const adapter = myAdapter({ validate: true })
+ * ```
  */
 export function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T> {
   return (options) => build(options ?? ({} as T['options']))

package/src/createStorage.ts

@@ -34,9 +34,17 @@ export type Storage = {
 }
 
 /**
- * Creates a storage factory. Call the returned function with optional options to get the storage instance.
+ * Factory for implementing custom storage backends that control where generated files are written.
+ *
+ * Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
+ * Kubb provides filesystem and in-memory implementations out of the box.
+ *
+ * @note Call the returned factory with optional options to instantiate the storage adapter.
  *
  * @example
+ * ```ts
+ * import { createStorage } from '@kubb/core'
+ *
  * export const memoryStorage = createStorage(() => {
  *   const store = new Map<string, string>()
  *   return {
@@ -52,6 +60,10 @@ export type Storage = {
  *     async clear(base) { if (!base) store.clear() },
  *   }
  * })
+ *
+ * // Instantiate:
+ * const storage = memoryStorage()
+ * ```
  */
 export function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage {
   return (options) => build(options ?? ({} as TOptions))

package/src/defineGenerator.ts

@@ -6,33 +6,26 @@ import type { GeneratorContext, PluginFactoryOptions } from './types.ts'
 export type { GeneratorContext } from './types.ts'
 
 /**
- * A generator is a named object with optional `schema`, `operation`, and `operations`
- * methods. Each method receives the AST node as the first argument and a typed
- * `ctx` object as the second, giving access to `ctx.config`, `ctx.resolver`,
- * `ctx.adapter`, `ctx.options`, `ctx.upsertFile`, etc.
+ * Declares a named generator unit that walks the AST and emits files.
  *
- * Generators that return renderer elements (e.g. JSX) must declare a `renderer`
- * factory so that core knows how to process the output without coupling core
- * to any specific renderer package.
+ * Each method (`schema`, `operation`, `operations`) is called for the matching node type.
+ * Each method returns `TElement | Array<FileNode> | void`. JSX-based generators require a `renderer` factory.
+ * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `void` to bypass rendering.
  *
- * Return a renderer element, an array of `FileNode`, or `void` to handle file
- * writing manually via `ctx.upsertFile`.
+ * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
  *
  * @example
  * ```ts
+ * import { defineGenerator } from '@kubb/core'
  * import { jsxRenderer } from '@kubb/renderer-jsx'
  *
- * export const typeGenerator = defineGenerator<PluginTs>({
+ * export const typeGenerator = defineGenerator({
  *   name: 'typescript',
  *   renderer: jsxRenderer,
  *   schema(node, ctx) {
  *     const { adapter, resolver, root, options } = ctx
  *     return <File ...><Type node={node} resolver={resolver} /></File>
  *   },
- *   operation(node, ctx) {
- *     const { options } = ctx
- *     return <File ...><OperationType node={node} /></File>
- *   },
  * })
  * ```
  */

package/src/defineMiddleware.ts

@@ -22,14 +22,17 @@ export type Middleware = {
 }
 
 /**
- * Creates a middleware factory using the hook-style (`hooks:`) API.
+ * 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.
+ * 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.
+ *
+ * @note The factory can accept typed options. See examples for using options and per-build state patterns.
  *
  * @example
  * ```ts
+ * import { defineMiddleware } from '@kubb/core'
+ *
  * // Stateless middleware
  * export const logMiddleware = defineMiddleware(() => ({
  *   name: 'log-middleware',
@@ -41,10 +44,10 @@ export type Middleware = {
  * }))
  *
  * // Middleware with options and per-build state
- * export const myMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
+ * export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
  *   const seen = new Set<string>()
  *   return {
- *     name: 'my-middleware',
+ *     name: 'prefix-middleware',
  *     hooks: {
  *       'kubb:plugin:end'({ plugin }) {
  *         seen.add(`${options.prefix}${plugin.name}`)
@@ -52,11 +55,6 @@ export type Middleware = {
  *     },
  *   }
  * })
- *
- * // Usage in kubb.config.ts:
- * export default defineConfig({
- *   middleware: [logMiddleware(), myMiddleware({ prefix: 'pfx:' })],
- * })
  * ```
  */
 export function defineMiddleware<TOptions extends object = object>(factory: (options: TOptions) => Middleware): (options?: TOptions) => Middleware {

package/src/defineParser.ts

@@ -21,10 +21,9 @@ export type Parser<TMeta extends object = any> = {
 }
 
 /**
- * Defines a parser with type safety.
+ * Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
  *
- * Use this function to create parsers that transform generated files to strings
- * based on their extension.
+ * @note Call the returned factory with optional options to instantiate the parser.
  *
  * @example
  * ```ts

package/src/definePlugin.ts

@@ -54,23 +54,23 @@ export function isPlugin(plugin: unknown): plugin is Plugin {
 }
 
 /**
- * Creates a plugin factory using the hook-style (`hooks:`) API.
+ * Wraps a factory function and returns a typed `Plugin` with lifecycle handlers grouped under `hooks`.
  *
- * The returned factory is called with optional options and produces a `Plugin`
- * that coexists with plugins created via the legacy `createPlugin` API in the same
- * `kubb.config.ts`.
+ * Handlers live in a single `hooks` object (inspired by Astro integrations).
+ * All lifecycle events from `KubbHooks` are available for subscription.
  *
- * Lifecycle handlers are registered on the `PluginDriver`'s `AsyncEventEmitter`, enabling
- * both the plugin's own handlers and external tooling (CLI, devtools) to observe every event.
+ * @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`).
  *
  * @example
  * ```ts
- * // With PluginFactoryOptions (recommended for real plugins)
- * export const pluginTs = definePlugin<PluginTs>((options) => ({
+ * import { definePlugin } from '@kubb/core'
+ *
+ * export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
  *   name: 'plugin-ts',
  *   hooks: {
  *     'kubb:plugin:setup'(ctx) {
- *       ctx.setResolver(resolverTs)  // typed as Partial<ResolverTs>
+ *       ctx.setResolver(resolverTs)
  *     },
  *   },
  * }))

package/src/mocks.ts

@@ -7,7 +7,8 @@ import { applyHookResult } from './renderNode.ts'
 import type { Adapter, AdapterFactoryOptions, Config, Generator, GeneratorContext, NormalizedPlugin, PluginFactoryOptions } from './types.ts'
 
 /**
- * Creates a minimal `PluginDriver` mock suitable for unit tests.
+
+ * Creates a minimal `PluginDriver` mock for unit tests.
  */
 export function createMockedPluginDriver(options: { name?: string; plugin?: NormalizedPlugin; config?: Config } = {}): PluginDriver {
   return {
@@ -26,10 +27,9 @@ export function createMockedPluginDriver(options: { name?: string; plugin?: Norm
 }
 
 /**
- * Creates a minimal `Adapter` mock suitable for unit tests.
- *
- * - `parse` returns an empty `InputNode` by default; override via `options.parse`.
- * - `getImports` returns `[]` by default (single-file mode, no cross-file imports).
+ * Creates a minimal `Adapter` mock for unit tests.
+ * `parse` returns an empty `InputNode` by default; override via `options.parse`.
+ * `getImports` returns `[]` by default.
  */
 export function createMockedAdapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions>(
   options: {
@@ -51,7 +51,7 @@ export function createMockedAdapter<TOptions extends AdapterFactoryOptions = Ada
 }
 
 /**
- * Creates a minimal plugin mock suitable for unit tests.
+ * Creates a minimal plugin mock for unit tests.
  *
  * @example
  * const plugin = createMockedPlugin<PluginTs>({ name: '@kubb/plugin-ts', options })