@databricks/appkit 0.0.2

package/dist/cache/index.js

@@ -0,0 +1,307 @@
+import { TelemetryManager } from "../telemetry/telemetry-manager.js";
+import { SpanStatusCode } from "../telemetry/index.js";
+import { deepMerge } from "../utils/merge.js";
+import { init_utils } from "../utils/index.js";
+import { LakebaseConnector } from "../connectors/lakebase/client.js";
+import "../connectors/index.js";
+import { cacheDefaults } from "./defaults.js";
+import { InMemoryStorage } from "./storage/memory.js";
+import { PersistentStorage } from "./storage/persistent.js";
+import "./storage/index.js";
+import { createHash } from "node:crypto";
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+
+//#region src/cache/index.ts
+init_utils();
+/**
+* Cache manager class to handle cache operations.
+* Can be used with in-memory storage or persistent storage (Lakebase).
+*
+* The cache is automatically initialized by AppKit. Use `getInstanceSync()` to access
+* the singleton instance after initialization.
+*
+* @example
+* ```typescript
+* const cache = CacheManager.getInstanceSync();
+* const result = await cache.getOrExecute(["users", userId], () => fetchUser(userId), userKey);
+* ```
+*/
+var CacheManager = class CacheManager {
+	static {
+		this.MIN_CLEANUP_INTERVAL_MS = 6e4;
+	}
+	static {
+		this.instance = null;
+	}
+	static {
+		this.initPromise = null;
+	}
+	constructor(storage, config) {
+		this.name = "cache-manager";
+		this.storage = storage;
+		this.config = config;
+		this.inFlightRequests = /* @__PURE__ */ new Map();
+		this.cleanupInProgress = false;
+		this.lastCleanupAttempt = 0;
+		this.telemetry = TelemetryManager.getProvider(this.name, this.config.telemetry);
+		this.telemetryMetrics = {
+			cacheHitCount: this.telemetry.getMeter().createCounter("cache.hit", {
+				description: "Total number of cache hits",
+				unit: "1"
+			}),
+			cacheMissCount: this.telemetry.getMeter().createCounter("cache.miss", {
+				description: "Total number of cache misses",
+				unit: "1"
+			})
+		};
+	}
+	/**
+	* Get the singleton instance of the cache manager (sync version).
+	*
+	* Throws if not initialized - ensure AppKit.create() has completed first.
+	* @returns CacheManager instance
+	*/
+	static getInstanceSync() {
+		if (!CacheManager.instance) throw new Error("CacheManager not initialized. Ensure AppKit.create() has completed before accessing the cache.");
+		return CacheManager.instance;
+	}
+	/**
+	* Initialize and get the singleton instance of the cache manager.
+	* Called internally by AppKit - prefer `getInstanceSync()` for plugin access.
+	* @param userConfig - User configuration for the cache manager
+	* @returns CacheManager instance
+	* @internal
+	*/
+	static async getInstance(userConfig) {
+		if (CacheManager.instance) return CacheManager.instance;
+		if (!CacheManager.initPromise) CacheManager.initPromise = CacheManager.create(userConfig).then((instance) => {
+			CacheManager.instance = instance;
+			return instance;
+		});
+		return CacheManager.initPromise;
+	}
+	/**
+	* Create a new cache manager instance
+	*
+	* Storage selection logic:
+	* 1. If `storage` provided and healthy → use provided storage
+	* 2. If `storage` provided but unhealthy → fallback to InMemory (or disable if strictPersistence)
+	* 3. If no `storage` provided and Lakebase available → use Lakebase
+	* 4. If no `storage` provided and Lakebase unavailable → fallback to InMemory (or disable if strictPersistence)
+	*
+	* @param userConfig - User configuration for the cache manager
+	* @returns CacheManager instance
+	*/
+	static async create(userConfig) {
+		const config = deepMerge(cacheDefaults, userConfig);
+		if (config.storage) {
+			if (await config.storage.healthCheck()) return new CacheManager(config.storage, config);
+			console.warn("[Cache] Provided storage health check failed");
+			if (config.strictPersistence) {
+				console.warn("[Cache] strictPersistence enabled but provided storage unhealthy. Cache disabled.");
+				const disabledConfig = {
+					...config,
+					enabled: false
+				};
+				return new CacheManager(new InMemoryStorage(disabledConfig), disabledConfig);
+			}
+			console.warn("[Cache] Falling back to in-memory cache.");
+			return new CacheManager(new InMemoryStorage(config), config);
+		}
+		try {
+			const connector = new LakebaseConnector({ workspaceClient: new WorkspaceClient({}) });
+			if (await connector.healthCheck()) {
+				const persistentStorage = new PersistentStorage(config, connector);
+				await persistentStorage.initialize();
+				return new CacheManager(persistentStorage, config);
+			}
+			console.warn("[Cache] Lakebase health check failed, default storage unhealthy");
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			console.warn(`[Cache] Lakebase unavailable: ${errorMessage}`);
+		}
+		if (config.strictPersistence) {
+			console.warn("[Cache] strictPersistence enabled but lakebase unavailable. Cache disabled.");
+			const disabledConfig = {
+				...config,
+				enabled: false
+			};
+			return new CacheManager(new InMemoryStorage(disabledConfig), disabledConfig);
+		}
+		console.warn("[Cache] Falling back to in-memory cache.");
+		return new CacheManager(new InMemoryStorage(config), config);
+	}
+	/**
+	* Get or execute a function and cache the result
+	* @param key - Cache key
+	* @param fn - Function to execute
+	* @param userKey - User key
+	* @param options - Options for the cache
+	* @returns Promise of the result
+	*/
+	async getOrExecute(key, fn, userKey, options) {
+		if (!this.config.enabled) return fn();
+		const cacheKey = this.generateKey(key, userKey);
+		return this.telemetry.startActiveSpan("cache.getOrExecute", { attributes: {
+			"cache.key": cacheKey,
+			"cache.enabled": this.config.enabled,
+			"cache.persistent": this.storage.isPersistent()
+		} }, async (span) => {
+			try {
+				const cached = await this.storage.get(cacheKey);
+				if (cached !== null) {
+					span.setAttribute("cache.hit", true);
+					span.setStatus({ code: SpanStatusCode.OK });
+					this.telemetryMetrics.cacheHitCount.add(1, { "cache.key": cacheKey });
+					return cached.value;
+				}
+				const inFlight = this.inFlightRequests.get(cacheKey);
+				if (inFlight) {
+					span.setAttribute("cache.hit", true);
+					span.setAttribute("cache.deduplication", true);
+					span.addEvent("cache.deduplication_used", { "cache.key": cacheKey });
+					span.setStatus({ code: SpanStatusCode.OK });
+					this.telemetryMetrics.cacheHitCount.add(1, {
+						"cache.key": cacheKey,
+						"cache.deduplication": "true"
+					});
+					span.end();
+					return inFlight;
+				}
+				span.setAttribute("cache.hit", false);
+				span.addEvent("cache.miss", { "cache.key": cacheKey });
+				this.telemetryMetrics.cacheMissCount.add(1, { "cache.key": cacheKey });
+				const promise = fn().then(async (result$1) => {
+					await this.set(cacheKey, result$1, options);
+					span.addEvent("cache.value_stored", {
+						"cache.key": cacheKey,
+						"cache.ttl": options?.ttl ?? this.config.ttl ?? 3600
+					});
+					return result$1;
+				}).catch((error) => {
+					span.recordException(error);
+					span.setStatus({ code: SpanStatusCode.ERROR });
+					throw error;
+				}).finally(() => {
+					this.inFlightRequests.delete(cacheKey);
+				});
+				this.inFlightRequests.set(cacheKey, promise);
+				const result = await promise;
+				span.setStatus({ code: SpanStatusCode.OK });
+				return result;
+			} catch (error) {
+				span.recordException(error);
+				span.setStatus({ code: SpanStatusCode.ERROR });
+				throw error;
+			} finally {
+				span.end();
+			}
+		}, {
+			name: this.name,
+			includePrefix: true
+		});
+	}
+	/**
+	* Get a cached value
+	* @param key - Cache key
+	* @returns Promise of the value or null if not found or expired
+	*/
+	async get(key) {
+		if (!this.config.enabled) return null;
+		this.maybeCleanup();
+		const entry = await this.storage.get(key);
+		if (!entry) return null;
+		if (Date.now() > entry.expiry) {
+			await this.storage.delete(key);
+			return null;
+		}
+		return entry.value;
+	}
+	/** Probabilistically trigger cleanup of expired entries (fire-and-forget) */
+	maybeCleanup() {
+		if (this.cleanupInProgress) return;
+		if (!this.storage.isPersistent()) return;
+		const now = Date.now();
+		if (now - this.lastCleanupAttempt < CacheManager.MIN_CLEANUP_INTERVAL_MS) return;
+		const probability = this.config.cleanupProbability ?? .01;
+		if (Math.random() > probability) return;
+		this.lastCleanupAttempt = now;
+		this.cleanupInProgress = true;
+		this.storage.cleanupExpired().catch((error) => {
+			console.debug("Error cleaning up expired entries:", error);
+		}).finally(() => {
+			this.cleanupInProgress = false;
+		});
+	}
+	/**
+	* Set a value in the cache
+	* @param key - Cache key
+	* @param value - Value to set
+	* @param options - Options for the cache
+	* @returns Promise of the result
+	*/
+	async set(key, value, options) {
+		if (!this.config.enabled) return;
+		const ttl = options?.ttl ?? this.config.ttl ?? 3600;
+		const expiryTime = Date.now() + ttl * 1e3;
+		await this.storage.set(key, {
+			value,
+			expiry: expiryTime
+		});
+	}
+	/**
+	* Delete a value from the cache
+	* @param key - Cache key
+	* @returns Promise of the result
+	*/
+	async delete(key) {
+		if (!this.config.enabled) return;
+		await this.storage.delete(key);
+	}
+	/** Clear the cache */
+	async clear() {
+		await this.storage.clear();
+		this.inFlightRequests.clear();
+	}
+	/**
+	* Check if a value exists in the cache
+	* @param key - Cache key
+	* @returns Promise of true if the value exists, false otherwise
+	*/
+	async has(key) {
+		if (!this.config.enabled) return false;
+		const entry = await this.storage.get(key);
+		if (!entry) return false;
+		if (Date.now() > entry.expiry) {
+			await this.storage.delete(key);
+			return false;
+		}
+		return true;
+	}
+	/**
+	* Generate a cache key
+	* @param parts - Parts of the key
+	* @param userKey - User key
+	* @returns Cache key
+	*/
+	generateKey(parts, userKey) {
+		const allParts = [userKey, ...parts];
+		const serialized = JSON.stringify(allParts);
+		return createHash("sha256").update(serialized).digest("hex");
+	}
+	/** Close the cache */
+	async close() {
+		await this.storage.close();
+	}
+	/**
+	* Check if the storage is healthy
+	* @returns Promise of true if the storage is healthy, false otherwise
+	*/
+	async isStorageHealthy() {
+		return this.storage.healthCheck();
+	}
+};
+
+//#endregion
+export { CacheManager };
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["result"],"sources":["../../src/cache/index.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { WorkspaceClient } from \"@databricks/sdk-experimental\";\nimport type { CacheConfig, CacheStorage } from \"shared\";\nimport { LakebaseConnector } from \"@/connectors\";\nimport type { Counter, TelemetryProvider } from \"../telemetry\";\nimport { SpanStatusCode, TelemetryManager } from \"../telemetry\";\nimport { deepMerge } from \"../utils\";\nimport { cacheDefaults } from \"./defaults\";\nimport { InMemoryStorage, PersistentStorage } from \"./storage\";\n\n/**\n * Cache manager class to handle cache operations.\n * Can be used with in-memory storage or persistent storage (Lakebase).\n *\n * The cache is automatically initialized by AppKit. Use `getInstanceSync()` to access\n * the singleton instance after initialization.\n *\n * @example\n * ```typescript\n * const cache = CacheManager.getInstanceSync();\n * const result = await cache.getOrExecute([\"users\", userId], () => fetchUser(userId), userKey);\n * ```\n */\nexport class CacheManager {\n  private static readonly MIN_CLEANUP_INTERVAL_MS = 60_000;\n  private readonly name: string = \"cache-manager\";\n  private static instance: CacheManager | null = null;\n  private static initPromise: Promise<CacheManager> | null = null;\n\n  private storage: CacheStorage;\n  private config: CacheConfig;\n  private inFlightRequests: Map<string, Promise<unknown>>;\n  private cleanupInProgress: boolean;\n  private lastCleanupAttempt: number;\n\n  // Telemetry\n  private telemetry: TelemetryProvider;\n  private telemetryMetrics: {\n    cacheHitCount: Counter;\n    cacheMissCount: Counter;\n  };\n\n  private constructor(storage: CacheStorage, config: CacheConfig) {\n    this.storage = storage;\n    this.config = config;\n    this.inFlightRequests = new Map();\n    this.cleanupInProgress = false;\n    this.lastCleanupAttempt = 0;\n\n    this.telemetry = TelemetryManager.getProvider(\n      this.name,\n      this.config.telemetry,\n    );\n    this.telemetryMetrics = {\n      cacheHitCount: this.telemetry.getMeter().createCounter(\"cache.hit\", {\n        description: \"Total number of cache hits\",\n        unit: \"1\",\n      }),\n      cacheMissCount: this.telemetry.getMeter().createCounter(\"cache.miss\", {\n        description: \"Total number of cache misses\",\n        unit: \"1\",\n      }),\n    };\n  }\n\n  /**\n   * Get the singleton instance of the cache manager (sync version).\n   *\n   * Throws if not initialized - ensure AppKit.create() has completed first.\n   * @returns CacheManager instance\n   */\n  static getInstanceSync(): CacheManager {\n    if (!CacheManager.instance) {\n      throw new Error(\n        \"CacheManager not initialized. Ensure AppKit.create() has completed before accessing the cache.\",\n      );\n    }\n\n    return CacheManager.instance;\n  }\n\n  /**\n   * Initialize and get the singleton instance of the cache manager.\n   * Called internally by AppKit - prefer `getInstanceSync()` for plugin access.\n   * @param userConfig - User configuration for the cache manager\n   * @returns CacheManager instance\n   * @internal\n   */\n  static async getInstance(\n    userConfig?: Partial<CacheConfig>,\n  ): Promise<CacheManager> {\n    if (CacheManager.instance) {\n      return CacheManager.instance;\n    }\n\n    if (!CacheManager.initPromise) {\n      CacheManager.initPromise = CacheManager.create(userConfig).then(\n        (instance) => {\n          CacheManager.instance = instance;\n          return instance;\n        },\n      );\n    }\n\n    return CacheManager.initPromise;\n  }\n\n  /**\n   * Create a new cache manager instance\n   *\n   * Storage selection logic:\n   * 1. If `storage` provided and healthy → use provided storage\n   * 2. If `storage` provided but unhealthy → fallback to InMemory (or disable if strictPersistence)\n   * 3. If no `storage` provided and Lakebase available → use Lakebase\n   * 4. If no `storage` provided and Lakebase unavailable → fallback to InMemory (or disable if strictPersistence)\n   *\n   * @param userConfig - User configuration for the cache manager\n   * @returns CacheManager instance\n   */\n  private static async create(\n    userConfig?: Partial<CacheConfig>,\n  ): Promise<CacheManager> {\n    const config = deepMerge(cacheDefaults, userConfig);\n\n    if (config.storage) {\n      const isHealthy = await config.storage.healthCheck();\n      if (isHealthy) {\n        return new CacheManager(config.storage, config);\n      }\n\n      console.warn(\"[Cache] Provided storage health check failed\");\n\n      if (config.strictPersistence) {\n        console.warn(\n          \"[Cache] strictPersistence enabled but provided storage unhealthy. Cache disabled.\",\n        );\n        const disabledConfig = { ...config, enabled: false };\n        return new CacheManager(\n          new InMemoryStorage(disabledConfig),\n          disabledConfig,\n        );\n      }\n\n      console.warn(\"[Cache] Falling back to in-memory cache.\");\n      return new CacheManager(new InMemoryStorage(config), config);\n    }\n\n    // try to use lakebase storage\n    try {\n      const workspaceClient = new WorkspaceClient({});\n      const connector = new LakebaseConnector({ workspaceClient });\n      const isHealthy = await connector.healthCheck();\n\n      if (isHealthy) {\n        const persistentStorage = new PersistentStorage(config, connector);\n        await persistentStorage.initialize();\n        return new CacheManager(persistentStorage, config);\n      }\n\n      console.warn(\n        \"[Cache] Lakebase health check failed, default storage unhealthy\",\n      );\n    } catch (error) {\n      const errorMessage =\n        error instanceof Error ? error.message : String(error);\n      console.warn(`[Cache] Lakebase unavailable: ${errorMessage}`);\n    }\n\n    if (config.strictPersistence) {\n      console.warn(\n        \"[Cache] strictPersistence enabled but lakebase unavailable. Cache disabled.\",\n      );\n      const disabledConfig = { ...config, enabled: false };\n      return new CacheManager(\n        new InMemoryStorage(disabledConfig),\n        disabledConfig,\n      );\n    }\n\n    console.warn(\"[Cache] Falling back to in-memory cache.\");\n    return new CacheManager(new InMemoryStorage(config), config);\n  }\n\n  /**\n   * Get or execute a function and cache the result\n   * @param key - Cache key\n   * @param fn - Function to execute\n   * @param userKey - User key\n   * @param options - Options for the cache\n   * @returns Promise of the result\n   */\n  async getOrExecute<T>(\n    key: (string | number | object)[],\n    fn: () => Promise<T>,\n    userKey: string,\n    options?: { ttl?: number },\n  ): Promise<T> {\n    if (!this.config.enabled) return fn();\n\n    const cacheKey = this.generateKey(key, userKey);\n\n    return this.telemetry.startActiveSpan(\n      \"cache.getOrExecute\",\n      {\n        attributes: {\n          \"cache.key\": cacheKey,\n          \"cache.enabled\": this.config.enabled,\n          \"cache.persistent\": this.storage.isPersistent(),\n        },\n      },\n      async (span) => {\n        try {\n          // check if the value is in the cache\n          const cached = await this.storage.get<T>(cacheKey);\n          if (cached !== null) {\n            span.setAttribute(\"cache.hit\", true);\n            span.setStatus({ code: SpanStatusCode.OK });\n            this.telemetryMetrics.cacheHitCount.add(1, {\n              \"cache.key\": cacheKey,\n            });\n            return cached.value as T;\n          }\n\n          // check if the value is being processed by another request\n          const inFlight = this.inFlightRequests.get(cacheKey);\n          if (inFlight) {\n            span.setAttribute(\"cache.hit\", true);\n            span.setAttribute(\"cache.deduplication\", true);\n            span.addEvent(\"cache.deduplication_used\", {\n              \"cache.key\": cacheKey,\n            });\n            span.setStatus({ code: SpanStatusCode.OK });\n            this.telemetryMetrics.cacheHitCount.add(1, {\n              \"cache.key\": cacheKey,\n              \"cache.deduplication\": \"true\",\n            });\n            span.end();\n            return inFlight as Promise<T>;\n          }\n\n          // cache miss - execute function\n          span.setAttribute(\"cache.hit\", false);\n          span.addEvent(\"cache.miss\", { \"cache.key\": cacheKey });\n          this.telemetryMetrics.cacheMissCount.add(1, {\n            \"cache.key\": cacheKey,\n          });\n\n          const promise = fn()\n            .then(async (result) => {\n              await this.set(cacheKey, result, options);\n              span.addEvent(\"cache.value_stored\", {\n                \"cache.key\": cacheKey,\n                \"cache.ttl\": options?.ttl ?? this.config.ttl ?? 3600,\n              });\n              return result;\n            })\n            .catch((error) => {\n              span.recordException(error);\n              span.setStatus({ code: SpanStatusCode.ERROR });\n              throw error;\n            })\n            .finally(() => {\n              this.inFlightRequests.delete(cacheKey);\n            });\n\n          this.inFlightRequests.set(cacheKey, promise);\n\n          const result = await promise;\n          span.setStatus({ code: SpanStatusCode.OK });\n          return result;\n        } catch (error) {\n          span.recordException(error as Error);\n          span.setStatus({ code: SpanStatusCode.ERROR });\n          throw error;\n        } finally {\n          span.end();\n        }\n      },\n      { name: this.name, includePrefix: true },\n    );\n  }\n\n  /**\n   * Get a cached value\n   * @param key - Cache key\n   * @returns Promise of the value or null if not found or expired\n   */\n  async get<T>(key: string): Promise<T | null> {\n    if (!this.config.enabled) return null;\n\n    // probabilistic cleanup trigger\n    this.maybeCleanup();\n\n    const entry = await this.storage.get<T>(key);\n    if (!entry) return null;\n\n    if (Date.now() > entry.expiry) {\n      await this.storage.delete(key);\n      return null;\n    }\n    return entry.value as T;\n  }\n\n  /** Probabilistically trigger cleanup of expired entries (fire-and-forget) */\n  private maybeCleanup(): void {\n    if (this.cleanupInProgress) return;\n    if (!this.storage.isPersistent()) return;\n    const now = Date.now();\n    if (now - this.lastCleanupAttempt < CacheManager.MIN_CLEANUP_INTERVAL_MS)\n      return;\n\n    const probability = this.config.cleanupProbability ?? 0.01;\n\n    if (Math.random() > probability) return;\n\n    this.lastCleanupAttempt = now;\n\n    this.cleanupInProgress = true;\n    (this.storage as PersistentStorage)\n      .cleanupExpired()\n      .catch((error) => {\n        console.debug(\"Error cleaning up expired entries:\", error);\n      })\n      .finally(() => {\n        this.cleanupInProgress = false;\n      });\n  }\n\n  /**\n   * Set a value in the cache\n   * @param key - Cache key\n   * @param value - Value to set\n   * @param options - Options for the cache\n   * @returns Promise of the result\n   */\n  async set<T>(\n    key: string,\n    value: T,\n    options?: { ttl?: number },\n  ): Promise<void> {\n    if (!this.config.enabled) return;\n\n    const ttl = options?.ttl ?? this.config.ttl ?? 3600;\n    const expiryTime = Date.now() + ttl * 1000;\n    await this.storage.set(key, { value, expiry: expiryTime });\n  }\n\n  /**\n   * Delete a value from the cache\n   * @param key - Cache key\n   * @returns Promise of the result\n   */\n  async delete(key: string): Promise<void> {\n    if (!this.config.enabled) return;\n    await this.storage.delete(key);\n  }\n\n  /** Clear the cache */\n  async clear(): Promise<void> {\n    await this.storage.clear();\n    this.inFlightRequests.clear();\n  }\n\n  /**\n   * Check if a value exists in the cache\n   * @param key - Cache key\n   * @returns Promise of true if the value exists, false otherwise\n   */\n  async has(key: string): Promise<boolean> {\n    if (!this.config.enabled) return false;\n\n    const entry = await this.storage.get(key);\n    if (!entry) return false;\n\n    if (Date.now() > entry.expiry) {\n      await this.storage.delete(key);\n      return false;\n    }\n    return true;\n  }\n\n  /**\n   * Generate a cache key\n   * @param parts - Parts of the key\n   * @param userKey - User key\n   * @returns Cache key\n   */\n  generateKey(parts: (string | number | object)[], userKey: string): string {\n    const allParts = [userKey, ...parts];\n    const serialized = JSON.stringify(allParts);\n    return createHash(\"sha256\").update(serialized).digest(\"hex\");\n  }\n\n  /** Close the cache */\n  async close(): Promise<void> {\n    await this.storage.close();\n  }\n\n  /**\n   * Check if the storage is healthy\n   * @returns Promise of true if the storage is healthy, false otherwise\n   */\n  async isStorageHealthy(): Promise<boolean> {\n    return this.storage.healthCheck();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;YAMqC;;;;;;;;;;;;;;AAiBrC,IAAa,eAAb,MAAa,aAAa;;iCAC0B;;;kBAEH;;;qBACY;;CAe3D,AAAQ,YAAY,SAAuB,QAAqB;cAjBhC;AAkB9B,OAAK,UAAU;AACf,OAAK,SAAS;AACd,OAAK,mCAAmB,IAAI,KAAK;AACjC,OAAK,oBAAoB;AACzB,OAAK,qBAAqB;AAE1B,OAAK,YAAY,iBAAiB,YAChC,KAAK,MACL,KAAK,OAAO,UACb;AACD,OAAK,mBAAmB;GACtB,eAAe,KAAK,UAAU,UAAU,CAAC,cAAc,aAAa;IAClE,aAAa;IACb,MAAM;IACP,CAAC;GACF,gBAAgB,KAAK,UAAU,UAAU,CAAC,cAAc,cAAc;IACpE,aAAa;IACb,MAAM;IACP,CAAC;GACH;;;;;;;;CASH,OAAO,kBAAgC;AACrC,MAAI,CAAC,aAAa,SAChB,OAAM,IAAI,MACR,iGACD;AAGH,SAAO,aAAa;;;;;;;;;CAUtB,aAAa,YACX,YACuB;AACvB,MAAI,aAAa,SACf,QAAO,aAAa;AAGtB,MAAI,CAAC,aAAa,YAChB,cAAa,cAAc,aAAa,OAAO,WAAW,CAAC,MACxD,aAAa;AACZ,gBAAa,WAAW;AACxB,UAAO;IAEV;AAGH,SAAO,aAAa;;;;;;;;;;;;;;CAetB,aAAqB,OACnB,YACuB;EACvB,MAAM,SAAS,UAAU,eAAe,WAAW;AAEnD,MAAI,OAAO,SAAS;AAElB,OADkB,MAAM,OAAO,QAAQ,aAAa,CAElD,QAAO,IAAI,aAAa,OAAO,SAAS,OAAO;AAGjD,WAAQ,KAAK,+CAA+C;AAE5D,OAAI,OAAO,mBAAmB;AAC5B,YAAQ,KACN,oFACD;IACD,MAAM,iBAAiB;KAAE,GAAG;KAAQ,SAAS;KAAO;AACpD,WAAO,IAAI,aACT,IAAI,gBAAgB,eAAe,EACnC,eACD;;AAGH,WAAQ,KAAK,2CAA2C;AACxD,UAAO,IAAI,aAAa,IAAI,gBAAgB,OAAO,EAAE,OAAO;;AAI9D,MAAI;GAEF,MAAM,YAAY,IAAI,kBAAkB,EAAE,iBADlB,IAAI,gBAAgB,EAAE,CAAC,EACY,CAAC;AAG5D,OAFkB,MAAM,UAAU,aAAa,EAEhC;IACb,MAAM,oBAAoB,IAAI,kBAAkB,QAAQ,UAAU;AAClE,UAAM,kBAAkB,YAAY;AACpC,WAAO,IAAI,aAAa,mBAAmB,OAAO;;AAGpD,WAAQ,KACN,kEACD;WACM,OAAO;GACd,MAAM,eACJ,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;AACxD,WAAQ,KAAK,iCAAiC,eAAe;;AAG/D,MAAI,OAAO,mBAAmB;AAC5B,WAAQ,KACN,8EACD;GACD,MAAM,iBAAiB;IAAE,GAAG;IAAQ,SAAS;IAAO;AACpD,UAAO,IAAI,aACT,IAAI,gBAAgB,eAAe,EACnC,eACD;;AAGH,UAAQ,KAAK,2CAA2C;AACxD,SAAO,IAAI,aAAa,IAAI,gBAAgB,OAAO,EAAE,OAAO;;;;;;;;;;CAW9D,MAAM,aACJ,KACA,IACA,SACA,SACY;AACZ,MAAI,CAAC,KAAK,OAAO,QAAS,QAAO,IAAI;EAErC,MAAM,WAAW,KAAK,YAAY,KAAK,QAAQ;AAE/C,SAAO,KAAK,UAAU,gBACpB,sBACA,EACE,YAAY;GACV,aAAa;GACb,iBAAiB,KAAK,OAAO;GAC7B,oBAAoB,KAAK,QAAQ,cAAc;GAChD,EACF,EACD,OAAO,SAAS;AACd,OAAI;IAEF,MAAM,SAAS,MAAM,KAAK,QAAQ,IAAO,SAAS;AAClD,QAAI,WAAW,MAAM;AACnB,UAAK,aAAa,aAAa,KAAK;AACpC,UAAK,UAAU,EAAE,MAAM,eAAe,IAAI,CAAC;AAC3C,UAAK,iBAAiB,cAAc,IAAI,GAAG,EACzC,aAAa,UACd,CAAC;AACF,YAAO,OAAO;;IAIhB,MAAM,WAAW,KAAK,iBAAiB,IAAI,SAAS;AACpD,QAAI,UAAU;AACZ,UAAK,aAAa,aAAa,KAAK;AACpC,UAAK,aAAa,uBAAuB,KAAK;AAC9C,UAAK,SAAS,4BAA4B,EACxC,aAAa,UACd,CAAC;AACF,UAAK,UAAU,EAAE,MAAM,eAAe,IAAI,CAAC;AAC3C,UAAK,iBAAiB,cAAc,IAAI,GAAG;MACzC,aAAa;MACb,uBAAuB;MACxB,CAAC;AACF,UAAK,KAAK;AACV,YAAO;;AAIT,SAAK,aAAa,aAAa,MAAM;AACrC,SAAK,SAAS,cAAc,EAAE,aAAa,UAAU,CAAC;AACtD,SAAK,iBAAiB,eAAe,IAAI,GAAG,EAC1C,aAAa,UACd,CAAC;IAEF,MAAM,UAAU,IAAI,CACjB,KAAK,OAAO,aAAW;AACtB,WAAM,KAAK,IAAI,UAAUA,UAAQ,QAAQ;AACzC,UAAK,SAAS,sBAAsB;MAClC,aAAa;MACb,aAAa,SAAS,OAAO,KAAK,OAAO,OAAO;MACjD,CAAC;AACF,YAAOA;MACP,CACD,OAAO,UAAU;AAChB,UAAK,gBAAgB,MAAM;AAC3B,UAAK,UAAU,EAAE,MAAM,eAAe,OAAO,CAAC;AAC9C,WAAM;MACN,CACD,cAAc;AACb,UAAK,iBAAiB,OAAO,SAAS;MACtC;AAEJ,SAAK,iBAAiB,IAAI,UAAU,QAAQ;IAE5C,MAAM,SAAS,MAAM;AACrB,SAAK,UAAU,EAAE,MAAM,eAAe,IAAI,CAAC;AAC3C,WAAO;YACA,OAAO;AACd,SAAK,gBAAgB,MAAe;AACpC,SAAK,UAAU,EAAE,MAAM,eAAe,OAAO,CAAC;AAC9C,UAAM;aACE;AACR,SAAK,KAAK;;KAGd;GAAE,MAAM,KAAK;GAAM,eAAe;GAAM,CACzC;;;;;;;CAQH,MAAM,IAAO,KAAgC;AAC3C,MAAI,CAAC,KAAK,OAAO,QAAS,QAAO;AAGjC,OAAK,cAAc;EAEnB,MAAM,QAAQ,MAAM,KAAK,QAAQ,IAAO,IAAI;AAC5C,MAAI,CAAC,MAAO,QAAO;AAEnB,MAAI,KAAK,KAAK,GAAG,MAAM,QAAQ;AAC7B,SAAM,KAAK,QAAQ,OAAO,IAAI;AAC9B,UAAO;;AAET,SAAO,MAAM;;;CAIf,AAAQ,eAAqB;AAC3B,MAAI,KAAK,kBAAmB;AAC5B,MAAI,CAAC,KAAK,QAAQ,cAAc,CAAE;EAClC,MAAM,MAAM,KAAK,KAAK;AACtB,MAAI,MAAM,KAAK,qBAAqB,aAAa,wBAC/C;EAEF,MAAM,cAAc,KAAK,OAAO,sBAAsB;AAEtD,MAAI,KAAK,QAAQ,GAAG,YAAa;AAEjC,OAAK,qBAAqB;AAE1B,OAAK,oBAAoB;AACzB,EAAC,KAAK,QACH,gBAAgB,CAChB,OAAO,UAAU;AAChB,WAAQ,MAAM,sCAAsC,MAAM;IAC1D,CACD,cAAc;AACb,QAAK,oBAAoB;IACzB;;;;;;;;;CAUN,MAAM,IACJ,KACA,OACA,SACe;AACf,MAAI,CAAC,KAAK,OAAO,QAAS;EAE1B,MAAM,MAAM,SAAS,OAAO,KAAK,OAAO,OAAO;EAC/C,MAAM,aAAa,KAAK,KAAK,GAAG,MAAM;AACtC,QAAM,KAAK,QAAQ,IAAI,KAAK;GAAE;GAAO,QAAQ;GAAY,CAAC;;;;;;;CAQ5D,MAAM,OAAO,KAA4B;AACvC,MAAI,CAAC,KAAK,OAAO,QAAS;AAC1B,QAAM,KAAK,QAAQ,OAAO,IAAI;;;CAIhC,MAAM,QAAuB;AAC3B,QAAM,KAAK,QAAQ,OAAO;AAC1B,OAAK,iBAAiB,OAAO;;;;;;;CAQ/B,MAAM,IAAI,KAA+B;AACvC,MAAI,CAAC,KAAK,OAAO,QAAS,QAAO;EAEjC,MAAM,QAAQ,MAAM,KAAK,QAAQ,IAAI,IAAI;AACzC,MAAI,CAAC,MAAO,QAAO;AAEnB,MAAI,KAAK,KAAK,GAAG,MAAM,QAAQ;AAC7B,SAAM,KAAK,QAAQ,OAAO,IAAI;AAC9B,UAAO;;AAET,SAAO;;;;;;;;CAST,YAAY,OAAqC,SAAyB;EACxE,MAAM,WAAW,CAAC,SAAS,GAAG,MAAM;EACpC,MAAM,aAAa,KAAK,UAAU,SAAS;AAC3C,SAAO,WAAW,SAAS,CAAC,OAAO,WAAW,CAAC,OAAO,MAAM;;;CAI9D,MAAM,QAAuB;AAC3B,QAAM,KAAK,QAAQ,OAAO;;;;;;CAO5B,MAAM,mBAAqC;AACzC,SAAO,KAAK,QAAQ,aAAa"}

