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

package/src/defineResolver.ts

@@ -0,0 +1,131 @@
+import { camelCase, pascalCase } from '@internals/utils'
+import { isOperationNode, isSchemaNode } from '@kubb/ast'
+import type { Node, OperationNode, SchemaNode } from '@kubb/ast/types'
+import type { PluginFactoryOptions, ResolveNameParams, ResolveOptionsContext } from './types.ts'
+
+/**
+ * Builder type for the plugin-specific resolver fields.
+ * `default`, `resolveOptions`, and `name` are optional — built-in fallbacks are used when omitted.
+ */
+type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'], 'default' | 'resolveOptions' | 'name'> &
+  Partial<Pick<T['resolver'], 'default' | 'resolveOptions'>> & { name: string } & ThisType<T['resolver']>
+
+/**
+ * Checks if an operation matches a pattern for a given filter type (`tag`, `operationId`, `path`, `method`).
+ */
+function matchesOperationPattern(node: OperationNode, type: string, pattern: string | RegExp): boolean {
+  switch (type) {
+    case 'tag':
+      return node.tags.some((tag) => !!tag.match(pattern))
+    case 'operationId':
+      return !!node.operationId.match(pattern)
+    case 'path':
+      return !!node.path.match(pattern)
+    case 'method':
+      return !!(node.method.toLowerCase() as string).match(pattern)
+    default:
+      return false
+  }
+}
+
+/**
+ * Checks if a schema matches a pattern for a given filter type (`schemaName`).
+ * Returns `null` when the filter type doesn't apply to schemas.
+ */
+function matchesSchemaPattern(node: SchemaNode, type: string, pattern: string | RegExp): boolean | null {
+  switch (type) {
+    case 'schemaName':
+      return node.name ? !!node.name.match(pattern) : false
+    default:
+      return null
+  }
+}
+
+/**
+ * Default name resolver — `camelCase` for most types, `PascalCase` for `type`.
+ */
+function defaultResolver(name: ResolveNameParams['name'], type: ResolveNameParams['type']): string {
+  let resolvedName = camelCase(name)
+
+  if (type === 'file' || type === 'function') {
+    resolvedName = camelCase(name, {
+      isFile: type === 'file',
+    })
+  }
+
+  if (type === 'type') {
+    resolvedName = pascalCase(name)
+  }
+
+  return resolvedName
+}
+
+/**
+ * Default option resolver — applies include/exclude filters and merges any matching override options.
+ * Returns `null` when the node is filtered out.
+ */
+export function defaultResolveOptions<TOptions>(
+  node: Node,
+  { options, exclude = [], include, override = [] }: ResolveOptionsContext<TOptions>,
+): TOptions | null {
+  if (isOperationNode(node)) {
+    const isExcluded = exclude.some(({ type, pattern }) => matchesOperationPattern(node, type, pattern))
+    if (isExcluded) {
+      return null
+    }
+
+    if (include && !include.some(({ type, pattern }) => matchesOperationPattern(node, type, pattern))) {
+      return null
+    }
+
+    const overrideOptions = override.find(({ type, pattern }) => matchesOperationPattern(node, type, pattern))?.options
+
+    return { ...options, ...overrideOptions }
+  }
+
+  if (isSchemaNode(node)) {
+    if (exclude.some(({ type, pattern }) => matchesSchemaPattern(node, type, pattern) === true)) {
+      return null
+    }
+
+    if (include) {
+      const results = include.map(({ type, pattern }) => matchesSchemaPattern(node, type, pattern))
+      const applicable = results.filter((r) => r !== null)
+      if (applicable.length > 0 && !applicable.includes(true)) {
+        return null
+      }
+    }
+
+    const overrideOptions = override.find(({ type, pattern }) => matchesSchemaPattern(node, type, pattern) === true)?.options
+
+    return { ...options, ...overrideOptions }
+  }
+
+  return options
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * export const resolver = defineResolver<PluginTs>(() => ({
+ *   name: 'default',
+ *   resolveName(name) {
+ *     return this.default(name, 'function')
+ *   },
+ *   resolveTypedName(name) {
+ *     return this.default(name, 'type')
+ *   },
+ *   resolveParamName(node, param) {
+ *     return this.resolveName(`${node.operationId} ${param.in} ${param.name}`)
+ *   },
+ * }))
+ */
+export function defineResolver<T extends PluginFactoryOptions>(build: ResolverBuilder<T>): T['resolver'] {
+  return {
+    default: defaultResolver,
+    resolveOptions: defaultResolveOptions,
+    ...build(),
+  } as T['resolver']
+}

package/src/hooks/index.ts

@@ -1,3 +1,4 @@
+export { useKubb } from './useKubb.ts'
 export { useMode } from './useMode.ts'
 export { usePlugin } from './usePlugin.ts'
-export { usePluginManager } from './usePluginManager.ts'
+export { usePluginDriver } from './usePluginDriver.ts'

package/src/hooks/useKubb.ts

@@ -0,0 +1,160 @@
+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
+    },
+  }
+}

