@kubb/core 5.0.0-beta.4 → 5.0.0-beta.40

package/src/createRenderer.ts

@@ -3,53 +3,84 @@ 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.
+ * `TElement` is the type the renderer accepts, for example `KubbReactElement`
+ * for `@kubb/renderer-jsx` or a custom type for your own renderer. Defaults to
+ * `unknown` so generators that don't care about the element type work without
+ * specifying it.
  */
 export type Renderer<TElement = unknown> = {
+  /**
+   * Renders `element` and populates {@link files} with the resulting {@link FileNode} objects.
+   * Called once per render cycle. Must resolve before {@link files} is read.
+   */
   render(element: TElement): Promise<void>
+  /**
+   * Tears down the renderer and releases any held resources.
+   * Pass an `Error` to signal a failure, a number for an exit code, or omit for a clean shutdown.
+   */
   unmount(error?: Error | number | null): void
+  /**
+   * Releases any held resources. `[Symbol.dispose]` delegates here.
+   */
+  dispose(): void
+  /**
+   * Accumulated {@link FileNode} results produced by the last {@link render} call.
+   * Not populated when {@link stream} is implemented.
+   */
   readonly files: Array<FileNode>
+  /**
+   * When present, core calls this instead of {@link render} and {@link files},
+   * forwarding each file to `FileManager` as soon as it is ready.
+   */
+  stream?(element: TElement): Iterable<FileNode>
+  /**
+   * Disposer hook so renderers participate in `using` blocks: `using r = rendererFactory()`
+   * guarantees {@link dispose} runs on every exit path, including thrown errors.
+   */
+  [Symbol.dispose](): void
 }
 
 /**
- * A factory function that produces a fresh {@link Renderer} per render.
+ * A factory function that produces a fresh {@link Renderer} per render cycle.
  *
  * 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.
+ * 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.
  *
- * 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.
+ * 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
+ * @example A minimal renderer that wraps a custom runtime
  * ```ts
- * // packages/renderer-jsx/src/index.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 },
- *     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()
+ *     },
  *   }
  * })
- *
- * // 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> {

package/src/createReporter.ts

@@ -0,0 +1,147 @@
+import type { logLevel } from './defineLogger.ts'
+import type { Config } from './createKubb.ts'
+import type { Diagnostic } from './diagnostics.ts'
+
+/**
+ * A built-in reporter that renders a run's output, independent of the live logger view.
+ *
+ * - `cli` renders the per-config summary to the terminal (the default).
+ * - `json` writes a machine-readable report to stdout, for CI.
+ * - `file` writes a config's diagnostics to `.kubb/kubb-<name>-<timestamp>.log`.
+ */
+export type ReporterName = 'cli' | 'json' | 'file'
+
+/**
+ * One config's outcome within a run, as handed to a {@link Reporter}.
+ */
+export type GenerationResult = {
+  config: Config
+  /**
+   * Diagnostics collected while generating this config.
+   */
+  diagnostics: Array<Diagnostic>
+  /**
+   * Number of files written for this config.
+   */
+  filesCreated: number
+  status: 'success' | 'failed'
+  /**
+   * `process.hrtime()` snapshot taken when this config started generating.
+   */
+  hrStart: [number, number]
+}
+
+/**
+ * Render context passed alongside the {@link GenerationResult}, carrying knobs a reporter needs
+ * but that are not part of the run data (e.g. verbosity).
+ */
+export type ReporterContext = {
+  /**
+   * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
+   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
+   */
+  logLevel: (typeof logLevel)[keyof typeof logLevel]
+}
+
+/**
+ * Host-facing reporter, as installed onto a run. Unlike a Logger (the live TUI view), a reporter
+ * never sees the event emitter. `report` runs once per config; `drain`, when present, runs once
+ * after the last config.
+ */
+export type Reporter = {
+  /**
+   * Display name, matching a {@link ReporterName} for the built-ins.
+   */
+  name: string
+  /**
+   * Called once per config with that config's result and the render context.
+   */
+  report: (result: GenerationResult, context: ReporterContext) => void | Promise<void>
+  /**
+   * Optional finalizer called once after the run's last config. The host wires it to
+   * `kubb:lifecycle:end`. {@link createReporter} closes it over the reports `report` returned.
+   */
+  drain?: (context: ReporterContext) => void | Promise<void>
+}
+
+/**
+ * Reporter definition passed to {@link createReporter}. `report` returns the value to collect for
+ * this config (e.g. a built report), and the optional `drain` receives the collected reports to
+ * emit as one document. `T` is inferred from `report`'s return type.
+ */
+export type UserReporter<T = void> = {
+  name: string
+  report: (result: GenerationResult, context: ReporterContext) => T | Promise<T>
+  drain?: (context: ReporterContext, reports: Array<T>) => void | Promise<void>
+}
+
+/**
+ * Defines a reporter. When the definition has a `drain`, the returned reporter buffers each value
+ * `report` returns and hands the array to `drain` once, then clears it. Without a `drain`, nothing
+ * is buffered. Wiring the reporter onto the run's events is the host's job, so the reporter only
+ * ever deals with a {@link GenerationResult}.
+ *
+ * @example
+ * ```ts
+ * import { createReporter, Diagnostics } from '@kubb/core'
+ *
+ * export const jsonReporter = createReporter({
+ *   name: 'json',
+ *   report(result) {
+ *     return { status: Diagnostics.hasError(result.diagnostics) ? 'failed' : 'success', diagnostics: result.diagnostics }
+ *   },
+ *   drain(context, reports) {
+ *     process.stdout.write(`${JSON.stringify(reports, null, 2)}\n`)
+ *   },
+ * })
+ * ```
+ */
+export function createReporter<T = void>(reporter: UserReporter<T>): Reporter {
+  const drain = reporter.drain
+  if (!drain) {
+    return {
+      name: reporter.name,
+      async report(result, context) {
+        await reporter.report(result, context)
+      },
+    }
+  }
+
+  const reports: Array<T> = []
+
+  return {
+    name: reporter.name,
+    async report(result, context) {
+      reports.push(await reporter.report(result, context))
+    },
+    async drain(context) {
+      await drain(context, reports)
+      reports.length = 0
+    },
+  }
+}
+
+/**
+ * Picks the reporters whose `name` matches one of `names`, in the order the names are given.
+ * The config carries every available reporter, and the host selects which to activate by name
+ * (the CLI maps `--reporter` to this). Duplicate names and names without a matching reporter are
+ * skipped.
+ */
+export function selectReporters(reporters: ReadonlyArray<Reporter>, names: ReadonlyArray<string>): Array<Reporter> {
+  const seen = new Set<string>()
+  const selected: Array<Reporter> = []
+
+  for (const name of names) {
+    if (seen.has(name)) {
+      continue
+    }
+    seen.add(name)
+
+    const reporter = reporters.find((candidate) => candidate.name === name)
+    if (reporter) {
+      selected.push(reporter)
+    }
+  }
+
+  return selected
+}

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