package/dist/cache/storage/defaults.js

@@ -0,0 +1,16 @@
+//#region src/cache/storage/defaults.ts
+/** Default configuration for in-memory storage */
+const inMemoryStorageDefaults = { maxSize: 1e3 };
+/** Default configuration for Lakebase storage */
+const lakebaseStorageDefaults = {
+	tableName: "appkit_cache_entries",
+	maxBytes: 256 * 1024 * 1024,
+	maxEntryBytes: 10 * 1024 * 1024,
+	maxSize: 1e3,
+	evictionBatchSize: 100,
+	evictionCheckProbability: .1
+};
+
+//#endregion
+export { inMemoryStorageDefaults, lakebaseStorageDefaults };
+//# sourceMappingURL=defaults.js.map

package/dist/cache/storage/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","names":[],"sources":["../../../src/cache/storage/defaults.ts"],"sourcesContent":["/** Default configuration for in-memory storage */\nexport const inMemoryStorageDefaults = {\n  /** Maximum number of entries in the cache */\n  maxSize: 1000,\n};\n\n/** Default configuration for Lakebase storage */\nexport const lakebaseStorageDefaults = {\n  /** Table name for the cache */\n  tableName: \"appkit_cache_entries\",\n  /** Maximum number of bytes in the cache */\n  maxBytes: 256 * 1024 * 1024, // 256MB\n  /** Maximum number of bytes per entry in the cache */\n  maxEntryBytes: 10 * 1024 * 1024, // 10MB\n  /** Maximum number of entries in the cache */\n  maxSize: 1000,\n  /** Number of entries to evict when cache is full */\n  evictionBatchSize: 100,\n  /** Probability (0-1) of checking total bytes on each write operation */\n  evictionCheckProbability: 0.1,\n};\n"],"mappings":";;AACA,MAAa,0BAA0B,EAErC,SAAS,KACV;;AAGD,MAAa,0BAA0B;CAErC,WAAW;CAEX,UAAU,MAAM,OAAO;CAEvB,eAAe,KAAK,OAAO;CAE3B,SAAS;CAET,mBAAmB;CAEnB,0BAA0B;CAC3B"}