package/src/hooks/useMode.ts

@@ -1,8 +1,11 @@
 import type { KubbFile } from '@kubb/fabric-core/types'
-import { useApp } from '@kubb/react-fabric'
+import { useFabric } from '@kubb/react-fabric'
 
+/**
+ * @deprecated use `useKubb` instead
+ */
 export function useMode(): KubbFile.Mode {
-  const { meta } = useApp<{ mode: KubbFile.Mode }>()
+  const { meta } = useFabric<{ mode: KubbFile.Mode }>()
 
   return meta.mode
 }

package/src/hooks/usePlugin.ts

@@ -1,8 +1,11 @@
-import { useApp } from '@kubb/react-fabric'
+import { useFabric } from '@kubb/react-fabric'
 import type { Plugin, PluginFactoryOptions } from '../types.ts'
 
+/**
+ * @deprecated use useKubb instead
+ */
 export function usePlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(): Plugin<TOptions> {
-  const { meta } = useApp<{ plugin: Plugin<TOptions> }>()
+  const { meta } = useFabric<{ plugin: Plugin<TOptions> }>()
 
   return meta.plugin
 }

package/src/hooks/usePluginDriver.ts

@@ -0,0 +1,11 @@
+import { useFabric } from '@kubb/react-fabric'
+import type { PluginDriver } from '../PluginDriver.ts'
+
+/**
+ * @deprecated use `useKubb` instead
+ */
+export function usePluginDriver(): PluginDriver {
+  const { meta } = useFabric<{ driver: PluginDriver }>()
+
+  return meta.driver
+}

package/src/index.ts

