@bayonai/offline 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,7 +1,31 @@
 # Changelog
 
-## Unreleased
+## 0.3.0 - 2026-08-31
 
+- Added optional `BroadcastChannel` wake-ups and `navigator.locks` replay
+  leases so browser tabs can avoid concurrent recovery attempts while retaining
+  a safe local fallback where either API is unavailable.
+- Added `summarizePendingWrites` for framework-neutral pending/syncing/failed
+  counts without exposing any product UI policy.
+- Added opt-in `pruneReadCache`, which deletes only valid read-cache envelopes
+  older than a host-supplied retention age. Pending writes are never pruned.
+
+## 0.2.0 - 2026-08-31
+
+- Added forced-fresh, per-key single-flight `readThroughCache` loads so a
+  post-mutation read cannot reuse or restore an earlier cached response.
+- Added generic write-or-queue and chronological, scoped batch replay helpers.
+- Added local pending-store subscriptions and a framework-free browser recovery
+  controller with silent startup/focus/reconnect/new-write replay plus bounded
+  exponential retry.
+- Documented the IndexedDB database/store-version topology constraint for host
+  applications that initialize more than one object store.
+
+## 0.1.1 - 2026-08-10
+
+- Added unique pending-write snapshot identities and atomic conditional
+  replacement/deletion, preventing overlapping sync and autosave operations
+  from deleting newer local data. Existing records remain compatible.
 - Added the initial workspace package with generic read-cache and pending-write
   primitives backed by `idb`.
 - Replaced app-specific test fixtures with neutral package examples.

package/README.md

@@ -1,6 +1,7 @@
 # @bayonai/offline
 
-Reusable offline read-cache and pending-write primitives.
+Reusable offline read-cache, pending-write, and silent browser-recovery
+primitives.
 
 This package owns generic browser and memory storage behavior. Host apps own
 their domain records, remote APIs, cache prefixes, database names, and sync
