@kubb/core 5.0.0-alpha.34 → 5.0.0-alpha.36

package/src/{build.ts → createKubb.ts}

@@ -1,28 +1,31 @@
 import { dirname, resolve } from 'node:path'
 import { AsyncEventEmitter, BuildError, exists, formatMs, getElapsedMs, getRelativePath, URLPath } from '@internals/utils'
+import type { ExportNode, FileNode, OperationNode } from '@kubb/ast'
 import { createExport, createFile, transform, walk } from '@kubb/ast'
-import type { ExportNode, FileNode, OperationNode } from '@kubb/ast/types'
 import { BARREL_FILENAME, DEFAULT_BANNER, DEFAULT_CONCURRENCY, DEFAULT_EXTENSION, DEFAULT_STUDIO_URL } from './constants.ts'
+import type { RendererFactory } from './createRenderer.ts'
+import type { Generator } from './defineGenerator.ts'
 import type { Parser } from './defineParser.ts'
 import { FileProcessor } from './FileProcessor.ts'
+import type { Kubb } from './Kubb.ts'
 import { PluginDriver } from './PluginDriver.ts'
-import { applyHookResult } from './renderNode.tsx'
+import { applyHookResult } from './renderNode.ts'
 import { fsStorage } from './storages/fsStorage.ts'
-import type { AdapterSource, Config, KubbEvents, Plugin, PluginContext, Storage, UserConfig } from './types.ts'
+import type { AdapterSource, Config, GeneratorContext, KubbHooks, Plugin, PluginContext, Storage } from './types.ts'
 import { getDiagnosticInfo } from './utils/diagnostics.ts'
 import type { FileMetaBase } from './utils/getBarrelFiles.ts'
 import { getBarrelFiles } from './utils/getBarrelFiles.ts'
 import { isInputPath } from './utils/isInputPath.ts'
 
 type BuildOptions = {
-  config: UserConfig
-  events?: AsyncEventEmitter<KubbEvents>
+  config: Config
+  hooks?: AsyncEventEmitter<KubbHooks>
 }
 
 /**
  * Full output produced by a successful or failed build.
  */
