@kubb/oas 4.11.2 → 4.12.0

package/dist/index.d.cts

@@ -7,7 +7,6 @@ import * as oas_normalize_lib_types0 from "oas-normalize/lib/types";
 import BaseOas from "oas";
 import { KubbFile } from "@kubb/fabric-core/types";
 import { Fabric } from "@kubb/react-fabric";
-import { ConsolaInstance, LogLevel } from "consola";
 
 //#region src/Oas.d.ts
 type Options$1 = {
@@ -37,75 +36,229 @@ declare class Oas<const TOAS = unknown> extends BaseOas {
   valdiate(): Promise<oas_normalize_lib_types0.ValidationResult>;
 }
 //#endregion
-//#region ../core/src/utils/EventEmitter.d.ts
-declare class EventEmitter<TEvents extends Record<string, any>> {
-  #private;
-  constructor();
-  emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArg: TEvents[TEventName]): void;
-  on<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void;
-  off<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void;
-  removeAll(): void;
-}
-//#endregion
-//#region ../core/src/logger.d.ts
+//#region ../core/src/Kubb.d.ts
 type DebugEvent = {
   date: Date;
   logs: string[];
   fileName?: string;
+};
+type ProgressStartMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
+  hookName: H;
+  plugins: Array<Plugin>;
+};
+type ProgressStopMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
+  hookName: H;
+};
+type ExecutingMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
+  strategy: Strategy;
+  hookName: H;
+  plugin: Plugin;
+  parameters?: unknown[] | undefined;
+  output?: unknown;
+};
+type ExecutedMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
+  duration: number;
+  strategy: Strategy;
+  hookName: H;
+  plugin: Plugin;
+  parameters?: unknown[] | undefined;
+  output?: unknown;
+};
+/**
+ * Events emitted during the Kubb code generation lifecycle.
+ * These events can be listened to for logging, progress tracking, and custom integrations.
+ *
+ * @example
+ * ```typescript
+ * import type { AsyncEventEmitter } from '@kubb/core'
+ * import type { KubbEvents } from '@kubb/core'
+ *
+ * const events: AsyncEventEmitter<KubbEvents> = new AsyncEventEmitter()
+ *
+ * events.on('lifecycle:start', () => {
+ *   console.log('Starting Kubb generation')
+ * })
+ *
+ * events.on('plugin:end', (plugin, duration) => {
+ *   console.log(`Plugin ${plugin.name} completed in ${duration}ms`)
+ * })
+ * ```
+ */
+interface KubbEvents {
   /**
-   * Category of the debug log, used for GitHub Actions grouping
-   * - 'setup': Initial configuration and environment setup
-   * - 'plugin': Plugin installation and execution
-   * - 'hook': Plugin hook execution details
-   * - 'schema': Schema parsing and generation
-   * - 'file': File operations (read/write/generate)
-   * - 'error': Error details and stack traces
-   * - undefined: Generic logs (always inline)
+   * Emitted at the beginning of the Kubb lifecycle, before any code generation starts.
    */
-  category?: 'setup' | 'plugin' | 'hook' | 'schema' | 'file' | 'error';
+  'lifecycle:start': [version: string];
   /**
-   * Plugin name for grouping plugin-specific logs together
+   * Emitted at the end of the Kubb lifecycle, after all code generation is complete.
    */
-  pluginName?: string;
+  'lifecycle:end': [];
   /**
-   * Indicates if this is the start or end of a plugin's execution
-   * - 'start': Start of plugin execution group
-   * - 'end': End of plugin execution group
+   * Emitted when configuration loading starts.
    */
-  pluginGroupMarker?: 'start' | 'end';
-};
-type Events$1 = {
-  start: [message: string];
-  success: [message: string];
-  error: [message: string, error: Error];
-  warning: [message: string];
-  debug: [DebugEvent];
-  verbose: [DebugEvent];
-  info: [message: string];
-  progress_start: [{
-    id: string;
-    size: number;
-    message?: string;
-  }];
-  progressed: [{
-    id: string;
-    message?: string;
+  'config:start': [];
+  /**
+   * Emitted when configuration loading is complete.
+   */
+  'config:end': [configs: Array<Config>];
+  /**
+   * Emitted when code generation phase starts.
+   */
+  'generation:start': [config: Config];
+  /**
+   * Emitted when code generation phase completes.
+   */
+  'generation:end': [Config: Config];
+  /**
+   * Emitted with a summary of the generation results.
+   * Contains 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<string, number>;
   }];
-  progress_stop: [{
-    id: string;
+  /**
+   * Emitted when code formatting starts (e.g., running Biome or Prettier).
+   */
+  'format:start': [];
+  /**
+   * Emitted when code formatting completes.
+   */
+  'format:end': [];
+  /**
+   * Emitted when linting starts.
+   */
+  'lint:start': [];
+  /**
+   * Emitted when linting completes.
+   */
+  'lint:end': [];
+  /**
+   * Emitted when plugin hooks execution starts.
+   */
+  'hooks:start': [];
+  /**
+   * Emitted when plugin hooks execution completes.
+   */
+  'hooks:end': [];
+  /**
+   * Emitted when a single hook execution starts.
+   */
+  'hook:start': [command: string];
+  /**
+   * Emitted to execute a hook command (e.g., format or lint).
+   * The callback should be invoked when the command completes.
+   */
+  'hook:execute': [{
+    command: string | URL;
+    args?: readonly string[];
+  }, cb: () => void];
+  /**
+   * Emitted when a single hook execution completes.
+   */
+  'hook:end': [command: string];
+  /**
+   * Emitted when a new version of Kubb is available.
+   */
+  'version:new': [currentVersion: string, latestVersion: string];
+  /**
+   * Informational message event.
+   */
+  info: [message: string, info?: string];
+  /**
+   * Error event. Emitted when an error occurs during code generation.
+   */
+  error: [error: Error, meta?: Record<string, unknown>];
+  /**
+   * Success message event.
+   */
+  success: [message: string, info?: string];
+  /**
+   * Warning message event.
+   */
+  warn: [message: string, info?: string];
+  /**
+   * Debug event for detailed logging.
+   * Contains timestamp, log messages, and optional filename.
+   */
+  debug: [meta: DebugEvent];
+  /**
+   * Emitted when file processing starts.
+   * Contains the list of files to be processed.
+   */
+  'files:processing:start': [files: Array<KubbFile.ResolvedFile>];
+  /**
+   * Emitted for each file being processed, providing progress updates.
+   * Contains processed count, total count, 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;
   }];
-};
-type Logger = {
   /**
-   * Optional config name to show in CLI output
+   * Emitted when file processing completes.
+   * Contains the list of processed files.
    */
-  name?: string;
-  logLevel: LogLevel;
-  consola?: ConsolaInstance;
-  on: EventEmitter<Events$1>['on'];
-  emit: EventEmitter<Events$1>['emit'];
-  writeLogs: () => Promise<void>;
-};
+  'files:processing:end': [files: KubbFile.ResolvedFile[]];
+  /**
+   * Emitted when a plugin starts executing.
+   */
+  'plugin:start': [plugin: Plugin];
+  /**
+   * Emitted when a plugin completes execution.
+   */
+  'plugin:end': [plugin: Plugin, duration: number];
+  /**
+   * Emitted when plugin hook progress tracking starts.
+   * Contains the hook name and list of plugins to execute.
+   */
+  'plugins:hook:progress:start': [meta: ProgressStartMeta];
+  /**
+   * Emitted when plugin hook progress tracking ends.
+   * Contains the hook name that completed.
+   */
+  'plugins:hook:progress:end': [meta: ProgressStopMeta];
+  /**
+   * Emitted when a plugin hook starts processing.
+   * Contains strategy, hook name, plugin, parameters, and output.
+   */
+  'plugins:hook:processing:start': [meta: ExecutingMeta];
+  /**
+   * Emitted when a plugin hook completes processing.
+   * Contains duration, strategy, hook name, plugin, parameters, and output.
+   */
+  'plugins:hook:processing:end': [meta: ExecutedMeta];
+}
+//#endregion
+//#region ../core/src/utils/AsyncEventEmitter.d.ts
+declare class AsyncEventEmitter<TEvents extends Record<string, any>> {
+  #private;
+  constructor(maxListener?: number);
+  emit<TEventName extends keyof TEvents & string>(eventName: TEventName, ...eventArgs: TEvents[TEventName]): Promise<void>;
+  on<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void;
+  onOnce<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArgs: TEvents[TEventName]) => void): void;
+  off<TEventName extends keyof TEvents & string>(eventName: TEventName, handler: (...eventArg: TEvents[TEventName]) => void): void;
+  removeAll(): void;
+}
 //#endregion
 //#region ../core/src/utils/types.d.ts
 type PossiblePromise<T> = Promise<T> | T;
