@kubb/core 5.0.0-beta.22 → 5.0.0-beta.24

package/src/createKubb.ts

@@ -90,22 +90,25 @@ export type Config<TInput = Input> = {
    */
   name?: string
   /**
-   * Project root directory, absolute or relative to the config file.
-   * @default process.cwd()
+   * Project root directory, absolute or relative to the config file. Already
+   * resolved on the `Config` instance — see `UserConfig` for the optional
+   * form that defaults to `process.cwd()`.
    */
   root: string
   /**
-   * Parsers that convert generated files to strings.
-   * Each parser handles specific extensions (e.g. `.ts`, `.tsx`).
-   * A fallback parser is appended for unhandled extensions.
-   * When omitted, defaults to `parserTs` from `@kubb/parser-ts`.
+   * Parsers that convert generated files into strings. Each parser handles a
+   * set of file extensions; a fallback parser handles anything else.
+   *
+   * Already resolved on the `Config` instance — see `UserConfig` for the
+   * optional form that defaults to `[parserTs, parserTsx]`.
    *
-   * @default [parserTs] from `@kubb/parser-ts`
    * @example
    * ```ts
-   * import { parserTs, tsxParser } from '@kubb/parser-ts'
+   * import { defineConfig } from 'kubb'
+   * import { parserTs, parserTsx } from '@kubb/parser-ts'
+   *
    * export default defineConfig({
-   *   parsers: [parserTs, tsxParser],
+   *   parsers: [parserTs, parserTsx],
    * })
    * ```
    */
@@ -821,6 +824,11 @@ export type CLIOptions = {
    * Path to the Kubb config file.
    */
   config?: string
+  /**
+   * OpenAPI input path passed as the positional argument to `kubb generate`.
+   * Overrides `config.input.path` when set.
+   */
+  input?: string
   /**
    * Re-run generation whenever input files change.
    */
@@ -828,9 +836,9 @@ export type CLIOptions = {
   /**
    * Controls how much output the CLI prints.
    *
-   * @default 'silent'
+   * @default 'info'
    */
-  logLevel?: 'silent' | 'info' | 'debug'
+  logLevel?: 'silent' | 'info' | 'verbose' | 'debug'
 }
 
 /**
@@ -1103,8 +1111,24 @@ export class Kubb {
 }
 
 /**
- * Factory for {@link Kubb}. Equivalent to `new Kubb(userConfig, options)` and kept
- * as the canonical public entry point.
+ * Constructs a {@link Kubb} build orchestrator from a user config. Equivalent
+ * to `new Kubb(userConfig, options)` and the canonical public entry point.
+ *
+ * @example
+ * ```ts
+ * import { createKubb } from '@kubb/core'
+ * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ *
+ * const kubb = createKubb({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas(),
+ *   plugins: [pluginTs()],
+ * })
+ *
+ * await kubb.build()
+ * ```
  */
 export function createKubb(userConfig: UserConfig, options: CreateKubbOptions = {}): Kubb {
   return new Kubb(userConfig, options)

package/src/createRenderer.ts

@@ -48,17 +48,37 @@ export type Renderer<TElement = unknown> = {
 export type RendererFactory<TElement = unknown> = () => Renderer<TElement>
 
 /**
- * Wraps a renderer factory for use in generator definitions.
+ * Defines a renderer factory. Renderers turn the generator's return value
+ * (JSX, a template string, a tree of any shape) into `FileNode`s that get
+ * written to disk.
  *
- * @example
+ * Use this to support output formats beyond JSX — for instance, a Handlebars
+ * renderer, a string-template renderer, or a renderer that writes binary
+ * files. Plugins and generators pick the renderer to use via the `renderer`
+ * field on `defineGenerator`.
+ *
+ * @example A minimal renderer that wraps a custom runtime
  * ```ts
- * export const jsxRenderer = createRenderer(() => {
- *   const runtime = new Runtime()
+ * import { createRenderer } from '@kubb/core'
+ *
+ * export const myRenderer = createRenderer(() => {
+ *   const runtime = new MyRuntime()
  *   return {
- *     async render(element) { await runtime.render(element) },
- *     get files() { return runtime.nodes },
- *     dispose() { runtime.unmount() },
- *     unmount(error) { runtime.unmount(error) },
+ *     async render(element) {
+ *       await runtime.render(element)
+ *     },
+ *     get files() {
+ *       return runtime.files
+ *     },
+ *     dispose() {
+ *       runtime.dispose()
+ *     },
+ *     unmount(error) {
+ *       runtime.dispose(error)
+ *     },
+ *     [Symbol.dispose]() {
+ *       this.dispose()
+ *     },
  *   }
  * })
  * ```

package/src/createStorage.ts

@@ -1,68 +1,81 @@
+/**
+ * Backend that persists generated files. Kubb ships with `fsStorage` (writes
+ * to disk) and `memoryStorage` (keeps everything in RAM). Implement this
+ * interface to write to S3, a database, or any other target.
+ */
 export type Storage = {
   /**
-   * Identifier used for logging and debugging (e.g. `'fs'`, `'s3'`).
+   * Identifier used in logs and diagnostics (`'fs'`, `'memory'`, `'s3'`).
    */
   readonly name: string
   /**
-   * Returns `true` when an entry for `key` exists in storage.
+   * Returns `true` when an entry for `key` exists.
    */
   hasItem(key: string): Promise<boolean>
   /**
-   * Returns the stored string value, or `null` when `key` does not exist.
+   * Reads the stored string. Returns `null` when the key is missing.
    */
   getItem(key: string): Promise<string | null>
   /**
-   * Persists `value` under `key`, creating any required structure.
+   * Stores `value` under `key`, creating any required structure (directories,
+   * buckets, ...).
    */
   setItem(key: string, value: string): Promise<void>
   /**
-   *  Removes the entry for `key`. No-ops when the key does not exist.
+   * Deletes the entry for `key`. No-op when the key does not exist.
    */
   removeItem(key: string): Promise<void>
   /**
-   * Returns all keys, optionally filtered to those starting with `base`.
+   * Returns every key. Pass `base` to filter to keys starting with that prefix.
    */
   getKeys(base?: string): Promise<Array<string>>
   /**
-   * Removes all entries, optionally scoped to those starting with `base`.
+   * Removes every entry. Pass `base` to scope the wipe to a key prefix.
    */
   clear(base?: string): Promise<void>
   /**
-   * Optional teardown hook called after the build completes.
+   * Optional teardown hook called after the build completes. Use to flush
+   * buffers, close connections, or release file locks.
    */
   dispose?(): Promise<void>
 }
 
 /**
- * Factory for implementing custom storage backends that control where generated files are written.
- *
- * Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
- * Kubb provides filesystem and in-memory implementations out of the box.
+ * Defines a custom storage backend. The builder receives user options and
+ * returns a `Storage` implementation. Kubb ships with filesystem and
+ * in-memory storages — reach for this when you need to write generated files
+ * elsewhere (cloud storage, a database, a remote API).
  *
- * @note Call the returned factory with optional options to instantiate the storage adapter.
- *
- * @example
+ * @example In-memory storage (the built-in implementation)
  * ```ts
  * import { createStorage } from '@kubb/core'
  *
  * 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 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() },
+ *     async clear(base) {
+ *       if (!base) store.clear()
+ *     },
  *   }
  * })
- *
- * // Instantiate:
- * const storage = memoryStorage()
  * ```
  */
 export function createStorage<TOptions = Record<string, never>>(build: (options: TOptions) => Storage): (options?: TOptions) => Storage {

package/src/defineGenerator.ts

@@ -98,8 +98,8 @@ export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFacto
  * Declares a named generator unit that walks the AST and emits files.
  *
  * Each method (`schema`, `operation`, `operations`) is called for the matching node type.
- * Each method returns `TElement | Array<FileNode> | void`. JSX-based generators require a `renderer` factory.
- * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `void` to bypass rendering.
+ * Each method returns `TElement | Array<FileNode> | undefined | null`. JSX-based generators require a `renderer` factory.
+ * Return `Array<FileNode>` directly or call `ctx.upsertFile()` manually and return `undefined` or `null` to bypass rendering.
  *
  * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
  *
@@ -149,25 +149,48 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
    * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
    */
-  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>
   /**
    * Called for each operation node in the AST walk.
    * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
    */
-  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>
   /**
    * Called once after all operations have been walked.
    * `ctx` carries the plugin context with `adapter` and `meta` (document metadata),
    * plus `ctx.options` with the plugin-level options for the batch call.
    */
-  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
+  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | undefined | null>
 }
 
 /**
- * Defines a generator. Returns the object as-is with correct `this` typings.
- * `applyHookResult` handles renderer elements and `File[]` uniformly using
- * the generator's declared `renderer` factory.
+ * Defines a generator: a unit of work that runs during the plugin's AST walk
+ * and produces files. Plugins register generators via `ctx.addGenerator()`
+ * inside `kubb:plugin:setup`.
+ *
+ * The returned object is the input as-is, but with `this` types preserved so
+ * `schema`/`operation`/`operations` methods are correctly typed against the
+ * plugin's `PluginFactoryOptions`. Renderer elements and `FileNode[]` returns
+ * are both handled by the runtime — pick whichever style fits.
+ *
+ * @example JSX-based schema generator
+ * ```tsx
+ * import { defineGenerator } from '@kubb/core'
+ * import { jsxRenderer } from '@kubb/renderer-jsx'
+ *
+ * export const typeGenerator = defineGenerator({
+ *   name: 'typescript',
+ *   renderer: jsxRenderer,
+ *   schema(node, ctx) {
+ *     return (
+ *       <File path={`${ctx.root}/${node.name}.ts`}>
+ *         <Type node={node} resolver={ctx.resolver} />
+ *       </File>
+ *     )
+ *   },
+ * })
+ * ```
  */
 export function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(
   generator: Generator<TOptions, TElement>,

package/src/defineLogger.ts

@@ -2,51 +2,71 @@ import type { AsyncEventEmitter } from '@internals/utils'
 import type { logLevel } from './constants.ts'
 import type { KubbHooks } from './types.ts'
 
+/**
+ * Options accepted by a logger's `install` callback.
+ */
 export type LoggerOptions = {
   /**
-   * Log level for output verbosity.
-   * @default 3
+   * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
+   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
    */
   logLevel: (typeof logLevel)[keyof typeof logLevel]
 }
 
 /**
- * Shared context passed to plugins, parsers, and other internals.
+ * Event emitter handed to `Logger.install`. Use `.on('kubb:info', ...)` and
+ * friends to subscribe to build events.
  */
 export type LoggerContext = AsyncEventEmitter<KubbHooks>
 
+/**
+ * Logger contract. A logger receives the build's event emitter and subscribes
+ * to whichever lifecycle events it wants to forward to its destination
+ * (console, file, remote sink).
+ */
 export type Logger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = {
+  /**
+   * Display name used in diagnostics.
+   */
   name: string
+  /**
+   * Called once per build with the shared event emitter. Subscribe to events
+   * here. The return value (if any) is forwarded to whoever installed the
+   * logger, which is handy for sink factories.
+   */
   install: (context: LoggerContext, options?: TOptions) => TInstallReturn | Promise<TInstallReturn>
 }
 
 export type UserLogger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = Logger<TOptions, TInstallReturn>
 
 /**
- * Wraps a logger definition into a typed {@link Logger}.
- *
- * The optional second type parameter `TInstallReturn` allows loggers to return
- * a value from `install` — for example, a sink factory that the caller can
- * forward to hook execution.
+ * Defines a typed logger. Use the second type parameter to declare a return
+ * value from `install`, which is handy when the logger exposes a sink factory
+ * or cleanup callback to the caller.
  *
  * @example Basic logger
  * ```ts
+ * import { defineLogger } from '@kubb/core'
+ *
  * export const myLogger = defineLogger({
  *   name: 'my-logger',
- *   install(context, options) {
- *     context.on('kubb:info', (message) => console.log('ℹ', message))
- *     context.on('kubb:error', (error) => console.error('✗', error.message))
+ *   install(context) {
+ *     context.on('kubb:info', ({ message }) => console.log('ℹ', message))
+ *     context.on('kubb:error', ({ error }) => console.error('✗', error.message))
  *   },
  * })
  * ```
  *
  * @example Logger that returns a hook sink factory
  * ```ts
+ * import { defineLogger, type LoggerOptions } from '@kubb/core'
+ * import type { HookSinkFactory } from './sinks'
+ *
  * export const myLogger = defineLogger<LoggerOptions, HookSinkFactory>({
  *   name: 'my-logger',
- *   install(context, options) {
+ *   install(context) {
  *     // … register event handlers …
- *     return (commandWithArgs) => ({ onStdout: console.log })
+ *     return () => ({ onStdout: console.log })
  *   },
  * })
  * ```

package/src/defineMiddleware.ts

@@ -1,20 +1,19 @@
 import type { KubbHooks } from './types.ts'
 
 /**
- * A middleware instance produced by calling a factory created with `defineMiddleware`.
- * It declares event handlers under a `hooks` object which are registered on the
- * shared emitter after all plugin hooks, so middleware handlers for any event
- * always fire last.
+ * A middleware instance. Subscribes to lifecycle events via `hooks`. Middleware
+ * handlers always fire after every plugin handler for the same event, so they
+ * see the full set of generated files.
  */
 export type Middleware = {
   /**
-   * Unique identifier for this middleware.
+   * Unique name. Use a `middleware-<feature>` convention (e.g.
+   * `middleware-barrel`).
    */
   name: string
   /**
-   * Lifecycle event handlers for this middleware.
-   * Any event from the global `KubbHooks` map can be subscribed to here.
-   * Handlers are registered after all plugin handlers, so they always fire last.
+   * Lifecycle event handlers. Any event from the global `KubbHooks` map can be
+   * subscribed to here. Handlers run after all plugin handlers for that event.
    */
   hooks: {
     [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void>
@@ -22,18 +21,17 @@ export type Middleware = {
 }
 
 /**
- * Creates a middleware factory using the hook-style `hooks` API.
+ * Creates a middleware factory. Middleware fires after every plugin handler
+ * for the same event, which makes it the natural place for post-processing
+ * (barrel files, lint runs, audit logs).
  *
- * Middleware handlers fire after all plugin handlers for any given event, making them ideal for post-processing, logging, and auditing.
- * Per-build state (such as accumulators) belongs inside the factory closure so each `createKubb` invocation gets its own isolated instance.
+ * Per-build state belongs inside the factory closure so each `createKubb`
+ * invocation gets its own isolated instance.
  *
- * @note The factory can accept typed options. See examples for using options and per-build state patterns.
- *
- * @example
+ * @example Stateless middleware
  * ```ts
  * import { defineMiddleware } from '@kubb/core'
  *
- * // Stateless middleware
  * export const logMiddleware = defineMiddleware(() => ({
  *   name: 'log-middleware',
  *   hooks: {
@@ -42,8 +40,12 @@ export type Middleware = {
  *     },
  *   },
  * }))
+ * ```
+ *
+ * @example Middleware with options and per-build state
+ * ```ts
+ * import { defineMiddleware } from '@kubb/core'
  *
- * // Middleware with options and per-build state
  * export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
  *   const seen = new Set<string>()
  *   return {

package/src/defineParser.ts

@@ -4,41 +4,58 @@ type PrintOptions = {
   extname?: FileNode['extname']
 }
 
-export type Parser<TMeta extends object = any> = {
+/**
+ * Converts a resolved {@link FileNode} into the final source string that gets
+ * written to disk. Kubb ships with TypeScript and TSX parsers; add your own
+ * for new file types (JSON, Markdown, ...).
+ */
+export type Parser<TMeta extends object = any, TNode = unknown> = {
+  /**
+   * Display name used in diagnostics and the parser registry.
+   */
   name: string
   /**
-   * File extensions this parser handles.
-   * Use `undefined` to create a catch-all fallback parser.
+   * File extensions this parser handles. Set to `undefined` to define a
+   * catch-all fallback used when no other parser claims the extension.
    *
-   * @example Handled extensions
+   * @example
    * `['.ts', '.js']`
    */
   extNames: Array<FileNode['extname']> | undefined
   /**
-   * Convert a resolved file to a string.
+   * Serialise the file's AST into source code.
    */
   parse(file: FileNode<TMeta>, options?: PrintOptions): string
+  /**
+   * Render compiler AST nodes for this parser's language into source text.
+   * Plugins call this to format the nodes they assemble before handing them
+   * back to the parser as `FileNode.sources`.
+   */
+  print(...nodes: TNode[]): string
 }
 
 /**
- * Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
- *
- * @note Call the returned factory with optional options to instantiate the parser.
+ * Defines a parser with type-safe `this`. Used to register handlers for new
+ * file extensions or to plug a non-TypeScript output into the build.
  *
  * @example
  * ```ts
- * import { defineParser } from '@kubb/core'
+ * import { defineParser, ast } from '@kubb/core'
  *
  * export const jsonParser = defineParser({
  *   name: 'json',
  *   extNames: ['.json'],
  *   parse(file) {
- *     const { extractStringsFromNodes } = await import('@kubb/ast')
- *     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
+ *     return file.sources
+ *       .map((source) => ast.extractStringsFromNodes(source.nodes ?? []))
+ *       .join('\n')
+ *   },
+ *   print(...nodes) {
+ *     return nodes.map(String).join('\n')
  *   },
  * })
  * ```
  */
-export function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta> {
+export function defineParser<T extends Parser>(parser: T): T {
   return parser
 }