@holo-js/cache 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -123,8 +123,8 @@ type RedisDriverModuleLoader = () => Promise<RedisCacheDriverModule>;
 declare function isNormalizedRedisConfig(config: HoloRedisConfig | NormalizedHoloRedisConfig): config is NormalizedHoloRedisConfig;
 declare function normalizeRuntimeRedisConfig(config: HoloRedisConfig | NormalizedHoloRedisConfig | undefined): NormalizedHoloRedisConfig | undefined;
 declare function resolveSharedRedisConnection(redisConfig: NormalizedHoloRedisConfig | undefined, connectionName: string): NormalizedHoloRedisConnectionConfig;
-declare function isModuleNotFoundError(error: unknown): boolean;
-declare function normalizeRedisModuleLoadError(error: unknown): CacheOptionalPackageError | unknown;
+declare function isModuleNotFoundError(error: unknown, expectedSpecifier?: string): boolean;
+declare function normalizeRedisModuleLoadError(error: unknown, expectedSpecifier?: string): CacheOptionalPackageError | unknown;
 declare function loadRedisDriverModule(): Promise<RedisCacheDriverModule>;
 declare function setRedisDriverModuleLoader(loader: RedisDriverModuleLoader): void;
 declare function resetRedisDriverModuleLoader(): void;

package/dist/index.mjs

@@ -28,6 +28,9 @@ import {
 } from "@holo-js/config";
 
 // src/db.ts
+import { createRequire } from "module";
+import { join } from "path";
+import { pathToFileURL } from "url";
 import {
   normalizeDatabaseConfig
 } from "@holo-js/config";
@@ -59,8 +62,9 @@ function isModuleNotFoundError(error, expectedSpecifier = "@holo-js/cache-db") {
     return false;
   }
   const message = "message" in error && typeof error.message === "string" ? error.message : "";
+  const code = "code" in error ? error.code : void 0;
   const escapedSpecifier = escapeRegExp(expectedSpecifier);