package/dist/cache/storage/index.js

@@ -0,0 +1,4 @@
+import { InMemoryStorage } from "./memory.js";
+import { PersistentStorage } from "./persistent.js";
+
+export {  };

package/dist/cache/storage/memory.js

@@ -0,0 +1,87 @@
+import { inMemoryStorageDefaults } from "./defaults.js";
+
+//#region src/cache/storage/memory.ts
+/**
+* In-memory cache storage implementation. Uses a least recently used (LRU) eviction policy
+* to manage memory usage and ensure efficient cache operations.
+*/
+var InMemoryStorage = class {
+	constructor(config) {
+		this.cache = /* @__PURE__ */ new Map();
+		this.accessOrder = /* @__PURE__ */ new Map();
+		this.cache = /* @__PURE__ */ new Map();
+		this.accessOrder = /* @__PURE__ */ new Map();
+		this.maxSize = config.maxSize ?? inMemoryStorageDefaults.maxSize;
+		this.accessCounter = 0;
+	}
+	/** Get an entry from the cache */
+	async get(key) {
+		const entry = this.cache.get(key);
+		if (!entry) return null;
+		this.accessOrder.set(key, ++this.accessCounter);
+		return entry;
+	}
+	/** Set an entry in the cache */
+	async set(key, entry) {
+		if (this.cache.size >= this.maxSize && !this.cache.has(key)) this.evictLRU();
+		this.cache.set(key, entry);
+		this.accessOrder.set(key, ++this.accessCounter);
+	}
+	/** Delete an entry from the cache */
+	async delete(key) {
+		this.cache.delete(key);
+		this.accessOrder.delete(key);
+	}
+	/** Clean in-memory cache */
+	async clear() {
+		this.cache.clear();
+		this.accessOrder.clear();
+		this.accessCounter = 0;
+	}
+	/** Check if the cache has an entry */
+	async has(key) {
+		const entry = this.cache.get(key);
+		if (!entry) return false;
+		if (Date.now() > entry.expiry) {
+			this.cache.delete(key);
+			this.accessOrder.delete(key);
+			return false;
+		}
+		return true;
+	}
+	/** Get the size of the cache */
+	async size() {
+		return this.cache.size;
+	}
+	/** Check if the cache is persistent */
+	isPersistent() {
+		return false;
+	}
+	/** Check the health of the cache */
+	async healthCheck() {
+		return true;
+	}
+	/** Close the cache */
+	async close() {
+		this.cache.clear();
+		this.accessOrder.clear();
+		this.accessCounter = 0;
+	}
+	/** Evict the least recently used entry (LRU) */
+	evictLRU() {
+		let oldestKey = null;
+		let oldestAccess = Infinity;
+		for (const [key, accessTime] of this.accessOrder) if (accessTime < oldestAccess) {
+			oldestAccess = accessTime;
+			oldestKey = key;
+		}
+		if (oldestKey) {
+			this.cache.delete(oldestKey);
+			this.accessOrder.delete(oldestKey);
+		}
+	}
+};
+
+//#endregion
+export { InMemoryStorage };
+//# sourceMappingURL=memory.js.map

