@bayonai/offline 0.1.1 → 0.4.0

package/dist/pendingWrites.js

@@ -1,19 +1,54 @@
 import { createIdbKeyValueDriver, } from "./idbDriver.js";
 export const pendingWriteSchemaVersion = 1;
 export const pendingWriteOperationTimeoutMs = 2_000;
+export const pendingWriteSyncLeaseTimeoutMs = 60_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 claimIfSnapshotId(id, snapshotId, record, now) {
+            const claimed = await driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => {
+                const current = toPendingWriteEnvelope(value, schemaVersion, {
+                    normalizeLegacyRecord,
+                    normalizePayload,
+                })?.record;
+                return (current?.snapshotId === snapshotId &&
+                    isPendingWriteSyncClaimAvailable(current, now));
+            });
+            if (claimed) {
+                notify({ record, type: "replace" });
+            }
+            return claimed;
+        },
         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 +63,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 +85,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() {
@@ -111,34 +156,193 @@ export function createPendingWriteKey({ id, prefix }) {
 export function createPendingWriteSnapshotId() {
     return globalThis.crypto.randomUUID();
 }
-export async function syncPendingWrite({ id, store, sync, }) {
+export async function syncPendingWrite({ id, now = () => new Date().toISOString(), store, sync, }) {
     const pending = await store.get(id);
     if (!pending) {
         return { status: "idle" };
     }
-    await markPendingSnapshot({
-        id,
-        nextRecord: { ...pending, error: undefined, syncStatus: "syncing" },
-        snapshotId: pending.snapshotId,
-        store,
-    });
+    const claimedSnapshotId = createPendingWriteSnapshotId();
+    const claimed = await store.claimIfSnapshotId(id, pending.snapshotId, {
+        ...pending,
+        error: undefined,
+        snapshotId: claimedSnapshotId,
+        syncingAt: now(),
+        syncStatus: "syncing",
+    }, now());
+    if (!claimed) {
+        return { status: "superseded" };
+    }
     try {
         await sync(pending.payload);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unable to sync pending write.";
-        await markPendingSnapshot({
+        const { syncingAt: _syncingAt, ...pendingWithoutSyncClaim } = pending;
+        const markedFailed = await markPendingSnapshot({
             id,
-            nextRecord: { ...pending, error: message, syncStatus: "failed" },
-            snapshotId: pending.snapshotId,
+            nextRecord: {
+                ...pendingWithoutSyncClaim,
+                error: message,
+                snapshotId: claimedSnapshotId,
+                syncStatus: "failed",
+            },
+            snapshotId: claimedSnapshotId,
             store,
         });
-        return { error: message, status: "failed" };
+        return markedFailed
+            ? { error: message, status: "failed" }
+            : { status: "superseded" };
     }
-    return (await store.clearIfSnapshotId(id, pending.snapshotId))
+    return (await store.clearIfSnapshotId(id, claimedSnapshotId))
         ? { 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, stopOnFailure = false, 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,
+        stopOnFailure,
+        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, stopOnFailure, 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;
+        if (stopOnFailure && result.status === "failed") {
+            break;
+        }
+    }
+    summary.remaining = (await store.list()).filter(select).length;
+    return summary;
+}
+function isPendingWriteSyncClaimAvailable(record, now) {
+    if (record.syncStatus !== "syncing") {
+        return true;
+    }
+    if (!record.syncingAt) {
+        return true;
+    }
+    const startedAt = Date.parse(record.syncingAt);
+    const currentTime = Date.parse(now);
+    return (!Number.isFinite(startedAt) ||
+        !Number.isFinite(currentTime) ||
+        currentTime - startedAt >= pendingWriteSyncLeaseTimeoutMs);
+}
+/**
+ * Creates a serial execution lane for a durable scope such as one user or
+ * workspace. Use its `recover` method for background replay and `run` for new
+ * writes so a newer remote mutation cannot overtake an older queued mutation.
+ */
+export function createOrderedPendingWriteExecutor({ scopeKey = "all", select = () => true, store, sync, }) {
+    let execution = Promise.resolve();
+    function inOrder(operation) {
+        const result = execution.then(operation, operation);
+        execution = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    function recover() {
+        return inOrder(() => syncPendingWrites({
+            scopeKey,
+            select,
+            stopOnFailure: true,
+            store,
+            sync,
+        }));
+    }
+    return {
+        recover,
+        run(options) {
+            return inOrder(async () => {
+                if (!options.isOnline()) {
+                    return runPendingWrite(options);
+                }
+                const replay = await syncPendingWrites({
+                    scopeKey,
+                    select,
+                    stopOnFailure: true,
+                    store,
+                    sync,
+                });
+                // Product decision: unresolved older records retain their position in
+                // this scope. Queue the later write rather than letting it overtake a
+                // replay whose remote effect may be ambiguous.
+                if (replay.remaining > 0) {
+                    return { queued: await options.enqueue(), status: "queued" };
+                }
+                return runPendingWrite(options);
+            });
+        },
+    };
+}
 function createNoopPendingWriteDriver() {
     return {
         async clear() { },
@@ -198,6 +402,9 @@ function normalizePendingWriteRecord(record, normalizePayload) {
         payload,
         savedAt: record.savedAt,
         snapshotId: record.snapshotId ?? createLegacyPendingWriteSnapshotId(record),
+        ...(typeof record.syncingAt === "string"
+            ? { syncingAt: record.syncingAt }
+            : {}),
         syncStatus: record.syncStatus,
     };
 }
@@ -223,6 +430,7 @@ function isPendingWriteRecord(value) {
         "savedAt" in value &&
         typeof value.savedAt === "string" &&
         (!("snapshotId" in value) || typeof value.snapshotId === "string") &&
+        (!("syncingAt" in value) || typeof value.syncingAt === "string") &&
         "syncStatus" in value &&
         (value.syncStatus === "pending" ||
             value.syncStatus === "syncing" ||

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,182 @@
+"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(options) {
+    const { environment = createDefaultBrowserRecoveryEnvironment(), coordination, initialRetryDelayMs = exports.initialPendingWriteRetryDelayMs, maxRetryDelayMs = exports.maxPendingWriteRetryDelayMs, onError, onResult, scopeKey = "all", select = () => true, store, } = options;
+    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 = () => options.recover
+                    ? options.recover()
+                    : (0, pendingWrites_1.syncPendingWrites)({
+                        scopeKey,
+                        select,
+                        store,
+                        sync: options.sync,
+                    });
+                const result = coordination
+                    ? await coordination.runExclusive(run)
+                    : await run();
+                if (!result) {
+                    // Another tab currently owns the lease. It may disappear before
+                    // completion, so active recovery must retry rather than go dormant.
+                    scheduleRetry();
+                    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);
+        },
+    };
+}