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

package/dist/{diagnostics-Ba-FcsPo.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.
@@ -679,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;
   /**
@@ -1976,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
@@ -2078,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()
@@ -2383,7 +2526,7 @@ type KubbDiagnosticContext = {
 };
 type KubbFilesProcessingStartContext = {
   /**
-   * Files about to be serialised and written.
+   * Files about to be serialized and written.
    */
   files: Array<FileNode>;
 };
@@ -2401,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;
   /**
@@ -2421,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>;
 };
@@ -2966,5 +3109,5 @@ declare class Diagnostics {
   static formatLines(diagnostic: Diagnostic): Array<string>;
 }
 //#endregion
-export { Output as $, KubbHookEndContext as A, defineLogger as At, UserConfig as B, createAdapter as Bt, KubbErrorContext as C, UserReporter as Ct, KubbFilesProcessingUpdateContext as D, LoggerContext as Dt, KubbFilesProcessingStartContext as E, Logger as Et, KubbLifecycleStartContext as F, Storage as Ft, KubbDriver as G, Generator$1 as H, KubbPluginsEndContext as I, createStorage as It, Include as J, Exclude$1 as K, KubbSuccessContext as L, Adapter as Lt, KubbHookStartContext as M, Renderer as Mt, KubbHooks as N, RendererFactory as Nt, KubbGenerationEndContext as O, LoggerOptions as Ot, KubbInfoContext as P, createRenderer as Pt, NormalizedPlugin as Q, KubbWarnContext as R, AdapterFactoryOptions as Rt, KubbDiagnosticContext as S, ReporterName as St, KubbFilesProcessingEndContext as T, selectReporters as Tt, GeneratorContext as U, createKubb as V, AsyncEventEmitter as Vt, defineGenerator as W, 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, AdapterSource as zt };
-//# sourceMappingURL=diagnostics-Ba-FcsPo.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

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_memoryStorage = require("./memoryStorage-DZqlEW7H.cjs");
+const require_memoryStorage = require("./memoryStorage-Dldu8sRT.cjs");
 let node_util = require("node:util");
 let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
@@ -61,7 +61,26 @@ const randomColors = [
 */
 function randomCliColor(text) {
 	if (!text) return "";
-	return (0, node_util.styleText)(randomColors[(0, node_crypto.createHash)("sha256").update(text).digest().readUInt32BE(0) % randomColors.length] ?? "white", text);
+	return (0, node_util.styleText)(randomColors[(0, node_crypto.hash)("sha256", text, "buffer").readUInt32BE(0) % randomColors.length] ?? "white", text);
+}
+//#endregion
+//#region ../../internals/utils/src/path.ts
+/**
+* Converts a filesystem path to use POSIX (`/`) separators.
+*
+* Most of the codebase compares and composes paths as strings (prefix matching, joining for
+* import specifiers, splitting on `/`). On POSIX `path.resolve` already returns `/`-separated
+* paths, but on Windows it returns `\`-separated paths, which breaks every such comparison.
+*
+* Routing every path that crosses a module boundary through `toPosixPath` keeps the rest of the
+* code platform-agnostic. The conversion runs unconditionally so Windows-specific behavior is
+* exercisable from POSIX CI.
+*
+* @example
+* toPosixPath('C:\\repo\\src\\pet.ts') // 'C:/repo/src/pet.ts'
+*/
+function toPosixPath(filePath) {
+	return filePath.replaceAll("\\", "/");
 }
 //#endregion
 //#region ../../internals/utils/src/env.ts
@@ -81,8 +100,72 @@ function isCIEnvironment() {
 	return !!(process.env.CI || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI || process.env.BITBUCKET_BUILD_NUMBER || process.env.JENKINS_URL || process.env.CIRCLECI || process.env.TRAVIS || process.env.TEAMCITY_VERSION || process.env.BUILDKITE || process.env.TF_BUILD);
 }
 //#endregion
