@kubb/core 4.36.1 → 5.0.0-alpha.10

package/src/build.ts

@@ -1,16 +1,14 @@
 import { dirname, relative, resolve } from 'node:path'
-import { AsyncEventEmitter, exists, formatMs, getElapsedMs, getRelativePath, URLPath } from '@internals/utils'
-import type { KubbFile } from '@kubb/fabric-core/types'
-import type { Fabric } from '@kubb/react-fabric'
+import { AsyncEventEmitter, BuildError, exists, formatMs, getElapsedMs, getRelativePath, URLPath } from '@internals/utils'
+import type { Fabric as FabricType, KubbFile } 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'
 import { isInputPath } from './config.ts'
 import { BARREL_FILENAME, DEFAULT_BANNER, DEFAULT_CONCURRENCY, DEFAULT_EXTENSION, DEFAULT_STUDIO_URL } from './constants.ts'
-import { BuildError } from './errors.ts'
-import { PluginManager } from './PluginManager.ts'
+import { PluginDriver } from './PluginDriver.ts'
 import { fsStorage } from './storages/fsStorage.ts'
-import type { AdapterSource, Config, DefineStorage, KubbEvents, Output, Plugin, UserConfig } from './types.ts'
+import type { AdapterSource, Config, KubbEvents, Output, Plugin, Storage, UserConfig } from './types.ts'
 import { getDiagnosticInfo } from './utils/diagnostics.ts'
 import type { FileMetaBase } from './utils/getBarrelFiles.ts'
 
