@kubb/core 4.36.1 → 5.0.0-alpha.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "4.36.1",
+  "version": "5.0.0-alpha.10",
   "description": "Core functionality for Kubb's plugin-based code generation system, providing the foundation for transforming OpenAPI specifications.",
   "keywords": [
     "typescript",
@@ -64,14 +64,14 @@
     }
   ],
   "dependencies": {
-    "@kubb/fabric-core": "0.13.3",
-    "@kubb/react-fabric": "0.13.3",
+    "@kubb/fabric-core": "0.14.0",
+    "@kubb/react-fabric": "0.14.0",
     "empathic": "^2.0.0",
     "fflate": "^0.8.2",
     "remeda": "^2.33.6",
     "semver": "^7.7.4",
     "tinyexec": "^1.0.4",
-    "@kubb/ast": "4.36.1"
+    "@kubb/ast": "5.0.0-alpha.10"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",
@@ -79,11 +79,11 @@
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/fabric-core": "0.13.3",
-    "@kubb/react-fabric": "0.13.3"
+    "@kubb/fabric-core": "0.14.0",
+    "@kubb/react-fabric": "0.14.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public",

package/src/Kubb.ts

@@ -1,36 +1,32 @@
 import type { KubbFile } from '@kubb/fabric-core/types'
-import type { Strategy } from './PluginManager.ts'
+import type { Strategy } from './PluginDriver.ts'
 import type { Config, Plugin, PluginLifecycleHooks } from './types'
 
-type DebugEvent = {
+type DebugInfo = {
   date: Date
-  logs: string[]
+  logs: Array<string>
   fileName?: string
 }
 
-type ProgressStartMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
+type HookProgress<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
   hookName: H
   plugins: Array<Plugin>
 }
 
-type ProgressStopMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
-  hookName: H
-}
-
-type ExecutingMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
+type HookExecution<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
   strategy: Strategy
   hookName: H
   plugin: Plugin
-  parameters?: unknown[] | undefined
+  parameters?: Array<unknown>
   output?: unknown
 }
 
-type ExecutedMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
+type HookResult<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
   duration: number
   strategy: Strategy
   hookName: H
   plugin: Plugin
-  parameters?: unknown[] | undefined
+  parameters?: Array<unknown>
   output?: unknown
 }
 
