@bayonai/offline 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 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

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,65 @@ 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.
@@ -115,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

@@ -5,6 +5,10 @@ export type BrowserKeyValueDriver = {
     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>;
 };

package/dist/idbDriver.js

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

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

package/dist/pendingWrites.d.ts

@@ -25,6 +25,19 @@ export type PendingWriteDriver = {
     setIf: (key: string, value: unknown, predicate: PendingWritePredicate) => Promise<boolean>;
 };
 export type PendingWritePredicate = (value: unknown | null) => boolean;
+export type PendingWriteStoreChange<Payload = unknown> = {
+    record: PendingWriteRecord<Payload>;
+    type: "set";
+} | {
+    id: string;
+    type: "clear";
+} | {
+    type: "clearAll";
+} | {
+    record: PendingWriteRecord<Payload>;
+    type: "replace";
+};
+export type PendingWriteStoreChangeListener<Payload = unknown> = (change: PendingWriteStoreChange<Payload>) => void;
 export type PendingWriteStore<Payload = unknown> = {
     clear: (id: string) => Promise<void>;
     clearAll: () => Promise<void>;
@@ -34,6 +47,11 @@ export type PendingWriteStore<Payload = unknown> = {
     list: () => Promise<Array<PendingWriteRecord<Payload>>>;
     replaceIfSnapshotId: (id: string, snapshotId: string, record: PendingWriteRecord<Payload>) => Promise<boolean>;
     set: (record: PendingWriteRecordInput<Payload>) => Promise<PendingWriteRecord<Payload>>;
+    /**
+     * Observes changes made through this in-memory store instance. It deliberately
+     * does not claim cross-tab/process delivery.
+     */
+    subscribe: (listener: PendingWriteStoreChangeListener<Payload>) => () => void;
 };
 export type PendingWriteStoreOptions<Payload = unknown> = {
     keyPrefix: string;
@@ -60,6 +78,29 @@ export type SyncPendingWriteResult = {
     error: string;
     status: "failed";
 };
+export type SyncPendingWritesResult = {
+    attempted: number;
+    failed: number;
+    idle: number;
+    /** Records still selected after this attempt, including newer superseding writes. */
+    remaining: number;
+    superseded: number;
+    synced: number;
+};
+export type PendingWriteSync<Payload> = (payload: Payload) => Promise<unknown>;
+export type RunPendingWriteResult<TResult, TQueued> = {
+    result: TResult;
+    status: "synced";
+} | {
+    queued: TQueued;
+    status: "queued";
+};
+export type PendingWriteSummary = {
+    failedCount: number;
+    pendingCount: number;
+    syncingCount: number;
+    totalCount: number;
+};
 export declare function createPendingWriteStore<Payload = unknown>(driver: PendingWriteDriver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion, }: PendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
 export declare function createMemoryPendingWriteDriver(): PendingWriteDriver;
 export declare function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: Omit<BrowserPendingWriteStoreOptions, "keyPrefix" | "normalizePayload" | "schemaVersion">): PendingWriteDriver | null;
@@ -69,5 +110,27 @@ export declare function createPendingWriteSnapshotId(): `${string}-${string}-${s
 export declare function syncPendingWrite<Payload>({ id, store, sync, }: {
     id: string;
     store: PendingWriteStore<Payload>;
-    sync: (payload: Payload) => Promise<unknown>;
+    sync: PendingWriteSync<Payload>;
 }): Promise<SyncPendingWriteResult>;
+/**
+ * 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 declare function syncPendingWrites<Payload>({ scopeKey, select, store, sync, }: {
+    scopeKey?: string;
+    select?: (record: PendingWriteRecord<Payload>) => boolean;
+    store: PendingWriteStore<Payload>;
+    sync: PendingWriteSync<Payload>;
+}): Promise<SyncPendingWritesResult>;
+/**
+ * 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 declare function runPendingWrite<TResult, TQueued>({ enqueue, isOnline, shouldQueue, write, }: {
+    enqueue: () => Promise<TQueued>;
+    isOnline: () => boolean;
+    shouldQueue: (error: unknown) => boolean;
+    write: () => Promise<TResult>;
+}): Promise<RunPendingWriteResult<TResult, TQueued>>;
+export declare function summarizePendingWrites<Payload>(records: Array<PendingWriteRecord<Payload>>): PendingWriteSummary;