@@ -346,7 +499,7 @@ type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions>
    * merging multiple sources into the same output file
    */
   upsertFile: (...file: Array<KubbFile.File>) => Promise<void>;
-  logger: Logger;
+  events: AsyncEventEmitter<KubbEvents>;
   mode: KubbFile.Mode;
   /**
    * Current plugin
@@ -357,35 +510,6 @@ type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions>
 //#region ../core/src/PluginManager.d.ts
 type RequiredPluginLifecycle = Required<PluginLifecycle>;
 type Strategy = 'hookFirst' | 'hookForPlugin' | 'hookParallel' | 'hookSeq';
-type ExecutingMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  strategy: Strategy;
-  hookName: H;
-  plugin: Plugin;
-  parameters?: unknown[] | undefined;
-  output?: unknown;
-};
-type ExecutedMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  duration: number;
-  strategy: Strategy;
-  hookName: H;
-  plugin: Plugin;
-  parameters?: unknown[] | undefined;
-  output?: unknown;
-};
-type ErrorMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  hookName: H;
-  duration: number;
-  strategy: Strategy;
-  parameters?: unknown[] | undefined;
-  plugin: Plugin;
-};
-type ProgressStartMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  hookName: H;
-  plugins: Array<Plugin>;
-};
-type ProgressStopMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  hookName: H;
-};
 type ParseResult<H extends PluginLifecycleHooks> = RequiredPluginLifecycle[H];
 type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseResult<H>>> = {
   result: Result;
@@ -393,19 +517,12 @@ type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseRe
 };
 type Options = {
   fabric: Fabric;
-  logger: Logger;
+  events: AsyncEventEmitter<KubbEvents>;
   /**
    * @default Number.POSITIVE_INFINITY
    */
   concurrency?: number;
 };
