@kubb/core 5.0.0-alpha.34 → 5.0.0-alpha.36

package/src/Kubb.ts

@@ -1,6 +1,8 @@
-import type { FileNode } from '@kubb/ast/types'
-import type { Strategy } from './PluginDriver.ts'
-import type { Config, Plugin, PluginLifecycleHooks } from './types'
+import type { AsyncEventEmitter } from '@internals/utils'
+import type { FileNode, OperationNode, SchemaNode } from '@kubb/ast'
+import type { BuildOutput } from './createKubb.ts'
+import type { PluginDriver, Strategy } from './PluginDriver.ts'
+import type { Config, GeneratorContext, KubbBuildEndContext, KubbBuildStartContext, KubbPluginSetupContext, Plugin, PluginLifecycleHooks } from './types'
 
 type DebugInfo = {
   date: Date
@@ -30,6 +32,47 @@ type HookResult<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
   output?: unknown
 }
 
+/**
+ * The instance returned by {@link createKubb}.
+ */
+export type Kubb = {
+  /**
+   * The shared event emitter. Attach listeners here 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.
+   */
+  readonly sources: Map<string, string>
+  /**
+   * The plugin driver. Available after `setup()` has been called.
+   */
+  readonly driver: PluginDriver | undefined
+  /**
+   * The resolved config with applied defaults. Available after `setup()` has been called.
+   */
+  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.
+   */
+  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.
+   */
+  build(): Promise<BuildOutput>
+  /**
+   * Runs a full Kubb build and captures errors instead of throwing.
+   * Automatically calls `setup()` if it has not been called yet.
+   */
+  safeBuild(): Promise<BuildOutput>
+}
+
 /**
  * Events emitted during the Kubb code generation lifecycle.
  * These events can be listened to for logging, progress tracking, and custom integrations.
@@ -37,51 +80,51 @@ type HookResult<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
  * @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.
    */
-  'lifecycle:start': [version: string]
+  'kubb:lifecycle:start': [version: string]
   /**
    * Emitted at the end of the Kubb lifecycle, after all code generation is complete.
    */
-  'lifecycle:end': []
+  'kubb:lifecycle:end': []
 
   /**
    * Emitted when configuration loading starts.
    */
-  'config:start': []
+  'kubb:config:start': []
   /**
    * Emitted when configuration loading is complete.
    */
-  'config:end': [configs: Array<Config>]
+  'kubb:config:end': [configs: Array<Config>]
 
   /**
    * Emitted when code generation phase starts.
    */
-  'generation:start': [config: Config]
+  'kubb:generation:start': [config: Config]
   /**
    * Emitted when code generation phase completes.
    */
-  'generation:end': [config: Config, files: Array<FileNode>, sources: Map<string, string>]
+  'kubb:generation:end': [config: Config, files: Array<FileNode>, sources: Map<string, string>]
   /**
    * Emitted with a summary of the generation results.
    * Contains summary lines, title, and success status.
    */
