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

package/src/Fingerprint.ts

@@ -0,0 +1,98 @@
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+import { URLPath } from '@internals/utils'
+import type { AdapterSource } from './createAdapter.ts'
+import type { Config } from './createKubb.ts'
+
+/**
+ * Computes the cache key for an incremental build. All methods are static, so call them as
+ * `Fingerprint.compute(...)` and `Fingerprint.stringify(...)`. The key holds no absolute
+ * paths or modification times, so it never depends on where the project lives on disk.
+ */
+export class Fingerprint {
+  /**
+   * Bumped when the snapshot format or fingerprint inputs change in an incompatible way, so stale
+   * cache entries from older Kubb builds are never reused.
+   */
+  static version = 1
+
+  /**
+   * Deterministically serializes a value to JSON: object keys are sorted recursively and
+   * `undefined` values and functions are dropped. Two structurally equal configs produce the same
+   * string regardless of key order, which keeps the fingerprint stable across machines.
+   */
+  static stringify(value: unknown): string {
+    return JSON.stringify(Fingerprint.#normalize(value))
+  }
+
+  /**
+   * Computes a cache key from everything that affects the generated output: the spec content, the
+   * output-shaping config, each plugin's name and options, the middleware names, the running
+   * `@kubb/core` version, and the cache format version. Returns `null` when the input can't be
+   * fingerprinted (remote URL or no adapter source), which disables caching for that build.
+   */
+  static async compute({ config, adapterSource, version }: { config: Config; adapterSource: AdapterSource | null; version: string }): Promise<string | null> {
+    if (!adapterSource) {
+      return null
+    }
+
+    const spec = await Fingerprint.#readSpec(adapterSource, config.root)
+    if (spec === null) {
+      return null
+    }
+
+    const input = {
+      cacheVersion: Fingerprint.version,
+      version,
+      spec,
+      name: config.name,
+      output: config.output,
+      adapter: config.adapter?.name,
+      parsers: config.parsers.map((parser) => parser.name),
+      plugins: config.plugins.map((plugin) => ({ name: plugin.name, options: plugin.options })),
+      middleware: (config.middleware ?? []).map((middleware) => middleware.name),
+    }
+
+    return createHash('sha256').update(Fingerprint.stringify(input)).digest('hex')
+  }
+
+  static #normalize(value: unknown): unknown {
+    if (value === null || typeof value !== 'object') {
+      return typeof value === 'function' ? undefined : value
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => Fingerprint.#normalize(item))
+    }
+    const source = value as Record<string, unknown>
+    const result: Record<string, unknown> = {}
+    for (const key of Object.keys(source).sort()) {
+      const normalized = Fingerprint.#normalize(source[key])
+      if (normalized !== undefined) {
+        result[key] = normalized
+      }
+    }
+    return result
+  }
+
+  /**
+   * Reads the spec content that feeds the fingerprint. Returns `null` for a remote URL source
+   * (hashing remote content would mean fetching it on every run) or when a file can't be read, so a
+   * missing or virtual spec disables caching instead of failing the build.
+   */
+  static async #readSpec(source: AdapterSource, root: string): Promise<unknown> {
+    if (source.type === 'data') {
+      return { kind: 'data', data: typeof source.data === 'string' ? source.data : Fingerprint.stringify(source.data) }
+    }
+    const paths = source.type === 'paths' ? source.paths : [source.path]
+    if (paths.some((path) => new URLPath(path).isURL)) {
+      return null
+    }
+    try {
+      const contents = await Promise.all(paths.map(async (path) => ({ path: relative(root, path), content: await readFile(path, 'utf8') })))
+      return { kind: 'path', contents }
+    } catch {
+      return null
+    }
+  }
+}

package/src/KubbDriver.ts

@@ -1,9 +1,12 @@
-import { resolve } from 'node:path'
+import { basename, join, relative, resolve } from 'node:path'
 import { arrayToAsyncIterable, type AsyncEventEmitter, forBatches, getElapsedMs, isPromise, memoize, URLPath } from '@internals/utils'
 import { collectUsedSchemaNames, createFile, createStreamInput } from '@kubb/ast'
 import type { FileNode, InputMeta, InputStreamNode, OperationNode, SchemaNode } from '@kubb/ast'
+import { version as coreVersion } from '../package.json'
 import { OPERATION_FILTER_TYPES, SCHEMA_PARALLEL } from './constants.ts'
+import { Fingerprint } from './Fingerprint.ts'
 import { type Diagnostic, Diagnostics, type ProblemDiagnostic } from './diagnostics.ts'
+import type { Cache } from './createCache.ts'
 import type { RendererFactory } from './createRenderer.ts'
 import type { Storage } from './createStorage.ts'
 import type { Generator } from './defineGenerator.ts'