-  if ("code" in error && error.code === "ERR_MODULE_NOT_FOUND" && [
+  if ((code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") && [
     new RegExp(`Cannot find package ['"]${escapedSpecifier}['"]`),
     new RegExp(`Cannot find module ['"]${escapedSpecifier}['"]`),
     new RegExp(`Could not resolve ['"]${escapedSpecifier}['"]`),
@@ -82,12 +86,26 @@ function normalizeDatabaseModuleLoadError(error, expectedSpecifier = "@holo-js/c
   }
   return error;
 }
+async function importDatabaseDriverModuleFromProject(specifier) {
+  const projectRequire = createRequire(join(process.cwd(), "package.json"));
+  return await import(pathToFileURL(projectRequire.resolve(specifier)).href);
+}
 async function loadDatabaseDriverModule() {
+  const specifier = "@holo-js/cache-db";
   try {
-    const specifier = "@holo-js/cache-db";
-    return await import(specifier);
+    return await import(
+      /* webpackIgnore: true */
+      specifier
+    );
   } catch (error) {
-    throw normalizeDatabaseModuleLoadError(error, "@holo-js/cache-db");
+    if (!isModuleNotFoundError(error, specifier)) {
+      throw normalizeDatabaseModuleLoadError(error, specifier);
+    }
+    try {
+      return await importDatabaseDriverModuleFromProject(specifier);
+    } catch (fallbackError) {
+      throw normalizeDatabaseModuleLoadError(fallbackError, specifier);
+    }
   }
 }
 var databaseDriverModuleLoader = loadDatabaseDriverModule;
@@ -181,14 +199,24 @@ var cacheDbInternals = {
 
 // src/file.ts
 import { createHash, randomUUID } from "crypto";
-import { mkdir, open, readFile, readdir, rename, rm, writeFile } from "fs/promises";
-import { dirname, join, resolve } from "path";
+import { mkdir, open, readFile, readdir, rename, rm, rmdir, writeFile } from "fs/promises";
+import { dirname, join as join2, resolve } from "path";
 var MALFORMED_FILE = /* @__PURE__ */ Symbol("MALFORMED_FILE");
 function defaultSleep(milliseconds) {
   return new Promise((resolveDelay) => {
     setTimeout(resolveDelay, milliseconds);
   });
 }
+function validateLockSeconds(seconds) {
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new CacheInvalidTtlError("[@holo-js/cache] Cache lock seconds must be a finite number greater than 0.");
+  }
+}
+function validateLockWaitSeconds(waitSeconds) {
+  if (!Number.isFinite(waitSeconds) || waitSeconds < 0) {
+    throw new CacheInvalidTtlError("[@holo-js/cache] Cache lock wait seconds must be a finite number greater than or equal to 0.");
+  }
+}
 function hashCacheKey(key) {
   return createHash("sha256").update(key).digest("hex");
 }
@@ -197,11 +225,14 @@ function resolveDriverRoot(path) {
 }
 function resolveEntryFilePath(rootPath, key) {
   const hash = hashCacheKey(key);
-  return join(rootPath, "entries", hash.slice(0, 2), `${hash}.json`);
+  return join2(rootPath, "entries", hash.slice(0, 2), `${hash}.json`);
 }
 function resolveLockFilePath(rootPath, name) {
   const hash = hashCacheKey(name);
-  return join(rootPath, "locks", hash.slice(0, 2), `${hash}.lock`);
+  return join2(rootPath, "locks", hash.slice(0, 2), `${hash}.lock`);
+}
+function resolveLockMarkerFilePath(lockPath, owner) {
+  return join2(lockPath, `${hashCacheKey(owner)}.json`);
 }
 function isPositiveTimestamp(value) {
   return typeof value === "number" && Number.isFinite(value) && value >= 0;
@@ -226,6 +257,16 @@ async function ensureParentDirectory(filePath) {
 async function removeFileIfPresent(filePath) {
   await rm(filePath, { force: true });
 }
+async function removeEmptyDirectoryIfPresent(path) {
+  try {
+    await rmdir(path);
+  } catch (error) {
+    if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTEMPTY" || error.code === "ENOTDIR")) {
+      return;
+    }
+    throw error;
+  }
+}
 async function readFileIfPresent(filePath) {
   try {
     return await readFile(filePath, "utf8");
@@ -277,7 +318,7 @@ async function listFiles(rootPath) {
   try {
     const entries = await readdir(rootPath, { withFileTypes: true });
     const nested = await Promise.all(entries.map(async (entry) => {
-      const entryPath = join(rootPath, entry.name);
+      const entryPath = join2(rootPath, entry.name);
       if (entry.isDirectory()) return listFiles(entryPath);
       return [entryPath];
     }));
@@ -299,6 +340,10 @@ async function removeInvalidFileAndReadMissing(filePath, decoded) {
   };
 }
 async function removeScopedCacheFiles(rootPath, prefix, isEnvelope, resolveName) {
+  async function removeScopedFile(filePath) {
+    await removeFileIfPresent(filePath);
+    await removeEmptyDirectoryIfPresent(dirname(filePath));
+  }
   if (!prefix) {
     await rm(rootPath, { recursive: true, force: true });
     await mkdir(rootPath, { recursive: true });
@@ -307,11 +352,11 @@ async function removeScopedCacheFiles(rootPath, prefix, isEnvelope, resolveName)
   for (const filePath of await listFiles(rootPath)) {
     const decoded = await readJsonFile(filePath);
     if (!decoded || decoded === MALFORMED_FILE || !isEnvelope(decoded)) {
-      await removeFileIfPresent(filePath);
+      await removeScopedFile(filePath);
       continue;
     }
     if (resolveName(decoded).startsWith(prefix)) {
-      await removeFileIfPresent(filePath);
+      await removeScopedFile(filePath);
     }
   }
 }
@@ -332,17 +377,77 @@ async function readEntry(rootPath, key, now) {
 }
 async function readLock(rootPath, name, now) {
   const filePath = resolveLockFilePath(rootPath, name);
-  const decoded = await readJsonFile(filePath);
-  if (decoded === MALFORMED_FILE || !isFileCacheLockEnvelope(decoded) || decoded.name !== name) {
-    return removeInvalidFileAndReadMissing(filePath, decoded);
+  let markerFilePaths;
+  try {
+    const entries = await readdir(filePath, { withFileTypes: true });
+    markerFilePaths = entries.filter((entry) => entry.isFile()).map((entry) => join2(filePath, entry.name));
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return {
+        state: "missing",
+        filePath
+      };
+    }
+    if (!(error instanceof Error && "code" in error && error.code === "ENOTDIR")) {
+      throw error;
+    }
+    const decoded = await readJsonFile(filePath);
+    if (decoded === MALFORMED_FILE || !isFileCacheLockEnvelope(decoded) || decoded.name !== name) {
+      if (typeof decoded !== "undefined") {
+        await removeFileIfPresent(filePath);
+      }
+      return {
+        state: "missing",
+        filePath
+      };
+    }
+    if (decoded.expiresAt <= now) {
+      await removeFileIfPresent(filePath);
+      return {
+        state: "missing",
+        filePath
+      };
+    }
+    return {
+      state: "hit",
+      filePath,
+      markerFilePath: filePath,
+      value: decoded
+    };
   }
-  if (decoded.expiresAt <= now) {
-    return removeInvalidFileAndReadMissing(filePath, decoded);
+  if (markerFilePaths.length === 0) {
+    return {
+      state: "hit",
+      filePath,
+      markerFilePath: resolveLockMarkerFilePath(filePath, ""),
+      value: {
+        name,
+        owner: "",
+        expiresAt: now + 1
+      }
+    };
+  }
+  for (const markerFilePath of markerFilePaths) {
+    const decoded = await readJsonFile(markerFilePath);
+    if (decoded === MALFORMED_FILE || !isFileCacheLockEnvelope(decoded) || decoded.name !== name) {
+      await removeFileIfPresent(markerFilePath);
+      continue;
+    }
+    if (decoded.expiresAt <= now) {
+      await removeFileIfPresent(markerFilePath);
+      continue;
+    }
+    return {
+      state: "hit",
+      filePath,
+      markerFilePath,
+      value: decoded
+    };
   }
+  await removeEmptyDirectoryIfPresent(filePath);
   return {
-    state: "hit",
-    filePath,
-    value: decoded
+    state: "missing",
+    filePath
   };
 }
 function createEntryEnvelope(input) {
@@ -353,7 +458,27 @@ function createEntryEnvelope(input) {
   };
 }
 function createFileLock(rootPath, name, seconds, now, sleep, ownerFactory) {
+  validateLockSeconds(seconds);
   const owner = ownerFactory();
+  async function writeLockDirectory(filePath, envelope) {
+    await ensureParentDirectory(filePath);
+    try {
+      await mkdir(filePath);
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+        return false;
+      }
+      throw error;
+    }
+    try {
+      await writeFile(resolveLockMarkerFilePath(filePath, owner), envelope, "utf8");
+    } catch (error) {
+      await removeFileIfPresent(resolveLockMarkerFilePath(filePath, owner));
+      await removeEmptyDirectoryIfPresent(filePath);
+      throw error;
+    }
+    return true;
+  }
   async function tryAcquire() {
     const filePath = resolveLockFilePath(rootPath, name);
     const envelope = JSON.stringify({
@@ -361,12 +486,12 @@ function createFileLock(rootPath, name, seconds, now, sleep, ownerFactory) {
       owner,
       expiresAt: now() + seconds * 1e3
     });
-    if (await writeFileExclusively(filePath, envelope)) {
+    if (await writeLockDirectory(filePath, envelope)) {
       return true;
     }
     const currentLock = await readLock(rootPath, name, now());
     if (currentLock.state === "missing") {
-      return writeFileExclusively(filePath, envelope);
+      return writeLockDirectory(filePath, envelope);
     }
     return false;
   }
@@ -393,14 +518,12 @@ function createFileLock(rootPath, name, seconds, now, sleep, ownerFactory) {
       if (currentLock.state === "missing" || currentLock.value.owner !== owner) {
         return false;
       }
-      const latestLock = await readLock(rootPath, name, now());
-      if (latestLock.state === "missing" || latestLock.value.owner !== owner) {
-        return false;
-      }
-      await removeFileIfPresent(currentLock.filePath);
+      await removeFileIfPresent(currentLock.markerFilePath);
+      await removeEmptyDirectoryIfPresent(currentLock.filePath);
       return true;
     },
     async block(waitSeconds, callback) {
+      validateLockWaitSeconds(waitSeconds);
       const deadline = now() + waitSeconds * 1e3;
       while (true) {
         if (await tryAcquire()) {
@@ -502,13 +625,13 @@ function createFileCacheDriver(options) {
     },
     async flush() {
       await removeScopedCacheFiles(
-        join(rootPath, "entries"),
+        join2(rootPath, "entries"),
         prefix,
         isFileCacheEntryEnvelope,
         (entry) => entry.key
       );
       await removeScopedCacheFiles(
-        join(rootPath, "locks"),
+        join2(rootPath, "locks"),
         prefix,
         isFileCacheLockEnvelope,
         (lock) => lock.name
@@ -546,7 +669,18 @@ function defaultSleep2(milliseconds) {
     setTimeout(resolve2, milliseconds);
   });
 }
+function validateLockSeconds2(seconds) {
+  if (!Number.isFinite(seconds) || seconds <= 0) {
+    throw new CacheInvalidTtlError("[@holo-js/cache] Cache lock seconds must be a finite number greater than 0.");
+  }
+}
+function validateLockWaitSeconds2(waitSeconds) {
+  if (!Number.isFinite(waitSeconds) || waitSeconds < 0) {
+    throw new CacheInvalidTtlError("[@holo-js/cache] Cache lock wait seconds must be a finite number greater than or equal to 0.");
+  }
+}
 function createMemoryLock(state, name, seconds, now, sleep) {
+  validateLockSeconds2(seconds);
   const owner = Symbol(name);
   function clearExpiredLock() {
     const current = state.locks.get(name);
@@ -594,6 +728,7 @@ function createMemoryLock(state, name, seconds, now, sleep) {
       return true;
     },
     async block(waitSeconds, callback) {
+      validateLockWaitSeconds2(waitSeconds);
       const deadline = now() + waitSeconds * 1e3;
       while (true) {
         if (tryAcquire()) {
@@ -710,9 +845,13 @@ function createMemoryCacheDriver(options) {
 }
 
 // src/redis.ts
+import { createRequire as createRequire2 } from "module";
+import { join as join3 } from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
 import {
   normalizeRedisConfig
 } from "@holo-js/config";
+var CACHE_DRIVER_DISPOSE_SYMBOL = /* @__PURE__ */ Symbol.for("holo.cache.driver.dispose");
 function isNormalizedRedisConfig(config) {
   return typeof config.default === "string" && typeof config.connections === "object" && config.connections !== null && Object.values(config.connections).every((connection) => {
     return typeof connection === "object" && connection !== null && "name" in connection && "host" in connection && "port" in connection && typeof connection.name === "string" && typeof connection.host === "string" && typeof connection.port === "number";
@@ -722,6 +861,9 @@ function normalizeRuntimeRedisConfig(config) {
   if (!config) return void 0;
   return isNormalizedRedisConfig(config) ? config : normalizeRedisConfig(config);
 }
+function escapeRegExp2(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function resolveSharedRedisConnection(redisConfig, connectionName) {
   if (!redisConfig) {
     throw new CacheDriverResolutionError(
@@ -735,11 +877,28 @@ function resolveSharedRedisConnection(redisConfig, connectionName) {
     `[@holo-js/cache] Redis cache connection "${connectionName}" was not found in config/redis.ts. Available connections: ${availableConnections.join(", ") || "(none)"}.`
   );
 }
-function isModuleNotFoundError2(error) {
-  return !!error && typeof error === "object" && "code" in error && error.code === "ERR_MODULE_NOT_FOUND";
+function isModuleNotFoundError2(error, expectedSpecifier = "@holo-js/cache-redis") {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  const message = "message" in error && typeof error.message === "string" ? error.message : "";
+  const code = "code" in error ? error.code : void 0;
+  const escapedSpecifier = escapeRegExp2(expectedSpecifier);
+  if ((code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") && [
+    new RegExp(`Cannot find package ['"]${escapedSpecifier}['"]`),
+    new RegExp(`Cannot find module ['"]${escapedSpecifier}['"]`),
+    new RegExp(`Could not resolve ['"]${escapedSpecifier}['"]`),
+    new RegExp(`Failed to load url\\s+(?:['"\`]${escapedSpecifier}['"\`]|${escapedSpecifier}(?=[\\s(]|$))`)
+  ].some((pattern) => pattern.test(message))) {
+    return true;
+  }
+  if ("cause" in error) {
+    return isModuleNotFoundError2(error.cause, expectedSpecifier);
+  }
+  return false;
 }
-function normalizeRedisModuleLoadError(error) {
-  if (isModuleNotFoundError2(error)) {
+function normalizeRedisModuleLoadError(error, expectedSpecifier = "@holo-js/cache-redis") {
+  if (isModuleNotFoundError2(error, expectedSpecifier)) {
     return new CacheOptionalPackageError(
       "[@holo-js/cache] Redis cache support requires @holo-js/cache-redis to be installed.",
       { cause: error }
@@ -747,12 +906,26 @@ function normalizeRedisModuleLoadError(error) {
   }
   return error;
 }
+async function importRedisDriverModuleFromProject(specifier) {
+  const projectRequire = createRequire2(join3(process.cwd(), "package.json"));
+  return await import(pathToFileURL2(projectRequire.resolve(specifier)).href);
+}
 async function loadRedisDriverModule() {
+  const specifier = "@holo-js/cache-redis";
   try {
-    const specifier = "@holo-js/cache-redis";
-    return await import(specifier);
+    return await import(
+      /* webpackIgnore: true */
+      specifier
+    );
   } catch (error) {
-    throw normalizeRedisModuleLoadError(error);
+    if (!isModuleNotFoundError2(error, specifier)) {
+      throw normalizeRedisModuleLoadError(error, specifier);
+    }
+    try {
+      return await importRedisDriverModuleFromProject(specifier);
+    } catch (fallbackError) {
+      throw normalizeRedisModuleLoadError(fallbackError, specifier);
+    }
   }
 }
 var redisDriverModuleLoader = loadRedisDriverModule;
@@ -769,14 +942,18 @@ var LazyRedisCacheDriver = class {
   driver = "redis";
   driverInstance;
   pending;
+  disposalGeneration = 0;
   get name() {
     return this.options.name;
   }
   async resolveDriver() {
     if (this.driverInstance) return this.driverInstance;
+    const pendingGeneration = this.disposalGeneration;
     this.pending ??= redisDriverModuleLoader().then((module) => {
       const driver = module.createRedisCacheDriver(this.options);
-      this.driverInstance = driver;
+      if (this.disposalGeneration === pendingGeneration) {
+        this.driverInstance = driver;
+      }
       return driver;
     }).finally(() => {
       this.pending = void 0;
@@ -786,6 +963,23 @@ var LazyRedisCacheDriver = class {
   async withDriver(callback) {
     return callback(await this.resolveDriver());
   }
+  [CACHE_DRIVER_DISPOSE_SYMBOL]() {
+    const pending = this.pending;
+    const driverInstance = this.driverInstance;
+    this.disposalGeneration += 1;
+    this.driverInstance = void 0;
+    this.pending = void 0;
+    if (driverInstance) {
+      const disposable = driverInstance;
+      disposable[CACHE_DRIVER_DISPOSE_SYMBOL]?.();
+      return;
+    }
+    pending?.then((driver) => {
+      const disposable = driver;
+      disposable[CACHE_DRIVER_DISPOSE_SYMBOL]?.();
+    }).catch(() => {
+    });
+  }
   createLockProxy(name, seconds) {
     let lockPromise;
     const resolveLock = async () => {
@@ -845,6 +1039,23 @@ var cacheRedisInternals = {
 };
 
 // src/runtime-shared.ts
+var CACHE_DRIVER_DISPOSE_SYMBOL2 = /* @__PURE__ */ Symbol.for("holo.cache.driver.dispose");
+function disposeDriver(driver) {
+  const disposable = driver;
+  disposable[CACHE_DRIVER_DISPOSE_SYMBOL2]?.();
+}
+function disposeCacheRuntimeBindings(bindings) {
+  if (!bindings) {
+    return;
+  }
+  for (const [driverName, driver] of bindings.drivers.entries()) {
+    try {
+      disposeDriver(driver);
+    } catch (error) {
+      console.error(`[@holo-js/cache] Failed to dispose cache driver "${driverName}".`, error);
+    }
+  }
+}
 function isNormalizedCacheConfig(config) {
   return typeof config.default === "string" && typeof config.prefix === "string" && typeof config.drivers === "object" && config.drivers !== null && Object.values(config.drivers).every((driver) => {
     return typeof driver === "object" && driver !== null && "name" in driver && "prefix" in driver && typeof driver.name === "string" && typeof driver.prefix === "string";
@@ -1155,9 +1366,10 @@ function createCacheQueryBridge(dependencyIndex = getOrCreateDependencyIndex())
       await dependencyIndex.removeKey(indexedKey);
       return context.driver.forget(resolveNormalizedKey(key, options?.driver));
     },
-    async invalidateDependencies(dependencies) {
+    async invalidateDependencies(dependencies, options) {
       const invalidatedKeys = /* @__PURE__ */ new Set();
       const runtime = getCacheRuntime();
+      const driverName = options?.driver?.trim();
       for (const dependency of dependencies) {
         const indexedKeys = await dependencyIndex.listKeys(dependency);
         for (const indexedKey of indexedKeys) {
@@ -1166,6 +1378,9 @@ function createCacheQueryBridge(dependencyIndex = getOrCreateDependencyIndex())
           }
           invalidatedKeys.add(indexedKey);
           const parsed = parseIndexedKey(indexedKey);
+          if (driverName && parsed.driverName !== driverName) {
+            continue;
+          }
           const driver = resolveConfiguredDriver(runtime, parsed.driverName);
           await driver.forget(parsed.normalizedKey);
           await dependencyIndex.removeKey(indexedKey);
@@ -1186,6 +1401,7 @@ var cacheQueryBridgeInternals = {
 
 // src/runtime.ts
 function configureCacheRuntime(bindings) {
+  disposeCacheRuntimeBindings(getCacheRuntimeState().bindings);
   if (!bindings) {
     getCacheRuntimeState().bindings = void 0;
     resetDefaultDependencyIndex();
@@ -1205,6 +1421,7 @@ function configureCacheRuntime(bindings) {
   setGlobalDatabaseQueryCacheBridge(queryBridge);
 }
 function resetCacheRuntime() {
+  disposeCacheRuntimeBindings(getCacheRuntimeState().bindings);
   getCacheRuntimeState().bindings = void 0;
   resetDefaultDependencyIndex();
   setGlobalDatabaseQueryCacheBridge(void 0);
@@ -1285,7 +1502,13 @@ function createCacheRepository(driverName) {
   }
   async function getCachedValue2(key) {
     const payload = await getEntryPayload(key);
-    return typeof payload === "string" ? deserializeCacheValue(payload) : null;
+    if (typeof payload !== "string") {
+      return Object.freeze({ hit: false });
+    }
+    return Object.freeze({
+      hit: true,
+      value: deserializeCacheValue(payload)
+    });
   }
   async function putFlexibleEnvelope(key, ttl, value) {
     const now = Date.now();
@@ -1377,8 +1600,8 @@ function createCacheRepository(driverName) {
     },
     async remember(key, ttl, callback) {
       const cached = await getCachedValue2(key);
-      if (cached !== null) {
-        return cached;
+      if (cached.hit) {
+        return cached.value;
       }
       const value = await resolveValue(callback);
       await repository.put(key, value, ttl);
@@ -1386,8 +1609,8 @@ function createCacheRepository(driverName) {
     },
     async rememberForever(key, callback) {
       const cached = await getCachedValue2(key);
-      if (cached !== null) {
-        return cached;
+      if (cached.hit) {
+        return cached.value;
       }
       const value = await resolveValue(callback);
       await repository.forever(key, value);
@@ -1397,17 +1620,17 @@ function createCacheRepository(driverName) {
       const normalizedTtl = normalizeFlexibleTtl2(ttl);
       const now = Date.now();
       const cached = await getCachedValue2(key);
-      if (isFlexibleEnvelope2(cached)) {
-        if (now <= cached.freshUntil) {
-          return cached.value;
+      if (cached.hit && isFlexibleEnvelope2(cached.value)) {
+        if (now <= cached.value.freshUntil) {
+          return cached.value.value;
         }
-        if (now <= cached.staleUntil) {
+        if (now <= cached.value.staleUntil) {
           const refreshLock2 = createRefreshLock(key, normalizedTtl.staleSeconds);
           void refreshLock2.get(async () => {
             await refreshFlexibleValue(key, normalizedTtl, callback);
             return true;
           }).catch(() => void 0);
-          return cached.value;
+          return cached.value.value;
         }
       }
       const refreshLock = createRefreshLock(key, normalizedTtl.staleSeconds);
@@ -1422,9 +1645,9 @@ function createCacheRepository(driverName) {
         return refreshed;
       }
       const retried = await getCachedValue2(key);
-      if (isFlexibleEnvelope2(retried)) {
-        if (Date.now() <= retried.staleUntil) {
-          return retried.value;
+      if (retried.hit && isFlexibleEnvelope2(retried.value)) {
+        if (Date.now() <= retried.value.staleUntil) {
+          return retried.value.value;
         }
       }
       return refreshFlexibleValue(key, normalizedTtl, callback);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holo-js/cache",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Holo-JS Framework - cache contracts, config helpers, serialization, and runtime seams",
   "type": "module",
   "license": "MIT",
@@ -28,12 +28,12 @@
     "test": "vitest --run"
   },
   "dependencies": {
-    "@holo-js/config": "^0.1.3"
+    "@holo-js/config": "^0.1.5"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.5"
   }
 }