@@ -40,7 +36,7 @@ type ExecutedMeta<H extends PluginLifecycleHooks = PluginLifecycleHooks> = {
  *
  * @example
  * ```typescript
- * import type { AsyncEventEmitter } from '@kubb/core'
+ * import type { AsyncEventEmitter } from '@internals/utils'
  * import type { KubbEvents } from '@kubb/core'
  *
  * const events: AsyncEventEmitter<KubbEvents> = new AsyncEventEmitter()
@@ -59,7 +55,6 @@ export interface KubbEvents {
    * Emitted at the beginning of the Kubb lifecycle, before any code generation starts.
    */
   'lifecycle:start': [version: string]
-
   /**
    * Emitted at the end of the Kubb lifecycle, after all code generation is complete.
    */
@@ -69,7 +64,6 @@ export interface KubbEvents {
    * Emitted when configuration loading starts.
    */
   'config:start': []
-
   /**
    * Emitted when configuration loading is complete.
    */
@@ -79,24 +73,22 @@ export interface KubbEvents {
    * Emitted when code generation phase starts.
    */
   'generation:start': [config: Config]
-
   /**
    * Emitted when code generation phase completes.
    */
-  'generation:end': [Config: Config, files: Array<KubbFile.ResolvedFile>, sources: Map<KubbFile.Path, string>]
-
+  'generation:end': [config: Config, files: Array<KubbFile.ResolvedFile>, sources: Map<KubbFile.Path, string>]
   /**
    * Emitted with a summary of the generation results.
    * Contains summary lines, title, and success status.
    */
   'generation:summary': [
-    Config: Config,
+    config: Config,
     {
       failedPlugins: Set<{ plugin: Plugin; error: Error }>
       status: 'success' | 'failed'
       hrStart: [number, number]
       filesCreated: number
-      pluginTimings?: Map<string, number>
+      pluginTimings?: Map<Plugin['name'], number>
     },
   ]
 
@@ -104,7 +96,6 @@ export interface KubbEvents {
    * Emitted when code formatting starts (e.g., running Biome or Prettier).
    */
   'format:start': []
-
   /**
    * Emitted when code formatting completes.
    */
@@ -114,7 +105,6 @@ export interface KubbEvents {
    * Emitted when linting starts.
    */
   'lint:start': []
-
   /**
    * Emitted when linting completes.
    */
@@ -124,29 +114,20 @@ export interface KubbEvents {
    * Emitted when plugin hooks execution starts.
    */
   'hooks:start': []
-
   /**
    * Emitted when plugin hooks execution completes.
    */
   'hooks:end': []
 
   /**
-   * Emitted when a single hook execution starts. (e.g., format or lint).
+   * 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[] }]
   /**
    * Emitted when a single hook execution completes.
    */
-  'hook:end': [
-    {
-      id?: string
-      command: string
-      args?: readonly string[]
-      success: boolean
-      error: Error | null
-    },
-  ]
+  'hook:end': [{ id?: string; command: string; args?: readonly string[]; success: boolean; error: Error | null }]
 
   /**
    * Emitted when a new version of Kubb is available.
@@ -157,49 +138,44 @@ export interface KubbEvents {
    * 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]
+  debug: [info: DebugInfo]
 
   /**
    * 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 */
+      /** Number of files processed so far. */
       processed: number
-      /** Total number of files to process */
+      /** Total number of files to process. */
       total: number
-      /** Processing percentage (0-100) */
+      /** Processing percentage (0–100). */
       percentage: number
-      /** Optional source identifier */
+      /** Optional source identifier. */
       source?: string
-      /** The file being processed */
+      /** The file being processed. */
       file: KubbFile.ResolvedFile
       /**
        * Kubb configuration (not present in Fabric).
@@ -208,45 +184,41 @@ export interface KubbEvents {
       config: Config
     },
   ]
-
   /**
    * Emitted when file processing completes.
    * Contains the list of processed files.
    */
-  'files:processing:end': [files: KubbFile.ResolvedFile[]]
+  'files:processing:end': [files: Array<KubbFile.ResolvedFile>]
 
   /**
    * Emitted when a plugin starts executing.
    */
   'plugin:start': [plugin: Plugin]
-
   /**
    * Emitted when a plugin completes execution.
-   * Duration in ms
+   * Duration in ms.
    */
-  'plugin:end': [plugin: Plugin, meta: { duration: number; success: boolean; error?: Error }]
+  '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': [meta: ProgressStartMeta]
-
+  'plugins:hook:progress:start': [progress: HookProgress]
   /**
    * Emitted when plugin hook progress tracking ends.
    * Contains the hook name that completed.
    */
-  'plugins:hook:progress:end': [meta: ProgressStopMeta]
+  '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': [meta: ExecutingMeta]
-
+  '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': [meta: ExecutedMeta]
+  'plugins:hook:processing:end': [result: HookResult]
 }

package/src/{PluginManager.ts → PluginDriver.ts}

@@ -1,15 +1,14 @@
-import path from 'node:path'
+import { basename, extname, resolve } from 'node:path'
 import { performance } from 'node:perf_hooks'
 import type { AsyncEventEmitter } from '@internals/utils'
-import { setUniqueName, transformReservedWord } from '@internals/utils'
+import { isPromiseRejectedResult, setUniqueName, transformReservedWord, ValidationPluginError } from '@internals/utils'
 import type { RootNode } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { Fabric } from '@kubb/react-fabric'
+import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
 import { CORE_PLUGIN_NAME, DEFAULT_STUDIO_URL } from './constants.ts'
 import { openInStudio as openInStudioFn } from './devtools.ts'
-import { ValidationPluginError } from './errors.ts'
-import { isPromiseRejectedResult, PromiseManager } from './PromiseManager.ts'
+
 import type {
+  Adapter,
   Config,
   DevtoolsOptions,
   KubbEvents,
@@ -24,6 +23,7 @@ import type {
   ResolvePathParams,
   UserPlugin,
 } from './types.ts'
+import { hookFirst, hookParallel, hookSeq } from './utils/executeStrategies.ts'
 
 type RequiredPluginLifecycle = Required<PluginLifecycle>
 
@@ -39,7 +39,7 @@ type SafeParseResult<H extends PluginLifecycleHooks, Result = ReturnType<ParseRe
 // inspired by: https://github.com/rollup/rollup/blob/master/src/utils/PluginDriver.ts#
 
 type Options = {
-  fabric: Fabric
+  fabric: FabricType
   events: AsyncEventEmitter<KubbEvents>
   /**
    * @default Number.POSITIVE_INFINITY
@@ -47,11 +47,11 @@ type Options = {
   concurrency?: number
 }
 
-type GetFileProps<TOptions = object> = {
+export type GetFileOptions<TOptions = object> = {
   name: string
   mode?: KubbFile.Mode
   extname: KubbFile.Extname
-  pluginKey: Plugin['key']
+  pluginName: string
   options?: TOptions
 }
 
@@ -59,10 +59,12 @@ export function getMode(fileOrFolder: string | undefined | null): KubbFile.Mode
   if (!fileOrFolder) {
     return 'split'
   }
-  return path.extname(fileOrFolder) ? 'single' : 'split'
+  return extname(fileOrFolder) ? 'single' : 'split'
 }
 
-export class PluginManager {
+const hookFirstNullCheck = (state: unknown) => !!(state as SafeParseResult<'resolveName'> | null)?.result
+
+export class PluginDriver {
   readonly config: Config
   readonly options: Options
 
@@ -71,18 +73,15 @@ export class PluginManager {
    * the build pipeline after the adapter's `parse()` resolves.
    */
   rootNode: RootNode | undefined = undefined
+  adapter: Adapter | undefined = undefined
   #studioIsOpen = false
 
   readonly #plugins = new Set<Plugin>()
   readonly #usedPluginNames: Record<string, number> = {}
-  readonly #promiseManager
 
   constructor(config: Config, options: Options) {
     this.config = config
     this.options = options
-    this.#promiseManager = new PromiseManager({
-      nullCheck: (state: SafeParseResult<'resolveName'> | null) => !!state?.result,
-    })
     ;[...(config.plugins || [])].forEach((plugin) => {
       const parsedPlugin = this.#parse(plugin as UserPlugin)
 
@@ -96,15 +95,15 @@ export class PluginManager {
 
   getContext<TOptions extends PluginFactoryOptions>(plugin: Plugin<TOptions>): PluginContext<TOptions> & Record<string, unknown> {
     const plugins = [...this.#plugins]
-    const pluginManager = this
+    const driver = this
 
     const baseContext = {
       fabric: this.options.fabric,
       config: this.config,
       plugin,
       events: this.options.events,
-      pluginManager: this,
-      mode: getMode(path.resolve(this.config.root, this.config.output.path)),
+      driver: this,
+      mode: getMode(resolve(this.config.root, this.config.output.path)),
       addFile: async (...files: Array<KubbFile.File>) => {
         await this.options.fabric.addFile(...files)
       },
@@ -112,26 +111,29 @@ export class PluginManager {
         await this.options.fabric.upsertFile(...files)
       },
       get rootNode(): RootNode | undefined {
-        return pluginManager.rootNode
+        return driver.rootNode
+      },
+      get adapter(): Adapter | undefined {
+        return driver.adapter
       },
       openInStudio(options?: DevtoolsOptions) {
-        if (typeof pluginManager.config.devtools !== 'object') {
-          throw new Error('Devtools must be an object')
+        if (!driver.config.devtools || driver.#studioIsOpen) {
+          return
         }
 
-        if (!pluginManager.rootNode) {
-          throw new Error('RootNode is not defined, make sure you have set the parser in kubb.config.ts')
+        if (typeof driver.config.devtools !== 'object') {
+          throw new Error('Devtools must be an object')
         }
 
-        if (pluginManager.#studioIsOpen) {
-          return
+        if (!driver.rootNode || !driver.adapter) {
+          throw new Error('adapter is not defined, make sure you have set the parser in kubb.config.ts')
         }
 
-        pluginManager.#studioIsOpen = true
+        driver.#studioIsOpen = true
 
-        const studioUrl = pluginManager.config.devtools?.studioUrl ?? DEFAULT_STUDIO_URL
+        const studioUrl = driver.config.devtools?.studioUrl ?? DEFAULT_STUDIO_URL
 
-        return openInStudioFn(pluginManager.rootNode, studioUrl, options)
+        return openInStudioFn(driver.rootNode, studioUrl, options)
       },
     } as unknown as PluginContext<TOptions>
 
@@ -158,19 +160,25 @@ export class PluginManager {
     return this.#getSortedPlugins()
   }
 
-  getFile<TOptions = object>({ name, mode, extname, pluginKey, options }: GetFileProps<TOptions>): KubbFile.File<{ pluginKey: Plugin['key'] }> {
-    const baseName = `${name}${extname}` as const
-    const path = this.resolvePath({ baseName, mode, pluginKey, options })
+  getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileOptions<TOptions>): KubbFile.File<{ pluginName: string }> {
+    const resolvedName = mode ? (mode === 'single' ? '' : this.resolveName({ name, pluginName, type: 'file' })) : name
+
+    const path = this.resolvePath({
+      baseName: `${resolvedName}${extname}` as const,
+      mode,
+      pluginName,
+      options,
+    })
 
     if (!path) {
-      throw new Error(`Filepath should be defined for resolvedName "${name}" and pluginKey [${JSON.stringify(pluginKey)}]`)
+      throw new Error(`Filepath should be defined for resolvedName "${resolvedName}" and pluginName "${pluginName}"`)
     }
 
     return {
       path,
-      baseName,
+      baseName: basename(path) as KubbFile.File['baseName'],
       meta: {
-        pluginKey,
+        pluginName,
       },
       sources: [],
       imports: [],
@@ -179,12 +187,12 @@ export class PluginManager {
   }
 
   resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): KubbFile.Path => {
-    const root = path.resolve(this.config.root, this.config.output.path)
-    const defaultPath = path.resolve(root, params.baseName)
+    const root = resolve(this.config.root, this.config.output.path)
+    const defaultPath = resolve(root, params.baseName)
 
-    if (params.pluginKey) {
+    if (params.pluginName) {
       const paths = this.hookForPluginSync({
-        pluginKey: params.pluginKey,
+        pluginName: params.pluginName,
         hookName: 'resolvePath',
         parameters: [params.baseName, params.mode, params.options as object],
       })
@@ -201,9 +209,9 @@ export class PluginManager {
   }
   //TODO refactor by using the order of plugins and the cache of the fileManager instead of guessing and recreating the name/path
   resolveName = (params: ResolveNameParams): string => {
-    if (params.pluginKey) {
+    if (params.pluginName) {
       const names = this.hookForPluginSync({
-        pluginKey: params.pluginKey,
+        pluginName: params.pluginName,
         hookName: 'resolveName',
         parameters: [params.name.trim(), params.type],
       })
@@ -225,15 +233,15 @@ export class PluginManager {
    * Run a specific hookName for plugin x.
    */
   async hookForPlugin<H extends PluginLifecycleHooks>({
-    pluginKey,
+    pluginName,
     hookName,
     parameters,
   }: {
-    pluginKey: Plugin['key']
+    pluginName: string
     hookName: H
     parameters: PluginParameter<H>
   }): Promise<Array<ReturnType<ParseResult<H>> | null>> {
-    const plugins = this.getPluginsByKey(hookName, pluginKey)
+    const plugins = this.getPluginsByName(hookName, pluginName)
 
     this.events.emit('plugins:hook:progress:start', {
       hookName,
@@ -264,15 +272,15 @@ export class PluginManager {
    */
 
   hookForPluginSync<H extends PluginLifecycleHooks>({
-    pluginKey,
+    pluginName,
     hookName,
     parameters,
   }: {
-    pluginKey: Plugin['key']
+    pluginName: string
     hookName: H
     parameters: PluginParameter<H>
   }): Array<ReturnType<ParseResult<H>>> | null {
-    const plugins = this.getPluginsByKey(hookName, pluginKey)
+    const plugins = this.getPluginsByName(hookName, pluginName)
 
     const result = plugins
       .map((plugin) => {
@@ -322,7 +330,7 @@ export class PluginManager {
       }
     })
 
-    const result = await this.#promiseManager.run('first', promises)
+    const result = await hookFirst(promises, hookFirstNullCheck)
 
     this.events.emit('plugins:hook:progress:end', { hookName })
 
@@ -392,9 +400,7 @@ export class PluginManager {
       }
     })
 
-    const results = await this.#promiseManager.run('parallel', promises, {
-      concurrency: this.options.concurrency,
-    })
+    const results = await hookParallel(promises, this.options.concurrency)
 
     results.forEach((result, index) => {
       if (isPromiseRejectedResult<Error>(result)) {
@@ -440,7 +446,7 @@ export class PluginManager {
         })
     })
 
-    await this.#promiseManager.run('seq', promises)
+    await hookSeq(promises)
 
     this.events.emit('plugins:hook:progress:end', { hookName })
   }
@@ -456,7 +462,12 @@ export class PluginManager {
     return plugins
       .map((plugin) => {
         if (plugin.pre) {
-          const missingPlugins = plugin.pre.filter((pluginName) => !plugins.find((pluginToFind) => pluginToFind.name === pluginName))
+          let missingPlugins = plugin.pre.filter((pluginName) => !plugins.find((pluginToFind) => pluginToFind.name === pluginName))
+
+          // when adapter is set, we can ignore the depends on plugin-oas, in v5 this will not be needed anymore
+          if (missingPlugins.includes('plugin-oas') && this.adapter) {
+            missingPlugins = missingPlugins.filter((pluginName) => pluginName !== 'plugin-oas')
+          }
 
           if (missingPlugins.length > 0) {
             throw new ValidationPluginError(`The plugin '${plugin.name}' has a pre set that references missing plugins for '${missingPlugins.join(', ')}'`)
@@ -476,41 +487,21 @@ export class PluginManager {
       })
   }
 
-  getPluginByKey(pluginKey: Plugin['key']): Plugin | undefined {
+  getPluginByName(pluginName: string): Plugin | undefined {
     const plugins = [...this.#plugins]
-    const [searchPluginName] = pluginKey
 
-    return plugins.find((item) => {
-      const [name] = item.key
-
-      return name === searchPluginName
-    })
+    return plugins.find((item) => item.name === pluginName)
   }
 
-  getPluginsByKey(hookName: keyof PluginWithLifeCycle, pluginKey: Plugin['key']): Plugin[] {
+  getPluginsByName(hookName: keyof PluginWithLifeCycle, pluginName: string): Plugin[] {
     const plugins = [...this.plugins]
-    const [searchPluginName, searchIdentifier] = pluginKey
 
-    const pluginByPluginName = plugins
-      .filter((plugin) => hookName in plugin)
-      .filter((item) => {
-        const [name, identifier] = item.key
-
-        const identifierCheck = identifier?.toString() === searchIdentifier?.toString()
-        const nameCheck = name === searchPluginName
-
-        if (searchIdentifier) {
-          return identifierCheck && nameCheck
-        }
-
-        return nameCheck
-      })
+    const pluginByPluginName = plugins.filter((plugin) => hookName in plugin).filter((item) => item.name === pluginName)
 
     if (!pluginByPluginName?.length) {
       // fallback on the core plugin when there is no match
 
       const corePlugin = plugins.find((plugin) => plugin.name === CORE_PLUGIN_NAME && hookName in plugin)
-      // Removed noisy debug logs for missing hooks - these are expected behavior, not errors
 
       return corePlugin ? [corePlugin] : []
     }
@@ -657,20 +648,16 @@ export class PluginManager {
 
     setUniqueName(plugin.name, usedPluginNames)
 
-    // Emit warning if this is a duplicate plugin (will be removed in v5)
     const usageCount = usedPluginNames[plugin.name]
     if (usageCount && usageCount > 1) {
-      this.events.emit(
-        'warn',
-        `Multiple instances of plugin "${plugin.name}" detected. This behavior is deprecated and will be removed in v5.`,
-        `Plugin key: [${plugin.name}, ${usageCount}]`,
+      throw new ValidationPluginError(
+        `Duplicate plugin "${plugin.name}" detected. Each plugin can only be used once. Use a different configuration instead of adding multiple instances of the same plugin.`,
       )
     }
 
     return {
       install() {},
       ...plugin,
-      key: [plugin.name, usedPluginNames[plugin.name]].filter(Boolean) as [typeof plugin.name, string],
     } as unknown as Plugin
   }
 }