@@ -21,9 +19,9 @@ type BuildOptions = {
 
 type BuildOutput = {
   failedPlugins: Set<{ plugin: Plugin; error: Error }>
-  fabric: Fabric
+  fabric: FabricType
   files: Array<KubbFile.ResolvedFile>
-  pluginManager: PluginManager
+  driver: PluginDriver
   pluginTimings: Map<string, number>
   error?: Error
   sources: Map<KubbFile.Path, string>
@@ -31,8 +29,8 @@ type BuildOutput = {
 
 type SetupResult = {
   events: AsyncEventEmitter<KubbEvents>
-  fabric: Fabric
-  pluginManager: PluginManager
+  fabric: FabricType
+  driver: PluginDriver
   sources: Map<KubbFile.Path, string>
 }
 
@@ -110,7 +108,7 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
   // storage or fall back to fsStorage (backwards-compatible default).
   // Keys are root-relative (e.g. `src/gen/api/getPets.ts`) so fsStorage()
   // needs no configuration — it resolves them against process.cwd().
-  const storage: DefineStorage | null = definedConfig.output.write === false ? null : (definedConfig.output.storage ?? fsStorage())
+  const storage: Storage | null = definedConfig.output.write === false ? null : (definedConfig.output.storage ?? fsStorage())
 
   if (definedConfig.output.clean) {
     await events.emit('debug', {
@@ -165,7 +163,7 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
     ],
   })
 
-  const pluginManager = new PluginManager(definedConfig, {
+  const pluginDriver = new PluginDriver(definedConfig, {
     fabric,
     events,
     concurrency: DEFAULT_CONCURRENCY,
@@ -180,14 +178,15 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
       logs: [`Running adapter: ${definedConfig.adapter.name}`],
     })
 
-    pluginManager.rootNode = await definedConfig.adapter.parse(source)
+    pluginDriver.adapter = definedConfig.adapter
+    pluginDriver.rootNode = await definedConfig.adapter.parse(source)
 
     await events.emit('debug', {
       date: new Date(),
       logs: [
         `✓ Adapter '${definedConfig.adapter.name}' resolved RootNode`,
-        `  • Schemas: ${pluginManager.rootNode.schemas.length}`,
-        `  • Operations: ${pluginManager.rootNode.operations.length}`,
+        `  • Schemas: ${pluginDriver.rootNode.schemas.length}`,
+        `  • Operations: ${pluginDriver.rootNode.operations.length}`,
       ],
     })
   }
@@ -195,13 +194,13 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
   return {
     events,
     fabric,
-    pluginManager,
+    driver: pluginDriver,
     sources,
   }
 }
 
 export async function build(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput> {
-  const { fabric, files, pluginManager, failedPlugins, pluginTimings, error, sources } = await safeBuild(options, overrides)
+  const { fabric, files, driver, failedPlugins, pluginTimings, error, sources } = await safeBuild(options, overrides)
 
   if (error) {
     throw error
@@ -217,7 +216,7 @@ export async function build(options: BuildOptions, overrides?: SetupResult): Pro
     failedPlugins,
     fabric,
     files,
-    pluginManager,
+    driver,
     pluginTimings,
     error: undefined,
     sources,
@@ -225,16 +224,16 @@ export async function build(options: BuildOptions, overrides?: SetupResult): Pro
 }
 
 export async function safeBuild(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput> {
-  const { fabric, pluginManager, events, sources } = overrides ? overrides : await setup(options)
+  const { fabric, driver, events, sources } = overrides ? overrides : await setup(options)
 
   const failedPlugins = new Set<{ plugin: Plugin; error: Error }>()
   // in ms
   const pluginTimings = new Map<string, number>()
-  const config = pluginManager.config
+  const config = driver.config
 
   try {
-    for (const plugin of pluginManager.plugins) {
-      const context = pluginManager.getContext(plugin)
+    for (const plugin of driver.plugins) {
+      const context = driver.getContext(plugin)
       const hrStart = process.hrtime()
 
       const installer = plugin.install.bind(context)
@@ -246,7 +245,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
 
         await events.emit('debug', {
           date: timestamp,
-          logs: ['Installing plugin...', `  • Plugin Key: [${plugin.key.join(', ')}]`],
+          logs: ['Installing plugin...', `  • Plugin Name: ${plugin.name}`],
         })
 
         await installer(context)
@@ -275,7 +274,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
           date: errorTimestamp,
           logs: [
             '✗ Plugin installation failed',
-            `  • Plugin Key: ${JSON.stringify(plugin.key)}`,
+            `  • Plugin Name: ${plugin.name}`,
             `  • Error: ${error.constructor.name} - ${error.message}`,
             '  • Stack Trace:',
             error.stack || 'No stack trace available',
@@ -313,7 +312,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       const rootFile: KubbFile.File = {
         path: rootPath,
         baseName: BARREL_FILENAME,
-        exports: buildBarrelExports({ barrelFiles, rootDir, existingExports, config, pluginManager }),
+        exports: buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }),
         sources: [],
         imports: [],
         meta: {},
@@ -335,7 +334,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       failedPlugins,
       fabric,
       files,
-      pluginManager,
+      driver,
       pluginTimings,
       sources,
     }
@@ -344,7 +343,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       failedPlugins,
       fabric,
       files: [],
-      pluginManager,
+      driver,
       pluginTimings,
       error: error as Error,
       sources,
@@ -357,13 +356,13 @@ type BuildBarrelExportsParams = {
   rootDir: string
   existingExports: Set<string>
   config: Config
-  pluginManager: PluginManager
+  driver: PluginDriver
 }
 
-function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, pluginManager }: BuildBarrelExportsParams): KubbFile.Export[] {
-  const pluginKeyMap = new Map<string, Plugin>()
-  for (const plugin of pluginManager.plugins) {
-    pluginKeyMap.set(JSON.stringify(plugin.key), plugin)
+function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, driver }: BuildBarrelExportsParams): KubbFile.Export[] {
+  const pluginNameMap = new Map<string, Plugin>()
+  for (const plugin of driver.plugins) {
+    pluginNameMap.set(plugin.name, plugin)
   }
 
   return barrelFiles.flatMap((file) => {
@@ -375,7 +374,7 @@ function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, plu
       }
 
       const meta = file.meta as FileMetaBase | undefined
-      const plugin = meta?.pluginKey ? pluginKeyMap.get(JSON.stringify(meta.pluginKey)) : undefined
+      const plugin = meta?.pluginName ? pluginNameMap.get(meta.pluginName) : undefined
       const pluginOptions = plugin?.options as { output?: Output<unknown> } | undefined
 
       if (!pluginOptions || pluginOptions.output?.barrelType === false) {

package/src/constants.ts

@@ -14,7 +14,7 @@ export const DEFAULT_BANNER = 'simple' as const
 
 export const DEFAULT_EXTENSION: Record<KubbFile.Extname, KubbFile.Extname | ''> = { '.ts': '.ts' }
 
-export const PATH_SEPARATORS = ['/', '\\'] as const
+export const PATH_SEPARATORS = new Set(['/', '\\'] as const)
 
 export const logLevel = {
   silent: Number.NEGATIVE_INFINITY,

package/src/createAdapter.ts

@@ -0,0 +1,25 @@
+import type { Adapter, AdapterFactoryOptions } from './types.ts'
+
+/**
+ * Builder type for an {@link Adapter} — takes options and returns the adapter instance.
+ */
+type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>
+
+/**
+ * Creates an adapter factory. Call the returned function with optional options to get the adapter instance.
+ *
+ * @example
+ * export const myAdapter = createAdapter<MyAdapter>((options) => {
+ *   return {
+ *     name: 'my-adapter',
+ *     options,
+ *     async parse(source) { ... },
+ *   }
+ * })
+ *
+ * // instantiate
+ * const adapter = myAdapter({ validate: true })
+ */
+export function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T> {
+  return (options) => build(options ?? ({} as T['options']))
+}

package/src/createPlugin.ts

@@ -0,0 +1,28 @@
+import type { PluginFactoryOptions, UserPluginWithLifeCycle } from './types.ts'
+
+/**
+ * Builder type for a {@link UserPluginWithLifeCycle} — takes options and returns the plugin instance.
+ */
+type PluginBuilder<T extends PluginFactoryOptions = PluginFactoryOptions> = (options: T['options']) => UserPluginWithLifeCycle<T>
+
+/**
+ * Creates a plugin factory. Call the returned function with optional options to get the plugin instance.
+ *
+ * @example
+ * export const myPlugin = createPlugin<MyPlugin>((options) => {
+ *   return {
+ *     name: 'my-plugin',
+ *     options,
+ *     resolvePath(baseName) { ... },
+ *     resolveName(name, type) { ... },
+ *   }
+ * })
+ *
+ * // instantiate
+ * const plugin = myPlugin({ output: { path: 'src/gen' } })
+ */
+export function createPlugin<T extends PluginFactoryOptions = PluginFactoryOptions>(
+  build: PluginBuilder<T>,
+): (options?: T['options']) => UserPluginWithLifeCycle<T> {
+  return (options) => build(options ?? ({} as T['options']))
+}

package/src/createStorage.ts

@@ -0,0 +1,58 @@
+export type Storage = {
+  /**
+   * Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`).
+   */
+  readonly name: string
+  /**
+   * Returns `true` when an entry for `key` exists in storage.
+   */
+  hasItem(key: string): Promise<boolean>
+  /**
+   * Returns the stored string value, or `null` when `key` does not exist.
+   */
+  getItem(key: string): Promise<string | null>
+  /**
+   * Persists `value` under `key`, creating any required structure.
+   */
+  setItem(key: string, value: string): Promise<void>
+  /**
+   *  Removes the entry for `key`. No-ops when the key does not exist.
+   */
+  removeItem(key: string): Promise<void>
+  /**
+   * Returns all keys, optionally filtered to those starting with `base`.
+   */
+  getKeys(base?: string): Promise<Array<string>>
+  /**
+   * Removes all entries, optionally scoped to those starting with `base`.
+   */
+  clear(base?: string): Promise<void>
+  /**
+   * Optional teardown hook called after the build completes.
+   */
+  dispose?(): Promise<void>
+}
+
+/**
+ * Creates a storage factory. Call the returned function with optional options to get the storage instance.
+ *
+ * @example
+ * export const memoryStorage = createStorage(() => {
+ *   const store = new Map<string, string>()
+ *   return {
+ *     name: 'memory',
+ *     async hasItem(key) { return store.has(key) },
+ *     async getItem(key) { return store.get(key) ?? null },
+ *     async setItem(key, value) { store.set(key, value) },
+ *     async removeItem(key) { store.delete(key) },
+ *     async getKeys(base) {
+ *       const keys = [...store.keys()]
+ *       return base ? keys.filter((k) => k.startsWith(base)) : keys
+ *     },
+ *     async clear(base) { if (!base) store.clear() },
+ *   }
+ * })
+ */
+export function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage {
+  return (options) => build(options ?? ({} as TOptions))
+}

package/src/defineGenerator.ts

@@ -0,0 +1,134 @@
+import type { OperationNode, SchemaNode } from '@kubb/ast/types'
+import type { KubbFile } from '@kubb/fabric-core/types'
+import type { FabricReactNode } from '@kubb/react-fabric/types'
+import type { Adapter, Config, Plugin, PluginFactoryOptions } from './types.ts'
+
+export type Version = '1' | '2'
+
+/**
+ * Props for the `operations` lifecycle — receives all operation nodes at once.
+ */
+export type OperationsV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config
+  adapter: Adapter
+  options: Plugin<TPlugin>['options']
+  nodes: Array<OperationNode>
+}
+
+/**
+ * Props for the `operation` lifecycle — receives a single operation node.
+ */
+export type OperationV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config
+  adapter: Adapter
+  options: Plugin<TPlugin>['options']
+  node: OperationNode
+}
+
+/**
+ * Props for the `schema` lifecycle — receives a single schema node.
+ */
+export type SchemaV2Props<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  config: Config
+  adapter: Adapter
+  options: Plugin<TPlugin>['options']
+  node: SchemaNode
+}
+
+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>>
+}
+
+type UserReactGeneratorV2<TPlugin extends PluginFactoryOptions> = {
+  name: string
+  type: 'react'
+  version?: '2'
+  Operations?(props: OperationsV2Props<TPlugin>): FabricReactNode
+  Operation?(props: OperationV2Props<TPlugin>): FabricReactNode
+  Schema?(props: SchemaV2Props<TPlugin>): FabricReactNode
+}
+
+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>>
+}
+
+export type ReactGeneratorV2<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = {
+  name: string
+  type: 'react'
+  version: '2'
+  Operations(props: OperationsV2Props<TPlugin>): FabricReactNode
+  Operation(props: OperationV2Props<TPlugin>): FabricReactNode
+  Schema(props: SchemaV2Props<TPlugin>): FabricReactNode
+}
+
+export type Generator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions> = UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>
+
+/**
+ * Defines a generator with no-op defaults for any omitted lifecycle methods.
+ * Works for both `core` (async file output) and `react` (JSX component) generators.
+ *
+ * @example
+ * // react generator
+ * export const typeGenerator = defineGenerator<PluginTs>({
+ *   name: 'typescript',
+ *   type: 'react',
+ *   Operation({ node, options }) { return <File>...</File> },
+ *   Schema({ node, options }) { return <File>...</File> },
+ * })
+ *
+ * @example
+ * // core generator
+ * export const myGenerator = defineGenerator<MyPlugin>({
+ *   name: 'my-generator',
+ *   type: 'core',
+ *   async operation({ node, options }) { return [{ path: '...', content: '...' }] },
+ * })
+ */
+export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(
+  generator: UserReactGeneratorV2<TPlugin>,
+): ReactGeneratorV2<TPlugin>
+
+export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(generator: UserCoreGeneratorV2<TPlugin>): CoreGeneratorV2<TPlugin>
+export function defineGenerator<TPlugin extends PluginFactoryOptions = PluginFactoryOptions>(
+  generator: UserCoreGeneratorV2<TPlugin> | UserReactGeneratorV2<TPlugin>,
+): unknown {
+  if (generator.type === 'react') {
+    return {
+      version: '2',
+      Operations() {
+        return null
+      },
+      Operation() {
+        return null
+      },
+      Schema() {
+        return null
+      },
+      ...generator,
+    }
+  }
+
+  return {
+    version: '2',
+    async operations() {
+      return []
+    },
+    async operation() {
+      return []
+    },
+    async schema() {
+      return []
+    },
+    ...generator,
+  }
+}

package/src/defineLogger.ts

@@ -1,7 +1,17 @@
 import type { Logger, LoggerOptions, UserLogger } from './types.ts'
 
+/**
+ * Wraps a logger definition into a typed {@link Logger}.
+ *
+ * @example
+ * export const myLogger = defineLogger({
+ *   name: 'my-logger',
+ *   install(context, options) {
+ *     context.on('info', (message) => console.log('ℹ', message))
+ *     context.on('error', (error) => console.error('✗', error.message))
+ *   },
+ * })
+ */
 export function defineLogger<Options extends LoggerOptions = LoggerOptions>(logger: UserLogger<Options>): Logger<Options> {
-  return {
-    ...logger,
-  }
+  return logger
 }

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` and `resolveOptions` are optional — built-in fallbacks are used when omitted.
+ */
+type ResolverBuilder<T extends PluginFactoryOptions> = () => Omit<T['resolver'], 'default' | 'resolveOptions'> &
+  Partial<Pick<T['resolver'], 'default' | 'resolveOptions'>> &
+  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>(() => ({
+ *   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'