@@ -1,16 +1,106 @@
-import type { PossiblePromise } from '@internals/utils'
-import type { FileNode, OperationNode, SchemaNode } from '@kubb/ast'
+import type { AsyncEventEmitter, PossiblePromise } from '@internals/utils'
+import type { FileNode, InputMeta, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
+import type { Adapter } from './createAdapter.ts'
 import type { RendererFactory } from './createRenderer.ts'
-import type { GeneratorContext, PluginFactoryOptions } from './types.ts'
+import type { KubbHooks } from './types.ts'
+import type { KubbDriver } from './KubbDriver.ts'
+import type { Plugin, PluginFactoryOptions } from './definePlugin.ts'
+import type { Resolver } from './defineResolver.ts'
+import type { Config } from './types.ts'
 
-export type { GeneratorContext } 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: KubbDriver
+  /**
+   * 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
+  /**
+   * Report a warning. Collected as a `warning` diagnostic attributed to the current
+   * plugin. It surfaces in the run summary but does not fail the build. For a structured
+   * diagnostic with a code and source location, use `Diagnostics.report` or throw a
+   * `Diagnostics.Error` directly.
+   */
+  warn: (message: string) => void
+  /**
+   * Report an error. Collected as an `error` diagnostic attributed to the current
+   * plugin, which fails the build.
+   */
+  error: (error: string | Error) => void
+  /**
+   * Report an informational message. Collected as an `info` diagnostic attributed to
+   * the current plugin.
+   */
+  info: (message: string) => void
+  /**
+   * The configured adapter instance.
+   */
+  adapter: Adapter
+  /**
+   * Document metadata from the adapter: title, version, base URL, and pre-computed
+   * schema index fields (`circularNames`, `enumNames`).
+   */
+  meta: InputMeta
+  /**
+   * 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.
+ * 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`.
  *
@@ -42,8 +132,7 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
    *
    * 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).
+   * Leave it unset or set `renderer: null` to opt out of rendering.
    *
    * @example
    * ```ts
@@ -57,28 +146,51 @@ export type Generator<TOptions extends PluginFactoryOptions = PluginFactoryOptio
   renderer?: RendererFactory<TElement> | null
   /**
    * Called for each schema node in the AST walk.
-   * `ctx` carries the plugin context with `adapter` and `inputNode` guaranteed present,
+   * `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 `inputNode` guaranteed present,
+   * `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 `inputNode` guaranteed present,
+   * `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, so 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

@@ -1,19 +1,90 @@
-import type { Logger, LoggerOptions, UserLogger } from './types.ts'
+import type { AsyncEventEmitter } from '@internals/utils'
+import type { KubbHooks } from './types.ts'
 
 /**
- * Wraps a logger definition into a typed {@link Logger}.
+ * Numeric log-level thresholds used internally to compare verbosity.
  *
- * @example
+ * Higher numbers are more verbose.
+ */
+export const logLevel = {
+  silent: Number.NEGATIVE_INFINITY,
+  error: 0,
+  warn: 1,
+  info: 3,
+  verbose: 4,
+} as const
+
+/**
+ * Options accepted by a logger's `install` callback.
+ */
+export type LoggerOptions = {
+  /**
+   * Output verbosity. Use the `logLevel` constants exported from `@kubb/core`
+   * (`silent`, `error`, `warn`, `info`, `verbose`, `debug`).
+   */
+  logLevel: (typeof logLevel)[keyof typeof logLevel]
+}
+
+/**
+ * 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>
+
+/**
+ * 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) {
+ *     // … register event handlers …
+ *     return () => ({ onStdout: console.log })
  *   },
  * })
  * ```
  */
-export function defineLogger<Options extends LoggerOptions = LoggerOptions>(logger: UserLogger<Options>): Logger<Options> {
+export function defineLogger<Options extends LoggerOptions = LoggerOptions, TInstallReturn = void>(
+  logger: UserLogger<Options, TInstallReturn>,
+): Logger<Options, TInstallReturn> {
   return logger
 }