@kubb/core 5.0.0-alpha.9 → 5.0.0-beta.2

package/src/Kubb.ts

@@ -1,224 +1,300 @@
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { Strategy } from './PluginDriver.ts'
-import type { Config, Plugin, PluginLifecycleHooks } from './types'
-
-type DebugInfo = {
-  date: Date
-  logs: Array<string>
-  fileName?: string
-}
-
-type HookProgress<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  hookName: H
-  plugins: Array<Plugin>
-}
-
-type HookExecution<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  strategy: Strategy
-  hookName: H
-  plugin: Plugin
-  parameters?: Array<unknown>
-  output?: unknown
-}
+import type { AsyncEventEmitter } from '@internals/utils'
+import type { OperationNode, SchemaNode } from '@kubb/ast'
+import type { BuildOutput } from './createKubb.ts'
+import type { PluginDriver } from './PluginDriver.ts'
+import type {
+  Config,
+  GeneratorContext,
+  KubbBuildEndContext,
+  KubbBuildStartContext,
+  KubbConfigEndContext,
+  KubbDebugContext,
+  KubbErrorContext,
+  KubbFileProcessingUpdateContext,
+  KubbFilesProcessingEndContext,
+  KubbFilesProcessingStartContext,
+  KubbGenerationEndContext,
+  KubbGenerationStartContext,
+  KubbGenerationSummaryContext,
+  KubbHookEndContext,
+  KubbHookStartContext,
+  KubbInfoContext,
+  KubbLifecycleStartContext,
+  KubbPluginEndContext,
+  KubbPluginSetupContext,
+  KubbPluginStartContext,
+  KubbPluginsEndContext,
+  KubbSuccessContext,
+  KubbVersionNewContext,
+  KubbWarnContext,
+} from './types'
 
-type HookResult<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  duration: number
-  strategy: Strategy
-  hookName: H
-  plugin: Plugin
-  parameters?: Array<unknown>
-  output?: unknown
+/**
+ * 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 = {
+  /**
+   * Shared event emitter for lifecycle and status events. Attach listeners before calling `setup()` or `build()`.
+   */
+  readonly hooks: AsyncEventEmitter<KubbHooks>
+  /**
+   * Generated source code keyed by absolute file path. Available after `build()` or `safeBuild()` completes.
+   */
+  readonly sources: Map<string, string>
+  /**
+   * Plugin driver managing all plugins. Available after `setup()` completes.
+   */
+  readonly driver: PluginDriver | undefined
+  /**
+   * Resolved configuration with defaults applied. Available after `setup()` completes.
+   */
+  readonly config: Config | undefined
+  /**
+   * Resolves config and initializes the driver. `build()` calls this automatically.
+   */
+  setup(): Promise<void>
+  /**
+   * Runs the full pipeline and throws on any plugin error. Automatically calls `setup()` if needed.
+   */
+  build(): Promise<BuildOutput>
+  /**
+   * 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
  * import type { AsyncEventEmitter } from '@internals/utils'
- * import type { KubbEvents } from '@kubb/core'
+ * import type { KubbHooks } from '@kubb/core'
  *
- * const events: AsyncEventEmitter<KubbEvents> = new AsyncEventEmitter()
+ * const hooks: AsyncEventEmitter<KubbHooks> = new AsyncEventEmitter()
  *
- * events.on('lifecycle:start', () => {
+ * hooks.on('kubb:lifecycle:start', () => {
  *   console.log('Starting Kubb generation')
  * })
  *
- * events.on('plugin:end', (plugin, { duration }) => {
+ * hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
  *   console.log(`Plugin ${plugin.name} completed in ${duration}ms`)
  * })
  * ```
  */