package/dist/cache/storage/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","names":["oldestKey: string | null"],"sources":["../../../src/cache/storage/memory.ts"],"sourcesContent":["import type { CacheConfig, CacheEntry, CacheStorage } from \"shared\";\nimport { inMemoryStorageDefaults } from \"./defaults\";\n\n/**\n * In-memory cache storage implementation. Uses a least recently used (LRU) eviction policy\n * to manage memory usage and ensure efficient cache operations.\n */\nexport class InMemoryStorage implements CacheStorage {\n  private cache: Map<string, CacheEntry> = new Map();\n  private accessOrder: Map<string, number> = new Map();\n  private accessCounter: number;\n  private maxSize: number;\n\n  constructor(config: CacheConfig) {\n    this.cache = new Map();\n    this.accessOrder = new Map();\n    this.maxSize = config.maxSize ?? inMemoryStorageDefaults.maxSize;\n    this.accessCounter = 0;\n  }\n\n  /** Get an entry from the cache */\n  async get<T>(key: string): Promise<CacheEntry<T> | null> {\n    const entry = this.cache.get(key);\n    if (!entry) return null;\n\n    this.accessOrder.set(key, ++this.accessCounter);\n    return entry as CacheEntry<T>;\n  }\n\n  /** Set an entry in the cache */\n  async set<T>(key: string, entry: CacheEntry<T>): Promise<void> {\n    if (this.cache.size >= this.maxSize && !this.cache.has(key)) {\n      this.evictLRU();\n    }\n\n    this.cache.set(key, entry);\n    this.accessOrder.set(key, ++this.accessCounter);\n  }\n\n  /** Delete an entry from the cache */\n  async delete(key: string): Promise<void> {\n    this.cache.delete(key);\n    this.accessOrder.delete(key);\n  }\n\n  /** Clean in-memory cache */\n  async clear(): Promise<void> {\n    this.cache.clear();\n    this.accessOrder.clear();\n    this.accessCounter = 0;\n  }\n\n  /** Check if the cache has an entry */\n  async has(key: string): Promise<boolean> {\n    const entry = this.cache.get(key);\n    if (!entry) return false;\n\n    if (Date.now() > entry.expiry) {\n      this.cache.delete(key);\n      this.accessOrder.delete(key);\n      return false;\n    }\n\n    return true;\n  }\n\n  /** Get the size of the cache */\n  async size(): Promise<number> {\n    return this.cache.size;\n  }\n\n  /** Check if the cache is persistent */\n  isPersistent(): boolean {\n    return false;\n  }\n\n  /** Check the health of the cache */\n  async healthCheck(): Promise<boolean> {\n    return true;\n  }\n\n  /** Close the cache */\n  async close(): Promise<void> {\n    this.cache.clear();\n    this.accessOrder.clear();\n    this.accessCounter = 0;\n  }\n\n  /** Evict the least recently used entry (LRU) */\n  private evictLRU(): void {\n    let oldestKey: string | null = null;\n    let oldestAccess = Infinity;\n\n    for (const [key, accessTime] of this.accessOrder) {\n      if (accessTime < oldestAccess) {\n        oldestAccess = accessTime;\n        oldestKey = key;\n      }\n    }\n\n    if (oldestKey) {\n      this.cache.delete(oldestKey);\n      this.accessOrder.delete(oldestKey);\n    }\n  }\n}\n"],"mappings":";;;;;;;AAOA,IAAa,kBAAb,MAAqD;CAMnD,YAAY,QAAqB;+BALQ,IAAI,KAAK;qCACP,IAAI,KAAK;AAKlD,OAAK,wBAAQ,IAAI,KAAK;AACtB,OAAK,8BAAc,IAAI,KAAK;AAC5B,OAAK,UAAU,OAAO,WAAW,wBAAwB;AACzD,OAAK,gBAAgB;;;CAIvB,MAAM,IAAO,KAA4C;EACvD,MAAM,QAAQ,KAAK,MAAM,IAAI,IAAI;AACjC,MAAI,CAAC,MAAO,QAAO;AAEnB,OAAK,YAAY,IAAI,KAAK,EAAE,KAAK,cAAc;AAC/C,SAAO;;;CAIT,MAAM,IAAO,KAAa,OAAqC;AAC7D,MAAI,KAAK,MAAM,QAAQ,KAAK,WAAW,CAAC,KAAK,MAAM,IAAI,IAAI,CACzD,MAAK,UAAU;AAGjB,OAAK,MAAM,IAAI,KAAK,MAAM;AAC1B,OAAK,YAAY,IAAI,KAAK,EAAE,KAAK,cAAc;;;CAIjD,MAAM,OAAO,KAA4B;AACvC,OAAK,MAAM,OAAO,IAAI;AACtB,OAAK,YAAY,OAAO,IAAI;;;CAI9B,MAAM,QAAuB;AAC3B,OAAK,MAAM,OAAO;AAClB,OAAK,YAAY,OAAO;AACxB,OAAK,gBAAgB;;;CAIvB,MAAM,IAAI,KAA+B;EACvC,MAAM,QAAQ,KAAK,MAAM,IAAI,IAAI;AACjC,MAAI,CAAC,MAAO,QAAO;AAEnB,MAAI,KAAK,KAAK,GAAG,MAAM,QAAQ;AAC7B,QAAK,MAAM,OAAO,IAAI;AACtB,QAAK,YAAY,OAAO,IAAI;AAC5B,UAAO;;AAGT,SAAO;;;CAIT,MAAM,OAAwB;AAC5B,SAAO,KAAK,MAAM;;;CAIpB,eAAwB;AACtB,SAAO;;;CAIT,MAAM,cAAgC;AACpC,SAAO;;;CAIT,MAAM,QAAuB;AAC3B,OAAK,MAAM,OAAO;AAClB,OAAK,YAAY,OAAO;AACxB,OAAK,gBAAgB;;;CAIvB,AAAQ,WAAiB;EACvB,IAAIA,YAA2B;EAC/B,IAAI,eAAe;AAEnB,OAAK,MAAM,CAAC,KAAK,eAAe,KAAK,YACnC,KAAI,aAAa,cAAc;AAC7B,kBAAe;AACf,eAAY;;AAIhB,MAAI,WAAW;AACb,QAAK,MAAM,OAAO,UAAU;AAC5B,QAAK,YAAY,OAAO,UAAU"}

