@bayonai/offline 0.8.0 → 0.9.0

package/dist-cjs/readCache.js

@@ -26,6 +26,10 @@ function createReadCache(driver) {
     function getVersion(key) {
         return `${globalVersion}:${keyVersions.get(key) ?? 0}`;
     }
+    function invalidate(key) {
+        pendingLoads.delete(key);
+        keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+    }
     function enqueue(operation) {
         const next = operationQueue.then(operation, operation);
         operationQueue = next.then(() => undefined, () => undefined);
@@ -42,10 +46,10 @@ function createReadCache(driver) {
             await enqueue(async () => driver.close?.());
         },
         async delete(key) {
-            pendingLoads.delete(key);
-            keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+            invalidate(key);
             await enqueue(() => driver.delete(key));
         },
+        invalidate,
         async get(key) {
             const envelope = toReadCacheEnvelope(await driver.get(key));
             return envelope
@@ -162,13 +166,21 @@ function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, }) {
+async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, }) {
     const resourceCache = cache.capture?.() ?? cache;
+    const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
     if (forceFresh) {
-        // Deletion advances the cache version, so a request started before this
-        // post-write refresh cannot restore stale data after it finishes.
+        reportReadCacheOutcome(onOutcome, "forced-refresh");
+        // Built-in caches advance generation without deleting fallback data.
+        // Legacy custom adapters retain their old delete behavior.
         try {
-            await resourceCache.delete(key);
+            if (resourceCache.invalidate) {
+                resourceCache.invalidate(key);
+            }
+            else {
+                await resourceCache.delete(key);
+            }
         }
         catch (error) {
             console.error("[Bayon offline] Unable to invalidate the read cache.", {
@@ -178,17 +190,22 @@ async function readThroughCache({ cache, forceFresh = false, key, loadFresh, max
         }
     }
     const version = resourceCache.getVersion(key);
-    const cached = await resourceCache.get(key);
-    if (cached && isCacheFresh(cached.savedAt, maxAgeMs)) {
+    const cached = forcedFallback ?? (await resourceCache.get(key));
+    const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
+    if (!forceFresh && retained && isCacheFresh(cached.savedAt, resolvedPolicy)) {
+        reportReadCacheOutcome(onOutcome, "fresh-hit");
         return {
             data: cached.value,
             error: null,
             fromCache: true,
             stale: false,
+            status: "fresh",
         };
     }
+    reportReadCacheOutcome(onOutcome, retained ? "stale-hit" : "cache-miss");
     try {
         const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
+        reportReadCacheOutcome(onOutcome, "loader-success");
         try {
             await resourceCache.setIfVersion(key, fresh, version);
         }
@@ -203,33 +220,74 @@ async function readThroughCache({ cache, forceFresh = false, key, loadFresh, max
             error: null,
             fromCache: false,
             stale: false,
+            status: retained ? "fresh" : "miss",
         };
     }
     catch (error) {
-        if (cached) {
+        reportReadCacheOutcome(onOutcome, "loader-failure");
+        if (retained && resolvedPolicy.refreshFailure === "use-retained") {
             return {
                 data: cached.value,
                 error: normalizeError(error),
                 fromCache: true,
                 stale: true,
+                status: "stale",
             };
         }
         throw error;
     }
 }
-async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache = false, }) {
+async function loadReadCacheResource({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache = false, }) {
     const resourceCache = cache.capture?.() ?? cache;
+    const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
+    if (forceFresh) {
+        reportReadCacheOutcome(onOutcome, "forced-refresh");
+        try {
+            if (resourceCache.invalidate) {
+                resourceCache.invalidate(key);
+            }
+            else {
+                await resourceCache.delete(key);
+            }
+        }
+        catch (error) {
+            console.error("[Bayon offline] Unable to invalidate the read cache.", {
+                error: normalizeError(error),
+                key,
+            });
+        }
+    }
     const version = resourceCache.getVersion(key);
-    const cached = skipCache ? null : await resourceCache.get(key);
-    if (cached) {
-        onUpdate({ data: cached.value, fromCache: true });
-        if (isCacheFresh(cached.savedAt, maxAgeMs)) {
+    const cached = skipCache
+        ? null
+        : (forcedFallback ?? (await resourceCache.get(key)));
+    const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
+    if (retained) {
+        const fresh = isCacheFresh(cached.savedAt, resolvedPolicy);
+        reportReadCacheOutcome(onOutcome, fresh && !forceFresh ? "fresh-hit" : "stale-hit");
+        onUpdate({
+            data: cached.value,
+            fromCache: true,
+            status: fresh && !forceFresh ? "fresh" : "stale",
+        });
+        if (fresh && !forceFresh) {
             return cached.value;
         }
     }
+    else {
+        reportReadCacheOutcome(onOutcome, "cache-miss");
+    }
     try {
         const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
-        onUpdate({ data: fresh, fromCache: false });
+        reportReadCacheOutcome(onOutcome, "loader-success");
+        if (resourceCache.getVersion(key) === version) {
+            onUpdate({
+                data: fresh,
+                fromCache: false,
+                status: retained ? "fresh" : "miss",
+            });
+        }
         void resourceCache.setIfVersion(key, fresh, version).catch((error) => {
             const normalizedError = normalizeError(error);
             console.error("[Bayon offline] Unable to refresh the read cache.", {
@@ -241,17 +299,32 @@ async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onCacheW
         return fresh;
     }
     catch (error) {
-        if (!cached) {
+        reportReadCacheOutcome(onOutcome, "loader-failure");
+        if (!retained || resolvedPolicy.refreshFailure === "throw") {
             throw error;
         }
         onUpdate({
             data: cached.value,
             error: normalizeError(error),
             fromCache: true,
+            status: "stale",
         });
         return cached.value;
     }
 }
+function reportReadCacheOutcome(onOutcome, outcome) {
+    if (!onOutcome)
+        return;
+    try {
+        onOutcome(outcome);
+    }
+    catch (error) {
+        console.error("[Bayon offline] Read-cache outcome callback failed.", {
+            error: normalizeError(error),
+            outcome,
+        });
+    }
+}
 function createNoopReadCacheDriver() {
     return {
         async clear() { },
@@ -266,12 +339,33 @@ function createNoopReadCacheDriver() {
         async set() { },
     };
 }
-function isCacheFresh(savedAt, maxAgeMs) {
-    if (!maxAgeMs || maxAgeMs <= 0) {
+function isCacheFresh(savedAt, policy) {
+    if (policy.freshForMs <= 0) {
         return false;
     }
     const savedTime = Date.parse(savedAt);
-    return Number.isFinite(savedTime) && Date.now() - savedTime <= maxAgeMs;
+    return (Number.isFinite(savedTime) && Date.now() - savedTime <= policy.freshForMs);
+}
+function resolvePolicy(policy, maxAgeMs) {
+    if (policy) {
+        if (!Number.isFinite(policy.freshForMs) ||
+            policy.freshForMs < 0 ||
+            !Number.isFinite(policy.retainForMs) ||
+            policy.retainForMs < policy.freshForMs ||
+            !["use-retained", "throw"].includes(policy.refreshFailure)) {
+            throw new RangeError("[Bayon offline] Invalid read-cache policy: require finite non-negative durations, retainForMs >= freshForMs, and a supported refreshFailure mode.");
+        }
+        return policy;
+    }
+    return {
+        freshForMs: maxAgeMs ?? 0,
+        retainForMs: Number.POSITIVE_INFINITY,
+        refreshFailure: "use-retained",
+    };
+}
+function isCacheRetained(savedAt, policy) {
+    const savedTime = Date.parse(savedAt);
+    return (Number.isFinite(savedTime) && Date.now() - savedTime <= policy.retainForMs);
 }
 async function loadSharedFreshResource(cache, key, loadFresh) {
     const pendingLoads = getPendingFreshLoads(cache);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",
@@ -21,6 +21,9 @@
     "idb",
     "typescript"
   ],
+  "engines": {
+    "node": ">=22"
+  },
   "sideEffects": false,
   "type": "module",
   "main": "./dist-cjs/index.js",
@@ -28,9 +31,14 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist-cjs/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist-cjs/index.d.ts",
+        "default": "./dist-cjs/index.js"
+      }
     }
   },
   "files": [
@@ -44,7 +52,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && node scripts/write-esm-extensions.mjs && tsc -p tsconfig.cjs.json && node scripts/write-cjs.mjs",
+    "build": "tsc -p tsconfig.json && node scripts/write-esm-extensions.mjs && tsc -p tsconfig.cjs.json && node scripts/write-cjs.mjs && node scripts/verify-dist.mjs",
     "lint": "tsc --noEmit -p tsconfig.json",
     "pack:smoke": "corepack pnpm run build && npm pack --dry-run --access public",
     "prepack": "corepack pnpm run build",