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

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { t as __name } from "./chunk--u3MIqq1.js";
-import { A as ResolveOptionsContext, B as ReactGeneratorV2, C as PluginParameter, D as Printer, E as Presets, F as UserPlugin, G as formatters, H as KubbEvents, I as UserPluginWithLifeCycle, J as PossiblePromise, K as linters, L as UserResolver, M as Resolver, N as UserConfig, O as PrinterFactoryOptions, P as UserLogger, R as CoreGeneratorV2, S as PluginLifecycleHooks, T as Preset, U as Storage, V as defineGenerator, W as createStorage, Y as AsyncEventEmitter, _ as Output, a as AdapterFactoryOptions, b as PluginFactoryOptions, c as CompatibilityPreset, d as Group, f as InputData, g as LoggerOptions, h as LoggerContext, i as Adapter, j as ResolvePathParams, k as ResolveNameParams, l as Config, m as Logger, n as PluginDriver, o as AdapterSource, p as InputPath, q as logLevel, r as getMode, s as BarrelType, u as DevtoolsOptions, v as Plugin, w as PluginWithLifeCycle, x as PluginLifecycle, y as PluginContext, z as Generator } from "./PluginDriver-BkSenc-R.js";
+import { $ as formatters, A as Printer, B as ResolverPathParams, C as PluginFactoryOptions, D as PluginWithLifeCycle, E as PluginParameter, F as ResolvePathOptions, G as UserResolver, H as UserLogger, I as ResolvePathParams, J as Generator, K as KubbEvents, L as Resolver, M as ResolveBannerContext, N as ResolveNameParams, O as Preset, P as ResolveOptionsContext, Q as createStorage, R as ResolverContext, S as PluginContext, T as PluginLifecycleHooks, U as UserPlugin, V as UserConfig, W as UserPluginWithLifeCycle, X as defineGenerator, Y as ReactGeneratorV2, Z as Storage, _ as LoggerContext, a as AdapterSource, b as Override, c as CompatibilityPreset, d as Exclude, et as linters, f as Group, g as Logger, h as InputPath, i as AdapterFactoryOptions, j as PrinterFactoryOptions, k as Presets, l as Config, m as InputData, n as getMode, nt as PossiblePromise, o as BarrelType, p as Include, q as CoreGeneratorV2, r as Adapter, rt as AsyncEventEmitter, s as Builder, t as PluginDriver, tt as logLevel, u as DevtoolsOptions, v as LoggerOptions, w as PluginLifecycle, x as Plugin, y as Output, z as ResolverFileParams } from "./PluginDriver-DZdEyCoa.js";
 import { definePrinter } from "@kubb/ast";
-import { Node, OperationNode, SchemaNode, Visitor } from "@kubb/ast/types";
-import { Fabric, KubbFile } from "@kubb/fabric-core/types";
+import { Node, OperationNode, RootNode, SchemaNode, Visitor } from "@kubb/ast/types";
+import { Fabric, FabricFile } from "@kubb/fabric-core/types";
 import { Fabric as Fabric$1 } from "@kubb/react-fabric/types";
 
 //#region ../../internals/utils/src/urlPath.d.ts
@@ -158,7 +158,7 @@ type BuildOutput = {
     error: Error;
   }>;
   fabric: Fabric;
-  files: Array<KubbFile.ResolvedFile>;
+  files: Array<FabricFile.ResolvedFile>;
   driver: PluginDriver;
   /**
    * Elapsed time in milliseconds for each plugin, keyed by plugin name.
@@ -168,7 +168,7 @@ type BuildOutput = {
   /**
    * Raw generated source, keyed by absolute file path.
    */
-  sources: Map<KubbFile.Path, string>;
+  sources: Map<FabricFile.Path, string>;
 };
 /**
  * Intermediate result returned by {@link setup} and accepted by {@link safeBuild}.
@@ -177,7 +177,7 @@ type SetupResult = {
   events: AsyncEventEmitter<KubbEvents>;
   fabric: Fabric;
   driver: PluginDriver;
-  sources: Map<KubbFile.Path, string>;
+  sources: Map<FabricFile.Path, string>;
 };
 /**
  * Initializes all Kubb infrastructure for a build without executing any plugins.
@@ -303,6 +303,29 @@ type PluginBuilder<T extends PluginFactoryOptions = PluginFactoryOptions> = (opt
  */
 declare function createPlugin<T extends PluginFactoryOptions = PluginFactoryOptions>(build: PluginBuilder<T>): (options?: T['options']) => UserPluginWithLifeCycle<T>;
 //#endregion