package/dist/cache/storage/persistent.js

@@ -0,0 +1,211 @@
+import { lakebaseStorageDefaults } from "./defaults.js";
+import { createHash } from "node:crypto";
+
+//#region src/cache/storage/persistent.ts
+/**
+* Persistent cache storage implementation. Uses a least recently used (LRU) eviction policy
+* to manage memory usage and ensure efficient cache operations.
+*
+* @example
+* const persistentStorage = new PersistentStorage(config, connector);
+* await persistentStorage.initialize();
+* await persistentStorage.get("my-key");
+* await persistentStorage.set("my-key", "my-value");
+* await persistentStorage.delete("my-key");
+* await persistentStorage.clear();
+* await persistentStorage.has("my-key");
+*
+*/
+var PersistentStorage = class {
+	constructor(config, connector) {
+		this.connector = connector;
+		this.maxBytes = config.maxBytes ?? lakebaseStorageDefaults.maxBytes;
+		this.maxEntryBytes = config.maxEntryBytes ?? lakebaseStorageDefaults.maxEntryBytes;
+		this.evictionBatchSize = lakebaseStorageDefaults.evictionBatchSize;
+		this.evictionCheckProbability = config.evictionCheckProbability ?? lakebaseStorageDefaults.evictionCheckProbability;
+		this.tableName = lakebaseStorageDefaults.tableName;
+		this.initialized = false;
+	}
+	/** Initialize the persistent storage and run migrations if necessary */
+	async initialize() {
+		if (this.initialized) return;
+		try {
+			await this.runMigrations();
+			this.initialized = true;
+		} catch (error) {
+			console.error("Error in persistent storage initialization:", error);
+			throw error;
+		}
+	}
+	/**
+	* Get a cached value from the persistent storage
+	* @param key - Cache key
+	* @returns Promise of the cached value or null if not found
+	*/
+	async get(key) {
+		await this.ensureInitialized();
+		const keyHash = this.hashKey(key);
+		const result = await this.connector.query(`SELECT value, expiry FROM ${this.tableName} WHERE key_hash = $1`, [keyHash]);
+		if (result.rows.length === 0) return null;
+		const entry = result.rows[0];
+		this.connector.query(`UPDATE ${this.tableName} SET last_accessed = NOW() WHERE key_hash = $1`, [keyHash]).catch(() => {
+			console.debug("Error updating last_accessed time for key:", key);
+		});
+		return {
+			value: this.deserializeValue(entry.value),
+			expiry: Number(entry.expiry)
+		};
+	}
+	/**
+	* Set a value in the persistent storage
+	* @param key - Cache key
+	* @param entry - Cache entry
+	* @returns Promise of the result
+	*/
+	async set(key, entry) {
+		await this.ensureInitialized();
+		const keyHash = this.hashKey(key);
+		const keyBytes = Buffer.from(key, "utf-8");
+		const valueBytes = this.serializeValue(entry.value);
+		const byteSize = keyBytes.length + valueBytes.length;
+		if (byteSize > this.maxEntryBytes) throw new Error(`Cache entry too large: ${byteSize} bytes exceeds maximum of ${this.maxEntryBytes} bytes`);
+		if (Math.random() < this.evictionCheckProbability) {
+			if (await this.totalBytes() + byteSize > this.maxBytes) await this.evictBySize(byteSize);
+		}
+		await this.connector.query(`INSERT INTO ${this.tableName} (key_hash, key, value, byte_size, expiry, created_at, last_accessed)
+      VALUES ($1, $2, $3, $4, $5, NOW(), NOW())
+      ON CONFLICT (key_hash)
+      DO UPDATE SET value = $3, byte_size = $4, expiry = $5, last_accessed = NOW()
+      `, [
+			keyHash,
+			keyBytes,
+			valueBytes,
+			byteSize,
+			entry.expiry
+		]);
+	}
+	/**
+	* Delete a value from the persistent storage
+	* @param key - Cache key
+	* @returns Promise of the result
+	*/
+	async delete(key) {
+		await this.ensureInitialized();
+		const keyHash = this.hashKey(key);
+		await this.connector.query(`DELETE FROM ${this.tableName} WHERE key_hash = $1`, [keyHash]);
+	}
+	/** Clear the persistent storage */
+	async clear() {
+		await this.ensureInitialized();
+		await this.connector.query(`TRUNCATE TABLE ${this.tableName}`);
+	}
+	/**
+	* Check if a value exists in the persistent storage
+	* @param key - Cache key
+	* @returns Promise of true if the value exists, false otherwise
+	*/
+	async has(key) {
+		await this.ensureInitialized();
+		const keyHash = this.hashKey(key);
+		return (await this.connector.query(`SELECT EXISTS(SELECT 1 FROM ${this.tableName} WHERE key_hash = $1) as exists`, [keyHash])).rows[0]?.exists ?? false;
+	}
+	/**
+	* Get the size of the persistent storage
+	* @returns Promise of the size of the storage
+	*/
+	async size() {
+		await this.ensureInitialized();
+		const result = await this.connector.query(`SELECT COUNT(*) as count FROM ${this.tableName}`);
+		return parseInt(result.rows[0]?.count ?? "0", 10);
+	}
+	/** Get the total number of bytes in the persistent storage */
+	async totalBytes() {
+		await this.ensureInitialized();
+		const result = await this.connector.query(`SELECT COALESCE(SUM(byte_size), 0) as total FROM ${this.tableName}`);
+		return parseInt(result.rows[0]?.total ?? "0", 10);
+	}
+	/**
+	* Check if the persistent storage is persistent
+	* @returns true if the storage is persistent, false otherwise
+	*/
+	isPersistent() {
+		return true;
+	}
+	/**
+	* Check if the persistent storage is healthy
+	* @returns Promise of true if the storage is healthy, false otherwise
+	*/
+	async healthCheck() {
+		try {
+			return await this.connector.healthCheck();
+		} catch {
+			return false;
+		}
+	}
+	/** Close the persistent storage */
+	async close() {
+		await this.connector.close();
+	}
+	/**
+	* Cleanup expired entries from the persistent storage
+	* @returns Promise of the number of expired entries
+	*/
+	async cleanupExpired() {
+		await this.ensureInitialized();
+		const result = await this.connector.query(`WITH deleted as (DELETE FROM ${this.tableName} WHERE expiry < $1 RETURNING *) SELECT COUNT(*) as count FROM deleted`, [Date.now()]);
+		return parseInt(result.rows[0]?.count ?? "0", 10);
+	}
+	/** Evict entries from the persistent storage by size */
+	async evictBySize(requiredBytes) {
+		if (await this.cleanupExpired() > 0) {
+			if (await this.totalBytes() + requiredBytes <= this.maxBytes) return;
+		}
+		await this.connector.query(`DELETE FROM ${this.tableName} WHERE key_hash IN
+      (SELECT key_hash FROM ${this.tableName} ORDER BY last_accessed ASC LIMIT $1)`, [this.evictionBatchSize]);
+	}
+	/** Ensure the persistent storage is initialized */
+	async ensureInitialized() {
+		if (!this.initialized) await this.initialize();
+	}
+	/** Generate a 64-bit hash for the cache key using SHA256 */
+	hashKey(key) {
+		if (!key) throw new Error("Cache key cannot be empty");
+		return createHash("sha256").update(key).digest().readBigInt64BE(0);
+	}
+	/** Serialize a value to a buffer */
+	serializeValue(value) {
+		return Buffer.from(JSON.stringify(value), "utf-8");
+	}
+	/** Deserialize a value from a buffer */
+	deserializeValue(buffer) {
+		return JSON.parse(buffer.toString("utf-8"));
+	}
+	/** Run migrations for the persistent storage */
+	async runMigrations() {
+		try {
+			await this.connector.query(`
+            CREATE TABLE IF NOT EXISTS ${this.tableName} (
+                id BIGSERIAL PRIMARY KEY,
+                key_hash BIGINT NOT NULL,
+                key BYTEA NOT NULL,
+                value BYTEA NOT NULL,
+                byte_size INTEGER NOT NULL,
+                expiry BIGINT NOT NULL,
+                created_at TIMESTAMP NOT NULL DEFAULT NOW(),
+                last_accessed TIMESTAMP NOT NULL DEFAULT NOW()
+            )
+            `);
+			await this.connector.query(`CREATE UNIQUE INDEX IF NOT EXISTS idx_${this.tableName}_key_hash ON ${this.tableName} (key_hash);`);
+			await this.connector.query(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_expiry ON ${this.tableName} (expiry); `);
+			await this.connector.query(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_last_accessed ON ${this.tableName} (last_accessed); `);
+			await this.connector.query(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_byte_size ON ${this.tableName} (byte_size); `);
+		} catch (error) {
+			console.error("Error in running migrations for persistent storage:", error);
+			throw error;
+		}
+	}
+};
+
+//#endregion
+export { PersistentStorage };
+//# sourceMappingURL=persistent.js.map