-type Events = {
-  progress_start: [meta: ProgressStartMeta];
-  progress_stop: [meta: ProgressStopMeta];
-  executing: [meta: ExecutingMeta];
-  executed: [meta: ExecutedMeta];
-  error: [error: Error, meta: ErrorMeta];
-};
 type GetFileProps<TOptions = object> = {
   name: string;
   mode?: KubbFile.Mode;
@@ -415,10 +532,10 @@ type GetFileProps<TOptions = object> = {
 };
 declare class PluginManager {
   #private;
-  readonly events: EventEmitter<Events>;
   readonly config: Config;
   readonly options: Options;
   constructor(config: Config, options: Options);
+  get events(): AsyncEventEmitter<KubbEvents>;
   getContext<TOptions extends PluginFactoryOptions>(plugin: Plugin<TOptions>): PluginContext<TOptions> & Record<string, any>;
   get plugins(): Array<Plugin>;
   getFile<TOptions = object>({
@@ -432,10 +549,6 @@ declare class PluginManager {
   }>;
   resolvePath: <TOptions = object>(params: ResolvePathParams<TOptions>) => KubbFile.Path;
   resolveName: (params: ResolveNameParams) => string;
-  /**
-   * Instead of calling `pluginManager.events.on` you can use `pluginManager.on`. This one also has better types.
-   */
-  on<TEventName extends keyof Events & string>(eventName: TEventName, handler: (...eventArg: Events[TEventName]) => void): void;
   /**
    * Run a specific hookName for plugin x.
    */