+//#region ../../internals/utils/src/runtime.ts
+/**
+* Returns `true` when the current process is running under Bun.
+*
+* Detection keys off the global `Bun` object rather than `process.versions`,
+* because Bun polyfills `process.versions.node` for Node compatibility and would
+* otherwise look like Node.
+*
+* @example
+* ```ts
+* if (isBun()) {
+*   await Bun.write(path, data)
+* }
+* ```
+*/
+function isBun() {
+	return typeof Bun !== "undefined";
+}
+/**
+* Returns `true` when the current process is running under Deno.
+*/
+function isDeno() {
+	return typeof globalThis.Deno !== "undefined";
+}
+/**
+* Returns the name of the runtime executing the current process.
+*
+* @example
+* ```ts
+* getRuntimeName() // 'bun' when run with `bun kubb`, 'node' otherwise
+* ```
+*/
+function getRuntimeName() {
+	if (isBun()) return "bun";
+	if (isDeno()) return "deno";
+	return "node";
+}
+/**
+* Returns the version of the active runtime, or an empty string when it cannot be read.
+*
+* @example
+* ```ts
+* getRuntimeVersion() // '1.3.11' under Bun, '22.22.2' under Node
+* ```
+*/
+function getRuntimeVersion() {
+	if (isBun()) return process.versions.bun ?? "";
+	if (isDeno()) return globalThis.Deno?.version?.deno ?? "";
+	return process.versions?.node ?? "";
+}
+//#endregion
 //#region ../../internals/utils/src/fs.ts
 /**
+* Reads the file at `path` as a UTF-8 string.
+* Uses `Bun.file().text()` when running under Bun, `fs.readFile` otherwise.
+*
+* @example
+* ```ts
+* const source = await read('./src/Pet.ts')
+* ```
+*/
+async function read(path) {
+	if (isBun()) return Bun.file(path).text();
+	return (0, node_fs_promises.readFile)(path, { encoding: "utf8" });
+}
+/**
 * Writes `data` to `path`, trimming leading/trailing whitespace before saving.
 * Skips the write when the trimmed content is empty or identical to what is already on disk.
 * Creates any missing parent directories automatically.
@@ -99,7 +182,7 @@ async function write(path, data, options = {}) {
 	const trimmed = data.trim();
 	if (trimmed === "") return null;
 	const resolved = (0, node_path.resolve)(path);
-	if (typeof Bun !== "undefined") {
+	if (isBun()) {
 		const file = Bun.file(resolved);
 		if ((await file.exists() ? await file.text() : null) === trimmed) return null;
 		await Bun.write(resolved, trimmed);
@@ -212,6 +295,35 @@ function createAdapter(build) {
 	return (options) => build(options ?? {});
 }
 //#endregion
+//#region src/createCache.ts
+/**
+* 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)
+*     },
+*   }
+* })
+* ```
+*/
+function createCache(build) {
+	return (options) => build(options ?? {});
+}
+//#endregion
 //#region src/storages/fsStorage.ts
 /**
 * Built-in filesystem storage driver.
@@ -263,21 +375,21 @@ const fsStorage = require_memoryStorage.createStorage(() => ({
 	},
 	async getKeys(base) {
 		const resolvedBase = (0, node_path.resolve)(base ?? process.cwd());
-		async function* walk(dir, prefix) {
-			let entries;
-			try {
-				entries = await (0, node_fs_promises.readdir)(dir, { withFileTypes: true });
-			} catch (_error) {
-				return;
-			}
-			for (const entry of entries) {
-				const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-				if (entry.isDirectory()) yield* walk((0, node_path.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 = [];
-		for await (const key of walk(resolvedBase, "")) keys.push(key);
+		try {
+			for await (const entry of (0, node_fs_promises.glob)("**/*", {
+				cwd: resolvedBase,
+				withFileTypes: true
+			})) if (entry.isFile()) keys.push(toPosixPath((0, node_path.relative)(resolvedBase, (0, node_path.join)(entry.parentPath, entry.name))));
+		} catch (_error) {}
 		return keys;
 	},
 	async clear(base) {
@@ -336,6 +448,7 @@ function resolveConfig(userConfig) {
 			...userConfig.output
 		},
 		storage: userConfig.storage ?? fsStorage(),
+		cache: userConfig.cache === false ? void 0 : userConfig.cache,
 		reporters: userConfig.reporters ?? [],
 		plugins: userConfig.plugins ?? []
 	};