-export interface KubbEvents {
+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.
    */
-  'lifecycle:start': [version: string]
+  '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.
    */
-  'lifecycle:end': []
+  'kubb:lifecycle:end': []
 
   /**
-   * Emitted when configuration loading starts.
+   * Fires when configuration loading starts.
    */
-  'config:start': []
+  'kubb:config:start': []
   /**
-   * Emitted when configuration loading is complete.
+   * Fires when configuration loading completes.
    */
-  'config:end': [configs: Array<Config>]
+  'kubb:config:end': [ctx: KubbConfigEndContext]
 
   /**
-   * Emitted when code generation phase starts.
+   * Fires when code generation starts.
    */
-  'generation:start': [config: Config]
+  'kubb:generation:start': [ctx: KubbGenerationStartContext]
   /**
-   * Emitted when code generation phase completes.
+   * Fires when code generation completes.
    */
-  'generation:end': [config: Config, files: Array<KubbFile.ResolvedFile>, sources: Map<KubbFile.Path, string>]
+  '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.
    */
-  'generation:summary': [
-    config: Config,
-    {
-      failedPlugins: Set<{ plugin: Plugin; error: Error }>
-      status: 'success' | 'failed'
-      hrStart: [number, number]
-      filesCreated: number
-      pluginTimings?: Map<Plugin['name'], number>
-    },
-  ]
+  '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).
    */
-  'format:start': []
+  'kubb:format:start': []
   /**
-   * Emitted when code formatting completes.
+   * Fires when code formatting completes.
    */
-  'format:end': []
+  'kubb:format:end': []
 
   /**
-   * Emitted when linting starts.
+   * Fires when linting starts.
    */
-  'lint:start': []
+  'kubb:lint:start': []
   /**
-   * Emitted when linting completes.
+   * Fires when linting completes.
    */
-  'lint:end': []
+  'kubb:lint:end': []
 
   /**
-   * Emitted when plugin hooks execution starts.
+   * Fires when plugin hooks execution starts.
    */
-  'hooks:start': []
+  'kubb:hooks:start': []
   /**
-   * Emitted when plugin hooks execution completes.
+   * Fires when plugin hooks execution completes.
    */
-  'hooks:end': []
+  '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.
    */
-  'hook:start': [{ id?: string; command: string; args?: readonly string[] }]
+  'kubb:hook:start': [ctx: KubbHookStartContext]
   /**
-   * Emitted when a single hook execution completes.
+   * Fires when a single hook execution completes.
    */
-  'hook:end': [{ id?: string; command: string; args?: readonly string[]; success: boolean; error: Error | null }]
+  'kubb:hook:end': [ctx: KubbHookEndContext]
 
   /**
-   * Emitted when a new version of Kubb is available.
+   * Fires when a new Kubb version is available.
    */
-  'version:new': [currentVersion: string, latestVersion: string]
+  'kubb:version:new': [ctx: KubbVersionNewContext]
 
   /**
    * Informational message event.
    */
-  info: [message: string, info?: string]
+  'kubb:info': [ctx: KubbInfoContext]
   /**
-   * Error event. Emitted when an error occurs during code generation.
+   * Error event, fired when an error occurs during generation.
    */
-  error: [error: Error, meta?: Record<string, unknown>]
+  'kubb:error': [ctx: KubbErrorContext]
   /**
    * Success message event.
    */
-  success: [message: string, info?: string]
+  'kubb:success': [ctx: KubbSuccessContext]
   /**
    * Warning message event.
    */
-  warn: [message: string, info?: string]
+  '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.
    */
-  debug: [info: DebugInfo]
+  '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.
    */
-  'files:processing:start': [files: Array<KubbFile.ResolvedFile>]
+  '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.
    */
-  'file:processing:update': [
-    {
-      /** Number of files processed so far. */
-      processed: number
-      /** Total number of files to process. */
-      total: number
-      /** Processing percentage (0–100). */
-      percentage: number
-      /** Optional source identifier. */
-      source?: string
-      /** The file being processed. */
-      file: KubbFile.ResolvedFile
-      /**
-       * Kubb configuration (not present in Fabric).
-       * Provides access to the current config during file processing.
-       */
-      config: Config
-    },
-  ]
+  '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.
    */
-  'files:processing:end': [files: Array<KubbFile.ResolvedFile>]
+  'kubb:files:processing:end': [ctx: KubbFilesProcessingEndContext]
 
   /**
-   * Emitted when a plugin starts executing.
+   * Fires when a plugin starts execution.
    */
-  'plugin:start': [plugin: Plugin]
+  'kubb:plugin:start': [ctx: KubbPluginStartContext]
   /**
-   * Emitted when a plugin completes execution.
-   * Duration in ms.
+   * Fires when a plugin completes execution. Duration measured in milliseconds.
    */
-  'plugin:end': [plugin: Plugin, result: { duration: number; success: boolean; error?: Error }]
+  'kubb:plugin:end': [ctx: KubbPluginEndContext]
 
   /**
-   * Emitted when plugin hook progress tracking starts.
-   * Contains the hook name and list of plugins to execute.
+   * Fires once before plugins execute — allowing plugins to register generators, configure resolvers/transformers/renderers, or inject files.
+   */
+  'kubb:plugin:setup': [ctx: KubbPluginSetupContext]
+  /**
+   * Fires before the plugin execution loop begins. The adapter has already parsed the source and `inputNode` is available.
    */
-  'plugins:hook:progress:start': [progress: HookProgress]
+  'kubb:build:start': [ctx: KubbBuildStartContext]
   /**
-   * Emitted when plugin hook progress tracking ends.
-   * Contains the hook name that completed.
+   * 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.
    */
-  'plugins:hook:progress:end': [{ hookName: PluginLifecycleHooks }]
+  'kubb:plugins:end': [ctx: KubbPluginsEndContext]
+  /**
+   * Fires after all files write to disk.
+   */
+  'kubb:build:end': [ctx: KubbBuildEndContext]
 
   /**
-   * Emitted when a plugin hook starts processing.
-   * Contains strategy, hook name, plugin, parameters, and output.
+   * Fires for each schema node during AST traversal. Generator listeners respond to this.
+   */
+  'kubb:generate:schema': [node: SchemaNode, ctx: GeneratorContext]
+  /**
+   * Fires for each operation node during AST traversal. Generator listeners respond to this.
    */
-  'plugins:hook:processing:start': [execution: HookExecution]
+  'kubb:generate:operation': [node: OperationNode, ctx: GeneratorContext]
   /**
-   * Emitted when a plugin hook completes processing.
-   * Contains duration, strategy, hook name, plugin, parameters, and output.
+   * Fires once after all operations traverse with the full collected array. Batch generator listeners respond to this.
    */
-  'plugins:hook:processing:end': [result: HookResult]
+  'kubb:generate:operations': [nodes: Array<OperationNode>, ctx: GeneratorContext]
+}
+
+declare global {
+  namespace Kubb {
+    /**
+     * Registry that maps plugin names to their `PluginFactoryOptions`.
+     * Augment this interface in each plugin's `types.ts` to enable automatic
+     * typing for `getPlugin` and `requirePlugin`.
+     *
+     * @example
+     * ```ts
+     * // packages/plugin-ts/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginRegistry {
+     *       'plugin-ts': PluginTs
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginRegistry {}
+
+    /**
+     * Extension point for root `Config['output']` options.
+     * Augment the `output` key in middleware or plugin packages to add extra fields
+     * to the global output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/middleware-barrel/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface ConfigOptionsRegistry {
+     *       output: {
+     *         barrel?: import('./types.ts').BarrelConfig | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface ConfigOptionsRegistry {}
+
+    /**
+     * Extension point for per-plugin `Output` options.
+     * Augment the `output` key in middleware or plugin packages to add extra fields
+     * to the per-plugin output configuration without touching core types.
+     *
+     * @example
+     * ```ts
+     * // packages/middleware-barrel/src/types.ts
+     * declare global {
+     *   namespace Kubb {
+     *     interface PluginOptionsRegistry {
+     *       output: {
+     *         barrel?: import('./types.ts').PluginBarrelConfig | false
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    interface PluginOptionsRegistry {}
+  }
 }