@kubb/core 5.0.0-beta.17 → 5.0.0-beta.19

package/dist/{createKubb-ZgT1MTxG.d.ts → createKubb-BJGymYhe.d.ts}

@@ -33,7 +33,7 @@ declare class AsyncEventEmitter<TEvents extends { [K in keyof TEvents]: unknown[
    * await emitter.emit('build', 'petstore')
    * ```
    */
-  emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArgs: TEvents[TEventName]): Promise<void>;
+  emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArgs: TEvents[TEventName]): Promise<void> | void;
   /**
    * Registers a persistent listener for `eventName`.
    *
@@ -245,35 +245,44 @@ declare function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryO
 /**
  * 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.
  */
 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;
+  /**
+   * 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>;
 };
 /**
- * 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.
  */
 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 {
@@ -282,14 +291,6 @@ type RendererFactory<TElement = unknown> = () => Renderer<TElement>;
  *     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> },
- * })
  * ```
  */
 declare function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement>;
@@ -389,7 +390,7 @@ 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;
 };
 /**
  * Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
@@ -446,15 +447,8 @@ declare class FileProcessor {
   parse(file: FileNode, {
     parsers,
     extension
-  }?: ParseOptions): Promise<string>;
-  /**
-   * Streams parsed files one at a time as each is processed.
-   *
-   * Unlike `run()`, files are yielded immediately after parsing rather than batched.
-   * Storage writes can begin as soon as the first file is ready, keeping peak
-   * memory proportional to one file at a time instead of the full batch.
-   */
-  stream(files: ReadonlyArray<FileNode>, options?: ParseOptions): AsyncGenerator<ParsedFile>;
+  }?: ParseOptions): string;
+  stream(files: ReadonlyArray<FileNode>, options?: ParseOptions): Generator<ParsedFile>;
   run(files: Array<FileNode>, options?: ParseOptions): Promise<Array<FileNode>>;
 }
 //#endregion
@@ -718,29 +712,6 @@ type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'],
   name: string;
   pluginName: T['name'];
 } & ThisType<T['resolver']>;
-/**
- * Default option resolver — applies include/exclude filters and merges matching override options.
- *
- * Returns `null` when the node is filtered out by an `exclude` rule or not matched by any `include` rule.
- *
- * @example Include/exclude filtering
- * ```ts
- * const options = defaultResolveOptions(operationNode, {
- *   options: { output: 'types' },
- *   exclude: [{ type: 'tag', pattern: 'internal' }],
- * })
- * // → null when node has tag 'internal'
- * ```
- *
- * @example Override merging
- * ```ts
- * const options = defaultResolveOptions(operationNode, {
- *   options: { enumType: 'asConst' },
- *   override: [{ type: 'operationId', pattern: 'listPets', options: { enumType: 'enum' } }],
- * })
- * // → { enumType: 'enum' } when operationId matches
- * ```
- */
 /**
  * Defines a resolver for a plugin, injecting built-in defaults for name casing,
  * include/exclude/override filtering, path resolution, and file construction.
@@ -985,7 +956,7 @@ type KubbPluginSetupContext<TFactory extends PluginFactoryOptions = PluginFactor
    * 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;
+  addGenerator<TElement = unknown>(generator: Generator$1<TFactory, TElement>): void;
   /**
    * Set or override the resolver for this plugin.
    * The resolver controls file naming and path resolution.
@@ -1076,7 +1047,7 @@ type NormalizedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptio
   resolver: TOptions['resolver'];
   transformer?: Visitor;
   renderer?: RendererFactory;
-  generators?: Array<Generator>;
+  generators?: Array<Generator$1>;
   apply?: (config: Config) => boolean;
   version?: string;
 };
@@ -1162,6 +1133,7 @@ declare class FileManager {
    * free the per-plugin FileNode caches for the rest of the process lifetime.
    */
   dispose(): void;
+  [Symbol.dispose](): void;
   /**
    * All stored files, sorted by path length (shorter paths first).
    */