-type BuildOutput = {
+export type BuildOutput = {
   /**
    * Plugins that threw during installation, paired with the caught error.
    */
@@ -40,39 +43,26 @@ type BuildOutput = {
   sources: Map<string, string>
 }
 
-/**
- * Intermediate result returned by {@link setup} and accepted by {@link safeBuild}.
- */
 type SetupResult = {
-  events: AsyncEventEmitter<KubbEvents>
+  hooks: AsyncEventEmitter<KubbHooks>
   driver: PluginDriver
   sources: Map<string, string>
   config: Config
   storage: Storage | null
 }
 
-/**
- * Initializes all Kubb infrastructure for a build without executing any plugins.
- *
- * - Validates the input path (when applicable).
- * - Applies config defaults (`root`, `output.*`, `devtools`).
- * - Runs the adapter (if configured) to produce the universal `InputNode`.
- *   When no adapter is supplied and `@kubb/adapter-oas` is installed as an
- *
- * Pass the returned {@link SetupResult} directly to {@link safeBuild} or {@link build}
- * via the `overrides` argument to reuse the same infrastructure across multiple runs.
- */
-export async function setup(options: BuildOptions): Promise<SetupResult> {
-  const { config: userConfig, events = new AsyncEventEmitter<KubbEvents>() } = options
+async function setup(options: BuildOptions): Promise<SetupResult> {
+  const { config: userConfig } = options
+  const hooks = options.hooks ?? new AsyncEventEmitter<KubbHooks>()
 
   const sources: Map<string, string> = new Map<string, string>()
   const diagnosticInfo = getDiagnosticInfo()
 
   if (Array.isArray(userConfig.input)) {
-    await events.emit('warn', 'This feature is still under development — use with caution')
+    await hooks.emit('kubb:warn', 'This feature is still under development — use with caution')
   }
 
-  await events.emit('debug', {
+  await hooks.emit('kubb:debug', {
     date: new Date(),
     logs: [
       'Configuration:',
@@ -95,7 +85,7 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
     if (isInputPath(userConfig) && !new URLPath(userConfig.input.path).isURL) {
       await exists(userConfig.input.path)
 
-      await events.emit('debug', {
+      await hooks.emit('kubb:debug', {
         date: new Date(),
         logs: [`✓ Input file validated: ${userConfig.input.path}`],
       })
@@ -118,8 +108,8 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
   }
 
   const config: Config = {
-    root: userConfig.root || process.cwd(),
     ...userConfig,
+    root: userConfig.root || process.cwd(),
     parsers: userConfig.parsers ?? [],
     adapter: userConfig.adapter,
     output: {
@@ -135,17 +125,13 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
           ...(typeof userConfig.devtools === 'boolean' ? {} : userConfig.devtools),
         }
       : undefined,
-    plugins: userConfig.plugins as Config['plugins'],
+    plugins: userConfig.plugins as unknown as Config['plugins'],
   }
 
-  // write: false is the explicit dry-run opt-out; otherwise use the provided
-  // storage or fall back to fsStorage (backwards-compatible default).
-  // Storage keys are the absolute file.path values so fsStorage() resolves
-  // them correctly regardless of the current working directory.
   const storage: Storage | null = config.output.write === false ? null : (config.output.storage ?? fsStorage())
 
   if (config.output.clean) {
-    await events.emit('debug', {
+    await hooks.emit('kubb:debug', {
       date: new Date(),
       logs: ['Cleaning output directories', `  • Output: ${config.output.path}`],
     })
@@ -153,19 +139,17 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
   }
 
   const driver = new PluginDriver(config, {
-    events,
+    hooks,
     concurrency: DEFAULT_CONCURRENCY,
   })
 
-  // Run the adapter to produce the universal InputNode.
-
   const adapter = config.adapter
   if (!adapter) {
     throw new Error('No adapter configured. Please provide an adapter in your kubb.config.ts.')
   }
   const source = inputToAdapterSource(config)
 
-  await events.emit('debug', {
+  await hooks.emit('kubb:debug', {
     date: new Date(),
     logs: [`Running adapter: ${adapter.name}`],
   })
@@ -173,7 +157,7 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
   driver.adapter = adapter
   driver.inputNode = await adapter.parse(source)
 
-  await events.emit('debug', {
+  await hooks.emit('kubb:debug', {
     date: new Date(),
     logs: [
       `✓ Adapter '${adapter.name}' resolved InputNode`,
@@ -184,51 +168,16 @@ export async function setup(options: BuildOptions): Promise<SetupResult> {
 
   return {
     config,
-    events,
+    hooks,
     driver,
     sources,
     storage,
   }
 }
 
-/**
- * Runs a full Kubb build and throws on any error or plugin failure.
- *
- * Internally delegates to {@link safeBuild} and rethrows collected errors.
- * Pass an existing {@link SetupResult} via `overrides` to skip the setup phase.
- */
-export async function build(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput> {
-  const { files, driver, failedPlugins, pluginTimings, error, sources } = await safeBuild(options, overrides)
-
-  if (error) {
-    throw error
-  }
-
-  if (failedPlugins.size > 0) {
-    const errors = [...failedPlugins].map(({ error }) => error)
-
-    throw new BuildError(`Build Error with ${failedPlugins.size} failed plugins`, { errors })
-  }
-
-  return {
-    failedPlugins,
-    files,
-    driver,
-    pluginTimings,
-    error: undefined,
-    sources,
-  }
-}
-
 /**
  * Walks the AST and dispatches nodes to a plugin's direct AST hooks
  * (`schema`, `operation`, `operations`).
- *
- * - Each hook accepts a single handler **or an array** — all entries are called in sequence.
- * - Nodes that are excluded by `exclude`/`include` plugin options are skipped automatically.
- * - Return values are handled via `applyHookResult`: React elements are rendered,
- *   `FileNode[]` are written via upsert, and `void` is a no-op (manual handling).
- * - Barrel files are generated automatically when `output.barrelType` is set.
  */
 async function runPluginAstHooks(plugin: Plugin, context: PluginContext): Promise<void> {
   const { adapter, inputNode, resolver, driver } = context
@@ -238,59 +187,87 @@ async function runPluginAstHooks(plugin: Plugin, context: PluginContext): Promis
     throw new Error(`[${plugin.name}] No adapter found. Add an OAS adapter (e.g. pluginOas()) before this plugin in your Kubb config.`)
   }
 
+  function resolveRenderer(gen: Generator<any>): RendererFactory | undefined {
+    return gen.renderer === null ? undefined : (gen.renderer ?? plugin.renderer ?? context.config.renderer)
+  }
+
+  const generators = plugin.generators ?? []
   const collectedOperations: Array<OperationNode> = []
 
+  const baseGeneratorContext = context as GeneratorContext
+  const generatorContext = {
+    ...baseGeneratorContext,
+    resolver: driver.getResolver(plugin.name),
+  }
+
   await walk(inputNode, {
     depth: 'shallow',
     async schema(node) {
-      if (!plugin.schema) return
       const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node
       const options = resolver.resolveOptions(transformedNode, { options: plugin.options, exclude, include, override })
       if (options === null) return
-      const result = await plugin.schema.call(context, transformedNode, options)
 
-      await applyHookResult(result, driver)
+      const ctx = { ...generatorContext, options }
+
+      for (const gen of generators) {
+        if (!gen.schema) continue
+        const result = await gen.schema(transformedNode, ctx)
+        await applyHookResult(result, driver, resolveRenderer(gen))
+      }
+
+      await driver.hooks.emit('kubb:generate:schema', transformedNode, ctx)
     },
     async operation(node) {
       const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node
       const options = resolver.resolveOptions(transformedNode, { options: plugin.options, exclude, include, override })
       if (options !== null) {
         collectedOperations.push(transformedNode)
-        if (plugin.operation) {
-          const result = await plugin.operation.call(context, transformedNode, options)
-          await applyHookResult(result, driver)
+
+        const ctx = { ...generatorContext, options }
+
+        for (const gen of generators) {
+          if (!gen.operation) continue
+          const result = await gen.operation(transformedNode, ctx)
+          await applyHookResult(result, driver, resolveRenderer(gen))
         }
+
+        await driver.hooks.emit('kubb:generate:operation', transformedNode, ctx)
       }
     },
   })
 
-  if (plugin.operations && collectedOperations.length > 0) {
-    const result = await plugin.operations.call(context, collectedOperations, plugin.options)
+  if (collectedOperations.length > 0) {
+    const ctx = { ...generatorContext, options: plugin.options }
 
-    await applyHookResult(result, driver)
+    for (const gen of generators) {
+      if (!gen.operations) continue
+      const result = await gen.operations(collectedOperations, ctx)
+      await applyHookResult(result, driver, resolveRenderer(gen))
+    }
+
+    await driver.hooks.emit('kubb:generate:operations', collectedOperations, ctx)
   }
 }
 
-/**
- * Runs a full Kubb build and captures errors instead of throwing.
- *
- * - Installs each plugin in order, recording failures in `failedPlugins`.
- * - Generates the root barrel file when `output.barrelType` is set.
- * - Writes all files through the driver's FileManager and FileProcessor.
- *
- * Returns a {@link BuildOutput} even on failure — inspect `error` and
- * `failedPlugins` to determine whether the build succeeded.
- */
-export async function safeBuild(options: BuildOptions, overrides?: SetupResult): Promise<BuildOutput> {
-  const setupResult = overrides ? overrides : await setup(options)
-  const { driver, events, sources, storage } = setupResult
+async function safeBuild(setupResult: SetupResult): Promise<BuildOutput> {
+  const { driver, hooks, sources, storage } = setupResult
 
   const failedPlugins = new Set<{ plugin: Plugin; error: Error }>()
-  // in ms
   const pluginTimings = new Map<string, number>()
   const config = driver.config
 
   try {
+    await driver.emitSetupHooks()
+
+    if (driver.adapter && driver.inputNode) {
+      await hooks.emit('kubb:build:start', {
+        config,
+        adapter: driver.adapter,
+        inputNode: driver.inputNode,
+        getPlugin: (name) => driver.getPlugin(name),
+      })
+    }
+
     for (const plugin of driver.plugins.values()) {
       const context = driver.getContext(plugin)
       const hrStart = process.hrtime()
@@ -300,18 +277,16 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       try {
         const timestamp = new Date()
 
-        await events.emit('plugin:start', plugin)
+        await hooks.emit('kubb:plugin:start', plugin)
 
-        await events.emit('debug', {
+        await hooks.emit('kubb:debug', {
           date: timestamp,
           logs: ['Starting plugin...', `  • Plugin Name: ${plugin.name}`],
         })
 
-        // Call buildStart() for any custom plugin logic
         await plugin.buildStart.call(context)
 
-        // Dispatch schema/operation/operations hooks (direct hooks or composed via composeGenerators)
-        if (plugin.schema || plugin.operation || plugin.operations) {
+        if (plugin.generators?.length || driver.hasRegisteredGenerators(plugin.name)) {
           await runPluginAstHooks(plugin, context)
         }
 
@@ -328,9 +303,9 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
         const duration = getElapsedMs(hrStart)
         pluginTimings.set(plugin.name, duration)
 
-        await events.emit('plugin:end', plugin, { duration, success: true })
+        await hooks.emit('kubb:plugin:end', plugin, { duration, success: true })
 
-        await events.emit('debug', {
+        await hooks.emit('kubb:debug', {
           date: new Date(),
           logs: [`✓ Plugin started successfully (${formatMs(duration)})`],
         })
@@ -339,13 +314,13 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
         const errorTimestamp = new Date()
         const duration = getElapsedMs(hrStart)
 
-        await events.emit('plugin:end', plugin, {
+        await hooks.emit('kubb:plugin:end', plugin, {
           duration,
           success: false,
           error,
         })
 
-        await events.emit('debug', {
+        await hooks.emit('kubb:debug', {
           date: errorTimestamp,
           logs: [
             '✗ Plugin start failed',
@@ -365,7 +340,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       const rootPath = resolve(root, config.output.path, BARREL_FILENAME)
       const rootDir = dirname(rootPath)
 
-      await events.emit('debug', {
+      await hooks.emit('kubb:debug', {
         date: new Date(),
         logs: ['Generating barrel file', `  • Type: ${config.output.barrelType}`, `  • Path: ${rootPath}`],
       })
@@ -374,7 +349,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
         return file.sources.some((source) => source.isIndexable)
       })
 
-      await events.emit('debug', {
+      await hooks.emit('kubb:debug', {
         date: new Date(),
         logs: [`Found ${barrelFiles.length} indexable files for barrel export`],
       })
@@ -395,7 +370,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
 
       driver.fileManager.upsert(rootFile)
 
-      await events.emit('debug', {
+      await hooks.emit('kubb:debug', {
         date: new Date(),
         logs: [`✓ Generated barrel file (${rootFile.exports?.length || 0} exports)`],
       })
@@ -403,7 +378,6 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
 
     const files = driver.fileManager.files
 
-    // Build a parsers map from config.parsers
     const parsersMap = new Map<FileNode['extname'], Parser>()
     for (const parser of config.parsers) {
       if (parser.extNames) {
@@ -415,7 +389,7 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
 
     const fileProcessor = new FileProcessor()
 
-    await events.emit('debug', {
+    await hooks.emit('kubb:debug', {
       date: new Date(),
       logs: [`Writing ${files.length} files...`],
     })
@@ -424,10 +398,10 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       parsers: parsersMap,
       extension: config.output.extension,
       onStart: async (processingFiles) => {
-        await events.emit('files:processing:start', processingFiles)
+        await hooks.emit('kubb:files:processing:start', processingFiles)
       },
       onUpdate: async ({ file, source, processed, total, percentage }) => {
-        await events.emit('file:processing:update', {
+        await hooks.emit('kubb:file:processing:update', {
           file,
           source,
           processed,
@@ -436,22 +410,19 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
           config,
         })
         if (source) {
-          // Use the absolute file.path as the storage key so fsStorage resolves
-          // it correctly regardless of the current working directory.
           await storage?.setItem(file.path, source)
           sources.set(file.path, source)
         }
       },
       onEnd: async (processedFiles) => {
-        await events.emit('files:processing:end', processedFiles)
-        await events.emit('debug', {
+        await hooks.emit('kubb:files:processing:end', processedFiles)
+        await hooks.emit('kubb:debug', {
           date: new Date(),
           logs: [`✓ File write process completed for ${processedFiles.length} files`],
         })
       },
     })
 
-    // Call buildEnd() on each plugin after all files are written
     for (const plugin of driver.plugins.values()) {
       if (plugin.buildEnd) {
         const context = driver.getContext(plugin)
@@ -459,6 +430,12 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       }
     }
 
+    await hooks.emit('kubb:build:end', {
+      files,
+      config,
+      outputDir: resolve(config.root, config.output.path),
+    })
+
     return {
       failedPlugins,
       files,
@@ -475,6 +452,31 @@ export async function safeBuild(options: BuildOptions, overrides?: SetupResult):
       error: error as Error,
       sources,
     }
+  } finally {
+    driver.dispose()
+  }
+}
+
+async function build(setupResult: SetupResult): Promise<BuildOutput> {
+  const { files, driver, failedPlugins, pluginTimings, error, sources } = await safeBuild(setupResult)
+
+  if (error) {
+    throw error
+  }
+
+  if (failedPlugins.size > 0) {
+    const errors = [...failedPlugins].map(({ error }) => error)
+
+    throw new BuildError(`Build Error with ${failedPlugins.size} failed plugins`, { errors })
+  }
+
+  return {
+    failedPlugins,
+    files,
+    driver,
+    pluginTimings,
+    error: undefined,
+    sources,
   }
 }
 
@@ -524,10 +526,6 @@ function buildBarrelExports({ barrelFiles, rootDir, existingExports, config, dri
   })
 }
 
-/**
- * Maps the resolved `Config['input']` shape into an `AdapterSource` that
- * the adapter's `parse()` can consume.
- */
 function inputToAdapterSource(config: Config): AdapterSource {
   if (Array.isArray(config.input)) {
     return {
@@ -547,3 +545,63 @@ function inputToAdapterSource(config: Config): AdapterSource {
   const resolved = resolve(config.root, config.input.path)
   return { type: 'path', path: resolved }
 }
+
+type KubbOptions = {
+  config: Config
+  hooks?: AsyncEventEmitter<KubbHooks>
+}
+
+/**
+ * Creates a Kubb instance bound to a single config entry.
+ *
+ * The instance holds shared state (`hooks`, `sources`, `driver`, `config`) across the
+ * `setup → build` lifecycle. Attach event listeners to `kubb.hooks` before
+ * calling `setup()` or `build()`.
+ *
+ * @example
+ * ```ts
+ * const kubb = createKubb({ config })
+ *
+ * kubb.hooks.on('kubb:plugin:end', (plugin, { duration }) => {
+ *   console.log(`${plugin.name} completed in ${duration}ms`)
+ * })
+ *
+ * const { files, failedPlugins } = await kubb.safeBuild()
+ * ```
+ */
+export function createKubb(options: KubbOptions): Kubb {
+  const hooks = options.hooks ?? new AsyncEventEmitter<KubbHooks>()
+  let setupResult: SetupResult | undefined
+
+  const instance: Kubb = {
+    get hooks() {
+      return hooks
+    },
+    get sources() {
+      return setupResult?.sources ?? new Map()
+    },
+    get driver() {
+      return setupResult?.driver
+    },
+    get config() {
+      return setupResult?.config
+    },
+    async setup() {
+      setupResult = await setup({ config: options.config, hooks })
+    },
+    async build() {
+      if (!setupResult) {
+        await instance.setup()
+      }
+      return build(setupResult!)
+    },
+    async safeBuild() {
+      if (!setupResult) {
+        await instance.setup()
+      }
+      return safeBuild(setupResult!)
+    },
+  }
+
+  return instance
+}

package/src/createPlugin.ts

@@ -22,6 +22,7 @@ type PluginBuilder<T extends PluginFactoryOptions = PluginFactoryOptions> = (opt
  * // instantiate
  * const plugin = myPlugin({ output: { path: 'src/gen' } })
  * ```
+ * @deprecated use definePlugin instead
  */
 export function createPlugin<T extends PluginFactoryOptions = PluginFactoryOptions>(
   build: PluginBuilder<T>,

package/src/createRenderer.ts

@@ -0,0 +1,57 @@
+import type { FileNode } from '@kubb/ast'
+
+/**
+ * Minimal interface any Kubb renderer must satisfy.
+ *
+ * The generic `TElement` is the type of the element the renderer accepts —
+ * e.g. `KubbReactElement` for `@kubb/renderer-jsx`, or a custom type for
+ * your own renderer.  Defaults to `unknown` so that generators which do not
+ * care about the element type continue to work without specifying it.
+ *
+ * This allows core to drive rendering without a hard dependency on
+ * `@kubb/renderer-jsx` or any specific renderer implementation.
+ */
+export type Renderer<TElement = unknown> = {
+  render(element: TElement): Promise<void>
+  unmount(error?: Error | number | null): void
+  readonly files: Array<FileNode>
+}
+
+/**
+ * A factory function that produces a fresh {@link Renderer} per render.
+ *
+ * Generators use this to declare which renderer handles their output.
+ */
+export type RendererFactory<TElement = unknown> = () => Renderer<TElement>
+
+/**
+ * Creates a renderer factory for use in generator definitions.
+ *
+ * Wrap your renderer factory function with this helper to register it as the
+ * renderer for a generator. Core will call this factory once per render cycle
+ * to obtain a fresh renderer instance.
+ *
+ * @example
+ * ```ts
+ * // packages/renderer-jsx/src/index.ts
+ * export const jsxRenderer = createRenderer(() => {
+ *   const runtime = new Runtime()
+ *   return {
+ *     async render(element) { await runtime.render(element) },
+ *     get files() { return runtime.nodes },
+ *     unmount(error) { runtime.unmount(error) },
+ *   }
+ * })
+ *
+ * // packages/plugin-zod/src/generators/zodGenerator.tsx
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ * export const zodGenerator = defineGenerator<PluginZod>({
+ *   name: 'zod',
+ *   renderer: jsxRenderer,
+ *   schema(node, options) { return <File ...>...</File> },
+ * })
+ * ```
+ */
+export function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement> {
+  return factory
+}