@@ -766,6 +879,8 @@ var Telemetry = class Telemetry {
 			command: options.command,
 			kubbVersion: options.kubbVersion,
 			nodeVersion: node_process.default.versions.node.split(".")[0],
+			runtime: getRuntimeName(),
+			runtimeVersion: getRuntimeVersion().split(".")[0],
 			platform: node_os.default.platform(),
 			ci: isCIEnvironment(),
 			plugins: options.plugins ?? [],
@@ -796,6 +911,14 @@ var Telemetry = class Telemetry {
 				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 }
@@ -1027,6 +1150,132 @@ function defineParser(parser) {
 	return parser;
 }
 //#endregion
+//#region src/Manifest.ts
+/**
+* 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`.
+*/
+var Manifest = 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) {
+		try {
+			const parsed = JSON.parse(await read((0, node_path.join)(dir, "manifest.json")));
+			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, { maxEntries, ttlDays, now }) {
+		const ttlMs = ttlDays * 24 * 60 * 60 * 1e3;
+		const removed = [];
+		const kept = [];
+		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() {
+		return {
+			version: Manifest.version,
+			entries: {}
+		};
+	}
+};
+//#endregion
+//#region src/caches/fsCache.ts
+function blobName(relativePath) {
+	return `${(0, node_crypto.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(),
+* })
+* ```
+*/
+const fsCache = createCache((options = {}) => {
+	const dir = (0, node_path.resolve)(options.dir ?? (0, node_path.join)("node_modules", ".cache", "kubb"));
+	const maxEntries = options.maxEntries ?? 50;
+	const ttlDays = options.ttlDays ?? 7;
+	const blobsDir = (0, node_path.join)(dir, "blobs");
+	const manifestPath = (0, node_path.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((0, node_path.join)(blobsDir, key, "index.json")));
+				const files = {};
+				for (const { path, blob } of index) files[path] = await read((0, node_path.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 = (0, node_path.join)(blobsDir, key);
+			const index = [];
+			for (const [path, source] of Object.entries(snapshot.files)) {
+				const blob = blobName(path);
+				await write((0, node_path.join)(entryDir, blob), source);
+				index.push({
+					path,
+					blob
+				});
+			}
+			await write((0, node_path.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((0, node_path.join)(blobsDir, removedKey))));
+			await write(manifestPath, JSON.stringify(pruned.manifest));
+		}
+	};
+});
+//#endregion
 exports.AsyncEventEmitter = require_memoryStorage.AsyncEventEmitter;
 exports.Diagnostics = require_memoryStorage.Diagnostics;
 exports.KubbDriver = require_memoryStorage.KubbDriver;
@@ -1040,6 +1289,7 @@ Object.defineProperty(exports, "ast", {
 });
 exports.cliReporter = cliReporter;
 exports.createAdapter = createAdapter;
+exports.createCache = createCache;
 exports.createKubb = createKubb;
 exports.createRenderer = createRenderer;
 exports.createReporter = createReporter;
@@ -1051,6 +1301,7 @@ exports.defineParser = defineParser;
 exports.definePlugin = require_memoryStorage.definePlugin;
 exports.defineResolver = require_memoryStorage.defineResolver;
 exports.fileReporter = fileReporter;
+exports.fsCache = fsCache;
 exports.fsStorage = fsStorage;
 exports.jsonReporter = jsonReporter;
 exports.logLevel = logLevel;