@@ -3,13 +3,16 @@ export { 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'
-export { defineAdapter } from './defineAdapter.ts'
+export { createAdapter } from './createAdapter.ts'
+export { createPlugin } from './createPlugin.ts'
+export { createStorage } from './createStorage.ts'
+export { defineGenerator } from './defineGenerator.ts'
 export { defineLogger } from './defineLogger.ts'
-export { definePlugin } from './definePlugin.ts'
-export { defineStorage } from './defineStorage.ts'
-export { PackageManager } from './PackageManager.ts'
-export { getMode, PluginManager } from './PluginManager.ts'
-export { PromiseManager } from './PromiseManager.ts'
+export { definePreset } from './definePreset.ts'
+export { definePresets } from './definePresets.ts'
+export { defaultResolveOptions, defineResolver } from './defineResolver.ts'
+export { getMode, PluginDriver } from './PluginDriver.ts'
+export { renderOperation, renderOperations, renderSchema } from './renderNode.tsx'
 export { fsStorage } from './storages/fsStorage.ts'
 export { memoryStorage } from './storages/memoryStorage.ts'
 export * from './types.ts'
@@ -19,4 +22,7 @@ export { detectFormatter } from './utils/formatters.ts'
 export type { FileMetaBase } from './utils/getBarrelFiles.ts'
 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/renderNode.tsx

@@ -0,0 +1,108 @@
+import type { OperationNode, SchemaNode } from '@kubb/ast/types'
+import type { KubbFile } from '@kubb/fabric-core/types'
+import { createReactFabric, Fabric } from '@kubb/react-fabric'
+import type { Fabric as FabricType } from '@kubb/react-fabric/types'
+import type { PluginDriver } from './PluginDriver.ts'
+import type { Adapter, Config, Plugin, PluginFactoryOptions, ReactGeneratorV2 } from './types.ts'
+
+type BuildOperationsV2Options<TOptions extends PluginFactoryOptions> = {
+  config: Config
+  fabric: FabricType
+  plugin: Plugin<TOptions>
+  Component: ReactGeneratorV2<TOptions>['Operations'] | undefined
+  adapter: Adapter
+  driver: PluginDriver
+  mode: KubbFile.Mode
+  options: TOptions['resolvedOptions']
+}
+
+/**
+ * Renders a React component for a list of operation nodes (V2 generators).
+ */
+export async function renderOperations<TOptions extends PluginFactoryOptions>(
+  nodes: Array<OperationNode>,
+  options: BuildOperationsV2Options<TOptions>,
+): Promise<void> {
+  const { config, fabric, plugin, Component, adapter } = options
+
+  if (!Component) {
+    return undefined
+  }
+
+  const fabricChild = createReactFabric()
+
+  await fabricChild.render(
+    <Fabric meta={{ plugin }}>
+      <Component config={config} adapter={adapter} nodes={nodes} options={options.options} />
+    </Fabric>,
+  )
+
+  fabric.context.fileManager.upsert(...fabricChild.files)
+  fabricChild.unmount()
+}
+
+type BuildOperationV2Options<TOptions extends PluginFactoryOptions> = {
+  config: Config
+  fabric: FabricType
+  plugin: Plugin<TOptions>
+  Component: ReactGeneratorV2<TOptions>['Operation'] | undefined
+  adapter: Adapter
+  driver: PluginDriver
+  mode: KubbFile.Mode
+  options: TOptions['resolvedOptions']
+}
+
+/**
+ * Renders a React component for a single operation node (V2 generators).
+ */
+export async function renderOperation<TOptions extends PluginFactoryOptions>(node: OperationNode, options: BuildOperationV2Options<TOptions>): Promise<void> {
+  const { config, fabric, plugin, Component, adapter, driver, mode } = options
+
+  if (!Component) {
+    return undefined
+  }
+
+  const fabricChild = createReactFabric()
+
+  await fabricChild.render(
+    <Fabric meta={{ plugin, driver, mode }}>
+      <Component config={config} adapter={adapter} node={node} options={options.options} />
+    </Fabric>,
+  )
+
+  fabric.context.fileManager.upsert(...fabricChild.files)
+  fabricChild.unmount()
+}
+
+type BuildSchemaV2Options<TOptions extends PluginFactoryOptions> = {
+  config: Config
+  fabric: FabricType
+  plugin: Plugin<TOptions>
+  Component: ReactGeneratorV2<TOptions>['Schema'] | undefined
+  adapter: Adapter
+  driver: PluginDriver
+  mode: KubbFile.Mode
+  options: TOptions['resolvedOptions']
+}
+
+/**
+ * Renders a React component for a single schema node (V2 generators).
+ */
+export async function renderSchema<TOptions extends PluginFactoryOptions>(node: SchemaNode, options: BuildSchemaV2Options<TOptions>): Promise<void> {
+  const { config, fabric, plugin, Component, adapter, driver, mode } = options
+
+  if (!Component) {
+    return undefined
+  }
+
+  const fabricChild = createReactFabric()
+
+  await fabricChild.render(
+    <Fabric meta={{ plugin, driver, mode }}>
+      <Component config={config} adapter={adapter} node={node} options={options.options} />
+    </Fabric>,
+  )
+
+  fabric.context.fileManager.upsert(...fabricChild.files)
+  fabricChild.unmount()
+}

package/src/storages/fsStorage.ts

@@ -2,7 +2,7 @@ import type { Dirent } from 'node:fs'
 import { access, readdir, readFile, rm } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
 import { clean, write } from '@internals/utils'
-import { defineStorage } from '../defineStorage.ts'
+import { createStorage } from '../createStorage.ts'
 
 /**
  * Built-in filesystem storage driver.
@@ -27,7 +27,7 @@ import { defineStorage } from '../defineStorage.ts'
  * })
  * ```
  */
-export const fsStorage = defineStorage(() => ({
+export const fsStorage = createStorage(() => ({
   name: 'fs',
   async hasItem(key: string) {
     try {

package/src/storages/memoryStorage.ts

@@ -1,4 +1,4 @@
-import { defineStorage } from '../defineStorage.ts'
+import { createStorage } from '../createStorage.ts'
 
 /**
  * In-memory storage driver. Useful for testing and dry-run scenarios where
@@ -17,7 +17,7 @@ import { defineStorage } from '../defineStorage.ts'
  * })
  * ```
  */
-export const memoryStorage = defineStorage(() => {
+export const memoryStorage = createStorage(() => {
   const store = new Map<string, string>()
 
   return {