-  'generation:summary': [
+  'kubb:generation:summary': [
     config: Config,
     {
       failedPlugins: Set<{ plugin: Plugin; error: Error }>
@@ -95,77 +138,77 @@ export interface KubbEvents {
   /**
    * Emitted when code formatting starts (e.g., running Biome or Prettier).
    */
-  'format:start': []
+  'kubb:format:start': []
   /**
    * Emitted when code formatting completes.
    */
-  'format:end': []
+  'kubb:format:end': []
 
   /**
    * Emitted when linting starts.
    */
-  'lint:start': []
+  'kubb:lint:start': []
   /**
    * Emitted when linting completes.
    */
-  'lint:end': []
+  'kubb:lint:end': []
 
   /**
    * Emitted when plugin hooks execution starts.
    */
-  'hooks:start': []
+  'kubb:hooks:start': []
   /**
    * Emitted 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.
    */
-  'hook:start': [{ id?: string; command: string; args?: readonly string[] }]
+  'kubb:hook:start': [{ id?: string; command: string; args?: readonly string[] }]
   /**
    * Emitted when a single hook execution completes.
    */
-  'hook:end': [{ id?: string; command: string; args?: readonly string[]; success: boolean; error: Error | null }]
+  'kubb:hook:end': [{ id?: string; command: string; args?: readonly string[]; success: boolean; error: Error | null }]
 
   /**
    * Emitted when a new version of Kubb is available.
    */
-  'version:new': [currentVersion: string, latestVersion: string]
+  'kubb:version:new': [currentVersion: string, latestVersion: string]
 
   /**
    * Informational message event.
    */
-  info: [message: string, info?: string]
+  'kubb:info': [message: string, info?: string]
   /**
    * Error event. Emitted when an error occurs during code generation.
    */
-  error: [error: Error, meta?: Record<string, unknown>]
+  'kubb:error': [error: Error, meta?: Record<string, unknown>]
   /**
    * Success message event.
    */
-  success: [message: string, info?: string]
+  'kubb:success': [message: string, info?: string]
   /**
    * Warning message event.
    */
-  warn: [message: string, info?: string]
+  'kubb:warn': [message: string, info?: string]
   /**
    * Debug event for detailed logging.
    * Contains timestamp, log messages, and optional filename.
    */
-  debug: [info: DebugInfo]
+  'kubb:debug': [info: DebugInfo]
 
   /**
    * Emitted when file processing starts.
    * Contains the list of files to be processed.
    */
-  'files:processing:start': [files: Array<FileNode>]
+  'kubb:files:processing:start': [files: Array<FileNode>]
   /**
    * Emitted for each file being processed, providing progress updates.
    * Contains processed count, total count, percentage, and file details.
    */
-  'file:processing:update': [
+  'kubb:file:processing:update': [
     {
       /**
        * Number of files processed so far.
@@ -198,37 +241,101 @@ export interface KubbEvents {
    * Emitted when file processing completes.
    * Contains the list of processed files.
    */
-  'files:processing:end': [files: Array<FileNode>]
+  'kubb:files:processing:end': [files: Array<FileNode>]
 
   /**
    * Emitted when a plugin starts executing.
    */
-  'plugin:start': [plugin: Plugin]
+  'kubb:plugin:start': [plugin: Plugin]
   /**
    * Emitted when a plugin completes execution.
    * Duration in ms.
    */
-  'plugin:end': [plugin: Plugin, result: { duration: number; success: boolean; error?: Error }]
+  'kubb:plugin:end': [plugin: Plugin, result: { duration: number; success: boolean; error?: Error }]
 
   /**
    * Emitted when plugin hook progress tracking starts.
    * Contains the hook name and list of plugins to execute.
    */
-  'plugins:hook:progress:start': [progress: HookProgress]
+  'kubb:plugins:hook:progress:start': [progress: HookProgress]
   /**
    * Emitted when plugin hook progress tracking ends.
    * Contains the hook name that completed.
    */
-  'plugins:hook:progress:end': [{ hookName: PluginLifecycleHooks }]
+  'kubb:plugins:hook:progress:end': [{ hookName: PluginLifecycleHooks }]
 
   /**
    * Emitted when a plugin hook starts processing.
    * Contains strategy, hook name, plugin, parameters, and output.
    */
-  'plugins:hook:processing:start': [execution: HookExecution]
+  'kubb:plugins:hook:processing:start': [execution: HookExecution]
   /**
    * Emitted when a plugin hook completes processing.
    * Contains duration, strategy, hook name, plugin, parameters, and output.
    */
-  'plugins:hook:processing:end': [result: HookResult]
+  'kubb:plugins:hook:processing:end': [result: HookResult]
+
+  /**
+   * 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', …)`.
+   */
+  'kubb:plugin:setup': [ctx: KubbPluginSetupContext]
+  /**
+   * Fired immediately 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 files have been written 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).
+   */
+  '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).
+   */
+  '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.
+   */
+  'kubb:generate:operations': [nodes: Array<OperationNode>, ctx: GeneratorContext]
+}
+
+declare global {
+  namespace Kubb {
+    interface PluginContext {}
+    /**
+     * 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 {}
+  }
 }