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

package/src/createKubb.ts

@@ -5,6 +5,7 @@ import type { FileNode, InputMeta, OperationNode, SchemaNode } from '@kubb/ast'
 import { HOOK_LISTENERS_PER_PLUGIN } from './constants.ts'
 import type { Adapter } from './createAdapter.ts'
 import { type Diagnostic, Diagnostics, type ProblemDiagnostic, type UpdateDiagnostic } from './diagnostics.ts'
+import type { Cache } from './createCache.ts'
 import { createStorage, type Storage } from './createStorage.ts'
 import type { GeneratorContext } from './defineGenerator.ts'
 import type { Middleware } from './defineMiddleware.ts'
@@ -233,6 +234,26 @@ export 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
@@ -336,7 +357,12 @@ export type Config<TInput = Input> = {
  * })
  * ```
  */
-export type UserConfig<TInput = Input> = Omit<Config<TInput>, 'root' | 'plugins' | 'parsers' | 'adapter' | 'storage' | 'reporters'> & {
+export 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()
@@ -464,6 +490,7 @@ export 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]
@@ -657,7 +684,7 @@ export type KubbDiagnosticContext = {
 
 export type KubbFilesProcessingStartContext = {
   /**
-   * Files about to be serialised and written.
+   * Files about to be serialized and written.
    */
   files: Array<FileNode>
 }
@@ -676,7 +703,7 @@ export 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
   /**
@@ -698,7 +725,7 @@ export type KubbFilesProcessingUpdateContext = {
 
 export type KubbFilesProcessingEndContext = {
   /**
-   * All files that were serialised in this batch.
+   * All files that were serialized in this batch.
    */
   files: Array<FileNode>
 }
@@ -718,6 +745,21 @@ export 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`.
+ */
+export type KubbHookLineContext = {
+  /**
+   * Identifier matching the corresponding `kubb:hook:start` event.
+   */
+  id: string
+  /**
+   * A single streamed stdout line, without its trailing newline.
+   */
+  line: string
+}
+
 export type KubbHookEndContext = {
   /**
    * Optional identifier matching the corresponding `kubb:hook:start` event.
@@ -739,6 +781,14 @@ export 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
 }
 
 /**
@@ -863,6 +913,9 @@ function resolveConfig(userConfig: UserConfig): Config {
       ...userConfig.output,
     },
     storage: userConfig.storage ?? fsStorage(),
+    // Resolve `false` to "no cache". The default `fsCache()` is applied by `defineConfig`, not here,
+    // so a raw `createKubb` stays deterministic (no surprise on-disk cache) unless a cache is passed.
+    cache: userConfig.cache === false ? undefined : userConfig.cache,
     reporters: userConfig.reporters ?? [],
     plugins: userConfig.plugins ?? [],
   }

package/src/defineLogger.ts

@@ -34,29 +34,27 @@ 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).
+ * (console, file, remote service).
  */
-export type Logger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = {
+export 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>
 }
 
-export type UserLogger<TOptions extends LoggerOptions = LoggerOptions, TInstallReturn = void> = Logger<TOptions, TInstallReturn>
+export 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'
  *
@@ -68,23 +66,7 @@ export type UserLogger<TOptions extends LoggerOptions = LoggerOptions, TInstallR
  *   },
  * })
  * ```
- *
- * @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, TInstallReturn = void>(
-  logger: UserLogger<Options, TInstallReturn>,
-): Logger<Options, TInstallReturn> {
+export function defineLogger<Options extends LoggerOptions = LoggerOptions>(logger: UserLogger<Options>): Logger<Options> {
   return logger
 }

package/src/defineParser.ts

@@ -23,7 +23,7 @@ export 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
   /**

package/src/index.ts

@@ -1,6 +1,7 @@
 export { AsyncEventEmitter, URLPath } from '@internals/utils'
 export * as ast from '@kubb/ast'
 export { createAdapter } from './createAdapter.ts'
+export { createCache } from './createCache.ts'
 export { Diagnostics } from './diagnostics.ts'
 export { createKubb } from './createKubb.ts'
 export { createReporter, selectReporters } from './createReporter.ts'
@@ -17,6 +18,7 @@ export { defineParser } from './defineParser.ts'
 export { definePlugin } from './definePlugin.ts'
 export { defineResolver } from './defineResolver.ts'
 export { KubbDriver } from './KubbDriver.ts'
+export { fsCache } from './caches/fsCache.ts'
 export { fsStorage } from './storages/fsStorage.ts'
 export { memoryStorage } from './storages/memoryStorage.ts'
 export * from './types.ts'

package/src/storages/fsStorage.ts

@@ -1,7 +1,6 @@
-import type { Dirent } from 'node:fs'
-import { access, readdir, readFile, rm } from 'node:fs/promises'
-import { join, resolve } from 'node:path'
-import { clean, write } from '@internals/utils'
+import { access, glob, readFile, rm } from 'node:fs/promises'
+import { join, relative, resolve } from 'node:path'
+import { clean, isBun, toPosixPath, write } from '@internals/utils'
 import { createStorage } from '../createStorage.ts'
 
 /**
@@ -55,29 +54,22 @@ export const fsStorage = createStorage(() => ({
   async getKeys(base?: string) {
     const resolvedBase = resolve(base ?? process.cwd())
 
-    async function* walk(dir: string, prefix: string): AsyncGenerator<string, void, undefined> {
-      let entries: Array<Dirent>
-      try {
-        entries = (await readdir(dir, {
-          withFileTypes: true,
-        })) as Array<Dirent>
-      } catch (_error) {
-        return
-      }
-      for (const entry of entries) {
-        const rel = prefix ? `${prefix}/${entry.name}` : entry.name
-        if (entry.isDirectory()) {
-          yield* walk(join(dir, entry.name), rel)
-        } else {
-          yield rel
-        }
-      }
+    if (isBun()) {
+      const bunGlob = new Bun.Glob('**/*')
+      return Array.fromAsync(bunGlob.scan({ cwd: resolvedBase, onlyFiles: true, dot: true }))
     }
 
     const keys: Array<string> = []
-    for await (const key of walk(resolvedBase, '')) {
-      keys.push(key)
+    try {
+      for await (const entry of glob('**/*', { cwd: resolvedBase, withFileTypes: true })) {
+        if (entry.isFile()) {
+          keys.push(toPosixPath(relative(resolvedBase, join(entry.parentPath, entry.name))))
+        }
+      }
+    } catch (_error) {
+      // base directory does not exist yet
     }
+
     return keys
   },
   async clear(base?: string) {

package/src/types.ts

@@ -1,4 +1,6 @@
 export type { Adapter, AdapterFactoryOptions, AdapterSource } from './createAdapter.ts'
+export type { Cache, CachedSnapshot } from './createCache.ts'
+export type { FsCacheOptions } from './caches/fsCache.ts'
 export type {
   Diagnostic,
   DiagnosticByCode,
@@ -31,6 +33,7 @@ export type {
   KubbGenerationEndContext,
   KubbGenerationStartContext,
   KubbHookEndContext,
+  KubbHookLineContext,
   KubbHookStartContext,
   KubbHooks,
   KubbInfoContext,