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

package/src/types.ts

@@ -1,8 +1,10 @@
 import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
 import type { Node, RootNode, SchemaNode, Visitor } from '@kubb/ast/types'
 import type { Fabric as FabricType, KubbFile } from '@kubb/fabric-core/types'
+import type { HttpMethod } from '@kubb/oas'
 import type { DEFAULT_STUDIO_URL, logLevel } from './constants.ts'
 import type { Storage } from './createStorage.ts'
+import type { Generator } from './defineGenerator.ts'
 import type { KubbEvents } from './Kubb.ts'
 import type { PluginDriver } from './PluginDriver.ts'
 
@@ -110,7 +112,8 @@ export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptio
    * The raw source document produced after the first `parse()` call.
    * `undefined` before parsing; typed by the adapter's `TDocument` generic.
    */
-  document?: TOptions['document']
+  document: TOptions['document'] | null
+  rootNode: RootNode | null
   /**
    * Convert the raw source into a universal `RootNode`.
    */
@@ -229,7 +232,7 @@ export type Config<TInput = Input> = {
      * Configures how `index.ts` files are created, including disabling barrel file generation. Each plugin has its own `barrelType` option; this setting controls the root barrel file (e.g., `src/gen/index.ts`).
      * @default 'named'
      */
-    barrelType?: Exclude<BarrelType, 'propagate'> | false
+    barrelType?: 'all' | 'named' | false
     /**
      * Adds a default banner to the start of every generated file indicating it was generated by Kubb.
      * - 'simple' adds banner with link to Kubb.
@@ -297,25 +300,53 @@ export type ResolveOptionsContext<TOptions> = {
 /**
  * Base constraint for all plugin resolver objects.
  *
- * `default` and `resolveOptions` are injected automatically by `defineResolver` — plugin
- * authors may override them but never need to implement them from scratch.
- * Concrete plugin resolver types extend this with their own helper methods.
+ * `default`, `resolveOptions`, `resolvePath`, and `resolveFile` are injected automatically
+ * by `defineResolver` — plugin authors may override them but never need to implement them
+ * from scratch.
+ *
+ * @example
+ * ```ts
+ * type MyResolver = Resolver & {
+ *   resolveName(node: SchemaNode): string
+ *   resolveTypedName(node: SchemaNode): string
+ * }
+ * ```
  */
 export type Resolver = {
   name: string
+  pluginName: Plugin['name']
   default(name: ResolveNameParams['name'], type?: ResolveNameParams['type']): string
   resolveOptions<TOptions>(node: Node, context: ResolveOptionsContext<TOptions>): TOptions | null
+  resolvePath(params: ResolverPathParams, context: ResolverContext): KubbFile.Path
+  resolveFile(params: ResolverFileParams, context: ResolverContext): KubbFile.File
+  resolveBanner(node: RootNode | null, context: ResolveBannerContext): string | undefined
+  resolveFooter(node: RootNode | null, context: ResolveBannerContext): string | undefined
 }
 
 /**
- * The user-facing subset of a `Resolver` — everything except the methods injected by
- * `defineResolver` (`default` and `resolveOptions`).
+ * The user-facing subset of a `Resolver` — everything except the four methods injected by
+ * `defineResolver` (`default`, `resolveOptions`, `resolvePath`, and `resolveFile`).
+ *
+ * All four injected methods can still be overridden by providing them explicitly in the builder.
  *
- * When you pass a `UserResolver` to `defineResolver`, the standard `default` and
- * `resolveOptions` implementations are injected automatically so plugin authors never
- * need to define them by hand. Both can still be overridden by providing them explicitly.
+ * @example
+ * ```ts
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
+ *   resolveName(node) { return this.default(node.name, 'function') },
+ * }))
+ * ```
+ */
+export type UserResolver = Omit<Resolver, 'default' | 'resolveOptions' | 'resolvePath' | 'resolveFile' | 'resolveBanner' | 'resolveFooter'>
+
+/**
+ * Base type for plugin builder objects.
+ * Concrete plugin builder types extend this with their own schema-building helpers.
+ * Use `defineBuilder` to define a builder object and export it alongside the plugin.
  */
-export type UserResolver = Omit<Resolver, 'default' | 'resolveOptions'>
+export type Builder = {
+  name: string
+}
 
 export type PluginFactoryOptions<
   /**
@@ -343,6 +374,11 @@ export type PluginFactoryOptions<
    * Use `defineResolver` to define the resolver object and export it alongside the plugin.
    */
   TResolver extends Resolver = Resolver,
+  /**
+   * Builder object that encapsulates the schema-building helpers used by this plugin.
+   * Use `defineBuilder` to define the builder object and export it alongside the plugin.
+   */
+  TBuilder extends Builder = Builder,
 > = {
   name: TName
   options: TOptions
@@ -350,6 +386,7 @@ export type PluginFactoryOptions<
   context: TContext
   resolvePathOptions: TResolvePathOptions
   resolver: TResolver
+  builder: TBuilder
 }
 
 export type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
@@ -419,6 +456,7 @@ export type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactor
    * Options can als be included.
    * @type hookFirst
    * @example ('./Pet.ts', './src/gen/') => '/src/gen/Pet.ts'
+   * @deprecated this will be replaced by resolvers
    */
   resolvePath?: (this: PluginContext<TOptions>, baseName: KubbFile.BaseName, mode?: KubbFile.Mode, options?: TOptions['resolvePathOptions']) => KubbFile.Path
   /**
@@ -426,6 +464,7 @@ export type PluginLifecycle<TOptions extends PluginFactoryOptions = PluginFactor
    * Useful when converting to PascalCase or camelCase.
    * @type hookFirst
    * @example ('pet') => 'Pet'
+   * @deprecated this will be replaced by resolvers
    */
   resolveName?: (this: PluginContext<TOptions>, name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
 }
@@ -504,7 +543,7 @@ export type PluginContext<TOptions extends PluginFactoryOptions = PluginFactoryO
 /**
  * Specify the export location for the files and define the behavior of the output
  */
-export type Output<TOptions> = {
+export type Output<_TOptions = unknown> = {
   /**
    * Path to the output folder or file that will contain the generated code
    */
@@ -517,11 +556,11 @@ export type Output<TOptions> = {
   /**
    * Add a banner text in the beginning of every file
    */
-  banner?: string | ((options: TOptions) => string)
+  banner?: string | ((node: RootNode) => string)
   /**
    * Add a footer text in the beginning of every file
    */
-  footer?: string | ((options: TOptions) => string)
+  footer?: string | ((node: RootNode) => string)
   /**
    * Whether to override existing external files if they already exist.
    * @default false
@@ -574,8 +613,8 @@ export type { CoreGeneratorV2, Generator, ReactGeneratorV2 } from './defineGener
 export type { KubbEvents } from './Kubb.ts'
 
 /**
- * A preset bundles a name, one or more resolvers, and optional AST transformers
- * into a single reusable configuration object.
+ * A preset bundles a name, one or more resolvers, optional AST transformers,
+ * and optional generators into a single reusable configuration object.
  *
  * @template TResolver - The concrete resolver type for this preset.
  */
@@ -592,6 +631,11 @@ export type Preset<TResolver extends Resolver = Resolver> = {
    * Optional AST visitors / transformers applied after resolving.
    */
   transformers?: Array<Visitor>
+  /**
+   * Optional generators used by this preset. Plugin implementations cast this
+   * to their concrete generator type.
+   */
+  generators?: Array<Generator<any>>
 }
 
 /**
@@ -601,3 +645,147 @@ export type Preset<TResolver extends Resolver = Resolver> = {
  * @template TName - The union of valid preset name keys.
  */
 export type Presets<TResolver extends Resolver = Resolver> = Record<CompatibilityPreset, Preset<TResolver>>
+
+type ByTag = {
+  type: 'tag'
+  pattern: string | RegExp
+}
+
+type ByOperationId = {
+  type: 'operationId'
+  pattern: string | RegExp
+}
+
+type ByPath = {
+  type: 'path'
+  pattern: string | RegExp
+}
+
+type ByMethod = {
+  type: 'method'
+  pattern: HttpMethod | RegExp
+}
+// TODO implement as alternative for ByMethod
+// type ByMethods = {
+//   type: 'methods'
+//   pattern: Array<HttpMethod>
+// }
+
+type BySchemaName = {
+  type: 'schemaName'
+  pattern: string | RegExp
+}
+
+type ByContentType = {
+  type: 'contentType'
+  pattern: string | RegExp
+}
+
+export type Exclude = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+export type Include = ByTag | ByOperationId | ByPath | ByMethod | ByContentType | BySchemaName
+
+export type Override<TOptions> = (ByTag | ByOperationId | ByPath | ByMethod | BySchemaName | ByContentType) & {
+  //TODO should be options: Omit<Partial<TOptions>, 'override'>
+  options: Partial<TOptions>
+}
+
+export type ResolvePathOptions = {
+  pluginName?: string
+  group?: {
+    tag?: string
+    path?: string
+  }
+  type?: ResolveNameParams['type']
+}
+
+/**
+ * File-specific parameters for `Resolver.resolvePath`.
+ *
+ * Pass alongside a `ResolverContext` to identify which file to resolve.
+ * Provide `tag` for tag-based grouping or `path` for path-based grouping.
+ *
+ * @example
+ * ```ts
+ * resolver.resolvePath(
+ *   { baseName: 'petTypes.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → '/src/types/petsController/petTypes.ts'
+ * ```
+ */
+export type ResolverPathParams = {
+  baseName: KubbFile.BaseName
+  pathMode?: KubbFile.Mode
+  /**
+   * Tag value used when `group.type === 'tag'`.
+   */
+  tag?: string
+  /**
+   * Path value used when `group.type === 'path'`.
+   */
+  path?: string
+}
+
+/**
+ * Shared context passed as the second argument to `Resolver.resolvePath` and `Resolver.resolveFile`.
+ *
+ * Describes where on disk output is rooted, which output config is active, and the optional
+ * grouping strategy that controls subdirectory layout.
+ *
+ * @example
+ * ```ts
+ * const context: ResolverContext = {
+ *   root: config.root,
+ *   output,
+ *   group,
+ * }
+ * ```
+ */
+export type ResolverContext = {
+  root: string
+  output: Output
+  group?: Group
+  /** Plugin name used to populate `meta.pluginName` on the resolved file. */
+  pluginName?: string
+}
+
+/**
+ * File-specific parameters for `Resolver.resolveFile`.
+ *
+ * Pass alongside a `ResolverContext` to fully describe the file to resolve.
+ * `tag` and `path` are used only when a matching `group` is present in the context.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveFile(
+ *   { name: 'listPets', extname: '.ts', tag: 'pets' },
+ *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+ * )
+ * // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
+ * ```
+ */
+export type ResolverFileParams = {
+  name: string
+  extname: KubbFile.Extname
+  /** Tag value used when `group.type === 'tag'`. */
+  tag?: string
+  /** Path value used when `group.type === 'path'`. */
+  path?: string
+}
+
+/**
+ * Context passed to `Resolver.resolveBanner` and `Resolver.resolveFooter`.
+ *
+ * `output` is optional — not every plugin configures a banner/footer.
+ * `config` carries the global Kubb config, used to derive the default Kubb banner.
+ *
+ * @example
+ * ```ts
+ * resolver.resolveBanner(rootNode, { output: { banner: '// generated' }, config })
+ * // → '// generated'
+ * ```
+ */
+export type ResolveBannerContext = {
+  output?: Pick<Output, 'banner' | 'footer'>
+  config: Config
+}

package/src/utils/getBarrelFiles.ts

@@ -33,7 +33,7 @@ function getBarrelFilesByRoot(root: string | undefined, files: Array<KubbFile.Re
   const cachedFiles = new Map<KubbFile.Path, KubbFile.File>()
 
   TreeNode.build(files, root)?.forEach((treeNode) => {
-    if (!treeNode || !treeNode.children || !treeNode.parent?.data.path) {
+    if (!treeNode?.children || !treeNode.parent?.data.path) {
       return
     }
 

package/src/utils/getPreset.ts

@@ -1,30 +1,35 @@
 import type { Visitor } from '@kubb/ast/types'
-import type { CompatibilityPreset, Preset, Presets, Resolver } from '../types.ts'
+import type { CompatibilityPreset, Generator, Preset, Presets, Resolver } from '../types.ts'
 import { mergeResolvers } from './mergeResolvers.ts'
 
 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.
  */
 export function getPreset<TResolver extends Resolver = Resolver>(params: GetPresetParams<TResolver>): GetPresetResult<TResolver> {
-  const { preset: presetName, presets, resolvers, transformers: userTransformers } = params
+  const { preset: presetName, presets, resolvers, transformers: userTransformers, generators: userGenerators } = params
   const [defaultResolver, ...userResolvers] = resolvers
   const preset = presets[presetName]
 
@@ -32,10 +37,16 @@ export function getPreset<TResolver extends Resolver = Resolver>(params: GetPres
   const resolver = mergeResolvers(baseResolver, ...(userResolvers ?? []))
   const transformers = [...(preset?.transformers ?? []), ...(userTransformers ?? [])]
 
+  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 {
-    baseResolver,
     resolver,
     transformers,
+    generators,
     preset,
   }
 }

package/src/hooks/useKubb.ts

@@ -1,160 +0,0 @@
-import path from 'node:path'
-import type { RootNode } from '@kubb/ast/types'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import { useFabric } from '@kubb/react-fabric'
-import type { GetFileOptions, PluginDriver } from '../PluginDriver.ts'
-import type { Config, Plugin, PluginFactoryOptions, ResolveNameParams, ResolvePathParams } from '../types.ts'
-
-type ResolvePathOptions = {
-  pluginName?: string
-  group?: {
-    tag?: string
-    path?: string
-  }
-  type?: ResolveNameParams['type']
-}
-
-type UseKubbReturn<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
-  plugin: Plugin<TOptions>
-  mode: KubbFile.Mode
-  config: Config
-  /**
-   * Returns the plugin whose `name` matches `pluginName`, defaulting to the current plugin.
-   */
-  getPluginByName: (pluginName?: string) => Plugin | undefined
-  /**
-   * Resolves a file reference, defaulting `pluginName` to the current plugin.
-   */
-  getFile: (params: Omit<GetFileOptions<ResolvePathOptions>, 'pluginName'> & { pluginName?: string }) => KubbFile.File<{ pluginName: string }>
-  /**
-   * Resolves a name, defaulting `pluginName` to the current plugin.
-   * @deprecated user `resolver` from options instead
-   */
-  resolveName: (params: Omit<ResolveNameParams, 'pluginName'> & { pluginName?: string }) => string
-  /**
-   * Resolves a path, defaulting `pluginName` to the current plugin.
-   */
-  resolvePath: <TPathOptions = object>(params: Omit<ResolvePathParams<TPathOptions>, 'pluginName'> & { pluginName?: string }) => KubbFile.Path
-  /**
-   * Resolves the banner using the plugin's `output.banner` option.
-   * Falls back to the default "Generated by Kubb" banner when `output.banner` is unset.
-   * When `output.banner` is a function and no node is provided, returns the default banner.
-   */
-  resolveBanner: (node?: RootNode) => string | undefined
-  /**
-   * Resolves the footer using the plugin's `output.footer` option.
-   * Returns `undefined` when no footer is configured.
-   * When `output.footer` is a function and no node is provided, returns `undefined`.
-   */
-  resolveFooter: (node?: RootNode) => string | undefined
-}
-
-/**
- * Generates the default "Generated by Kubb" banner from node metadata.
- */
-function buildDefaultBanner({ title, description, version, config }: { title?: string; description?: string; version?: string; config: Config }): string {
-  try {
-    let source = ''
-    if (Array.isArray(config.input)) {
-      const first = config.input[0]
-      if (first && 'path' in first) {
-        source = path.basename(first.path)
-      }
-    } else if ('path' in config.input) {
-      source = path.basename(config.input.path)
-    } else if ('data' in config.input) {
-      source = 'text content'
-    }
-
-    let banner = '/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n'
-
-    if (config.output.defaultBanner === 'simple') {
-      banner += '*/\n'
-      return banner
-    }
-
-    if (source) {
-      banner += `* Source: ${source}\n`
-    }
-
-    if (title) {
-      banner += `* Title: ${title}\n`
-    }
-
-    if (description) {
-      const formattedDescription = description.replace(/\n/gm, '\n* ')
-      banner += `* Description: ${formattedDescription}\n`
-    }
-
-    if (version) {
-      banner += `* OpenAPI spec version: ${version}\n`
-    }
-
-    banner += '*/\n'
-    return banner
-  } catch (_error) {
-    return '/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n*/'
-  }
-}
-
-/**
- * React-Fabric hook that exposes the current plugin context inside a generator component.
- *
- * Returns the active `plugin`, `mode`, `config`, and a set of resolver helpers
- * (`getFile`, `resolveName`, `resolvePath`, `resolveBanner`, `resolveFooter`) that
- * all default to the current plugin when no explicit `pluginName` is provided.
- *
- * @example
- * ```ts
- * function Operation({ node }: OperationProps) {
- *   const { config, resolvePath } = useKubb()
- *   const filePath = resolvePath({ baseName: node.operationId })
- *   return <File path={filePath}>...</File>
- * }
- * ```
- */
-export function useKubb<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(): UseKubbReturn<TOptions> {
-  const { meta } = useFabric<{
-    plugin: Plugin<TOptions>
-    mode: KubbFile.Mode
-    driver: PluginDriver
-  }>()
-
-  const config = meta.driver.config
-  const defaultPluginName = meta.plugin.name
-
-  const output = (
-    meta.plugin.options as { output?: { banner?: string | ((node: RootNode) => string); footer?: string | ((node: RootNode) => string) } } | undefined
-  )?.output
-
-  return {
-    plugin: meta.plugin as Plugin<TOptions>,
-    mode: meta.mode,
-    config,
-    getPluginByName: (pluginName = defaultPluginName) => meta.driver.getPluginByName.call(meta.driver, pluginName),
-    getFile: ({ pluginName = defaultPluginName, ...rest }) => meta.driver.getFile.call(meta.driver, { pluginName, ...rest }),
-    resolveName: ({ pluginName = defaultPluginName, ...rest }) => meta.driver.resolveName.call(meta.driver, { pluginName, ...rest }),
-    resolvePath: ({ pluginName = defaultPluginName, ...rest }) => meta.driver.resolvePath.call(meta.driver, { pluginName, ...rest }),
-    resolveBanner: (node?: RootNode) => {
-      if (typeof output?.banner === 'function') {
-        return node ? output.banner(node) : buildDefaultBanner({ config })
-      }
-      if (typeof output?.banner === 'string') {
-        return output.banner
-      }
-      if (config.output.defaultBanner === false) {
-        return undefined
-      }
-      return buildDefaultBanner({ config })
-    },
-    resolveFooter: (node?: RootNode) => {
-      if (typeof output?.footer === 'function') {
-        return node ? output.footer(node) : undefined
-      }
-      if (typeof output?.footer === 'string') {
-        return output.footer
-      }
-      return undefined
-    },
-  }
-}