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

package/README.md

@@ -5,9 +5,9 @@
 
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![Coverage][coverage-src]][coverage-href]
+[![Stars][stars-src]][stars-href]
 [![License][license-src]][license-href]
-[![Sponsors][sponsors-src]][sponsors-href]
+[![Node][node-src]][node-href]
 
 <h4>
 <a href="https://kubb.dev" target="_blank">Documentation</a>
@@ -26,7 +26,7 @@
 
 Core engine for Kubb's plugin-based code generation system. Provides the plugin driver, file manager, `defineConfig`, `definePlugin`, `defineMiddleware`, and the build orchestration layer used by every Kubb plugin.
 
-> **Note:** Most users should install the [`kubb`](https://npmjs.com/package/kubb) meta-package instead of `@kubb/core` directly. Install `@kubb/core` only when building custom plugins or extending the Kubb internals.
+> **Note:** Most users should install the [`kubb`](https://npmx.dev/package/kubb) meta-package instead of `@kubb/core` directly. Install `@kubb/core` only when building custom plugins or extending the Kubb internals.
 
 ## Installation
 
@@ -57,13 +57,13 @@ Kubb is an open source project, and its development is funded entirely by sponso
 
 <!-- Badges -->
 
-[npm-version-src]: https://img.shields.io/npm/v/@kubb/core?flat&colorA=18181B&colorB=f58517
-[npm-version-href]: https://npmjs.com/package/@kubb/core
-[npm-downloads-src]: https://img.shields.io/npm/dm/@kubb/core?flat&colorA=18181B&colorB=f58517
-[npm-downloads-href]: https://npmjs.com/package/@kubb/core
-[license-src]: https://img.shields.io/npm/l/%40kubb%2Fcore?flat&colorA=18181B&colorB=f58517
-[license-href]: https://github.com/kubb-labs/kubb/blob/main/licenses/LICENSE-MIT
-[coverage-src]: https://img.shields.io/codecov/c/github/kubb-labs/kubb?style=flat&colorA=18181B&colorB=f58517
-[coverage-href]: https://www.npmjs.com/package/@kubb/core
-[sponsors-src]: https://img.shields.io/github/sponsors/stijnvanhulle?style=flat&colorA=18181B&colorB=f58517
-[sponsors-href]: https://github.com/sponsors/stijnvanhulle/
+[npm-version-src]: https://shieldcn.dev/npm/v/@kubb/core.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[npm-version-href]: https://npmx.dev/package/@kubb/core
+[npm-downloads-src]: https://shieldcn.dev/npm/dm/@kubb/core.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[npm-downloads-href]: https://npmx.dev/package/@kubb/core
+[stars-src]: https://shieldcn.dev/github/stars/kubb-labs/kubb.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[stars-href]: https://github.com/kubb-labs/kubb
+[license-src]: https://shieldcn.dev/npm/license/@kubb/core.svg?variant=secondary&size=xs&theme=zinc
+[license-href]: https://github.com/kubb-labs/kubb/blob/main/LICENSE
+[node-src]: https://shieldcn.dev/npm/node/@kubb/core.svg?variant=secondary&size=xs&theme=zinc&mode=dark
+[node-href]: https://npmx.dev/package/@kubb/core

package/dist/{diagnostics-DhfW8YpT.d.ts → diagnostics-DZGgDzSv.d.ts}

@@ -238,6 +238,83 @@ type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) =
  */
 declare function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T>;
 //#endregion
+//#region src/createCache.d.ts
+/**
+ * A snapshot of a completed build: the final rendered source of every generated
+ * file, keyed by its path relative to the output root. Restoring a snapshot writes
+ * those sources straight to storage, skipping generation entirely.
+ *
+ * Paths are relative, not absolute, so the snapshot never depends on where the
+ * project lives on disk.
+ */
+type CachedSnapshot = {
+  /**
+   * Final source per output file, keyed by the path relative to
+   * `resolve(config.root, config.output.path)`.
+   */
+  files: Record<string, string>;
+};
+/**
+ * Backend that stores build snapshots for incremental ("hot") rebuilds. When the
+ * input fingerprint matches a stored key, Kubb restores the snapshot instead of
+ * regenerating. Kubb ships with `fsCache` (local disk). Implement this interface to
+ * back the cache with any other store.
+ *
+ * @see {@link createCache} to build a custom backend.
+ */
+type Cache = {
+  /**
+   * Identifier used in logs and diagnostics (`'fs'`, `'memory'`).
+   */
+  readonly name: string;
+  /**
+   * Returns the snapshot stored under `key`, or `null` on a miss. A backend never
+   * throws on a miss or a transient failure. It returns `null` so the build falls
+   * through to regeneration.
+   */
+  restore(params: {
+    key: string;
+  }): Promise<CachedSnapshot | null>;
+  /**
+   * Stores `snapshot` under `key`. Only called after a successful build with no
+   * error diagnostics.
+   */
+  persist(params: {
+    key: string;
+    snapshot: CachedSnapshot;
+  }): Promise<void>;
+  /**
+   * Optional teardown called after the build. Use to flush buffers or close
+   * connections.
+   */
+  dispose?(): Promise<void>;
+};
+/**
+ * Defines a custom cache backend. The builder receives user options and returns a
+ * {@link Cache}. Reach for this when the filesystem backend doesn't fit, for
+ * example to store snapshots in Redis or a database.
+ *
+ * @example In-memory cache (the built-in implementation)
+ * ```ts
+ * import { createCache } from '@kubb/core'
+ *
+ * export const memoryCache = createCache(() => {
+ *   const store = new Map<string, CachedSnapshot>()
+ *
+ *   return {
+ *     name: 'memory',
+ *     async restore({ key }) {
+ *       return store.get(key) ?? null
+ *     },
+ *     async persist({ key, snapshot }) {
+ *       store.set(key, snapshot)
+ *     },
+ *   }
+ * })
+ * ```
+ */
+declare function createCache<TOptions = Record<string, never>>(build: (options: TOptions) => Cache): (options?: TOptions) => Cache;
+//#endregion
 //#region src/constants.d.ts
 /**
  * Stable codes Kubb attaches to a `Diagnostic`. Each maps to a known failure mode
@@ -493,6 +570,47 @@ type RendererFactory<TElement = unknown> = () => Renderer<TElement>;
  */
 declare function createRenderer<TElement = unknown>(factory: RendererFactory<TElement>): RendererFactory<TElement>;
 //#endregion
+//#region src/caches/fsCache.d.ts
+/**
+ * Options for {@link fsCache}.
+ */
+type FsCacheOptions = {
+  /**
+   * Directory that holds the cache. Resolved against `process.cwd()` when relative.
+   *
+   * @default 'node_modules/.cache/kubb'
+   */
+  dir?: string;
+  /**
+   * Maximum number of build snapshots to keep. The least-recently-used entries are
+   * evicted once the cache grows past it.
+   *
+   * @default 50
+   */
+  maxEntries?: number;
+  /**
+   * Days a snapshot may go untouched before it is evicted.
+   *
+   * @default 7
+   */
+  ttlDays?: number;
+};
+/**
+ * Local filesystem cache. Stores each build snapshot as content blobs plus an index,
+ * tracked by a manifest under `node_modules/.cache/kubb/` (the Nx and Vitest
+ * convention). Least-recently-used and expired entries are pruned on every persist.
+ *
+ * @example
+ * ```ts
+ * import { fsCache } from '@kubb/core'
+ *
+ * export default defineConfig({
+ *   cache: fsCache(),
+ * })
+ * ```
+ */
+declare const fsCache: (options?: FsCacheOptions | undefined) => Cache;
+//#endregion
 //#region src/defineLogger.d.ts
 /**
  * Numeric log-level thresholds used internally to compare verbosity.
@@ -524,27 +642,25 @@ 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).
+ * (console, file, remote service).
  */
-type Logger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = {
+type Logger<TOptions extends LoggerOptions = LoggerOptions> = {
   /**
    * 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.
+   * Called once per build with the shared event emitter. Subscribe to the
+   * lifecycle events the logger wants to forward to its destination.
    */
-  install: (context: LoggerContext, options?: TOptions) => TInstallReturn | Promise<TInstallReturn>;
+  install: (context: LoggerContext, options?: TOptions) => void | Promise<void>;
 };
-type UserLogger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = Logger<TOptions, TInstallReturn>;
+type UserLogger<TOptions extends LoggerOptions = LoggerOptions> = Logger<TOptions>;
 /**
- * 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.
+ * Defines a typed logger. The `install` method subscribes to lifecycle events
+ * on the shared emitter and forwards them to the logger's destination.
  *
- * @example Basic logger
+ * @example
  * ```ts
  * import { defineLogger } from '@kubb/core'
  *
@@ -556,22 +672,8 @@ type UserLogger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn =
  *   },
  * })
  * ```
- *
- * @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 })
- *   },
- * })
- * ```
  */
-declare function defineLogger<Options extends LoggerOptions = LoggerOptions, TInstallReturn = void>(logger: UserLogger<Options, TInstallReturn>): Logger<Options, TInstallReturn>;
+declare function defineLogger<Options extends LoggerOptions = LoggerOptions>(logger: UserLogger<Options>): Logger<Options>;
 //#endregion
 //#region src/createReporter.d.ts
 /**
@@ -695,7 +797,7 @@ type Parser<TMeta extends object = object, TNode = unknown> = {
    */
   extNames: Array<FileNode['extname']> | undefined;
   /**
-   * Serialise the file's AST into source code.
+   * Serialize the file's AST into source code.
    */
   parse(file: FileNode<TMeta>, options?: PrintOptions): string;
   /**
@@ -1992,6 +2094,26 @@ type Config<TInput = Input> = {
    * @see {@link Storage} interface for implementing custom backends.
    */
   storage: Storage;
+  /**
+   * Incremental build cache. Kubb fingerprints the inputs (spec content, config, plugin options,
+   * versions) and, on an unchanged "hot" run, restores the previously generated output instead of
+   * regenerating it. Same idea as Nx's computation cache.
+   *
+   * `defineConfig` enables `fsCache()` (local disk under `node_modules/.cache/kubb`) by default.
+   * Pass another backend to change where snapshots live, or `false` to turn caching off. A bare
+   * `createKubb` leaves it off unless a cache is provided.
+   *
+   * @example
+   * ```ts
+   * import { fsCache } from '@kubb/core'
+   *
+   * cache: fsCache({ dir: '.kubb-cache' })
+   * cache: false
+   * ```
+   *
+   * @see {@link Cache} interface for implementing custom backends.
+   */
+  cache?: Cache;
   /**
    * Plugins that run during the build to generate code and transform the AST. Each one processes
    * the adapter's AST and can emit files for a different target (TypeScript, Zod, Faker). A plugin
@@ -2094,7 +2216,12 @@ type Config<TInput = Input> = {
  * })
  * ```
  */
-type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage' | 'reporters'> & {
+type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage' | 'reporters' | 'cache'> & {
+  /**
+   * Incremental build cache. Defaults to `fsCache()` (local disk). Pass another {@link Cache}
+   * backend, or `false` to turn caching off.
+   */
+  cache?: Cache | false;
   /**
    * Project root directory, absolute or relative to the config file location.
    * @default process.cwd()
@@ -2218,6 +2345,7 @@ interface KubbHooks {
   'kubb:hooks:start': [];
   'kubb:hooks:end': [];
   'kubb:hook:start': [ctx: KubbHookStartContext];
+  'kubb:hook:line': [ctx: KubbHookLineContext];
   'kubb:hook:end': [ctx: KubbHookEndContext];
   'kubb:info': [ctx: KubbInfoContext];
   'kubb:error': [ctx: KubbErrorContext];
@@ -2398,7 +2526,7 @@ type KubbDiagnosticContext = {
 };
 type KubbFilesProcessingStartContext = {
   /**
-   * Files about to be serialised and written.
+   * Files about to be serialized and written.
    */
   files: Array<FileNode>;
 };
@@ -2416,7 +2544,7 @@ type KubbFileProcessingUpdate = {
    */
   percentage: number;
   /**
-   * Serialised file content, or `undefined` when the file produced no output.
+   * Serialized file content, or `undefined` when the file produced no output.
    */
   source?: string;
   /**
@@ -2436,7 +2564,7 @@ type KubbFilesProcessingUpdateContext = {
 };
 type KubbFilesProcessingEndContext = {
   /**
-   * All files that were serialised in this batch.
+   * All files that were serialized in this batch.
    */
   files: Array<FileNode>;
 };
@@ -2454,6 +2582,20 @@ type KubbHookStartContext = {
    */
   args?: ReadonlyArray<string>;
 };
+/**
+ * Emitted for each line streamed from a hook's stdout while it runs.
+ * A logger correlates the line to its active UI element via `id`.
+ */
+type KubbHookLineContext = {
+  /**
+   * Identifier matching the corresponding `kubb:hook:start` event.
+   */
+  id: string;
+  /**
+   * A single streamed stdout line, without its trailing newline.
+   */
+  line: string;
+};
 type KubbHookEndContext = {
   /**
    * Optional identifier matching the corresponding `kubb:hook:start` event.
@@ -2475,6 +2617,14 @@ type KubbHookEndContext = {
    * Error thrown by the command, or `null` on success.
    */
   error: Error | null;
+  /**
+   * Captured stdout from the process, populated when it exits non-zero.
+   */
+  stdout?: string;
+  /**
+   * Captured stderr from the process, populated when it exits non-zero.
+   */
+  stderr?: string;
 };
 /**
  * CLI options derived from command-line flags.
@@ -2959,5 +3109,5 @@ declare class Diagnostics {
   static formatLines(diagnostic: Diagnostic): Array<string>;
 }
 //#endregion
-export { Override as $, KubbHookEndContext as A, logLevel as At, createKubb as B, AsyncEventEmitter as Bt, KubbErrorContext as C, createReporter as Ct, KubbFilesProcessingUpdateContext as D, LoggerOptions as Dt, KubbFilesProcessingStartContext as E, LoggerContext as Et, KubbPluginsEndContext as F, createStorage as Ft, Exclude$1 as G, GeneratorContext as H, KubbSuccessContext as I, Adapter as It, KubbPluginEndContext as J, Group as K, KubbWarnContext as L, AdapterFactoryOptions as Lt, KubbHooks as M, RendererFactory as Mt, KubbInfoContext as N, createRenderer as Nt, KubbGenerationEndContext as O, UserLogger as Ot, KubbLifecycleStartContext as P, Storage as Pt, Output as Q, PossibleConfig as R, AdapterSource as Rt, KubbDiagnosticContext as S, UserReporter as St, KubbFilesProcessingEndContext as T, Logger as Tt, defineGenerator as U, Generator$1 as V, KubbDriver as W, KubbPluginStartContext as X, KubbPluginSetupContext as Y, NormalizedPlugin as Z, InputPath as _, defineParser as _t, DiagnosticLocation as a, ResolveBannerFile as at, KubbBuildStartContext as b, ReporterContext as bt, PerformanceDiagnostic as c, ResolverContext as ct, SerializedDiagnostic as d, defineResolver as dt, Plugin as et, UpdateDiagnostic as f, Middleware as ft, InputData as g, Parser as gt, Config as h, ParsedFile as ht, DiagnosticKind as i, ResolveBannerContext as it, KubbHookStartContext as j, Renderer as jt, KubbGenerationStartContext as k, defineLogger as kt, ProblemCode as l, ResolverFileParams as lt, CLIOptions as m, FileProcessorHooks as mt, DiagnosticByCode as n, definePlugin as nt, DiagnosticSeverity as o, ResolveOptionsContext as ot, BuildOutput as p, defineMiddleware as pt, Include as q, DiagnosticDoc as r, BannerMeta as rt, Diagnostics as s, Resolver as st, Diagnostic as t, PluginFactoryOptions as tt, ProblemDiagnostic as u, ResolverPathParams as ut, Kubb$1 as v, GenerationResult as vt, KubbFileProcessingUpdate as w, selectReporters as wt, KubbConfigEndContext as x, ReporterName as xt, KubbBuildEndContext as y, Reporter as yt, UserConfig as z, createAdapter as zt };
-//# sourceMappingURL=diagnostics-DhfW8YpT.d.ts.map
+export { Output as $, KubbHookEndContext as A, defineLogger as At, UserConfig as B, CachedSnapshot as Bt, KubbErrorContext as C, UserReporter as Ct, KubbFilesProcessingUpdateContext as D, LoggerContext as Dt, KubbFilesProcessingStartContext as E, Logger as Et, KubbLifecycleStartContext as F, RendererFactory as Ft, KubbDriver as G, createAdapter as Gt, Generator$1 as H, Adapter as Ht, KubbPluginsEndContext as I, createRenderer as It, Include as J, Exclude$1 as K, AsyncEventEmitter as Kt, KubbSuccessContext as L, Storage as Lt, KubbHookStartContext as M, FsCacheOptions as Mt, KubbHooks as N, fsCache as Nt, KubbGenerationEndContext as O, LoggerOptions as Ot, KubbInfoContext as P, Renderer as Pt, NormalizedPlugin as Q, KubbWarnContext as R, createStorage as Rt, KubbDiagnosticContext as S, ReporterName as St, KubbFilesProcessingEndContext as T, selectReporters as Tt, GeneratorContext as U, AdapterFactoryOptions as Ut, createKubb as V, createCache as Vt, defineGenerator as W, AdapterSource as Wt, KubbPluginSetupContext as X, KubbPluginEndContext as Y, KubbPluginStartContext as Z, InputPath as _, Parser as _t, DiagnosticLocation as a, ResolveBannerContext as at, KubbBuildStartContext as b, Reporter as bt, PerformanceDiagnostic as c, Resolver as ct, SerializedDiagnostic as d, ResolverPathParams as dt, Override as et, UpdateDiagnostic as f, defineResolver as ft, InputData as g, ParsedFile as gt, Config as h, FileProcessorHooks as ht, DiagnosticKind as i, BannerMeta as it, KubbHookLineContext as j, logLevel as jt, KubbGenerationStartContext as k, UserLogger as kt, ProblemCode as l, ResolverContext as lt, CLIOptions as m, defineMiddleware as mt, DiagnosticByCode as n, PluginFactoryOptions as nt, DiagnosticSeverity as o, ResolveBannerFile as ot, BuildOutput as p, Middleware as pt, Group as q, DiagnosticDoc as r, definePlugin as rt, Diagnostics as s, ResolveOptionsContext as st, Diagnostic as t, Plugin as tt, ProblemDiagnostic as u, ResolverFileParams as ut, Kubb$1 as v, defineParser as vt, KubbFileProcessingUpdate as w, createReporter as wt, KubbConfigEndContext as x, ReporterContext as xt, KubbBuildEndContext as y, GenerationResult as yt, PossibleConfig as z, Cache as zt };
+//# sourceMappingURL=diagnostics-DZGgDzSv.d.ts.map