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

package/dist/index.js

@@ -1,5 +1,5 @@
 import "./chunk--u3MIqq1.js";
-import { a as FileManager, c as DEFAULT_BANNER, d as logLevel, f as URLPath, i as FileProcessor, l as DEFAULT_EXTENSION, m as BuildError, o as defineResolver, p as AsyncEventEmitter, r as _usingCtx, s as definePlugin, t as KubbDriver, u as DEFAULT_STUDIO_URL } from "./KubbDriver-l31wllgN.js";
+import { a as FileManager, c as DEFAULT_BANNER, d as logLevel, f as URLPath, i as FileProcessor, l as DEFAULT_EXTENSION, m as BuildError, o as defineResolver, p as AsyncEventEmitter, r as _usingCtx, s as definePlugin, t as KubbDriver, u as DEFAULT_STUDIO_URL } from "./KubbDriver-BkwOamHp.js";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import * as ast from "@kubb/ast";
@@ -72,28 +72,33 @@ async function clean(path) {
 //#endregion
 //#region src/createAdapter.ts
 /**
-* Factory for implementing custom adapters that translate non-OpenAPI specs into Kubb's AST.
+* Defines a custom adapter that translates a spec format into Kubb's universal
+* AST. Use this when you need to consume GraphQL, gRPC, AsyncAPI, or another
+* domain-specific schema. Built-in adapters: `@kubb/adapter-oas` for
+* OpenAPI/Swagger documents.
 *
-* Use this to support GraphQL schemas, gRPC definitions, AsyncAPI, or custom domain-specific languages.
-* Built-in adapters include `@kubb/adapter-oas` for OpenAPI and Swagger documents.
-*
-* @note Adapters must parse their input format to Kubb's `InputNode` structure.
+* Adapters must return an `InputNode` from `parse`. That node is what every
+* plugin in the build consumes.
 *
 * @example
 * ```ts
-* export const myAdapter = createAdapter<MyAdapter>((options) => {
-*   return {
-*     name: 'my-adapter',
-*     options,
-*     async parse(source) {
-*       // Transform source format to InputNode
-*       return { ... }
-*     },
-*   }
-* })
+* import { createAdapter, ast, type AdapterFactoryOptions } from '@kubb/core'
+*
+* type MyAdapter = AdapterFactoryOptions<'my-adapter', { validate?: boolean }>
 *
-* // Instantiate:
-* const adapter = myAdapter({ validate: true })
+* export const myAdapter = createAdapter<MyAdapter>((options) => ({
+*   name: 'my-adapter',
+*   options,
+*   document: null,
+*   async parse(_source) {
+*     // Convert `source` (path or inline data) into an InputNode.
+*     return ast.createInput()
+*   },
+*   getImports: () => [],
+*   async validate() {
+*     // Throw or call ctx.error here when the spec is invalid.
+*   },
+* }))
 * ```
 */
 function createAdapter(build) {
@@ -101,39 +106,45 @@ function createAdapter(build) {
 }
 //#endregion
 //#region package.json
-var version$1 = "5.0.0-beta.22";
+var version$1 = "5.0.0-beta.23";
 //#endregion
 //#region src/createStorage.ts
 /**
-* Factory for implementing custom storage backends that control where generated files are written.
+* 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).
 *
-* 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.
-*
-* @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()
 * ```
 */
 function createStorage(build) {
@@ -422,8 +433,24 @@ var Kubb = class {
 	}
 };
 /**
-* 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()
+* ```
 */
 function createKubb(userConfig, options = {}) {
 	return new Kubb(userConfig, options);
@@ -431,17 +458,37 @@ function createKubb(userConfig, options = {}) {
 //#endregion
 //#region src/createRenderer.ts
 /**
-* 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()
+*     },
 *   }
 * })
 * ```
@@ -452,9 +499,32 @@ function createRenderer(factory) {
 //#endregion
 //#region src/defineGenerator.ts
 /**
-* 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>
+*     )
+*   },
+* })
+* ```
 */
 function defineGenerator(generator) {
 	return generator;
@@ -462,30 +532,33 @@ function defineGenerator(generator) {
 //#endregion
 //#region src/defineLogger.ts
 /**
-* 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 })
 *   },
 * })
 * ```
@@ -496,18 +569,17 @@ function defineLogger(logger) {
 //#endregion
 //#region src/defineMiddleware.ts
 /**
-* Creates a middleware factory using the hook-style `hooks` API.
-*
-* 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.
+* 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).
 *
-* @note The factory can accept typed options. See examples for using options and per-build state patterns.
+* Per-build state belongs inside the factory closure so each `createKubb`
+* invocation gets its own isolated instance.
 *
-* @example
+* @example Stateless middleware
 * ```ts
 * import { defineMiddleware } from '@kubb/core'
 *
-* // Stateless middleware
 * export const logMiddleware = defineMiddleware(() => ({
 *   name: 'log-middleware',
 *   hooks: {
@@ -516,8 +588,12 @@ function defineLogger(logger) {
 *     },
 *   },
 * }))
+* ```
+*
+* @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 {
@@ -537,20 +613,20 @@ function defineMiddleware(factory) {
 //#endregion
 //#region src/defineParser.ts
 /**
-* 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')
 *   },
 * })
 * ```