@@ -1243,7 +1215,7 @@ declare class PluginDriver {
    *
    * Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
    */
-  registerGenerator(pluginName: string, gen: Generator): void;
+  registerGenerator(pluginName: string, gen: Generator$1): void;
   /**
    * Returns `true` when at least one generator was registered for the given plugin
    * via `addGenerator()` in `kubb:plugin:setup` (event-based path).
@@ -1259,6 +1231,7 @@ declare class PluginDriver {
    * @internal
    */
   dispose(): void;
+  [Symbol.dispose](): void;
   /**
    * Merges `partial` with the plugin's default resolver and stores the result.
    * Also mirrors it onto `plugin.resolver` so callers using `getPlugin(name).resolver`
@@ -1394,7 +1367,7 @@ type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptio
  * })
  * ```
  */
-type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown> = {
+type Generator$1<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown> = {
   /**
    * Used in diagnostic messages and debug output.
    */
@@ -1444,7 +1417,7 @@ type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TEl
  * `applyHookResult` handles renderer elements and `File[]` uniformly using
  * the generator's declared `renderer` factory.
  */
-declare function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(generator: Generator<TOptions, TElement>): Generator<TOptions, TElement>;
+declare function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(generator: Generator$1<TOptions, TElement>): Generator$1<TOptions, TElement>;
 //#endregion
 //#region src/createKubb.d.ts
 /**
@@ -1899,21 +1872,16 @@ declare global {
 }
 /**
  * Lifecycle events emitted during Kubb code generation.
- * Use these for logging, progress tracking, and custom integrations.
+ * Attach listeners before calling `setup()` or `build()` to observe and react to build progress.
  *
  * @example
- * ```typescript
- * import type { AsyncEventEmitter } from '@internals/utils'
- * import type { KubbHooks } from '@kubb/core'
- *
- * const hooks: AsyncEventEmitter<KubbHooks> = new AsyncEventEmitter()
- *
- * hooks.on('kubb:lifecycle:start', () => {
+ * ```ts
+ * kubb.hooks.on('kubb:lifecycle:start', () => {
  *   console.log('Starting Kubb generation')
  * })
  *
- * hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
- *   console.log(`Plugin ${plugin.name} completed in ${duration}ms`)
+ * kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
+ *   console.log(`${plugin.name} completed in ${duration}ms`)
  * })
  * ```
  */
@@ -1953,45 +1921,90 @@ interface KubbHooks {
   'kubb:generate:operations': [nodes: Array<OperationNode>, ctx: GeneratorContext];
 }
 type KubbBuildStartContext = {
+  /**
+   * Resolved configuration for this build.
+   */
   config: Config;
+  /**
+   * Adapter that parsed the input into the universal AST.
+   */
   adapter: Adapter;
+  /**
+   * Parsed input node. For streaming builds the node is a synthetic empty shell
+   * with only `meta` populated — use `kubb:generate:schema` / `kubb:generate:operation` to observe individual nodes.
+   */
   inputNode: InputNode;
+  /**
+   * Looks up a registered plugin by name, typed by the plugin registry.
+   */
   getPlugin<TName extends keyof Kubb$1.PluginRegistry>(name: TName): Plugin<Kubb$1.PluginRegistry[TName]> | undefined;
   getPlugin(name: string): Plugin | undefined;
+  /**
+   * Snapshot of all files accumulated so far.
+   */
   readonly files: ReadonlyArray<FileNode>;
+  /**
+   * Adds or merges one or more files into the file manager.
+   */
   upsertFile: (...files: Array<FileNode>) => void;
 };
 type KubbPluginsEndContext = {
+  /**
+   * Resolved configuration for this build.
+   */
   config: Config;
+  /**
+   * Snapshot of all files accumulated across all plugins.
+   */
   readonly files: ReadonlyArray<FileNode>;
+  /**
+   * Adds or merges one or more files into the file manager.
+   */
   upsertFile: (...files: Array<FileNode>) => void;
 };
 type KubbBuildEndContext = {
+  /**
+   * All files generated during this build.
+   */
   files: Array<FileNode>;
+  /**
+   * Resolved configuration for this build.
+   */
   config: Config;
+  /**
+   * Absolute path to the output directory.
+   */
   outputDir: string;
 };
 type KubbLifecycleStartContext = {
+  /**
+   * Current Kubb version string.
+   */
   version: string;
 };
 type KubbConfigEndContext = {
+  /**
+   * All resolved configs after defaults are applied.
+   */
   configs: Array<Config>;
 };
 type KubbGenerationStartContext = {
+  /**
+   * Resolved configuration for this generation run.
+   */
   config: Config;
 };
 type KubbGenerationEndContext = {
+  /**
+   * Resolved configuration for this generation run.
+   */
   config: Config;
   /**
-   * Read-only view of the files Kubb wrote during this build.
-   *
-   * Keys are scoped to this run; files from earlier builds are not included.
-   * Reads go directly to `config.storage`, so nothing is buffered in memory.
+   * Read-only view of the files written during this build.
+   * Reads go directly to `config.storage` — nothing extra is held in memory.
    *
    * @example Read a generated file
-   * ```ts
-   * const code = await storage.getItem('/src/gen/pet.ts')
-   * ```
+   * `const code = await storage.getItem('/src/gen/pet.ts')`
    *
    * @example Walk every generated file
    * ```ts
@@ -2003,73 +2016,189 @@ type KubbGenerationEndContext = {
   storage: Storage;
 };
 type KubbGenerationSummaryContext = {
+  /**
+   * Resolved configuration for this generation run.
+   */
   config: Config;
+  /**
+   * Plugins that threw during generation, paired with their errors.
+   */
   failedPlugins: Set<{
     plugin: Plugin;
     error: Error;
   }>;
+  /**
+   * `'success'` when all plugins completed without errors, `'failed'` otherwise.
+   */
   status: 'success' | 'failed';
+  /**
+   * High-resolution start time from `process.hrtime()`.
+   */
   hrStart: [number, number];
+  /**
+   * Total number of files created during this run.
+   */
   filesCreated: number;
+  /**
+   * Elapsed milliseconds per plugin, keyed by plugin name.
+   */
   pluginTimings?: Map<Plugin['name'], number>;
 };
 type KubbVersionNewContext = {
+  /**
+   * The installed Kubb version.
+   */
   currentVersion: string;
+  /**
+   * The newest available version on npm.
+   */
   latestVersion: string;
 };
 type KubbInfoContext = {
+  /**
+   * Human-readable info message.
+   */
   message: string;
+  /**
+   * Optional supplementary detail.
+   */
   info?: string;
 };
 type KubbErrorContext = {
+  /**
+   * The caught error.
+   */
   error: Error;
+  /**
+   * Optional structured metadata for additional context.
+   */
   meta?: Record<string, unknown>;
 };
 type KubbSuccessContext = {
+  /**
+   * Human-readable success message.
+   */
   message: string;
+  /**
+   * Optional supplementary detail.
+   */
   info?: string;
 };
 type KubbWarnContext = {
+  /**
+   * Human-readable warning message.
+   */
   message: string;
+  /**
+   * Optional supplementary detail.
+   */
   info?: string;
 };
 type KubbDebugContext = {
+  /**
+   * Timestamp when the debug entry was created.
+   */
   date: Date;
+  /**
+   * One or more log lines to emit.
+   */
   logs: Array<string>;
+  /**
+   * Optional source file name associated with this entry.
+   */
   fileName?: string;
 };
 type KubbFilesProcessingStartContext = {
+  /**
+   * Files about to be serialised and written.
+   */
   files: Array<FileNode>;
 };
 type KubbFileProcessingUpdateContext = {
+  /**
+   * Number of files processed so far in this batch.
+   */
   processed: number;
+  /**
+   * Total number of files in this batch.
+   */
   total: number;
+  /**
+   * Completion percentage (`0`–`100`).
+   */
   percentage: number;
+  /**
+   * Serialised file content, or `undefined` when the file produced no output.
+   */
   source?: string;
+  /**
+   * The file that was just processed.
+   */
   file: FileNode;
+  /**
+   * Resolved configuration for this build.
+   */
   config: Config;
 };
 type KubbFilesProcessingEndContext = {
+  /**
+   * All files that were serialised in this batch.
+   */
   files: Array<FileNode>;
 };
 type KubbHookStartContext = {
+  /**
+   * Optional identifier for correlating start/end events.
+   */
   id?: string;
+  /**
+   * The shell command that is about to run.
+   */
   command: string;
+  /**
+   * Parsed argument list, when available.
+   */
   args?: readonly string[];
 };
 type KubbHookEndContext = {
+  /**
+   * Optional identifier matching the corresponding `kubb:hook:start` event.
+   */
   id?: string;
+  /**
+   * The shell command that ran.
+   */
   command: string;
+  /**
+   * Parsed argument list, when available.
+   */
   args?: readonly string[];
+  /**
+   * `true` when the command exited with code `0`.
+   */
   success: boolean;
+  /**
+   * Error thrown by the command, or `null` on success.
+   */
   error: Error | null;
 };
 /**
  * CLI options derived from command-line flags.
  */
 type CLIOptions = {
+  /**
+   * Path to the Kubb config file.
+   */
   config?: string;
-  watch?: boolean; /** @default 'silent' */
+  /**
+   * Re-run generation whenever input files change.
+   */
+  watch?: boolean;
+  /**
+   * Controls how much output the CLI prints.
+   *
+   * @default 'silent'
+   */
   logLevel?: 'silent' | 'info' | 'debug';
 };
 /**
@@ -2082,34 +2211,37 @@ type PossibleConfig<TCliOptions = undefined> = PossiblePromise<Config | Config[]
  */
 type BuildOutput = {
   /**
-   * Plugins that threw during installation, paired with the caught error.
+   * Plugins that threw during generation, paired with their errors.
    */
   failedPlugins: Set<{
     plugin: Plugin;
     error: Error;
   }>;
+  /**
+   * All files generated during this build.
+   */
   files: Array<FileNode>;
+  /**
+   * The plugin driver that orchestrated this build.
+   */
   driver: PluginDriver;
   /**
-   * Elapsed time in milliseconds for each plugin, keyed by plugin name.
+   * Elapsed milliseconds per plugin, keyed by plugin name.
    */
   pluginTimings: Map<string, number>;
+  /**
+   * Top-level error when the build threw before completing, otherwise `undefined`.
+   */
   error?: Error;
   /**
    * Read-only view of every file written during this build.
-   *
-   * Keys are limited to this run. Reads go straight to `config.storage`,
-   * so nothing extra is held in memory.
+   * Reads go straight to `config.storage` — nothing extra is held in memory.
    *
    * @example Read a generated file
-   * ```ts
-   * const code = await buildOutput.storage.getItem('/src/gen/pet.ts')
-   * ```
+   * `const code = await buildOutput.storage.getItem('/src/gen/pet.ts')`
    *
    * @example List all generated file paths
-   * ```ts
-   * const paths = await buildOutput.storage.getKeys()
-   * ```
+   * `const paths = await buildOutput.storage.getKeys()`
    */
   storage: Storage;
 };
@@ -2199,5 +2331,5 @@ type CreateKubbOptions = {
  */
 declare function createKubb(userConfig: UserConfig, options?: CreateKubbOptions): Kubb$1;
 //#endregion
-export { ResolverPathParams as $, isInputPath as A, KubbPluginSetupContext as B, KubbPluginsEndContext as C, logLevel as Ct, PossibleConfig as D, KubbWarnContext as E, FileManager as F, Plugin as G, NormalizedPlugin as H, Exclude as I, ResolveBannerContext as J, PluginFactoryOptions as K, Group as L, GeneratorContext as M, defineGenerator as N, UserConfig as O, PluginDriver as P, ResolverFileParams as Q, Include as R, KubbLifecycleStartContext as S, createAdapter as St, KubbVersionNewContext as T, Output as U, KubbPluginStartContext as V, Override as W, Resolver as X, ResolveOptionsContext as Y, ResolverContext as Z, KubbGenerationSummaryContext as _, RendererFactory as _t, InputPath as a, LoggerOptions as at, KubbHooks as b, AdapterFactoryOptions as bt, KubbBuildStartContext as c, FileProcessor as ct, KubbErrorContext as d, Parser as dt, defineResolver as et, KubbFileProcessingUpdateContext as f, defineParser as ft, KubbGenerationStartContext as g, Renderer as gt, KubbGenerationEndContext as h, createStorage as ht, InputData as i, LoggerContext as it, Generator as j, createKubb as k, KubbConfigEndContext as l, FileProcessorEvents as lt, KubbFilesProcessingStartContext as m, Storage as mt, CLIOptions as n, defineMiddleware as nt, Kubb$1 as o, UserLogger as ot, KubbFilesProcessingEndContext as p, DevtoolsOptions as pt, definePlugin as q, Config as r, Logger as rt, KubbBuildEndContext as s, defineLogger as st, BuildOutput as t, Middleware as tt, KubbDebugContext as u, ParsedFile as ut, KubbHookEndContext as v, createRenderer as vt, KubbSuccessContext as w, AsyncEventEmitter as wt, KubbInfoContext as x, AdapterSource as xt, KubbHookStartContext as y, Adapter as yt, KubbPluginEndContext as z };
-//# sourceMappingURL=createKubb-ZgT1MTxG.d.ts.map
+export { ResolverPathParams as $, isInputPath as A, KubbPluginSetupContext as B, KubbPluginsEndContext as C, logLevel as Ct, PossibleConfig as D, KubbWarnContext as E, FileManager as F, Plugin as G, NormalizedPlugin as H, Exclude as I, ResolveBannerContext as J, PluginFactoryOptions as K, Group as L, GeneratorContext as M, defineGenerator as N, UserConfig as O, PluginDriver as P, ResolverFileParams as Q, Include as R, KubbLifecycleStartContext as S, createAdapter as St, KubbVersionNewContext as T, Output as U, KubbPluginStartContext as V, Override as W, Resolver as X, ResolveOptionsContext as Y, ResolverContext as Z, KubbGenerationSummaryContext as _, RendererFactory as _t, InputPath as a, LoggerOptions as at, KubbHooks as b, AdapterFactoryOptions as bt, KubbBuildStartContext as c, FileProcessor as ct, KubbErrorContext as d, Parser as dt, defineResolver as et, KubbFileProcessingUpdateContext as f, defineParser as ft, KubbGenerationStartContext as g, Renderer as gt, KubbGenerationEndContext as h, createStorage as ht, InputData as i, LoggerContext as it, Generator$1 as j, createKubb as k, KubbConfigEndContext as l, FileProcessorEvents as lt, KubbFilesProcessingStartContext as m, Storage as mt, CLIOptions as n, defineMiddleware as nt, Kubb$1 as o, UserLogger as ot, KubbFilesProcessingEndContext as p, DevtoolsOptions as pt, definePlugin as q, Config as r, Logger as rt, KubbBuildEndContext as s, defineLogger as st, BuildOutput as t, Middleware as tt, KubbDebugContext as u, ParsedFile as ut, KubbHookEndContext as v, createRenderer as vt, KubbSuccessContext as w, AsyncEventEmitter as wt, KubbInfoContext as x, AdapterSource as xt, KubbHookStartContext as y, Adapter as yt, KubbPluginEndContext as z };
+//# sourceMappingURL=createKubb-BJGymYhe.d.ts.map