@kubb/core 5.0.0-alpha.26 → 5.0.0-alpha.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/core",
-  "version": "5.0.0-alpha.26",
+  "version": "5.0.0-alpha.27",
   "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.7",
     "semver": "^7.7.4",
     "tinyexec": "^1.0.4",
-    "@kubb/ast": "5.0.0-alpha.26"
+    "@kubb/ast": "5.0.0-alpha.27"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/PluginDriver.ts

@@ -141,6 +141,9 @@ export class PluginDriver {
       get resolver() {
         return plugin.resolver
       },
+      get transformer() {
+        return plugin.transformer
+      },
       openInStudio(options?: DevtoolsOptions) {
         if (!driver.config.devtools || driver.#studioIsOpen) {
           return

package/src/index.ts

@@ -1,5 +1,5 @@
 export { AsyncEventEmitter, URLPath } from '@internals/utils'
-export { definePrinter } from '@kubb/ast'
+export { composeTransformers, definePrinter } from '@kubb/ast'
 export { build, build as default, safeBuild, setup } from './build.ts'
 export { type CLIOptions, type ConfigInput, defineConfig, isInputPath } from './config.ts'
 export { formatters, linters, logLevel } from './constants.ts'
@@ -31,5 +31,4 @@ export { getBarrelFiles } from './utils/getBarrelFiles.ts'
 export { getConfigs } from './utils/getConfigs.ts'
 export { getPreset } from './utils/getPreset.ts'
 export { detectLinter } from './utils/linters.ts'
-export { mergeResolvers } from './utils/mergeResolvers.ts'
 export { satisfiesDependency } from './utils/packageJSON.ts'

package/src/types.ts

@@ -1,5 +1,5 @@
 import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
-import type { Node, RootNode, SchemaNode, Visitor } from '@kubb/ast/types'
+import type { Node, Printer, RootNode, SchemaNode, Visitor } from '@kubb/ast/types'
 import type { FabricFile, Fabric as FabricType } from '@kubb/fabric-core/types'
 import type { HttpMethod } from '@kubb/oas'
 import type { DEFAULT_STUDIO_URL, logLevel } from './constants.ts'
@@ -8,7 +8,7 @@ import type { Generator } from './defineGenerator.ts'
 import type { KubbEvents } from './Kubb.ts'
 import type { PluginDriver } from './PluginDriver.ts'
 
-export type { Printer, PrinterFactoryOptions } from '@kubb/ast/types'
+export type { Printer, PrinterFactoryOptions, PrinterPartial } from '@kubb/ast/types'
 
 declare global {
   namespace Kubb {
@@ -396,9 +396,16 @@ export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOpti
    */
   options: TOptions['resolvedOptions']
   /**
-   * The resolver for this plugin, accessible via `driver.getPluginByName(name)?.resolver`.
+   * The resolver for this plugin.
+   * Composed by `getPreset` from the preset resolver and the user's `resolver` partial override.
    */
   resolver?: TOptions['resolver']
+  /**
+   * The composed transformer for this plugin.
+   * Composed by `getPreset` from the preset's transformers and the user's `transformer` visitor.
+   * When a visitor method returns `null`/`undefined`, the preset transformer's result is used instead.
+   */
+  transformer?: Visitor
   /**
    * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin is executed after these plugins.
    * Can be used to validate dependent plugins.
@@ -435,9 +442,16 @@ export type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>
    */
   options: TOptions['resolvedOptions']
   /**
-   * The resolver for this plugin, accessible via `driver.getPluginByName(name)?.resolver`.
+   * The resolver for this plugin.
+   * Composed by `getPreset` from the preset resolver and the user's `resolver` partial override.
    */
   resolver: TOptions['resolver']
+  /**
+   * The composed transformer for this plugin. Accessible via `context.transformer`.
+   * Composed by `getPreset` from the preset's transformers and the user's `transformer` visitor.
+   * When a visitor method returns `null`/`undefined`, the preset transformer's result is used instead.
+   */
+  transformer?: Visitor
 
   install: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => PossiblePromise<void>
   /**
@@ -527,6 +541,11 @@ export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryO
    * Resolver for the current plugin. Shorthand for `plugin.resolver`.
    */
   resolver: TOptions['resolver']
+  /**
+   * Composed transformer for the current plugin. Shorthand for `plugin.transformer`.
+   * Apply with `transform(node, context.transformer)` to pre-process AST nodes before printing.
+   */
+  transformer: Visitor | undefined
 
   /**
    * Opens the Kubb Studio URL for the current `rootNode` in the default browser.
@@ -639,7 +658,7 @@ export type { CoreGeneratorV2, Generator, ReactGeneratorV2 } from './defineGener
 export type { KubbEvents } from './Kubb.ts'
 
 /**
- * A preset bundles a name, one or more resolvers, optional AST transformers,
+ * A preset bundles a name, a resolver, optional AST transformers,
  * and optional generators into a single reusable configuration object.
  *
  * @template TResolver - The concrete resolver type for this preset.
@@ -650,9 +669,9 @@ export type Preset<TResolver extends Resolver = Resolver> = {
    */
   name: string
   /**
-   * Ordered list of resolvers applied by this preset (last entry wins on merge).
+   * The resolver used by this preset.
    */
-  resolvers: Array<TResolver>
+  resolver: TResolver
   /**
    * Optional AST visitors / transformers applied after resolving.
    */
@@ -662,6 +681,11 @@ export type Preset<TResolver extends Resolver = Resolver> = {
    * to their concrete generator type.
    */
   generators?: Array<Generator<any>>
+  /**
+   * Optional printer factory used by this preset.
+   * The generator calls this function at render-time to produce a configured printer instance.
+   */
+  printer?: (options: any) => Printer
 }
 
 /**

package/src/utils/getPreset.ts

@@ -1,52 +1,78 @@
+import { composeTransformers } from '@kubb/ast'
 import type { Visitor } from '@kubb/ast/types'
 import type { CompatibilityPreset, Generator, Preset, Presets, Resolver } from '../types.ts'
-import { mergeResolvers } from './mergeResolvers.ts'
+
+/**
+ * Returns a copy of `defaults` where each function in `userOverrides` is wrapped
+ * so a `null`/`undefined` return falls back to the original. Non-function values
+ * are assigned directly. All calls use the merged object as `this`.
+ */
+function withFallback<T extends object>(defaults: T, userOverrides: Partial<T>): T {
+  const merged = { ...defaults } as T
+
+  for (const key of Object.keys(userOverrides) as Array<keyof T>) {
+    const userVal = userOverrides[key]
+    const defaultVal = defaults[key]
+
+    if (typeof userVal === 'function' && typeof defaultVal === 'function') {
+      ;(merged as any)[key] = (...args: any[]) => (userVal as Function).apply(merged, args) ?? (defaultVal as Function).apply(merged, args)
+    } else if (userVal !== undefined) {
+      merged[key] = userVal as T[typeof key]
+    }
+  }
+
+  return merged
+}
 
 type GetPresetParams<TResolver extends Resolver> = {
   preset: CompatibilityPreset
   presets: Presets<TResolver>
-  resolvers?: Array<TResolver>
+  /**
+   * Optional single resolver whose methods override the preset resolver.
+   * When a method returns `null` or `undefined` the preset resolver's method is used instead.
+   */
+  resolver?: Partial<TResolver> & ThisType<TResolver>
   /**
    * User-supplied generators to append after the preset's generators.
    */
   generators?: Array<Generator<any>>
-  transformers?: Array<Visitor>
+  /**
+   * Optional single transformer visitor whose methods override the preset transformer.
+   * When a method returns `null` or `undefined` the preset transformer's method is used instead.
+   */
+  transformer?: Visitor
 }
 
 type GetPresetResult<TResolver extends Resolver> = {
   resolver: TResolver
-  transformers: Array<Visitor>
+  transformer: Visitor | undefined
   generators: Array<Generator<any>>
   preset: Preset<TResolver> | undefined
 }
 
 /**
- * Resolves a named preset into merged resolvers, transformers, and generators.
+ * Resolves a named preset into a resolver, transformer, and generators.
  *
- * - 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.
+ * - Selects the preset resolver; wraps it with user overrides using null/undefined fallback.
+ * - Composes the preset's transformers into a single visitor; wraps it with the user transformer using null/undefined fallback.
  * - Combines preset generators with user-supplied generators; falls back to the `default` preset's generators when neither provides any.
  */
 export function getPreset<TResolver extends Resolver = Resolver>(params: GetPresetParams<TResolver>): GetPresetResult<TResolver> {
-  const { preset: presetName, presets, resolvers = [], transformers: userTransformers = [], generators: userGenerators = [] } = params
-  const [defaultResolver, ...userResolvers] = resolvers
+  const { preset: presetName, presets, resolver: userResolver, transformer: userTransformer, generators: userGenerators = [] } = params
   const preset = presets[presetName]
 
-  const baseResolver = mergeResolvers(defaultResolver!, ...(preset?.resolvers ?? []))
-  const resolver = mergeResolvers(baseResolver, ...(userResolvers ?? []))
-  const transformers = [...(preset?.transformers ?? []), ...(userTransformers ?? [])]
+  const presetResolver = preset?.resolver ?? presets['default']!.resolver
+  const resolver = userResolver ? withFallback(presetResolver, userResolver) : presetResolver
+
+  const presetTransformers = preset?.transformers ?? []
+  const presetTransformer = presetTransformers.length > 0 ? composeTransformers(...presetTransformers) : undefined
+  const transformer = presetTransformer && userTransformer ? withFallback(presetTransformer, userTransformer) : (userTransformer ?? presetTransformer)
 
   const presetGenerators = preset?.generators ?? []
-  const defaultPresetGenerators = presets['default']?.generators ?? []
-  const generators = (presetGenerators.length > 0 || userGenerators.length
-    ? [...presetGenerators, ...userGenerators]
-    : defaultPresetGenerators) as unknown as Array<Generator<any>>
-
-  return {
-    resolver,
-    transformers,
-    generators,
-    preset,
-  }
+  const defaultGenerators = presets['default']?.generators ?? []
+  const generators = (presetGenerators.length > 0 || userGenerators.length > 0 ? [...presetGenerators, ...userGenerators] : defaultGenerators) as Array<
+    Generator<any>
+  >
+
+  return { resolver, transformer, generators, preset }
 }

package/src/utils/mergeResolvers.ts

@@ -1,16 +0,0 @@
-import type { Resolver } from '../types.ts'
-
-/**
- * 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
- * ```
- */
-export function mergeResolvers<T extends Resolver>(...resolvers: Array<T>): T {
-  return resolvers.reduce<T>((acc, curr) => ({ ...acc, ...curr }), resolvers[0]!)
-}