+//#region src/defineBuilder.d.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: [] })
+ *   },
+ * }))
+ */
+declare function defineBuilder<T extends PluginFactoryOptions>(build: BuilderBuilder<T>): T['builder'];
+//#endregion
 //#region src/defineLogger.d.ts
 /**
  * Wraps a logger definition into a typed {@link Logger}.
@@ -320,8 +343,8 @@ declare function defineLogger<Options extends LoggerOptions = LoggerOptions>(log
 //#endregion
 //#region src/definePreset.d.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'
@@ -332,13 +355,19 @@ declare function defineLogger<Options extends LoggerOptions = LoggerOptions>(log
  * @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] })
  */
 declare function definePreset<TResolver extends Resolver = Resolver, TName extends string = string>(name: TName, {
   resolvers,
-  transformers
+  transformers,
+  generators
 }: {
   resolvers: Array<TResolver>;
   transformers?: Array<Visitor>;
+  generators?: Array<Generator<any>>;
 }): Preset<TResolver> & {
   name: TName;
 };
@@ -360,14 +389,36 @@ declare function definePresets<TResolver extends Resolver = Resolver>(presets: P
 //#region src/defineResolver.d.ts
 /**
  * Builder type for the plugin-specific resolver fields.
- * `default`, `resolveOptions`, and `name` are optional — built-in fallbacks are used when omitted.
+ *
+ * `default`, `resolveOptions`, `resolvePath`, `resolveFile`, `resolveBanner`, and `resolveFooter`
+ * are optional — built-in fallbacks are injected when omitted.
  */
-type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'], 'default' | 'resolveOptions' | 'name'> & Partial<Pick<T['resolver'], 'default' | 'resolveOptions'>> & {
+type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'], 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter' | 'name' | 'pluginName'> & Partial<Pick<T['resolver'], 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter'>> & {
   name: string;
+  pluginName: T['name'];
 } & ThisType<T['resolver']>;
 /**
- * Default option resolver — applies include/exclude filters and merges any matching override options.
- * Returns `null` when the node is filtered out.
+ * Default option resolver — applies include/exclude filters and merges matching override options.
+ *
+ * Returns `null` when the node is filtered out by an `exclude` rule or not matched by any `include` rule.
+ *
+ * @example Include/exclude filtering
+ * ```ts
+ * const options = defaultResolveOptions(operationNode, {
+ *   options: { output: 'types' },
+ *   exclude: [{ type: 'tag', pattern: 'internal' }],
+ * })
+ * // → null when node has tag 'internal'
+ * ```
+ *
+ * @example Override merging
+ * ```ts
+ * const options = defaultResolveOptions(operationNode, {
+ *   options: { enumType: 'asConst' },
+ *   override: [{ type: 'operationId', pattern: 'listPets', options: { enumType: 'enum' } }],
+ * })
+ * // → { enumType: 'enum' } when operationId matches
+ * ```
  */
 declare function defaultResolveOptions<TOptions>(node: Node, {
   options,
@@ -376,22 +427,205 @@ declare function defaultResolveOptions<TOptions>(node: Node, {
   override
 }: ResolveOptionsContext<TOptions>): TOptions | null;
 /**
- * Defines a resolver for a plugin, with built-in defaults for name casing and include/exclude/override filtering.
- * Override `default` or `resolveOptions` in the builder to customize the behavior.
+ * Default path resolver used by `defineResolver`.
  *
- * @example
+ * - Returns the output directory in `single` mode.
+ * - Resolves into a tag- or path-based subdirectory when `group` and a `tag`/`path` value are provided.
+ * - Falls back to a flat `output/baseName` path otherwise.
+ *
+ * A custom `group.name` function overrides the default subdirectory naming.
+ * For `tag` groups the default is `${camelCase(tag)}Controller`.
+ * For `path` groups the default is the first path segment after `/`.
+ *
+ * @example Flat output
+ * ```ts
+ * defaultResolvePath({ baseName: 'petTypes.ts' }, { root: '/src', output: { path: 'types' } })
+ * // → '/src/types/petTypes.ts'
+ * ```
+ *
+ * @example Tag-based grouping
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → '/src/types/petsController/petTypes.ts'
+ * ```
+ *
+ * @example Path-based grouping
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', path: '/pets/list' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'path' } },
+ * )
+ * // → '/src/types/pets/petTypes.ts'
+ * ```
+ *
+ * @example Single-file mode
+ * ```ts
+ * defaultResolvePath(
+ *   { baseName: 'petTypes.ts', pathMode: 'single' },
+ *   { root: '/src', output: { path: 'types' } },
+ * )
+ * // → '/src/types'
+ * ```
+ */
+declare function defaultResolvePath({
+  baseName,
+  pathMode,
+  tag,
+  path: groupPath
+}: ResolverPathParams, {
+  root,
+  output,
+  group
+}: ResolverContext): FabricFile.Path;
+/**
+ * Default file resolver used by `defineResolver`.
+ *
+ * Resolves a `FabricFile.File` by combining name resolution (`resolver.default`) with
+ * path resolution (`resolver.resolvePath`). The resolved file always has empty
+ * `sources`, `imports`, and `exports` arrays — consumers populate those separately.
+ *
+ * In `single` mode the name is omitted and the file sits directly in the output directory.
+ *
+ * @example Resolve a schema file
+ * ```ts
+ * const file = defaultResolveFile.call(resolver,
+ *   { name: 'pet', extname: '.ts' },
+ *   { root: '/src', output: { path: 'types' } },
+ * )
+ * // → { baseName: 'pet.ts', path: '/src/types/pet.ts', sources: [], ... }
+ * ```
+ *
+ * @example Resolve an operation file with tag grouping
+ * ```ts
+ * const file = defaultResolveFile.call(resolver,
+ *   { name: 'listPets', extname: '.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
+ * ```
+ */
+declare function defaultResolveFile(this: Resolver, {
+  name,
+  extname,
+  tag,
+  path: groupPath
+}: ResolverFileParams, context: ResolverContext): FabricFile.File;
+/**
+ * Generates the default "Generated by Kubb" banner from config and optional node metadata.
+ */
+declare function buildDefaultBanner({
+  title,
+  description,
+  version,
+  config
+}: {
+  title?: string;
+  description?: string;
+  version?: string;
+  config: Config;
+}): string;
+/**
+ * Default banner resolver — returns the banner string for a generated file.
+ *
+ * - When `output.banner` is a function and `node` is provided, calls it with the node.
+ * - When `output.banner` is a function and `node` is absent, falls back to the default Kubb banner.
+ * - When `output.banner` is a string, returns it directly.
+ * - When `config.output.defaultBanner` is `false`, returns `undefined`.
+ * - Otherwise returns the default "Generated by Kubb" banner.
+ *
+ * @example String banner
+ * ```ts
+ * defaultResolveBanner(undefined, { output: { banner: '// my banner' }, config })
+ * // → '// my banner'
+ * ```
+ *
+ * @example Function banner with node
+ * ```ts
+ * defaultResolveBanner(rootNode, { output: { banner: (node) => `// v${node.version}` }, config })
+ * // → '// v3.0.0'
+ * ```
+ *
+ * @example Disabled banner
+ * ```ts
+ * defaultResolveBanner(undefined, { config: { output: { defaultBanner: false }, ...config } })
+ * // → undefined
+ * ```
+ */
+declare function defaultResolveBanner(node: RootNode | undefined, {
+  output,
+  config
+}: ResolveBannerContext): string | undefined;
+/**
+ * Default footer resolver — returns the footer string for a generated file.
+ *
+ * - When `output.footer` is a function and `node` is provided, calls it with the node.
+ * - When `output.footer` is a function and `node` is absent, returns `undefined`.
+ * - When `output.footer` is a string, returns it directly.
+ * - Otherwise returns `undefined`.
+ *
+ * @example String footer
+ * ```ts
+ * defaultResolveFooter(undefined, { output: { footer: '// end of file' }, config })
+ * // → '// end of file'
+ * ```
+ *
+ * @example Function footer with node
+ * ```ts
+ * defaultResolveFooter(rootNode, { output: { footer: (node) => `// ${node.title}` }, config })
+ * // → '// Pet Store'
+ * ```
+ */
+declare function defaultResolveFooter(node: RootNode | undefined, {
+  output
+}: ResolveBannerContext): string | undefined;
+/**
+ * Defines a resolver for a plugin, injecting built-in defaults for name casing,
+ * include/exclude/override filtering, path resolution, and file construction.
+ *
+ * All four defaults can be overridden by providing them in the builder function:
+ * - `default` — name casing strategy (camelCase / PascalCase)
+ * - `resolveOptions` — include/exclude/override filtering
+ * - `resolvePath` — output path computation
+ * - `resolveFile` — full `FabricFile.File` construction
+ *
+ * Methods in the builder have access to `this` (the full resolver object), so they
+ * can call other resolver methods without circular imports.
+ *
+ * @example Basic resolver with naming helpers
+ * ```ts
  * export const resolver = defineResolver<PluginTs>(() => ({
  *   name: 'default',
- *   resolveName(name) {
- *     return this.default(name, 'function')
+ *   resolveName(node) {
+ *     return this.default(node.name, 'function')
  *   },
- *   resolveTypedName(name) {
- *     return this.default(name, 'type')
+ *   resolveTypedName(node) {
+ *     return this.default(node.name, 'type')
  *   },
+ * }))
+ * ```
+ *
+ * @example Override resolvePath for a custom output structure
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'custom',
+ *   resolvePath({ baseName }, { root, output }) {
+ *     return path.resolve(root, output.path, 'generated', baseName)
+ *   },
+ * }))
+ * ```
+ *
+ * @example Use this.default inside a helper
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
  *   resolveParamName(node, param) {
- *     return this.resolveName(`${node.operationId} ${param.in} ${param.name}`)
+ *     return this.default(`${node.operationId} ${param.in} ${param.name}`, 'type')
  *   },
  * }))
+ * ```
  */
 declare function defineResolver<T extends PluginFactoryOptions>(build: ResolverBuilder<T>): T['resolver'];
 //#endregion
@@ -403,7 +637,6 @@ type BuildOperationsV2Options<TOptions extends PluginFactoryOptions> = {
   Component: ReactGeneratorV2<TOptions>['Operations'] | undefined;
   adapter: Adapter;
   driver: PluginDriver;
-  mode: KubbFile.Mode;
   options: TOptions['resolvedOptions'];
 };
 /**
@@ -417,7 +650,6 @@ type BuildOperationV2Options<TOptions extends PluginFactoryOptions> = {
   Component: ReactGeneratorV2<TOptions>['Operation'] | undefined;
   adapter: Adapter;
   driver: PluginDriver;
-  mode: KubbFile.Mode;
   options: TOptions['resolvedOptions'];
 };
 /**
@@ -431,7 +663,6 @@ type BuildSchemaV2Options<TOptions extends PluginFactoryOptions> = {
   Component: ReactGeneratorV2<TOptions>['Schema'] | undefined;
   adapter: Adapter;
   driver: PluginDriver;
-  mode: KubbFile.Mode;
   options: TOptions['resolvedOptions'];
 };
 /**
@@ -577,12 +808,12 @@ type AddIndexesProps = {
  * - When `type` is `'all'`, strips named exports so every re-export becomes a wildcard (`export * from`).
  * - Attaches `meta` to each barrel file for downstream plugin identification.
  */
-declare function getBarrelFiles(files: Array<KubbFile.ResolvedFile>, {
+declare function getBarrelFiles(files: Array<FabricFile.ResolvedFile>, {
   type,
   meta,
   root,
   output
-}: AddIndexesProps): Promise<Array<KubbFile.File>>;
+}: AddIndexesProps): Promise<Array<FabricFile.File>>;
 //#endregion
 //#region src/utils/getConfigs.d.ts
 /**
@@ -599,20 +830,25 @@ type GetPresetParams<TResolver extends Resolver> = {
   preset: CompatibilityPreset;
   presets: Presets<TResolver>;
   resolvers: Array<TResolver>;
+  /**
+   * User-supplied generators to append after the preset's generators.
+   */
+  generators: Array<Generator<any>>;
   transformers?: Array<Visitor>;
 };
 type GetPresetResult<TResolver extends Resolver> = {
-  baseResolver: TResolver;
   resolver: TResolver;
   transformers: Array<Visitor>;
+  generators: Array<Generator<any>>;
   preset: Preset<TResolver> | undefined;
 };
 /**
- * Resolves a named preset into merged resolvers and transformers.
+ * Resolves a named preset into merged resolvers, transformers, and generators.
  *
- * - Merges the preset's resolvers on top of the first (default) resolver to produce `baseResolver`.
+ * - Merges the preset's resolvers on top of the first (default)
  * - Merges any additional user-supplied resolvers on top of that to produce the final `resolver`.
  * - Concatenates preset transformers before user-supplied transformers.
+ * - Combines preset generators with user-supplied generators; falls back to the `default` preset's generators when neither provides any.
  */
 declare function getPreset<TResolver extends Resolver = Resolver>(params: GetPresetParams<TResolver>): GetPresetResult<TResolver>;
 //#endregion
@@ -636,7 +872,15 @@ declare function detectLinter(): Promise<Linter | null>;
 //#endregion
 //#region src/utils/mergeResolvers.d.ts
 /**
- * Merges an array of resolvers into a single resolver. Later entries override earlier ones (last wins).
+ * Merges an ordered list of resolvers into a single resolver by shallow-merging each entry left to right.
+ *
+ * Later entries win when keys conflict, so the last resolver in the list takes highest precedence.
+ *
+ * @example
+ * ```ts
+ * const resolver = mergeResolvers(resolverTs, resolverTsLegacy)
+ * // resolverTsLegacy methods override resolverTs where they overlap
+ * ```
  */
 declare function mergeResolvers<T extends Resolver>(...resolvers: Array<T>): T;
 //#endregion
@@ -660,5 +904,5 @@ type DependencyVersion = string;
  */
 declare function satisfiesDependency(dependency: DependencyName | RegExp, version: DependencyVersion, cwd?: string): boolean;
 //#endregion
-export { Adapter, AdapterFactoryOptions, AdapterSource, AsyncEventEmitter, BarrelType, type CLIOptions, CompatibilityPreset, Config, type ConfigInput, CoreGeneratorV2, DevtoolsOptions, type FileMetaBase, FunctionParams, type FunctionParamsAST, Generator, Group, InputData, InputPath, KubbEvents, Logger, LoggerContext, LoggerOptions, Output, Plugin, PluginContext, PluginDriver, PluginFactoryOptions, PluginLifecycle, PluginLifecycleHooks, PluginParameter, PluginWithLifeCycle, Preset, Presets, Printer, PrinterFactoryOptions, ReactGeneratorV2, ResolveNameParams, ResolveOptionsContext, ResolvePathParams, Resolver, Storage, URLPath, UserConfig, UserLogger, UserPlugin, UserPluginWithLifeCycle, UserResolver, build, build as default, createAdapter, createPlugin, createStorage, defaultResolveOptions, defineConfig, defineGenerator, defineLogger, definePreset, definePresets, definePrinter, defineResolver, detectFormatter, detectLinter, formatters, fsStorage, getBarrelFiles, getConfigs, getMode, getPreset, isInputPath, linters, logLevel, memoryStorage, mergeResolvers, renderOperation, renderOperations, renderSchema, safeBuild, satisfiesDependency, setup };
+export { Adapter, AdapterFactoryOptions, AdapterSource, AsyncEventEmitter, BarrelType, Builder, type CLIOptions, CompatibilityPreset, Config, type ConfigInput, CoreGeneratorV2, DevtoolsOptions, Exclude, type FileMetaBase, FunctionParams, type FunctionParamsAST, Generator, Group, Include, InputData, InputPath, KubbEvents, Logger, LoggerContext, LoggerOptions, Output, Override, Plugin, PluginContext, PluginDriver, PluginFactoryOptions, PluginLifecycle, PluginLifecycleHooks, PluginParameter, PluginWithLifeCycle, Preset, Presets, Printer, PrinterFactoryOptions, ReactGeneratorV2, ResolveBannerContext, ResolveNameParams, ResolveOptionsContext, ResolvePathOptions, ResolvePathParams, Resolver, ResolverContext, ResolverFileParams, ResolverPathParams, Storage, URLPath, UserConfig, UserLogger, UserPlugin, UserPluginWithLifeCycle, UserResolver, build, build as default, buildDefaultBanner, createAdapter, createPlugin, createStorage, defaultResolveBanner, defaultResolveFile, defaultResolveFooter, defaultResolveOptions, defaultResolvePath, defineBuilder, defineConfig, defineGenerator, defineLogger, definePreset, definePresets, definePrinter, defineResolver, detectFormatter, detectLinter, formatters, fsStorage, getBarrelFiles, getConfigs, getMode, getPreset, isInputPath, linters, logLevel, memoryStorage, mergeResolvers, renderOperation, renderOperations, renderSchema, safeBuild, satisfiesDependency, setup };
 //# sourceMappingURL=index.d.ts.map