@kubb/core 5.0.0-beta.8 → 5.0.0-beta.80

package/src/createRenderer.ts

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

package/src/createStorage.ts

@@ -1,70 +0,0 @@
-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>
-}
-
-/**
- * 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.
- *
- * @note Call the returned factory with optional options to instantiate the storage adapter.
- *
- * @example
- * ```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 getKeys(base) {
- *       const keys = [...store.keys()]
- *       return base ? keys.filter((k) => k.startsWith(base)) : keys
- *     },
- *     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 {
-  return (options) => build(options ?? ({} as TOptions))
-}

package/src/defineGenerator.ts

@@ -1,175 +0,0 @@
-import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
-import type { FileNode, InputNode, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
-import type { Adapter } from './createAdapter.ts'
-import type { RendererFactory } from './createRenderer.ts'
-import type { KubbHooks } from './types.ts'
-import type { PluginDriver } from './PluginDriver.ts'
-import type { Plugin, PluginFactoryOptions } from './definePlugin.ts'
-import type { Resolver } from './defineResolver.ts'
-import type { Config, DevtoolsOptions } from './types.ts'
-
-/**
- * Context object passed to generator `schema`, `operation`, and `operations` methods.
- *
- * The adapter is always defined (guaranteed by `runPluginAstHooks`) so no runtime checks
- * are needed. `ctx.options` carries resolved per-node options after exclude/include/override
- * filtering for individual schema/operation calls, or plugin-level options for operations.
- */
-export type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
-  config: Config
-  /**
-   * Absolute path to the current plugin's output directory.
-   */
-  root: string
-  /**
-   * Determine output mode based on the output config.
-   * Returns `'single'` when `output.path` is a file, `'split'` for a directory.
-   */
-  getMode: (output: { path: string }) => 'single' | 'split'
-  driver: PluginDriver
-  /**
-   * Get a plugin by name, typed via `Kubb.PluginRegistry` when registered.
-   */
-  getPlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]> | undefined
-  getPlugin(name: string): Plugin | undefined
-  /**
-   * Get a plugin by name, throws an error if not found.
-   */
-  requirePlugin<TName extends keyof Kubb.PluginRegistry>(name: TName): Plugin<Kubb.PluginRegistry[TName]>
-  requirePlugin(name: string): Plugin
-  /**
-   * Get a resolver by plugin name, typed via `Kubb.PluginRegistry` when registered.
-   */
-  getResolver<TName extends keyof Kubb.PluginRegistry>(name: TName): Kubb.PluginRegistry[TName]['resolver']
-  getResolver(name: string): Resolver
-  /**
-   * Add files only if they don't exist.
-   */
-  addFile: (...file: Array<FileNode>) => Promise<void>
-  /**
-   * Merge sources into the same output file.
-   */
-  upsertFile: (...file: Array<FileNode>) => Promise<void>
-  hooks: AsyncEventEmitter<KubbHooks>
-  /**
-   * The current plugin instance.
-   */
-  plugin: Plugin<TOptions>
-  /**
-   * The current plugin's resolver.
-   */
-  resolver: TOptions['resolver']
-  /**
-   * The current plugin's transformer.
-   */
-  transformer: Visitor | undefined
-  /**
-   * Emit a warning.
-   */
-  warn: (message: string) => void
-  /**
-   * Emit an error.
-   */
-  error: (error: string | Error) => void
-  /**
-   * Emit an info message.
-   */
-  info: (message: string) => void
-  /**
-   * Open the current input node in Kubb Studio.
-   */
-  openInStudio: (options?: DevtoolsOptions) => Promise<void>
-  /**
-   * The configured adapter instance.
-   */
-  adapter: Adapter
-  /**
-   * The universal `InputNode` produced by the adapter.
-   */
-  inputNode: InputNode
-  /**
-   * Resolved options after exclude/include/override filtering.
-   */
-  options: TOptions['resolvedOptions']
-}
-
-/**
- * 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.
- *
- * @note Generators are consumed by plugins and registered via `ctx.addGenerator()` in `kubb:plugin:setup`.
- *
- * @example
- * ```ts
- * import { defineGenerator } from '@kubb/core'
- * import { jsxRenderer } from '@kubb/renderer-jsx'
- *
- * export const typeGenerator = defineGenerator({
- *   name: 'typescript',
- *   renderer: jsxRenderer,
- *   schema(node, ctx) {
- *     const { adapter, resolver, root, options } = ctx
- *     return <File ...><Type node={node} resolver={resolver} /></File>
- *   },
- * })
- * ```
- */
-export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown> = {
-  /**
-   * Used in diagnostic messages and debug output.
-   */
-  name: string
-  /**
-   * Optional renderer factory that produces a {@link Renderer} for each render cycle.
-   *
-   * Generators that return renderer elements (e.g. JSX via `@kubb/renderer-jsx`) must set this
-   * to the matching renderer factory (e.g. `jsxRenderer` from `@kubb/renderer-jsx`).
-   *
-   * Generators that only return `Array<FileNode>` or `void` do not need to set this.
-   *
-   * Set `renderer: null` to explicitly opt out of rendering even when the parent plugin
-   * declares a `renderer` (overrides the plugin-level fallback).
-   *
-   * @example
-   * ```ts
-   * import { jsxRenderer } from '@kubb/renderer-jsx'
-   * export const myGenerator = defineGenerator<PluginTs>({
-   *   renderer: jsxRenderer,
-   *   schema(node, ctx) { return <File ...>...</File> },
-   * })
-   * ```
-   */
-  renderer?: RendererFactory<TElement> | null
-  /**
-   * Called for each schema node in the AST walk.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
-   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
-   */
-  schema?: (node: SchemaNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
-  /**
-   * Called for each operation node in the AST walk.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
-   * plus `ctx.options` with the per-node resolved options (after exclude/include/override).
-   */
-  operation?: (node: OperationNode, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
-  /**
-   * Called once after all operations have been walked.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
-   * plus `ctx.options` with the plugin-level options for the batch call.
-   */
-  operations?: (nodes: Array<OperationNode>, ctx: GeneratorContext<TOptions>) => PossiblePromise<TElement | Array<FileNode> | void>
-}
-
-/**
- * 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.
- */
-export function defineGenerator<TOptions extends PluginFactoryOptions = PluginFactoryOptions, TElement = unknown>(
-  generator: Generator<TOptions, TElement>,
-): Generator<TOptions, TElement> {
-  return generator
-}

package/src/defineLogger.ts

@@ -1,58 +0,0 @@
-import type { AsyncEventEmitter } from '@internals/utils'
-import type { logLevel } from './constants.ts'
-import type { KubbHooks } from './types.ts'
-
-export type LoggerOptions = {
-  /**
-   * Log level for output verbosity.
-   * @default 3
-   */
-  logLevel: (typeof logLevel)[keyof typeof logLevel]
-}
-
-/**
- * Shared context passed to plugins, parsers, and other internals.
- */
-export type LoggerContext = AsyncEventEmitter<KubbHooks>
-
-export type Logger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = {
-  name: string
-  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.
- *
- * @example Basic logger
- * ```ts
- * 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))
- *   },
- * })
- * ```
- *
- * @example Logger that returns a hook sink factory
- * ```ts
- * export const myLogger = defineLogger<LoggerOptions, HookSinkFactory>({
- *   name: 'my-logger',
- *   install(context, options) {
- *     // … register event handlers …
- *     return (commandWithArgs) => ({ onStdout: console.log })
- *   },
- * })
- * ```
- */
-export function defineLogger<Options extends LoggerOptions = LoggerOptions, TInstallReturn = void>(
-  logger: UserLogger<Options, TInstallReturn>,
-): Logger<Options, TInstallReturn> {
-  return logger
-}

package/src/defineMiddleware.ts

@@ -1,62 +0,0 @@
-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.
- */
-export type Middleware = {
-  /**
-   * Unique identifier for this middleware.
-   */
-  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.
-   */
-  hooks: {
-    [K in keyof KubbHooks]?: (...args: KubbHooks[K]) => void | Promise<void>
-  }
-}
-
-/**
- * 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.
- *
- * @note The factory can accept typed options. See examples for using options and per-build state patterns.
- *
- * @example
- * ```ts
- * import { defineMiddleware } from '@kubb/core'
- *
- * // Stateless middleware
- * export const logMiddleware = defineMiddleware(() => ({
- *   name: 'log-middleware',
- *   hooks: {
- *     'kubb:build:end'({ files }) {
- *       console.log(`Build complete with ${files.length} files`)
- *     },
- *   },
- * }))
- *
- * // Middleware with options and per-build state
- * export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
- *   const seen = new Set<string>()
- *   return {
- *     name: 'prefix-middleware',
- *     hooks: {
- *       'kubb:plugin:end'({ plugin }) {
- *         seen.add(`${options.prefix}${plugin.name}`)
- *       },
- *     },
- *   }
- * })
- * ```
- */
-export function defineMiddleware<TOptions extends object = object>(factory: (options: TOptions) => Middleware): (options?: TOptions) => Middleware {
-  return (options) => factory(options ?? ({} as TOptions))
-}

package/src/defineParser.ts

@@ -1,44 +0,0 @@
-import type { FileNode } from '@kubb/ast'
-
-type PrintOptions = {
-  extname?: FileNode['extname']
-}
-
-export type Parser<TMeta extends object = any> = {
-  name: string
-  /**
-   * File extensions this parser handles.
-   * Use `undefined` to create a catch-all fallback parser.
-   *
-   * @example Handled extensions
-   * `['.ts', '.js']`
-   */
-  extNames: Array<FileNode['extname']> | undefined
-  /**
-   * Convert a resolved file to a string.
-   */
-  parse(file: FileNode<TMeta>, options?: PrintOptions): Promise<string> | 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.
- *
- * @example
- * ```ts
- * import { defineParser } 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')
- *   },
- * })
- * ```
- */
-export function defineParser<TMeta extends object = any>(parser: Parser<TMeta>): Parser<TMeta> {
-  return parser
-}