@kubb/core 5.0.0-beta.40 → 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.
@@ -473,6 +535,11 @@ export class KubbDriver {
    * A failing plugin contributes an error diagnostic so the rest of the build continues.
    * Every plugin also contributes a `timing` diagnostic.
    *
+   * Plugins run sequentially so `kubb:plugin:end` fires as each plugin completes, instead
+   * of all at once after every plugin has marched through the parallel batches together.
+   * That ordering is what drives the CLI's `Plugins N/M` counter; without it the bar would
+   * sit at the initial value until the very end of the run.
+   *
    * When `entries` is empty or `this.inputNode` is `null`, every entry still gets a
    * `kubb:plugin:end` so middleware listeners (the barrel writer and friends) complete.
    */
@@ -526,22 +593,25 @@ export class KubbDriver {
 
     const emitsSchemaHook = this.hooks.listenerCount('kubb:generate:schema') > 0
     const emitsOperationHook = this.hooks.listenerCount('kubb:generate:operation') > 0
+    const emitsOperationsHook = this.hooks.listenerCount('kubb:generate:operations') > 0
+
+    // 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> = 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,
-    // since transitive reachability can't be derived from a single node. `allSchemas` is
-    // released as soon as the pre-scan returns, so the main passes get fresh iterators.
+    // since transitive reachability can't be derived from a single node.
     const pruningStates = states.filter(({ plugin }) => {
       const { include } = plugin.options
       return (include?.some(({ type }) => OPERATION_FILTER_TYPES.has(type)) ?? false) && !(include?.some(({ type }) => type === 'schemaName') ?? false)
     })
 
     if (pruningStates.length > 0) {
-      const allSchemas: Array<SchemaNode> = []
-      for await (const schema of schemas) allSchemas.push(schema)
-
       const includedOpsByState = new Map<PluginState, Array<OperationNode>>(pruningStates.map((state) => [state, []]))
-      for await (const operation of operations) {
+      for (const operation of operationsBuffer) {
         for (const state of pruningStates) {
           const { exclude, include, override } = state.plugin.options
           const options = state.generatorContext.resolver.resolveOptions(operation, { options: state.plugin.options, exclude, include, override })
@@ -550,7 +620,7 @@ export class KubbDriver {
       }
 
       for (const state of pruningStates) {
-        state.allowedSchemaNames = collectUsedSchemaNames(includedOpsByState.get(state) ?? [], allSchemas)
+        state.allowedSchemaNames = collectUsedSchemaNames(includedOpsByState.get(state) ?? [], schemasBuffer)
         includedOpsByState.delete(state)
       }
     }
@@ -628,30 +698,29 @@ export class KubbDriver {
       emit: emitsOperationHook ? (node: OperationNode, ctx: GeneratorContext) => this.hooks.emit('kubb:generate:operation', node, ctx) : null,
     } as const
 
-    // Skip building the aggregated operations array when nothing consumes it. Saves an
-    // N-sized allocation on the common path where plugins only define per-node `gen.operation`.
-    const needsCollectedOperations =
-      this.hooks.listenerCount('kubb:generate:operations') > 0 || states.some((state) => state.generators.some((gen) => !!gen.operations))
-    const collectedOperations: Array<OperationNode> | undefined = needsCollectedOperations ? [] : undefined
-
-    // Run schemas before operations: the two passes share `flushPending` and the
-    // FileProcessor's event emitter, so running them concurrently would interleave
-    // `kubb:files:processing:start|end` events and race on the shared dirty list.
-    await forBatches(schemas, (nodes) => Promise.all(nodes.flatMap((node) => states.map((state) => dispatchNode(state, node, schemaDispatch)))), {
-      concurrency: SCHEMA_PARALLEL,
-      flush: flushPending,
-    })
+    for (const state of states) {
+      // Skip building the aggregated operations array when this plugin doesn't consume it.
+      // Saves an N-sized allocation when the plugin only defines per-node `gen.operation`.
+      const needsCollectedOperations = emitsOperationsHook || state.generators.some((gen) => !!gen.operations)
+      const collectedOperations: Array<OperationNode> | undefined = needsCollectedOperations ? [] : undefined
+
+      // Run schemas before operations: the two passes share `flushPending` and the
+      // FileProcessor's event emitter, so running them concurrently would interleave
+      // `kubb:files:processing:start|end` events and race on the shared dirty list.
+      await forBatches(schemasBuffer, (nodes) => Promise.all(nodes.map((node) => dispatchNode(state, node, schemaDispatch))), {
+        concurrency: SCHEMA_PARALLEL,
+        flush: flushPending,
+      })
 
-    await forBatches(
-      operations,
-      (nodes) => {
-        if (needsCollectedOperations) collectedOperations?.push(...nodes)
-        return Promise.all(nodes.flatMap((node) => states.map((state) => dispatchNode(state, node, operationDispatch))))
-      },
-      { concurrency: SCHEMA_PARALLEL, flush: flushPending },
-    )
+      await forBatches(
+        operationsBuffer,
+        (nodes) => {
+          if (needsCollectedOperations) collectedOperations?.push(...nodes)
+          return Promise.all(nodes.map((node) => dispatchNode(state, node, operationDispatch)))
+        },
+        { concurrency: SCHEMA_PARALLEL, flush: flushPending },
+      )
 
-    for (const state of states) {
       if (!state.failed && needsCollectedOperations) {
         try {
           const { plugin, generatorContext, generators } = state

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))
+}