@bayonai/offline 0.1.0 → 0.3.0

package/dist/readCache.js

@@ -1,16 +1,38 @@
 import { createIdbKeyValueDriver, } from "./idbDriver.js";
 export const readCacheSchemaVersion = 1;
 export const readCacheFreshnessMaxAgeMs = 30_000;
+export const durableReadCacheFreshnessMaxAgeMs = 60 * 60_000;
+export const identityReadCacheFreshnessMaxAgeMs = 24 * 60 * 60_000;
 export const browserReadCacheOperationTimeoutMs = 2_000;
-const pendingFreshLoads = new Map();
+const pendingFreshLoads = new WeakMap();
+const cachePruners = new WeakMap();
 export function createReadCache(driver) {
-    return {
+    let globalVersion = 0;
+    const keyVersions = new Map();
+    let operationQueue = Promise.resolve();
+    const pendingLoads = new Map();
+    function getVersion(key) {
+        return `${globalVersion}:${keyVersions.get(key) ?? 0}`;
+    }
+    function enqueue(operation) {
+        const next = operationQueue.then(operation, operation);
+        operationQueue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    const cache = {
         async clear() {
-            pendingFreshLoads.clear();
-            await driver.clear();
+            pendingLoads.clear();
+            globalVersion += 1;
+            keyVersions.clear();
+            await enqueue(() => driver.clear());
         },
         async close() {
-            await driver.close?.();
+            await enqueue(async () => driver.close?.());
+        },
+        async delete(key) {
+            pendingLoads.delete(key);
+            keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+            await enqueue(() => driver.delete(key));
         },
         async get(key) {
             const envelope = toReadCacheEnvelope(await driver.get(key));
@@ -22,14 +44,48 @@ export function createReadCache(driver) {
                 }
                 : null;
         },
+        getVersion,
         async set(key, value) {
-            await driver.set(key, {
+            await enqueue(() => driver.set(key, {
                 savedAt: new Date().toISOString(),
                 schemaVersion: readCacheSchemaVersion,
                 value,
+            }));
+        },
+        async setIfVersion(key, value, version) {
+            if (getVersion(key) !== version) {
+                return false;
+            }
+            return enqueue(async () => {
+                if (getVersion(key) !== version) {
+                    return false;
+                }
+                await driver.set(key, {
+                    savedAt: new Date().toISOString(),
+                    schemaVersion: readCacheSchemaVersion,
+                    value,
+                });
+                return true;
             });
         },
     };
+    pendingFreshLoads.set(cache, pendingLoads);
+    cachePruners.set(cache, async ({ maxAgeMs, now }) => {
+        if (!driver.listEntries || maxAgeMs < 0) {
+            return 0;
+        }
+        const cutoff = now() - maxAgeMs;
+        const expiredKeys = (await driver.listEntries())
+            .filter(({ value }) => {
+            const envelope = toReadCacheEnvelope(value);
+            const savedAt = envelope ? Date.parse(envelope.savedAt) : Number.NaN;
+            return Number.isFinite(savedAt) && savedAt < cutoff;
+        })
+            .map(({ key }) => key);
+        await Promise.all(expiredKeys.map((key) => cache.delete(key)));
+        return expiredKeys.length;
+    });
+    return cache;
 }
 export function createMemoryReadCacheDriver() {
     const records = new Map();
@@ -38,9 +94,15 @@ export function createMemoryReadCacheDriver() {
             records.clear();
         },
         async close() { },
+        async delete(key) {
+            records.delete(key);
+        },
         async get(key) {
             return records.get(key) ?? null;
         },
+        async listEntries() {
+            return [...records.entries()].map(([key, value]) => ({ key, value }));
+        },
         async set(key, value) {
             records.set(key, value);
         },
@@ -54,7 +116,25 @@ export function createBrowserReadCache({ databaseName, databaseVersion, indexedD
         operationTimeoutMs,
         storeName,
     });
-    return createReadCache(driver ?? createNoopReadCacheDriver());
+    return createReadCache(driver
+        ? {
+            clear: driver.clear,
+            close: driver.close,
+            delete: driver.delete,
+            get: driver.get,
+            listEntries: driver.listEntries,
+            set: driver.set,
+        }
+        : createNoopReadCacheDriver());
+}
+/**
+ * Deletes only valid read-cache envelopes older than the supplied age. It is
+ * opt-in and returns zero for custom cache adapters that cannot enumerate keys.
+ */
+export function pruneReadCache({ cache, maxAgeMs, now = () => Date.now(), }) {
+    const resourceCache = cache.capture?.() ?? cache;
+    return cachePruners.get(resourceCache)?.({ maxAgeMs, now }) ??
+        Promise.resolve(0);
 }
 export function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
     const serializedParams = Object.entries(params)
@@ -71,11 +151,26 @@ export function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-export async function readThroughCache({ cache, key, loadFresh, }) {
-    const cached = await cache.get(key);
+export async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, }) {
+    const resourceCache = cache.capture?.() ?? cache;
+    if (forceFresh) {
+        // Deletion advances the cache version, so a request started before this
+        // post-write refresh cannot restore stale data after it finishes.
+        await resourceCache.delete(key);
+    }
+    const version = resourceCache.getVersion(key);
+    const cached = await resourceCache.get(key);
+    if (cached && isCacheFresh(cached.savedAt, maxAgeMs)) {
+        return {
+            data: cached.value,
+            error: null,
+            fromCache: true,
+            stale: false,
+        };
+    }
     try {
-        const fresh = await loadFresh();
-        await cache.set(key, fresh);
+        const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
+        await resourceCache.setIfVersion(key, fresh, version);
         return {
             data: fresh,
             error: null,
@@ -95,8 +190,10 @@ export async function readThroughCache({ cache, key, loadFresh, }) {
         throw error;
     }
 }
-export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onUpdate, }) {
-    const cached = await cache.get(key);
+export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache = false, }) {
+    const resourceCache = cache.capture?.() ?? cache;
+    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)) {
@@ -104,9 +201,16 @@ export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, o
         }
     }
     try {
-        const fresh = await loadSharedFreshResource(key, loadFresh);
+        const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
         onUpdate({ data: fresh, fromCache: false });
-        void cache.set(key, fresh).catch(() => undefined);
+        void resourceCache.setIfVersion(key, fresh, version).catch((error) => {
+            const normalizedError = normalizeError(error);
+            console.error("[Bayon offline] Unable to refresh the read cache.", {
+                error: normalizedError,
+                key,
+            });
+            onCacheWriteError?.(normalizedError);
+        });
         return fresh;
     }
     catch (error) {
@@ -125,9 +229,13 @@ function createNoopReadCacheDriver() {
     return {
         async clear() { },
         async close() { },
+        async delete() { },
         async get() {
             return null;
         },
+        async listEntries() {
+            return [];
+        },
         async set() { },
     };
 }
@@ -138,22 +246,32 @@ function isCacheFresh(savedAt, maxAgeMs) {
     const savedTime = Date.parse(savedAt);
     return Number.isFinite(savedTime) && Date.now() - savedTime <= maxAgeMs;
 }
-async function loadSharedFreshResource(key, loadFresh) {
-    const pendingLoad = pendingFreshLoads.get(key);
+async function loadSharedFreshResource(cache, key, loadFresh) {
+    const pendingLoads = getPendingFreshLoads(cache);
+    const pendingLoad = pendingLoads.get(key);
     if (pendingLoad) {
         return (await pendingLoad);
     }
     const nextLoad = loadFresh();
-    pendingFreshLoads.set(key, nextLoad);
+    pendingLoads.set(key, nextLoad);
     try {
         return await nextLoad;
     }
     finally {
-        if (pendingFreshLoads.get(key) === nextLoad) {
-            pendingFreshLoads.delete(key);
+        if (pendingLoads.get(key) === nextLoad) {
+            pendingLoads.delete(key);
         }
     }
 }
+function getPendingFreshLoads(cache) {
+    const existing = pendingFreshLoads.get(cache);
+    if (existing) {
+        return existing;
+    }
+    const next = new Map();
+    pendingFreshLoads.set(cache, next);
+    return next;
+}
 function toReadCacheEnvelope(value) {
     if (!value || typeof value !== "object") {
         return null;

package/dist-cjs/browserCoordination.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrowserPendingWriteRecoveryCoordination = createBrowserPendingWriteRecoveryCoordination;
+function createBrowserPendingWriteRecoveryCoordination({ channelName, leaseName, channel = createDefaultChannel(channelName), locks = readDefaultLockManager(), }) {
+    const listeners = new Set();
+    const handleMessage = () => {
+        for (const listener of listeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error("[Bayon offline] Cross-tab recovery listener failed.", {
+                    channelName,
+                    error,
+                });
+            }
+        }
+    };
+    channel?.addEventListener("message", handleMessage);
+    return {
+        close() {
+            channel?.removeEventListener("message", handleMessage);
+            channel?.close();
+            listeners.clear();
+        },
+        notify() {
+            try {
+                channel?.postMessage("pending-write-recovery");
+            }
+            catch (error) {
+                console.error("[Bayon offline] Unable to wake cross-tab recovery.", {
+                    channelName,
+                    error,
+                });
+            }
+        },
+        async runExclusive(attempt) {
+            if (!locks) {
+                return attempt();
+            }
+            return locks.request(leaseName, { ifAvailable: true }, (lock) => lock ? attempt() : Promise.resolve(null));
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+function createDefaultChannel(name) {
+    if (typeof BroadcastChannel === "undefined") {
+        return null;
+    }
+    return new BroadcastChannel(name);
+}
+function readDefaultLockManager() {
+    if (typeof navigator === "undefined") {
+        return null;
+    }
+    return navigator.locks ?? null;
+}

package/dist-cjs/browserRecovery.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maxPendingWriteRetryDelayMs = exports.initialPendingWriteRetryDelayMs = void 0;
+exports.createBrowserPendingWriteRecovery = createBrowserPendingWriteRecovery;
+const pendingWrites_1 = require("./pendingWrites");
+exports.initialPendingWriteRetryDelayMs = 2_000;
+exports.maxPendingWriteRetryDelayMs = 60_000;
+function createBrowserPendingWriteRecovery({ environment = createDefaultBrowserRecoveryEnvironment(), coordination, initialRetryDelayMs = exports.initialPendingWriteRetryDelayMs, maxRetryDelayMs = exports.maxPendingWriteRetryDelayMs, onError, onResult, scopeKey = "all", select = () => true, store, sync, }) {
+    let active = false;
+    let retryDelayMs = Math.max(0, initialRetryDelayMs);
+    let retryTimer;
+    let recoveryPromise;
+    let immediateRecoveryRequested = false;
+    let unsubscribePeerWakeups;
+    let unsubscribe;
+    function clearRetryTimer() {
+        if (retryTimer) {
+            environment.clearTimeout(retryTimer);
+        }
+        retryTimer = undefined;
+    }
+    function emitResult(result) {
+        try {
+            onResult?.(result);
+        }
+        catch (error) {
+            console.error("[Bayon offline] Pending-write recovery result listener failed.", {
+                error,
+            });
+        }
+    }
+    function emitError(error) {
+        console.error("[Bayon offline] Pending-write recovery failed.", {
+            error,
+            scopeKey,
+        });
+        try {
+            onError?.(error);
+        }
+        catch (callbackError) {
+            console.error("[Bayon offline] Pending-write recovery error listener failed.", {
+                callbackError,
+                scopeKey,
+            });
+        }
+    }
+    function scheduleRetry() {
+        if (!active || !environment.isOnline() || retryTimer) {
+            return;
+        }
+        retryTimer = environment.setTimeout(() => {
+            retryTimer = undefined;
+            void recoverNow();
+        }, retryDelayMs);
+        retryDelayMs = Math.min(Math.max(initialRetryDelayMs, retryDelayMs * 2), Math.max(initialRetryDelayMs, maxRetryDelayMs));
+    }
+    function recoverNow() {
+        if (!environment.isOnline()) {
+            clearRetryTimer();
+            return Promise.resolve(null);
+        }
+        if (recoveryPromise) {
+            return recoveryPromise;
+        }
+        const attempt = (async () => {
+            try {
+                const run = () => (0, pendingWrites_1.syncPendingWrites)({
+                    scopeKey,
+                    select,
+                    store,
+                    sync,
+                });
+                const result = coordination
+                    ? await coordination.runExclusive(run)
+                    : await run();
+                if (!result) {
+                    return null;
+                }
+                emitResult(result);
+                if (result.remaining > 0) {
+                    scheduleRetry();
+                }
+                else {
+                    retryDelayMs = Math.max(0, initialRetryDelayMs);
+                }
+                return result;
+            }
+            catch (error) {
+                emitError(error);
+                scheduleRetry();
+                return null;
+            }
+        })();
+        recoveryPromise = attempt.finally(() => {
+            recoveryPromise = undefined;
+            if (active && immediateRecoveryRequested) {
+                immediateRecoveryRequested = false;
+                triggerImmediateRecovery();
+            }
+        });
+        return recoveryPromise;
+    }
+    function triggerImmediateRecovery() {
+        if (!active) {
+            return;
+        }
+        immediateRecoveryRequested ||= Boolean(recoveryPromise);
+        clearRetryTimer();
+        retryDelayMs = Math.max(0, initialRetryDelayMs);
+        void recoverNow();
+    }
+    function handleOffline() {
+        clearRetryTimer();
+    }
+    function handleStoreChange(change) {
+        if (change.type === "set") {
+            coordination?.notify();
+            triggerImmediateRecovery();
+        }
+    }
+    return {
+        notifyQueued() {
+            coordination?.notify();
+            triggerImmediateRecovery();
+        },
+        recoverNow,
+        start() {
+            if (active) {
+                return;
+            }
+            active = true;
+            unsubscribe = store.subscribe(handleStoreChange);
+            unsubscribePeerWakeups = coordination?.subscribe(triggerImmediateRecovery);
+            environment.addEventListener("focus", triggerImmediateRecovery);
+            environment.addEventListener("online", triggerImmediateRecovery);
+            environment.addEventListener("offline", handleOffline);
+            if (environment.isOnline()) {
+                triggerImmediateRecovery();
+            }
+        },
+        stop() {
+            if (!active) {
+                return;
+            }
+            active = false;
+            clearRetryTimer();
+            unsubscribe?.();
+            unsubscribe = undefined;
+            unsubscribePeerWakeups?.();
+            unsubscribePeerWakeups = undefined;
+            environment.removeEventListener("focus", triggerImmediateRecovery);
+            environment.removeEventListener("online", triggerImmediateRecovery);
+            environment.removeEventListener("offline", handleOffline);
+        },
+    };
+}
+function createDefaultBrowserRecoveryEnvironment() {
+    const target = typeof window === "undefined" ? null : window;
+    return {
+        addEventListener(type, listener) {
+            target?.addEventListener(type, listener);
+        },
+        clearTimeout(timer) {
+            globalThis.clearTimeout(timer);
+        },
+        isOnline() {
+            return typeof navigator !== "undefined" && navigator.onLine;
+        },
+        removeEventListener(type, listener) {
+            target?.removeEventListener(type, listener);
+        },
+        setTimeout(callback, delayMs) {
+            return globalThis.setTimeout(callback, delayMs);
+        },
+    };
+}

package/dist-cjs/idbDriver.js

@@ -16,6 +16,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         async clear() {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "clear object store",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.clear(storeName);
@@ -26,6 +27,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         async close() {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "close database",
                 operation: async () => {
                     const database = await databasePromise;
                     database.close();
@@ -36,6 +38,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         async delete(key) {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "delete key",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.delete(storeName, key);
@@ -43,9 +46,32 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
                 timeoutMs: operationTimeoutMs,
             });
         },
+        async deleteIf(key, predicate) {
+            return runBrowserStorageOperation({
+                fallback: false,
+                operationName: "conditionally delete key",
+                operation: async () => {
+                    const database = await databasePromise;
+                    // The ownership check and deletion must share a transaction; splitting
+                    // them can delete a newer offline snapshot written by another trigger.
+                    const transaction = database.transaction(storeName, "readwrite");
+                    const objectStore = transaction.objectStore(storeName);
+                    const current = (await objectStore.get(key)) ?? null;
+                    if (!predicate(current)) {
+                        await transaction.done;
+                        return false;
+                    }
+                    await objectStore.delete(key);
+                    await transaction.done;
+                    return true;
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
         async get(key) {
             return runBrowserStorageOperation({
                 fallback: null,
+                operationName: "read key",
                 operation: async () => {
                     const database = await databasePromise;
                     return (await database.get(storeName, key)) ?? null;
@@ -56,6 +82,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         async list() {
             return runBrowserStorageOperation({
                 fallback: [],
+                operationName: "list object store",
                 operation: async () => {
                     const database = await databasePromise;
                     return database.getAll(storeName);
@@ -63,9 +90,34 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
                 timeoutMs: operationTimeoutMs,
             });
         },
+        async listEntries() {
+            return runBrowserStorageOperation({
+                fallback: [],
+                operationName: "list object-store entries",
+                operation: async () => {
+                    const database = await databasePromise;
+                    // Keys and values must come from one transaction. Separate database
+                    // reads could pair a key from one cross-tab storage state with a
+                    // value from another, causing retention code to delete the wrong key.
+                    const transaction = database.transaction(storeName, "readonly");
+                    const objectStore = transaction.objectStore(storeName);
+                    const [keys, values] = await Promise.all([
+                        objectStore.getAllKeys(),
+                        objectStore.getAll(),
+                    ]);
+                    await transaction.done;
+                    return keys.map((key, index) => ({
+                        key: String(key),
+                        value: values[index],
+                    }));
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
         async set(key, value) {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "write key",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.put(storeName, value, key);
@@ -73,6 +125,26 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
                 timeoutMs: operationTimeoutMs,
             });
         },
+        async setIf(key, value, predicate) {
+            return runBrowserStorageOperation({
+                fallback: false,
+                operationName: "conditionally replace key",
+                operation: async () => {
+                    const database = await databasePromise;
+                    const transaction = database.transaction(storeName, "readwrite");
+                    const objectStore = transaction.objectStore(storeName);
+                    const current = (await objectStore.get(key)) ?? null;
+                    if (!predicate(current)) {
+                        await transaction.done;
+                        return false;
+                    }
+                    await objectStore.put(value, key);
+                    await transaction.done;
+                    return true;
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
     };
 }
 async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB, storeName, }) {
@@ -89,17 +161,23 @@ async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB,
     }
     return database;
 }
-async function runBrowserStorageOperation({ fallback, operation, timeoutMs, }) {
+async function runBrowserStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
     let timeoutId = null;
     try {
         return await Promise.race([
             operation(),
             new Promise((resolve) => {
-                timeoutId = setTimeout(() => resolve(fallback), timeoutMs);
+                timeoutId = setTimeout(() => {
+                    console.error(`IndexedDB timed out while trying to ${operationName}.`, {
+                        timeoutMs,
+                    });
+                    resolve(fallback);
+                }, timeoutMs);
             }),
         ]);
     }
-    catch {
+    catch (error) {
+        console.error(`IndexedDB failed to ${operationName}.`, { error });
         return fallback;
     }
     finally {

package/dist-cjs/index.js

@@ -16,3 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./readCache"), exports);
 __exportStar(require("./pendingWrites"), exports);
+__exportStar(require("./browserRecovery"), exports);
+__exportStar(require("./browserCoordination"), exports);