@bayonai/offline 0.1.1 → 0.3.0

package/dist/pendingWrites.js

@@ -2,18 +2,38 @@ import { createIdbKeyValueDriver, } from "./idbDriver.js";
 export const pendingWriteSchemaVersion = 1;
 export const pendingWriteOperationTimeoutMs = 2_000;
 export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion = pendingWriteSchemaVersion, }) {
+    const listeners = new Set();
+    const notify = (change) => {
+        for (const listener of listeners) {
+            try {
+                listener(change);
+            }
+            catch (error) {
+                console.error("[Bayon offline] Pending-write store listener failed.", {
+                    error,
+                    type: change.type,
+                });
+            }
+        }
+    };
     return {
         async clear(id) {
             await driver.clear(createPendingWriteKey({ id, prefix: keyPrefix }));
+            notify({ id, type: "clear" });
         },
         async clearAll() {
             await driver.clearAll();
+            notify({ type: "clearAll" });
         },
         async clearIfSnapshotId(id, snapshotId) {
-            return driver.clearIf(createPendingWriteKey({ id, prefix: keyPrefix }), (value) => toPendingWriteEnvelope(value, schemaVersion, {
+            const cleared = await driver.clearIf(createPendingWriteKey({ id, prefix: keyPrefix }), (value) => toPendingWriteEnvelope(value, schemaVersion, {
                 normalizeLegacyRecord,
                 normalizePayload,
             })?.record.snapshotId === snapshotId);
+            if (cleared) {
+                notify({ id, type: "clear" });
+            }
+            return cleared;
         },
         async close() {
             await driver.close?.();
@@ -28,13 +48,18 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
                 normalizePayload,
             })?.record)
                 .filter((record) => Boolean(record))
-                .sort((left, right) => left.savedAt.localeCompare(right.savedAt));
+                .sort((left, right) => left.savedAt.localeCompare(right.savedAt) ||
+                left.id.localeCompare(right.id));
         },
         async replaceIfSnapshotId(id, snapshotId, record) {
-            return driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => toPendingWriteEnvelope(value, schemaVersion, {
+            const replaced = await driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => toPendingWriteEnvelope(value, schemaVersion, {
                 normalizeLegacyRecord,
                 normalizePayload,
             })?.record.snapshotId === snapshotId);
+            if (replaced) {
+                notify({ record, type: "replace" });
+            }
+            return replaced;
         },
         async set(record) {
             const storedRecord = {
@@ -45,8 +70,13 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
                 record: storedRecord,
                 schemaVersion,
             });
+            notify({ record: storedRecord, type: "set" });
             return storedRecord;
         },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
     };
 }
 export function createMemoryPendingWriteDriver() {
@@ -139,6 +169,85 @@ export async function syncPendingWrite({ id, store, sync, }) {
         ? { status: "synced" }
         : { status: "superseded" };
 }
+/**
+ * Replays selected writes oldest first and coalesces overlapping runs for the
+ * same store/scope. Callers own the selection predicate and idempotent remote
+ * mutation semantics.
+ */
+export function syncPendingWrites({ scopeKey = "all", select = () => true, store, sync, }) {
+    let inFlightByScope = pendingWriteSyncs.get(store);
+    if (!inFlightByScope) {
+        inFlightByScope = new Map();
+        pendingWriteSyncs.set(store, inFlightByScope);
+    }
+    const existing = inFlightByScope.get(scopeKey);
+    if (existing) {
+        return existing;
+    }
+    const syncRun = performPendingWriteSync({ select, store, sync });
+    inFlightByScope.set(scopeKey, syncRun);
+    const clearInFlight = () => {
+        inFlightByScope.delete(scopeKey);
+    };
+    void syncRun.then(clearInFlight, clearInFlight);
+    return syncRun;
+}
+/**
+ * Attempts a remote write now and persists a caller-created durable fallback
+ * only when offline or when the supplied retry classifier accepts the error.
+ */
+export async function runPendingWrite({ enqueue, isOnline, shouldQueue, write, }) {
+    if (!isOnline()) {
+        return { queued: await enqueue(), status: "queued" };
+    }
+    try {
+        return { result: await write(), status: "synced" };
+    }
+    catch (error) {
+        if (!shouldQueue(error)) {
+            throw error;
+        }
+        return { queued: await enqueue(), status: "queued" };
+    }
+}
+export function summarizePendingWrites(records) {
+    return records.reduce((summary, record) => {
+        summary.totalCount += 1;
+        if (record.syncStatus === "failed") {
+            summary.failedCount += 1;
+        }
+        else if (record.syncStatus === "syncing") {
+            summary.syncingCount += 1;
+        }
+        else {
+            summary.pendingCount += 1;
+        }
+        return summary;
+    }, { failedCount: 0, pendingCount: 0, syncingCount: 0, totalCount: 0 });
+}
+const pendingWriteSyncs = new WeakMap();
+async function performPendingWriteSync({ select, store, sync, }) {
+    const summary = {
+        attempted: 0,
+        failed: 0,
+        idle: 0,
+        remaining: 0,
+        superseded: 0,
+        synced: 0,
+    };
+    const records = (await store.list()).filter(select);
+    for (const record of records) {
+        const result = await syncPendingWrite({
+            id: record.id,
+            store,
+            sync,
+        });
+        summary.attempted += 1;
+        summary[result.status] += 1;
+    }
+    summary.remaining = (await store.list()).filter(select).length;
+    return summary;
+}
 function createNoopPendingWriteDriver() {
     return {
         async clear() { },

package/dist/readCache.d.ts

@@ -14,6 +14,10 @@ export type ReadCacheDriver = {
     close?: () => Promise<void>;
     delete: (key: string) => Promise<void>;
     get: (key: string) => Promise<unknown | null>;
+    listEntries?: () => Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
     set: (key: string, value: unknown) => Promise<void>;
 };
 export type ReadCache = {
@@ -55,9 +59,23 @@ export type ReadCacheKeyOptions = {
 export declare function createReadCache(driver: ReadCacheDriver): ReadCache;
 export declare function createMemoryReadCacheDriver(): ReadCacheDriver;
 export declare function createBrowserReadCache({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: BrowserReadCacheOptions): ReadCache;
+/**
+ * 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 declare function pruneReadCache({ cache, maxAgeMs, now, }: {
+    cache: ReadCache;
+    maxAgeMs: number;
+    now?: () => number;
+}): Promise<number>;
 export declare function createReadCacheKey({ namespace, params, prefix, scope, }: ReadCacheKeyOptions): string;
-export declare function readThroughCache<T>({ cache, key, loadFresh, maxAgeMs, }: {
+export declare function readThroughCache<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, }: {
     cache: ReadCache;
+    /**
+     * Invalidates the current value before loading. Use after a successful write
+     * when a cached or earlier in-flight response must not become authoritative.
+     */
+    forceFresh?: boolean;
     key: string;
     loadFresh: () => Promise<T>;
     maxAgeMs?: number;

package/dist/readCache.js

@@ -5,6 +5,7 @@ export const durableReadCacheFreshnessMaxAgeMs = 60 * 60_000;
 export const identityReadCacheFreshnessMaxAgeMs = 24 * 60 * 60_000;
 export const browserReadCacheOperationTimeoutMs = 2_000;
 const pendingFreshLoads = new WeakMap();
+const cachePruners = new WeakMap();
 export function createReadCache(driver) {
     let globalVersion = 0;
     const keyVersions = new Map();
@@ -69,6 +70,21 @@ export function createReadCache(driver) {
         },
     };
     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() {
@@ -84,6 +100,9 @@ export function createMemoryReadCacheDriver() {
         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);
         },
@@ -97,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)
@@ -114,8 +151,13 @@ export function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-export async function readThroughCache({ cache, key, loadFresh, maxAgeMs, }) {
+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)) {
@@ -127,7 +169,7 @@ export async function readThroughCache({ cache, key, loadFresh, maxAgeMs, }) {
         };
     }
     try {
-        const fresh = await loadFresh();
+        const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
         await resourceCache.setIfVersion(key, fresh, version);
         return {
             data: fresh,
@@ -191,6 +233,9 @@ function createNoopReadCacheDriver() {
         async get() {
             return null;
         },
+        async listEntries() {
+            return [];
+        },
         async set() { },
     };
 }

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

@@ -90,6 +90,30 @@ 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,

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);