@@ -105,9 +108,11 @@ export class KubbDriver {
   async setup() {
     const normalized: Array<NormalizedPlugin> = this.config.plugins.map((rawPlugin) => this.#normalizePlugin(rawPlugin as Plugin))
 
+    const dependenciesByName = new Map(normalized.map((plugin) => [plugin.name, new Set(plugin.dependencies ?? [])]))
+
     normalized.sort((a, b) => {
-      if (b.dependencies?.includes(a.name)) return -1
-      if (a.dependencies?.includes(b.name)) return 1
+      if (dependenciesByName.get(b.name)?.has(a.name)) return -1
+      if (dependenciesByName.get(a.name)?.has(b.name)) return 1
 
       return enforceOrder(a.enforce) - enforceOrder(b.enforce)
     })
@@ -352,8 +357,12 @@ export class KubbDriver {
       await hooks.emit('kubb:files:processing:start', { files })
     })
     const updateBuffer: Array<{ file: FileNode; source?: string; processed: number; total: number; percentage: number }> = []
+    // Final rendered source per output path, captured for the cache snapshot on a miss. Barrel
+    // files flow through here too, after the second `drain()`.
+    const snapshotSources = new Map<string, string>()
     processor.hooks.on('update', (item) => {
       updateBuffer.push(item)
+      if (item.source !== undefined) snapshotSources.set(item.file.path, item.source)
     })
     processor.hooks.on('end', async (files) => {
       await hooks.emit('kubb:files:processing:update', {
@@ -373,6 +382,16 @@ export class KubbDriver {
       (diagnostic) => diagnostics.push(diagnostic),
       async () => {
         try {
+          const cache = config.cache
+          const outputRoot = resolve(config.root, config.output.path)
+          const cacheKey = cache ? await Fingerprint.compute({ config, adapterSource: this.#adapterSource, version: coreVersion }) : null
+
+          // On a cache hit, restore the snapshot and skip everything below. Skipping the work is the
+          // whole point, so the only event emitted is `kubb:build:end`, which reporters key off.
+          if (cache && cacheKey && (await this.#restoreSnapshot({ cache, cacheKey, outputRoot, storage }))) {
+            return { diagnostics: Diagnostics.dedupe(diagnostics) }
+          }
+
           // Parse the adapter source into the streaming `InputNode`.
           await this.#parseInput()
           // Emit `kubb:plugin:setup` so plugins can register transformers via `setTransformer`.
@@ -431,7 +450,11 @@ export class KubbDriver {
           // Plugins-end listeners (barrel middleware etc.) may have queued more files.
           await processor.drain()
 
-          await hooks.emit('kubb:build:end', { files: this.fileManager.files, config, outputDir: resolve(config.root, config.output.path) })
+          await hooks.emit('kubb:build:end', { files: this.fileManager.files, config, outputDir: outputRoot })
+
+          if (cache && cacheKey && !Diagnostics.hasError(diagnostics)) {
+            await this.#persistSnapshot({ cache, cacheKey, outputRoot, sources: snapshotSources })
+          }
 
           return { diagnostics: Diagnostics.dedupe(diagnostics) }
         } catch (caughtError) {
@@ -444,6 +467,45 @@ export class KubbDriver {
     )
   }
 
+  /**
+   * Writes a restored snapshot straight to storage and emits `kubb:build:end`. Returns `true` on a
+   * hit (the build is done), `false` on a miss so the caller falls through to a full build.
+   */
+  async #restoreSnapshot({ cache, cacheKey, outputRoot, storage }: { cache: Cache; cacheKey: string; outputRoot: string; storage: Storage }): Promise<boolean> {
+    const snapshot = await cache.restore({ key: cacheKey })
+    if (!snapshot) return false
+
+    for (const [relativePath, source] of Object.entries(snapshot.files)) {
+      const absolutePath = join(outputRoot, relativePath)
+      this.fileManager.upsert(createFile({ path: absolutePath, baseName: basename(relativePath) as `${string}.${string}` }))
+      await storage.setItem(absolutePath, source)
+    }
+    await this.hooks.emit('kubb:build:end', { files: this.fileManager.files, config: this.config, outputDir: outputRoot })
+    return true
+  }
+
+  /**
+   * Stores this run's rendered output, keyed by the input fingerprint, so the next unchanged build
+   * restores it instead of regenerating. `sources` is keyed by absolute path and relativized here.
+   */
+  async #persistSnapshot({
+    cache,
+    cacheKey,
+    outputRoot,
+    sources,
+  }: {
+    cache: Cache
+    cacheKey: string
+    outputRoot: string
+    sources: ReadonlyMap<string, string>
+  }): Promise<void> {
+    const files: Record<string, string> = {}
+    for (const [absolutePath, source] of sources) {
+      files[relative(outputRoot, absolutePath)] = source
+    }
+    await cache.persist({ key: cacheKey, snapshot: { files } })
+  }
+
   // Returns a fresh object with a lazy `files` getter and a bound `upsertFile`.
   // Caller must use `Object.assign(extra, this.#filesPayload())`, not object spread.
   // Spread would eagerly invoke the getter and freeze a stale snapshot into the payload.
@@ -536,10 +598,8 @@ export class KubbDriver {
     // Buffer the streaming adapter's nodes once. Each plugin reads the same buffer
     // instead of re-parsing the document per pass, and the pruning pre-scan below
     // shares it too (previously it iterated its own copies).
-    const schemasBuffer: Array<SchemaNode> = []
-    for await (const schema of schemas) schemasBuffer.push(schema)
-    const operationsBuffer: Array<OperationNode> = []
-    for await (const operation of operations) operationsBuffer.push(operation)
+    const schemasBuffer: Array<SchemaNode> = await Array.fromAsync(schemas)
+    const operationsBuffer: Array<OperationNode> = await Array.fromAsync(operations)
 
     // Pre-scan: plugins with operation-based includes (but no schemaName include) need
     // the reachable schema set. This requires the full schema graph in memory at once,

package/src/Manifest.ts

@@ -0,0 +1,85 @@
+import { join } from 'node:path'
+import { read } from '@internals/utils'
+
+/**
+ * Bookkeeping for one cached build: the relative paths it covers and timestamps used by the pruner.
+ */
+export type ManifestEntry = {
+  files: Array<string>
+  createdAt: number
+  lastAccess: number
+}
+
+/**
+ * The on-disk manifest: a version marker plus an entry per cached build, keyed by fingerprint.
+ */
+export type ManifestData = {
+  version: number
+  entries: Record<string, ManifestEntry>
+}
+
+/**
+ * Reads and prunes the local cache manifest. All methods are static, so call them as
+ * `Manifest.read(dir)` and `Manifest.prune(data, ...)`. A damaged manifest reads as empty so the
+ * cache degrades to misses instead of throwing. Writing goes through `write` from `@internals/utils`.
+ */
+export class Manifest {
+  /**
+   * On-disk layout version for the manifest itself. Bumped when the manifest shape changes; a
+   * mismatch makes the whole local cache read as empty.
+   */
+  static version = 1
+
+  /**
+   * Reads the manifest at `dir/manifest.json`. A missing, corrupt, or version-mismatched file reads
+   * as an empty manifest.
+   */
+  static async read(dir: string): Promise<ManifestData> {
+    try {
+      const parsed = JSON.parse(await read(join(dir, 'manifest.json'))) as ManifestData
+      if (parsed.version !== Manifest.version || typeof parsed.entries !== 'object') {
+        return Manifest.#empty()
+      }
+      return parsed
+    } catch {
+      return Manifest.#empty()
+    }
+  }
+
+  /**
+   * Selects the keys to evict so the cache stays within `ttlDays` and `maxEntries`. Returns the
+   * surviving manifest plus the evicted keys (the caller deletes their blobs). Pure, does no IO.
+   */
+  static prune(
+    manifest: ManifestData,
+    { maxEntries, ttlDays, now }: { maxEntries: number; ttlDays: number; now: number },
+  ): {
+    manifest: ManifestData
+    removed: Array<string>
+  } {
+    const ttlMs = ttlDays * 24 * 60 * 60 * 1000
+    const removed: Array<string> = []
+    const kept: Array<[string, ManifestEntry]> = []
+
+    for (const [key, entry] of Object.entries(manifest.entries)) {
+      if (now - entry.lastAccess > ttlMs) {
+        removed.push(key)
+      } else {
+        kept.push([key, entry])
+      }
+    }
+
+    if (kept.length > maxEntries) {
+      kept.sort((a, b) => b[1].lastAccess - a[1].lastAccess)
+      for (const [key] of kept.splice(maxEntries)) {
+        removed.push(key)
+      }
+    }
+
+    return { manifest: { version: Manifest.version, entries: Object.fromEntries(kept) }, removed }
+  }
+
+  static #empty(): ManifestData {
+    return { version: Manifest.version, entries: {} }
+  }
+}

package/src/Telemetry.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto'
 import os from 'node:os'
 import process from 'node:process'
-import { executeIfOnline, isCIEnvironment } from '@internals/utils'
+import { executeIfOnline, getRuntimeName, getRuntimeVersion, isCIEnvironment, type RuntimeName } from '@internals/utils'
 import { OTLP_ENDPOINT } from './constants.ts'
 
 // OpenTelemetry OTLP JSON types
@@ -114,6 +114,14 @@ export type TelemetryEvent = {
   command: string
   kubbVersion: string
   nodeVersion: string
+  /**
+   * Name of the JavaScript runtime that executed the run, `'bun'`, `'deno'`, or `'node'`.
+   */
+  runtime: RuntimeName
+  /**
+   * Major version of the active runtime, e.g. `'1'` under Bun or `'22'` under Node.
+   */
+  runtimeVersion: string
   platform: string
   ci: boolean
   plugins: Array<TelemetryPlugin>
@@ -158,6 +166,8 @@ export class Telemetry {
       command: options.command,
       kubbVersion: options.kubbVersion,
       nodeVersion: process.versions.node.split('.')[0] as string,
+      runtime: getRuntimeName(),
+      runtimeVersion: getRuntimeVersion().split('.')[0] as string,
       platform: os.platform(),
       ci: isCIEnvironment(),
       plugins: options.plugins ?? [],
@@ -181,6 +191,8 @@ export class Telemetry {
       { key: 'kubb.command', value: { stringValue: event.command } },
       { key: 'kubb.version', value: { stringValue: event.kubbVersion } },
       { key: 'kubb.node_version', value: { stringValue: event.nodeVersion } },
+      { key: 'kubb.runtime', value: { stringValue: event.runtime } },
+      { key: 'kubb.runtime_version', value: { stringValue: event.runtimeVersion } },
       { key: 'kubb.platform', value: { stringValue: event.platform } },
       { key: 'kubb.ci', value: { boolValue: event.ci } },
       { key: 'kubb.files_created', value: { intValue: event.filesCreated } },

package/src/caches/fsCache.ts

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto'
+import { join, resolve } from 'node:path'
+import { clean, read, write } from '@internals/utils'
+import { createCache } from '../createCache.ts'
+import { Manifest } from '../Manifest.ts'
+
+/**
+ * Options for {@link fsCache}.
+ */
+export 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
+}
+
+type IndexFile = Array<{ path: string; blob: string }>
+
+function blobName(relativePath: string): string {
+  return `${createHash('sha256').update(relativePath).digest('hex')}.blob`
+}
+
+/**
+ * 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(),
+ * })
+ * ```
+ */
+export const fsCache = createCache((options: FsCacheOptions = {}) => {
+  const dir = resolve(options.dir ?? join('node_modules', '.cache', 'kubb'))
+  const maxEntries = options.maxEntries ?? 50
+  const ttlDays = options.ttlDays ?? 7
+  const blobsDir = join(dir, 'blobs')
+  const manifestPath = join(dir, 'manifest.json')
+
+  return {
+    name: 'fs',
+    async restore({ key }) {
+      const manifest = await Manifest.read(dir)
+      const entry = manifest.entries[key]
+      if (!entry) {
+        return null
+      }
+
+      try {
+        const index = JSON.parse(await read(join(blobsDir, key, 'index.json'))) as IndexFile
+        const files: Record<string, string> = {}
+        for (const { path, blob } of index) {
+          files[path] = await read(join(blobsDir, key, blob))
+        }
+
+        entry.lastAccess = Date.now()
+        await write(manifestPath, JSON.stringify(manifest)).catch(() => {})
+
+        return { files }
+      } catch {
+        return null
+      }
+    },
+    async persist({ key, snapshot }) {
+      const entryDir = join(blobsDir, key)
+
+      const index: IndexFile = []
+      for (const [path, source] of Object.entries(snapshot.files)) {
+        const blob = blobName(path)
+        await write(join(entryDir, blob), source)
+        index.push({ path, blob })
+      }
+      await write(join(entryDir, 'index.json'), JSON.stringify(index))
+
+      const manifest = await Manifest.read(dir)
+      const now = Date.now()
+      manifest.entries[key] = { files: index.map((item) => item.path), createdAt: now, lastAccess: now }
+
+      const pruned = Manifest.prune(manifest, { maxEntries, ttlDays, now })
+      await Promise.all(pruned.removed.map((removedKey) => clean(join(blobsDir, removedKey))))
+      await write(manifestPath, JSON.stringify(pruned.manifest))
+    },
+  }
+})

package/src/createCache.ts

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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)
+ *     },
+ *   }
+ * })
+ * ```
+ */
+export function createCache<TOptions = Record<string, never>>(build: (options: TOptions) => Cache): (options?: TOptions) => Cache {
+  return (options) => build(options ?? ({} as TOptions))
+}

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()
@@ -658,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>
 }
@@ -677,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
   /**
@@ -699,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>
 }
@@ -887,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/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'