@kubb/core 5.0.0-alpha.21 → 5.0.0-alpha.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "5.0.0-alpha.21",
+  "version": "5.0.0-alpha.23",
   "description": "Core functionality for Kubb's plugin-based code generation system, providing the foundation for transforming OpenAPI specifications.",
   "keywords": [
     "typescript",
@@ -71,7 +71,7 @@
     "remeda": "^2.33.6",
     "semver": "^7.7.4",
     "tinyexec": "^1.0.4",
-    "@kubb/ast": "5.0.0-alpha.21"
+    "@kubb/ast": "5.0.0-alpha.23"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/Kubb.ts

@@ -1,4 +1,4 @@
-import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
 import type { Strategy } from './PluginDriver.ts'
 import type { Config, Plugin, PluginLifecycleHooks } from './types'
 
@@ -76,7 +76,7 @@ export interface KubbEvents {
   /**
    * 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<FabricFile.ResolvedFile>, sources: Map<FabricFile.Path, string>]
   /**
    * Emitted with a summary of the generation results.
    * Contains summary lines, title, and success status.
@@ -160,7 +160,7 @@ export interface KubbEvents {
    * Emitted when file processing starts.
    * Contains the list of files to be processed.
    */
-  'files:processing:start': [files: Array<KubbFile.ResolvedFile>]
+  'files:processing:start': [files: Array<FabricFile.ResolvedFile>]
   /**
    * Emitted for each file being processed, providing progress updates.
    * Contains processed count, total count, percentage, and file details.
@@ -186,7 +186,7 @@ export interface KubbEvents {
       /**
        * The file being processed.
        */
-      file: KubbFile.ResolvedFile
+      file: FabricFile.ResolvedFile
       /**
        * Kubb configuration (not present in Fabric).
        * Provides access to the current config during file processing.
@@ -198,7 +198,7 @@ export interface KubbEvents {
    * Emitted when file processing completes.
    * Contains the list of processed files.
    */
-  'files:processing:end': [files: Array<KubbFile.ResolvedFile>]
+  'files:processing:end': [files: Array<FabricFile.ResolvedFile>]
 
   /**
    * Emitted when a plugin starts executing.

package/src/PluginDriver.ts

@@ -1,10 +1,10 @@
 import { basename, extname, resolve } from 'node:path'
 import { performance } from 'node:perf_hooks'
 import type { AsyncEventEmitter } from '@internals/utils'
-import { isPromiseRejectedResult, setUniqueName, transformReservedWord, ValidationPluginError } from '@internals/utils'
+import { isPromiseRejectedResult, transformReservedWord } from '@internals/utils'
 import type { RootNode } from '@kubb/ast/types'
-import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
-import { CORE_PLUGIN_NAME, DEFAULT_STUDIO_URL } from './constants.ts'
+import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
+import { DEFAULT_STUDIO_URL } from './constants.ts'
 import { openInStudio as openInStudioFn } from './devtools.ts'
 
 import type {
@@ -21,12 +21,19 @@ import type {
   PluginWithLifeCycle,
   ResolveNameParams,
   ResolvePathParams,
-  UserPlugin,
 } from './types.ts'
 import { hookFirst, hookParallel, hookSeq } from './utils/executeStrategies.ts'
 
 type RequiredPluginLifecycle = Required<PluginLifecycle>
 
+/**
+ * Hook dispatch strategy used by the `PluginDriver`.
+ *
+ * - `hookFirst` — stops at the first non-null result.
+ * - `hookForPlugin` — calls only the matching plugin.
+ * - `hookParallel` — calls all plugins concurrently.
+ * - `hookSeq` — calls all plugins in order, threading the result.
+ */
 export type Strategy = 'hookFirst' | 'hookForPlugin' | 'hookParallel' | 'hookSeq'
 
 type ParseResult<H extends PluginLifecycleHooks> = RequiredPluginLifecycle[H]
@@ -47,15 +54,27 @@ type Options = {
   concurrency?: number
 }
 
+/**
+ * Parameters accepted by `PluginDriver.getFile` to resolve a generated file descriptor.
+ */
 export type GetFileOptions<TOptions = object> = {
   name: string
-  mode?: KubbFile.Mode
-  extname: KubbFile.Extname
+  mode?: FabricFile.Mode
+  extname: FabricFile.Extname
   pluginName: string
   options?: TOptions
 }
 
-export function getMode(fileOrFolder: string | undefined | null): KubbFile.Mode {
+/**
+ * Returns `'single'` when `fileOrFolder` has a file extension, `'split'` otherwise.
+ *
+ * @example
+ * ```ts
+ * getMode('src/gen/types.ts')  // 'single'
+ * getMode('src/gen/types')     // 'split'
+ * ```
+ */
+export function getMode(fileOrFolder: string | undefined | null): FabricFile.Mode {
   if (!fileOrFolder) {
     return 'split'
   }
@@ -76,17 +95,21 @@ export class PluginDriver {
   adapter: Adapter | undefined = undefined
   #studioIsOpen = false
 
-  readonly #plugins = new Set<Plugin>()
-  readonly #usedPluginNames: Record<string, number> = {}
+  readonly plugins = new Map<string, Plugin>()
 
   constructor(config: Config, options: Options) {
     this.config = config
     this.options = options
-    ;[...(config.plugins || [])].forEach((plugin) => {
-      const parsedPlugin = this.#parse(plugin as UserPlugin)
-
-      this.#plugins.add(parsedPlugin)
-    })
+    config.plugins
+      .map((plugin) => Object.assign({ install() {} }, plugin) as unknown as Plugin)
+      .sort((a, b) => {
+        if (b.pre?.includes(a.name)) return 1
+        if (b.post?.includes(a.name)) return -1
+        return 0
+      })
+      .forEach((plugin) => {
+        this.plugins.set(plugin.name, plugin)
+      })
   }
 
   get events() {
@@ -94,20 +117,19 @@ export class PluginDriver {
   }
 
   getContext<TOptions extends PluginFactoryOptions>(plugin: Plugin<TOptions>): PluginContext<TOptions> & Record<string, unknown> {
-    const plugins = [...this.#plugins]
     const driver = this
 
     const baseContext = {
-      fabric: this.options.fabric,
-      config: this.config,
+      fabric: driver.options.fabric,
+      config: driver.config,
       plugin,
-      events: this.options.events,
-      driver: this,
-      mode: getMode(resolve(this.config.root, this.config.output.path)),
-      addFile: async (...files: Array<KubbFile.File>) => {
+      getPlugin: driver.getPlugin.bind(driver),
+      events: driver.options.events,
+      driver: driver,
+      addFile: async (...files: Array<FabricFile.File>) => {
         await this.options.fabric.addFile(...files)
       },
-      upsertFile: async (...files: Array<KubbFile.File>) => {
+      upsertFile: async (...files: Array<FabricFile.File>) => {
         await this.options.fabric.upsertFile(...files)
       },
       get rootNode(): RootNode | undefined {
@@ -116,6 +138,9 @@ export class PluginDriver {
       get adapter(): Adapter | undefined {
         return driver.adapter
       },
+      get resolver() {
+        return plugin.resolver
+      },
       openInStudio(options?: DevtoolsOptions) {
         if (!driver.config.devtools || driver.#studioIsOpen) {
           return
@@ -138,9 +163,10 @@ export class PluginDriver {
     } as unknown as PluginContext<TOptions>
 
     const mergedExtras: Record<string, unknown> = {}
-    for (const p of plugins) {
-      if (typeof p.inject === 'function') {
-        const result = (p.inject as (this: PluginContext, context: PluginContext) => unknown).call(
+
+    for (const plugin of this.plugins.values()) {
+      if (typeof plugin.inject === 'function') {
+        const result = (plugin.inject as (this: PluginContext, context: PluginContext) => unknown).call(
           baseContext as unknown as PluginContext,
           baseContext as unknown as PluginContext,
         )
@@ -155,12 +181,10 @@ export class PluginDriver {
       ...mergedExtras,
     }
   }
-
-  get plugins(): Array<Plugin> {
-    return this.#getSortedPlugins()
-  }
-
-  getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileOptions<TOptions>): KubbFile.File<{ pluginName: string }> {
+  /**
+   * @deprecated use resolvers context instead
+   */
+  getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileOptions<TOptions>): FabricFile.File<{ pluginName: string }> {
     const resolvedName = mode ? (mode === 'single' ? '' : this.resolveName({ name, pluginName, type: 'file' })) : name
 
     const path = this.resolvePath({
@@ -176,7 +200,7 @@ export class PluginDriver {
 
     return {
       path,
-      baseName: basename(path) as KubbFile.File['baseName'],
+      baseName: basename(path) as FabricFile.File['baseName'],
       meta: {
         pluginName,
       },
@@ -186,7 +210,10 @@ export class PluginDriver {
     }
   }
 
-  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): KubbFile.Path => {
+  /**
+   * @deprecated use resolvers context instead
+   */
+  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): FabricFile.Path => {
     const root = resolve(this.config.root, this.config.output.path)
     const defaultPath = resolve(root, params.baseName)
 
@@ -207,7 +234,9 @@ export class PluginDriver {
 
     return firstResult?.result || defaultPath
   }
-  //TODO refactor by using the order of plugins and the cache of the fileManager instead of guessing and recreating the name/path
+  /**
+   * @deprecated use resolvers context instead
+   */
   resolveName = (params: ResolveNameParams): string => {
     if (params.pluginName) {
       const names = this.hookForPluginSync({
@@ -216,9 +245,7 @@ export class PluginDriver {
         parameters: [params.name.trim(), params.type],
       })
 
-      const uniqueNames = new Set(names)
-
-      return transformReservedWord([...uniqueNames].at(0) || params.name)
+      return transformReservedWord(names?.at(0) ?? params.name)
     }
 
     const name = this.hookFirstSync({
@@ -241,36 +268,32 @@ export class PluginDriver {
     hookName: H
     parameters: PluginParameter<H>
   }): Promise<Array<ReturnType<ParseResult<H>> | null>> {
-    const plugins = this.getPluginsByName(hookName, pluginName)
+    const plugin = this.plugins.get(pluginName)
+
+    if (!plugin) {
+      return [null]
+    }
 
     this.events.emit('plugins:hook:progress:start', {
       hookName,
-      plugins,
+      plugins: [plugin],
     })
 
-    const items: Array<ReturnType<ParseResult<H>>> = []
-
-    for (const plugin of plugins) {
-      const result = await this.#execute<H>({
-        strategy: 'hookFirst',
-        hookName,
-        parameters,
-        plugin,
-      })
-
-      if (result !== undefined && result !== null) {
-        items.push(result)
-      }
-    }
+    const result = await this.#execute<H>({
+      strategy: 'hookFirst',
+      hookName,
+      parameters,
+      plugin,
+    })
 
     this.events.emit('plugins:hook:progress:end', { hookName })
 
-    return items
+    return [result]
   }
+
   /**
    * Run a specific hookName for plugin x.
    */
-
   hookForPluginSync<H extends PluginLifecycleHooks>({
     pluginName,
     hookName,
@@ -280,20 +303,20 @@ export class PluginDriver {
     hookName: H
     parameters: PluginParameter<H>
   }): Array<ReturnType<ParseResult<H>>> | null {
-    const plugins = this.getPluginsByName(hookName, pluginName)
+    const plugin = this.plugins.get(pluginName)
 
-    const result = plugins
-      .map((plugin) => {
-        return this.#executeSync<H>({
-          strategy: 'hookFirst',
-          hookName,
-          parameters,
-          plugin,
-        })
-      })
-      .filter((x): x is NonNullable<typeof x> => x !== null)
+    if (!plugin) {
+      return null
+    }
 
-    return result
+    const result = this.#executeSync<H>({
+      strategy: 'hookFirst',
+      hookName,
+      parameters,
+      plugin,
+    })
+
+    return result !== null ? [result] : []
   }
 
   /**
@@ -308,9 +331,10 @@ export class PluginDriver {
     parameters: PluginParameter<H>
     skipped?: ReadonlySet<Plugin> | null
   }): Promise<SafeParseResult<H>> {
-    const plugins = this.#getSortedPlugins(hookName).filter((plugin) => {
-      return skipped ? !skipped.has(plugin) : true
-    })
+    const plugins: Array<Plugin> = []
+    for (const plugin of this.plugins.values()) {
+      if (hookName in plugin && (skipped ? !skipped.has(plugin) : true)) plugins.push(plugin)
+    }
 
     this.events.emit('plugins:hook:progress:start', { hookName, plugins })
 
@@ -350,11 +374,11 @@ export class PluginDriver {
     skipped?: ReadonlySet<Plugin> | null
   }): SafeParseResult<H> | null {
     let parseResult: SafeParseResult<H> | null = null
-    const plugins = this.#getSortedPlugins(hookName).filter((plugin) => {
-      return skipped ? !skipped.has(plugin) : true
-    })
 
-    for (const plugin of plugins) {
+    for (const plugin of this.plugins.values()) {
+      if (!(hookName in plugin)) continue
+      if (skipped?.has(plugin)) continue
+
       parseResult = {
         result: this.#executeSync<H>({
           strategy: 'hookFirst',
@@ -365,9 +389,7 @@ export class PluginDriver {
         plugin,
       } as SafeParseResult<H>
 
-      if (parseResult?.result != null) {
-        break
-      }
+      if (parseResult.result != null) break
     }
 
     return parseResult
@@ -383,7 +405,10 @@ export class PluginDriver {
     hookName: H
     parameters?: Parameters<RequiredPluginLifecycle[H]> | undefined
   }): Promise<Awaited<TOutput>[]> {
-    const plugins = this.#getSortedPlugins(hookName)
+    const plugins: Array<Plugin> = []
+    for (const plugin of this.plugins.values()) {
+      if (hookName in plugin) plugins.push(plugin)
+    }
     this.events.emit('plugins:hook:progress:start', { hookName, plugins })
 
     const pluginStartTimes = new Map<Plugin, number>()
@@ -404,7 +429,7 @@ export class PluginDriver {
 
     results.forEach((result, index) => {
       if (isPromiseRejectedResult<Error>(result)) {
-        const plugin = this.#getSortedPlugins(hookName)[index]
+        const plugin = plugins[index]
 
         if (plugin) {
           const startTime = pluginStartTimes.get(plugin) ?? performance.now()
@@ -433,7 +458,10 @@ export class PluginDriver {
    * Chains plugins
    */
   async hookSeq<H extends PluginLifecycleHooks>({ hookName, parameters }: { hookName: H; parameters?: PluginParameter<H> }): Promise<void> {
-    const plugins = this.#getSortedPlugins(hookName)
+    const plugins: Array<Plugin> = []
+    for (const plugin of this.plugins.values()) {
+      if (hookName in plugin) plugins.push(plugin)
+    }
     this.events.emit('plugins:hook:progress:start', { hookName, plugins })
 
     const promises = plugins.map((plugin) => {
@@ -451,62 +479,8 @@ export class PluginDriver {
     this.events.emit('plugins:hook:progress:end', { hookName })
   }
 
-  #getSortedPlugins(hookName?: keyof PluginLifecycle): Array<Plugin> {
-    const plugins = [...this.#plugins]
-
-    if (hookName) {
-      return plugins.filter((plugin) => hookName in plugin)
-    }
-    // TODO add test case for sorting with pre/post
-
-    return plugins
-      .map((plugin) => {
-        if (plugin.pre) {
-          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(', ')}'`)
-          }
-        }
-
-        return plugin
-      })
-      .sort((a, b) => {
-        if (b.pre?.includes(a.name)) {
-          return 1
-        }
-        if (b.post?.includes(a.name)) {
-          return -1
-        }
-        return 0
-      })
-  }
-
-  getPluginByName(pluginName: string): Plugin | undefined {
-    const plugins = [...this.#plugins]
-
-    return plugins.find((item) => item.name === pluginName)
-  }
-
-  getPluginsByName(hookName: keyof PluginWithLifeCycle, pluginName: string): Plugin[] {
-    const plugins = [...this.plugins]
-
-    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)
-
-      return corePlugin ? [corePlugin] : []
-    }
-
-    return pluginByPluginName
+  getPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(pluginName: string): Plugin<TOptions> | undefined {
+    return this.plugins.get(pluginName) as Plugin<TOptions> | undefined
   }
 
   /**
@@ -642,22 +616,4 @@ export class PluginDriver {
       return null
     }
   }
-
-  #parse(plugin: UserPlugin): Plugin {
-    const usedPluginNames = this.#usedPluginNames
-
-    setUniqueName(plugin.name, usedPluginNames)
-
-    const usageCount = usedPluginNames[plugin.name]
-    if (usageCount && usageCount > 1) {
-      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,
-    } as unknown as Plugin
-  }
 }

package/src/build.ts

@@ -1,6 +1,6 @@
 import { dirname, relative, resolve } from 'node:path'
 import { AsyncEventEmitter, BuildError, exists, formatMs, getElapsedMs, getRelativePath, URLPath } from '@internals/utils'
-import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
 import { createFabric } from '@kubb/react-fabric'
 import { typescriptParser } from '@kubb/react-fabric/parsers'
 import { fsPlugin } from '@kubb/react-fabric/plugins'
@@ -26,7 +26,7 @@ type BuildOutput = {
    */
   failedPlugins: Set<{ plugin: Plugin; error: Error }>
   fabric: FabricType
-  files: Array<KubbFile.ResolvedFile>
+  files: Array<FabricFile.ResolvedFile>
   driver: PluginDriver
   /**
    * Elapsed time in milliseconds for each plugin, keyed by plugin name.
@@ -36,7 +36,7 @@ type BuildOutput = {
   /**
    * Raw generated source, keyed by absolute file path.
    */
-  sources: Map<KubbFile.Path, string>
+  sources: Map<FabricFile.Path, string>
 }
 
 /**
@@ -46,7 +46,7 @@ type SetupResult = {
   events: AsyncEventEmitter<KubbEvents>
   fabric: FabricType
   driver: PluginDriver
-  sources: Map<KubbFile.Path, string>
+  sources: Map<FabricFile.Path, string>
 }
 
 /**
@@ -63,7 +63,7 @@ type SetupResult = {
 export async function setup(options: BuildOptions): Promise<SetupResult> {
   const { config: userConfig, events = new AsyncEventEmitter<KubbEvents>() } = options
 
-  const sources: Map<KubbFile.Path, string> = new Map<KubbFile.Path, string>()
+  const sources: Map<FabricFile.Path, string> = new Map<FabricFile.Path, string>()
   const diagnosticInfo = getDiagnosticInfo()
 
   if (Array.isArray(userConfig.input)) {
@@ -274,7 +274,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
   const config = driver.config
 
   try {
-    for (const plugin of driver.plugins) {
+    for (const plugin of driver.plugins.values()) {
       const context = driver.getContext(plugin)
       const hrStart = process.hrtime()
 
@@ -351,7 +351,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
         existingBarrel?.exports?.flatMap((e) => (Array.isArray(e.name) ? e.name : [e.name])).filter((n): n is string => Boolean(n)) ?? [],
       )
 
-      const rootFile: KubbFile.File = {
+      const rootFile: FabricFile.File = {
         path: rootPath,
         baseName: BARREL_FILENAME,
         exports: buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }),
@@ -394,16 +394,16 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
 }
 
 type BuildBarrelExportsParams = {
-  barrelFiles: KubbFile.ResolvedFile[]
+  barrelFiles: FabricFile.ResolvedFile[]
   rootDir: string
   existingExports: Set<string>
   config: Config
   driver: PluginDriver
 }
 
-function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }: BuildBarrelExportsParams): KubbFile.Export[] {
+function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }: BuildBarrelExportsParams): FabricFile.Export[] {
   const pluginNameMap = new Map<string, Plugin>()
-  for (const plugin of driver.plugins) {
+  for (const plugin of driver.plugins.values()) {
     pluginNameMap.set(plugin.name, plugin)
   }
 
@@ -433,7 +433,7 @@ function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, dri
           name: exportName,
           path: getRelativePath(rootDir, file.path),
           isTypeOnly: config.output.barrelType === 'all' ? containsOnlyTypes : source.isTypeOnly,
-        } satisfies KubbFile.Export,
+        } satisfies FabricFile.Export,
       ]
     })
   })

package/src/constants.ts

@@ -1,20 +1,10 @@
-import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
 
 /**
  * Base URL for the Kubb Studio web app.
  */
 export const DEFAULT_STUDIO_URL = 'https://studio.kubb.dev' as const
 
-/**
- * Internal plugin name used to identify the core Kubb runtime.
- */
-export const CORE_PLUGIN_NAME = 'core' as const
-
-/**
- * Maximum number of event-emitter listeners before Node.js emits a warning.
- */
-export const DEFAULT_MAX_LISTENERS = 100
-
 /**
  * Default number of plugins that may run concurrently during a build.
  */
@@ -33,7 +23,7 @@ export const DEFAULT_BANNER = 'simple' as const
 /**
  * Default file-extension mapping used when no explicit mapping is configured.
  */
-export const DEFAULT_EXTENSION: Record<KubbFile.Extname, KubbFile.Extname | ''> = { '.ts': '.ts' }
+export const DEFAULT_EXTENSION: Record<FabricFile.Extname, FabricFile.Extname | ''> = { '.ts': '.ts' }
 
 /**
  * Characters recognized as path separators on both POSIX and Windows.