@@ -23,6 +24,7 @@ import {
   createBrowserReadCache,
   createReadCacheKey,
   loadReadCacheResource,
+  pruneReadCache,
 } from "@bayonai/offline";
 
 const cache = createBrowserReadCache({
@@ -48,6 +50,21 @@ const projects = await loadReadCacheResource({
 });
 ```
 
+After a successful write, use `readThroughCache({ forceFresh: true })` when
+the next read must be server-confirmed rather than a pre-write cached or
+in-flight response. Concurrent ordinary reads for the same cache/key share one
+fresh load; a forced-fresh read starts a new load after invalidating the key.
+
+Read-cache retention is deliberately opt-in. It removes only valid cache
+envelopes older than the chosen lifetime; it never affects pending writes.
+
+```ts
+const removed = await pruneReadCache({
+  cache,
+  maxAgeMs: 7 * 24 * 60 * 60_000,
+});
+```
+
 ## Pending Writes
 
 ```ts
@@ -81,6 +98,72 @@ await syncPendingWrite({
 });
 ```
 
+For a browser application that wants durable, silent recovery, mount the
+headless controller once for the active account or workspace:
+
+```ts
+import {
+  createBrowserPendingWriteRecovery,
+  createBrowserPendingWriteRecoveryCoordination,
+  runPendingWrite,
+  summarizePendingWrites,
+} from "@bayonai/offline";
+
+const coordination = createBrowserPendingWriteRecoveryCoordination({
+  // Scope names must be stable per user/workspace and unique to this app.
+  channelName: `my-app:pending-recovery:${currentUser.id}`,
+  leaseName: `my-app:pending-recovery:${currentUser.id}`,
+});
+
+const recovery = createBrowserPendingWriteRecovery({
+  coordination,
+  scopeKey: currentUser.id,
+  select: (record) => record.payload.userId === currentUser.id,
+  store,
+  sync: (mutation) => replayMutation(mutation),
+  onError: (error) => console.error("Pending replay failed", { error }),
+});
+
+recovery.start(); // silent initial, focus, online, and local-set recovery
+
+const result = await runPendingWrite({
+  isOnline: () => navigator.onLine,
+  write: () => saveRemotely(),
+  shouldQueue: isRetryableNetworkError,
+  enqueue: () => store.set(createPendingMutation()),
+});
+
+// On unmount or account change:
+recovery.stop();
+coordination.close();
+```
+
+The controller never creates product UI. It preserves failed writes locally,
+retries remaining selected writes with bounded exponential backoff, and exposes
+only `onResult`/`onError` callbacks for host diagnostics or telemetry. Stores
+also expose a local-instance `subscribe` API; it is not a cross-tab delivery
+mechanism.
+
+When coordination is supplied, a queued write wakes peer tabs through
+`BroadcastChannel`, and each recovery attempt acquires a non-blocking
+`navigator.locks` lease when supported. Browsers without either API recover in
+the current tab as before. Remote write handlers must remain idempotent because
+leases do not cover other devices or every browser failure mode.
+
+Use generic record summaries when an app needs to render its own status:
+
+```ts
+const summary = summarizePendingWrites(await store.list());
+// { pendingCount, syncingCount, failedCount, totalCount }
+```
+
+Each call to `set` assigns a unique `snapshotId`. Sync status updates and
+successful cleanup compare that identity inside a single storage transaction,
+so a newer local write cannot be overwritten or deleted by an older sync.
+Records created before snapshot identities were introduced remain readable;
+they receive a stable compatibility identity and are upgraded when next
+updated.
+
 Host apps that change their pending-write payload shape can normalize current
 records while keeping domain logic outside the package:
 
@@ -108,6 +191,11 @@ Host apps are also responsible for:
 - Deciding when to clear browser storage, such as on sign-out.
 - Providing remote read and write functions.
 
+Use a separate IndexedDB database for independently initialized stores unless
+the host coordinates a database-version upgrade that creates every required
+object store. IndexedDB cannot add a missing store when an existing database is
+opened at the same version.
+
 ## Package Scripts
 
 ```bash

package/dist/browserCoordination.d.ts

@@ -0,0 +1,23 @@
+export type BrowserRecoveryMessageChannel = {
+    addEventListener: (type: "message", listener: () => void) => void;
+    close: () => void;
+    postMessage: (message: "pending-write-recovery") => void;
+    removeEventListener: (type: "message", listener: () => void) => void;
+};
+export type BrowserRecoveryLockManager = {
+    request: <T>(name: string, options: {
+        ifAvailable: true;
+    }, callback: (lock: unknown | null) => Promise<T | null>) => Promise<T | null>;
+};
+export type BrowserPendingWriteRecoveryCoordination = {
+    close: () => void;
+    notify: () => void;
+    runExclusive: <T>(attempt: () => Promise<T>) => Promise<T | null>;
+    subscribe: (listener: () => void) => () => void;
+};
+export declare function createBrowserPendingWriteRecoveryCoordination({ channelName, leaseName, channel, locks, }: {
+    channel?: BrowserRecoveryMessageChannel | null;
+    channelName: string;
+    leaseName: string;
+    locks?: BrowserRecoveryLockManager | null;
+}): BrowserPendingWriteRecoveryCoordination;

package/dist/browserCoordination.js

@@ -0,0 +1,57 @@
+export 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/browserRecovery.d.ts

@@ -0,0 +1,34 @@
+import { type PendingWriteRecord, type PendingWriteStore, type PendingWriteSync, type SyncPendingWritesResult } from "./pendingWrites";
+import type { BrowserPendingWriteRecoveryCoordination } from "./browserCoordination";
+export declare const initialPendingWriteRetryDelayMs = 2000;
+export declare const maxPendingWriteRetryDelayMs = 60000;
+export type BrowserPendingWriteRecoveryEnvironment = {
+    addEventListener: (type: "focus" | "offline" | "online", listener: () => void) => void;
+    clearTimeout: (timer: ReturnType<typeof setTimeout>) => void;
+    isOnline: () => boolean;
+    removeEventListener: (type: "focus" | "offline" | "online", listener: () => void) => void;
+    setTimeout: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+};
+export type BrowserPendingWriteRecovery<Payload> = {
+    /** Signals that a caller has persisted a record outside the store subscription. */
+    notifyQueued: () => void;
+    /** Runs one immediate, silent recovery attempt when the browser is online. */
+    recoverNow: () => Promise<SyncPendingWritesResult | null>;
+    start: () => void;
+    stop: () => void;
+};
+export declare function createBrowserPendingWriteRecovery<Payload>({ environment, coordination, initialRetryDelayMs, maxRetryDelayMs, onError, onResult, scopeKey, select, store, sync, }: {
+    /** Optional BroadcastChannel/Web Locks coordination supplied by the package factory. */
+    coordination?: BrowserPendingWriteRecoveryCoordination;
+    environment?: BrowserPendingWriteRecoveryEnvironment;
+    initialRetryDelayMs?: number;
+    maxRetryDelayMs?: number;
+    /** Diagnostic callback only. Recovery never renders or presents product UI. */
+    onError?: (error: unknown) => void;
+    /** Diagnostic callback only. Recovery never renders or presents product UI. */
+    onResult?: (result: SyncPendingWritesResult) => void;
+    scopeKey?: string;
+    select?: (record: PendingWriteRecord<Payload>) => boolean;
+    store: PendingWriteStore<Payload>;
+    sync: PendingWriteSync<Payload>;
+}): BrowserPendingWriteRecovery<Payload>;

package/dist/browserRecovery.js

@@ -0,0 +1,172 @@
+import { syncPendingWrites, } from "./pendingWrites.js";
+export const initialPendingWriteRetryDelayMs = 2_000;
+export const maxPendingWriteRetryDelayMs = 60_000;
+export function createBrowserPendingWriteRecovery({ environment = createDefaultBrowserRecoveryEnvironment(), coordination, initialRetryDelayMs = initialPendingWriteRetryDelayMs, maxRetryDelayMs = 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 = () => 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/idbDriver.d.ts

@@ -2,10 +2,17 @@ export type BrowserKeyValueDriver = {
     clear: () => Promise<void>;
     close: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    deleteIf: (key: string, predicate: KeyValuePredicate) => Promise<boolean>;
     get: (key: string) => Promise<unknown | null>;
     list: () => Promise<unknown[]>;
+    listEntries: () => Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
     set: (key: string, value: unknown) => Promise<void>;
+    setIf: (key: string, value: unknown, predicate: KeyValuePredicate) => Promise<boolean>;
 };
+export type KeyValuePredicate = (value: unknown | null) => boolean;
 export type BrowserKeyValueDriverOptions = {
     databaseName: string;
     databaseVersion?: number;

package/dist/idbDriver.js

@@ -13,6 +13,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         async clear() {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "clear object store",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.clear(storeName);
@@ -23,6 +24,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         async close() {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "close database",
                 operation: async () => {
                     const database = await databasePromise;
                     database.close();
@@ -33,6 +35,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         async delete(key) {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "delete key",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.delete(storeName, key);
@@ -40,9 +43,32 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
                 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;
@@ -53,6 +79,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         async list() {
             return runBrowserStorageOperation({
                 fallback: [],
+                operationName: "list object store",
                 operation: async () => {
                     const database = await databasePromise;
                     return database.getAll(storeName);
@@ -60,9 +87,34 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
                 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);
@@ -70,6 +122,26 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
                 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, }) {
@@ -86,17 +158,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/index.d.ts

@@ -1,2 +1,4 @@
 export * from "./readCache";
 export * from "./pendingWrites";
+export * from "./browserRecovery";
+export * from "./browserCoordination";

package/dist/index.js

@@ -1,2 +1,4 @@
 export * from "./readCache.js";
 export * from "./pendingWrites.js";
+export * from "./browserRecovery.js";
+export * from "./browserCoordination.js";