@kubb/core 5.0.0-alpha.20 → 5.0.0-alpha.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "5.0.0-alpha.20",
+  "version": "5.0.0-alpha.22",
   "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.20"
+    "@kubb/ast": "5.0.0-alpha.22"
   },
   "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

@@ -3,7 +3,7 @@ import { performance } from 'node:perf_hooks'
 import type { AsyncEventEmitter } from '@internals/utils'
 import { isPromiseRejectedResult, setUniqueName, transformReservedWord, ValidationPluginError } from '@internals/utils'
 import type { RootNode } from '@kubb/ast/types'
-import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
 import { CORE_PLUGIN_NAME, DEFAULT_STUDIO_URL } from './constants.ts'
 import { openInStudio as openInStudioFn } from './devtools.ts'
 
@@ -27,6 +27,14 @@ 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 +55,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'
   }
@@ -104,10 +124,10 @@ export class PluginDriver {
       events: this.options.events,
       driver: this,
       mode: getMode(resolve(this.config.root, this.config.output.path)),
-      addFile: async (...files: Array<KubbFile.File>) => {
+      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 {
@@ -160,7 +180,7 @@ export class PluginDriver {
     return this.#getSortedPlugins()
   }
 
-  getFile<TOptions = object>({ name, mode, extname, pluginName, options }: GetFileOptions<TOptions>): KubbFile.File<{ pluginName: string }> {
+  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 +196,7 @@ export class PluginDriver {
 
     return {
       path,
-      baseName: basename(path) as KubbFile.File['baseName'],
+      baseName: basename(path) as FabricFile.File['baseName'],
       meta: {
         pluginName,
       },
@@ -186,7 +206,7 @@ export class PluginDriver {
     }
   }
 
-  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): KubbFile.Path => {
+  resolvePath = <TOptions = object>(params: ResolvePathParams<TOptions>): FabricFile.Path => {
     const root = resolve(this.config.root, this.config.output.path)
     const defaultPath = resolve(root, params.baseName)
 

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)) {
@@ -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,14 +394,14 @@ 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) {
     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,4 +1,4 @@
-import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
 
 /**
  * Base URL for the Kubb Studio web app.
@@ -33,7 +33,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.

package/src/defineBuilder.ts

@@ -0,0 +1,26 @@
+import type { PluginFactoryOptions } from './types.ts'
+
+/**
+ * Builder type for the plugin-specific builder fields.
+ * `name` is required; all other methods are defined by the concrete plugin builder type.
+ */
+type BuilderBuilder<T extends PluginFactoryOptions> = () => T['builder'] & ThisType<T['builder']>
+
+/**
+ * Defines a builder for a plugin — a named collection of schema-building helpers that
+ * can be exported alongside the plugin and imported by other plugins or generators.
+ *
+ * @example
+ * export const builder = defineBuilder<PluginTs>(() => ({
+ *   name: 'default',
+ *   buildParamsSchema({ params, node, resolver }) {
+ *     return createSchema({ type: 'object', properties: [] })
+ *   },
+ *   buildDataSchemaNode({ node, resolver }) {
+ *     return createSchema({ type: 'object', properties: [] })
+ *   },
+ * }))
+ */
+export function defineBuilder<T extends PluginFactoryOptions>(build: BuilderBuilder<T>): T['builder'] {
+  return build() as T['builder']
+}

package/src/defineGenerator.ts

@@ -1,5 +1,5 @@
 import type { OperationNode, SchemaNode } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricFile } from '@kubb/fabric-core/types'
 import type { FabricReactNode } from '@kubb/react-fabric/types'
 import type { Adapter, Config, Plugin, PluginFactoryOptions } from './types.ts'
 
@@ -10,6 +10,7 @@ export type Version = '1' | '2'
  */
 export type OperationsV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
   config: Config
+  plugin: Plugin<TPlugin>
   adapter: Adapter
   options: Plugin<TPlugin>['options']
   nodes: Array<OperationNode>
@@ -21,6 +22,7 @@ export type OperationsV2Props<TPlugin extends PluginFactoryOptions = PluginFacto
 export type OperationV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
   config: Config
   adapter: Adapter
+  plugin: Plugin<TPlugin>
   options: Plugin<TPlugin>['options']
   node: OperationNode
 }
@@ -31,19 +33,26 @@ export type OperationV2Props<TPlugin extends PluginFactoryOptions = PluginFactor
 export type SchemaV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
   config: Config
   adapter: Adapter
+  plugin: Plugin<TPlugin>
   options: Plugin<TPlugin>['options']
   node: SchemaNode
 }
 
+/**
+ * Input shape for a core v2 async generator — lifecycle methods are optional.
+ */
 type UserCoreGeneratorV2<TPlugin extends PluginFactoryOptions> = {
   name: string
   type: 'core'
   version?: '2'
-  operations?(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  operation?(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  schema?(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>
+  operations?(props: OperationsV2Props<TPlugin>): Promise<Array<FabricFile.File>>
+  operation?(props: OperationV2Props<TPlugin>): Promise<Array<FabricFile.File>>
+  schema?(props: SchemaV2Props<TPlugin>): Promise<Array<FabricFile.File>>
 }
 
+/**
+ * Input shape for a React v2 generator — component methods are optional.
+ */
 type UserReactGeneratorV2<TPlugin extends PluginFactoryOptions> = {
   name: string
   type: 'react'
@@ -53,15 +62,21 @@ type UserReactGeneratorV2<TPlugin extends PluginFactoryOptions> = {
   Schema?(props: SchemaV2Props<TPlugin>): FabricReactNode
 }
 
+/**
+ * A fully resolved core v2 generator with `version: '2'` and guaranteed async lifecycle methods.
+ */
 export type CoreGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
   name: string
   type: 'core'
   version: '2'
-  operations(props: OperationsV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  operation(props: OperationV2Props<TPlugin>): Promise<Array<KubbFile.File>>
-  schema(props: SchemaV2Props<TPlugin>): Promise<Array<KubbFile.File>>
+  operations(props: OperationsV2Props<TPlugin>): Promise<Array<FabricFile.File>>
+  operation(props: OperationV2Props<TPlugin>): Promise<Array<FabricFile.File>>
+  schema(props: SchemaV2Props<TPlugin>): Promise<Array<FabricFile.File>>
 }
 
+/**
+ * A fully resolved React v2 generator with `version: '2'` and guaranteed component methods.
+ */
 export type ReactGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
   name: string
   type: 'react'
@@ -71,6 +86,9 @@ export type ReactGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactor
   Schema(props: SchemaV2Props<TPlugin>): FabricReactNode
 }
 
+/**
+ * Union of all v2 generator shapes accepted by the plugin system.
+ */
 export type Generator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>
 
 /**

package/src/definePreset.ts

@@ -1,9 +1,9 @@
 import type { Visitor } from '@kubb/ast/types'
-import type { Preset, Resolver } from './types.ts'
+import type { Generator, Preset, Resolver } from './types.ts'
 
 /**
- * Creates a typed preset object that bundles a name, resolvers, and optional
- * transformers — the building block for composable plugin presets.
+ * Creates a typed preset object that bundles a name, resolvers, optional
+ * transformers, and optional generators — the building block for composable plugin presets.
  *
  * @example
  * import { definePreset } from '@kubb/core'
@@ -14,10 +14,14 @@ import type { Preset, Resolver } from './types.ts'
  * @example
  * // With custom transformers
  * export const myPreset = definePreset('myPreset', { resolvers: [resolverTsLegacy], transformers: [myTransformer] })
+ *
+ * @example
+ * // With generators
+ * export const myPreset = definePreset('myPreset', { resolvers: [resolverTsLegacy], generators: [typeGeneratorLegacy] })
  */
 export function definePreset<TResolver extends Resolver = Resolver, TName extends string = string>(
   name: TName,
-  { resolvers, transformers }: { resolvers: Array<TResolver>; transformers?: Array<Visitor> },
+  { resolvers, transformers, generators }: { resolvers: Array<TResolver>; transformers?: Array<Visitor>; generators?: Array<Generator<any>> },
 ): Preset<TResolver> & { name: TName } {
-  return { name, resolvers, transformers }
+  return { name, resolvers, transformers, generators }
 }