@bayonai/offline 0.8.0 → 0.10.0

package/dist-cjs/browserFallbackRecovery.d.ts

@@ -0,0 +1,33 @@
+export declare const defaultOfflineFallbackRetryEvent = "app:network-restored";
+export declare const defaultOfflineFallbackPullThreshold = 72;
+export type BrowserOfflineFallbackRecoveryEnvironment = {
+    addEventListener: (type: string, listener: (event: unknown) => void) => void;
+    getScrollY: () => number;
+    reload: () => void;
+    removeEventListener: (type: string, listener: (event: unknown) => void) => void;
+};
+export type OfflineFallbackRetryControl = {
+    disabled: boolean;
+    textContent: string | null;
+};
+export type BrowserOfflineFallbackRecovery = {
+    /** Requests one safe refresh; unsafe or failed proof is rechecked automatically. */
+    refresh: () => void;
+    /** Compatibility for hosts that label navigation as Reload. */
+    reload: () => void;
+    /** @deprecated Internal compatibility alias; never a user retry instruction. */
+    retry: () => void;
+    start: () => void;
+    stop: () => void;
+};
+export type BrowserOfflineFallbackRecoveryOptions = {
+    /** Optional legacy UI; new hosts use pull-down without a refresh button. */
+    control?: OfflineFallbackRetryControl;
+    canReload?: () => boolean | Promise<boolean>;
+    environment?: BrowserOfflineFallbackRecoveryEnvironment;
+    retryEvent?: string;
+    retryingText?: string;
+    pullThreshold?: number | null;
+};
+/** Owns pull/reconnect recovery, including safe asynchronous durability proof. */
+export declare function createBrowserOfflineFallbackRecovery({ control, canReload, environment, pullThreshold, retryEvent, retryingText, }: BrowserOfflineFallbackRecoveryOptions): BrowserOfflineFallbackRecovery;

package/dist-cjs/browserFallbackRecovery.js

@@ -2,70 +2,142 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultOfflineFallbackPullThreshold = exports.defaultOfflineFallbackRetryEvent = void 0;
 exports.createBrowserOfflineFallbackRecovery = createBrowserOfflineFallbackRecovery;
+const recoveryPolicy_1 = require("./recoveryPolicy");
+const browserRecovery_1 = require("./browserRecovery");
 exports.defaultOfflineFallbackRetryEvent = "app:network-restored";
 exports.defaultOfflineFallbackPullThreshold = 72;
-/**
- * Owns generic recovery mechanics for a static offline fallback. Hosts retain
- * all markup, copy, styling, and the choice of a native reconnect event.
- */
-function createBrowserOfflineFallbackRecovery({ control, environment = createDefaultBrowserOfflineFallbackRecoveryEnvironment(), pullThreshold = exports.defaultOfflineFallbackPullThreshold, retryEvent = exports.defaultOfflineFallbackRetryEvent, retryingText = "Reconnecting…", }) {
+/** Owns pull/reconnect recovery, including safe asynchronous durability proof. */
+function createBrowserOfflineFallbackRecovery({ control, canReload, environment = createDefaultBrowserOfflineFallbackRecoveryEnvironment(), pullThreshold = exports.defaultOfflineFallbackPullThreshold, retryEvent = exports.defaultOfflineFallbackRetryEvent, retryingText = recoveryPolicy_1.offlineRecoveryCopy.reloading, }) {
+    if (control)
+        control.textContent = recoveryPolicy_1.offlineRecoveryCopy.reload;
     let active = false;
-    let retrying = false;
+    let navigating = false;
+    let checking = false;
+    let requested = false;
+    let generation = 0;
+    let timer;
+    let delay = browserRecovery_1.initialPendingWriteRetryDelayMs;
     let pullStartY = null;
-    const touchThreshold = pullThreshold === null ? Number.POSITIVE_INFINITY : pullThreshold;
-    function retry() {
-        if (retrying)
+    const touchThreshold = pullThreshold === null ? Infinity : pullThreshold;
+    function clearTimer() {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    }
+    function schedule() {
+        if (!active || !requested || timer !== undefined)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            attempt();
+        }, delay);
+        delay = Math.min(delay * 2, browserRecovery_1.maxPendingWriteRetryDelayMs);
+    }
+    function failed(error) {
+        console.error("[Bayon offline] Offline fallback refresh could not complete; local work retained.", { error });
+        navigating = false;
+        if (control) {
+            control.disabled = false;
+            control.textContent = recoveryPolicy_1.offlineRecoveryCopy.reload;
+        }
+        schedule();
+    }
+    function complete(safe, currentGeneration) {
+        if (currentGeneration !== generation)
+            return;
+        checking = false;
+        if (!safe) {
+            schedule();
             return;
-        retrying = true;
-        control.disabled = true;
-        control.textContent = retryingText;
+        }
+        clearTimer();
+        navigating = true;
+        if (control) {
+            control.disabled = true;
+            control.textContent = retryingText;
+        }
         try {
             environment.reload();
+            requested = false;
         }
         catch (error) {
-            // A failed navigation must leave the recovery action visible and usable.
-            console.error("[Bayon offline] Offline fallback reload failed.", {
-                error,
-            });
-            retrying = false;
-            control.disabled = false;
+            failed(error);
         }
     }
+    function attempt() {
+        if (!requested || checking || navigating)
+            return;
+        checking = true;
+        const currentGeneration = generation;
+        try {
+            const proof = canReload ? canReload() : true;
+            if (typeof proof === "boolean")
+                complete(proof, currentGeneration);
+            else
+                void proof.then((safe) => complete(safe, currentGeneration), (error) => {
+                    if (currentGeneration !== generation)
+                        return;
+                    checking = false;
+                    failed(error);
+                });
+        }
+        catch (error) {
+            checking = false;
+            failed(error);
+        }
+    }
+    function refresh() {
+        requested = true;
+        clearTimer();
+        delay = browserRecovery_1.initialPendingWriteRetryDelayMs;
+        attempt();
+    }
     function handleTouchStart(event) {
-        const touchY = getSingleTouchY(event, "touches");
-        pullStartY = environment.getScrollY() === 0 ? touchY : null;
+        pullStartY =
+            environment.getScrollY() === 0 ? getSingleTouchY(event, "touches") : null;
     }
     function handleTouchEnd(event) {
         const touchY = getSingleTouchY(event, "changedTouches");
         if (pullStartY !== null &&
             touchY !== null &&
-            touchY - pullStartY >= touchThreshold) {
-            retry();
-        }
+            touchY - pullStartY >= touchThreshold)
+            refresh();
+        pullStartY = null;
+    }
+    function handleTouchCancel() {
         pullStartY = null;
     }
     return {
-        retry,
+        refresh,
+        reload: refresh,
+        retry: refresh,
         start() {
             if (active)
                 return;
             active = true;
-            environment.addEventListener("online", retry);
-            environment.addEventListener(retryEvent, retry);
+            environment.addEventListener("online", refresh);
+            environment.addEventListener(retryEvent, refresh);
             if (pullThreshold !== null) {
                 environment.addEventListener("touchstart", handleTouchStart);
                 environment.addEventListener("touchend", handleTouchEnd);
+                environment.addEventListener("touchcancel", handleTouchCancel);
             }
         },
         stop() {
+            // Fence a proof completing after unmount, including manual pre-start calls.
+            generation++;
+            requested = false;
+            checking = false;
+            clearTimer();
             if (!active)
                 return;
             active = false;
-            environment.removeEventListener("online", retry);
-            environment.removeEventListener(retryEvent, retry);
+            environment.removeEventListener("online", refresh);
+            environment.removeEventListener(retryEvent, refresh);
             if (pullThreshold !== null) {
                 environment.removeEventListener("touchstart", handleTouchStart);
                 environment.removeEventListener("touchend", handleTouchEnd);
+                environment.removeEventListener("touchcancel", handleTouchCancel);
             }
             pullStartY = null;
         },

package/dist-cjs/browserRecovery.d.ts

@@ -0,0 +1,42 @@
+import { type PendingWriteRecord, type PendingWriteStore, type PendingWriteSync, type SyncPendingWritesResult } from "./pendingWrites.js";
+import type { BrowserPendingWriteRecoveryCoordination } from "./browserCoordination.js";
+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;
+};
+type BrowserPendingWriteRecoveryOptions<Payload> = {
+    /** 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>;
+} & ({
+    /** Runs one complete host-owned recovery pass, such as through an ordered executor. */
+    recover: () => Promise<SyncPendingWritesResult>;
+    sync?: never;
+} | {
+    recover?: never;
+    sync: PendingWriteSync<Payload>;
+});
+export declare function createBrowserPendingWriteRecovery<Payload>(options: BrowserPendingWriteRecoveryOptions<Payload>): BrowserPendingWriteRecovery<Payload>;
+export {};

package/dist-cjs/durableCommandStore.d.ts

@@ -0,0 +1,49 @@
+import { type PendingWriteRecord, type PendingWriteStore } from "./pendingWrites.js";
+export type DurableCommandErrorCategory = "auth" | "conflict" | "connectivity" | "local-storage" | "permission" | "unexpected" | "validation";
+export type DurableCommandOperation<Command> = {
+    command: Command;
+    error?: DurableCommandErrorCategory;
+    id: string;
+    status: "accepted" | "failed" | "syncing";
+};
+export type DurableCommandSnapshot<State, Command> = {
+    operations: DurableCommandOperation<Command>[];
+    state: State;
+};
+export type DurableCommandDispatch = {
+    accepted: Promise<void>;
+    operationId: string;
+};
+export type DurableCommandExecutionContext = {
+    /** Stable across retries so the remote command can be idempotent. */
+    operationId: string;
+};
+export type DurableCommandStore<State, Command, Scope> = {
+    cancel: (operationId: string) => Promise<boolean>;
+    close: () => void;
+    dispatch: (command: Command, options?: {
+        notBefore?: string;
+    }) => DurableCommandDispatch;
+    getSnapshot: () => DurableCommandSnapshot<State, Command>;
+    recover: () => Promise<void>;
+    refresh: (scope: Scope) => Promise<void>;
+    subscribe: (listener: () => void) => () => void;
+};
+/**
+ * Hosts provide domain projection and transport; this package only owns the
+ * durable command lifecycle. A command becomes visible immediately, but is
+ * never sent remotely until IndexedDB has accepted it.
+ */
+export declare function createDurableCommandStore<State, Command, Scope, Result = unknown>({ canCancel, classifyError, createId, execute, initialState, load, now, project, reconcile, shouldRetry, store, }: {
+    canCancel?: (command: Command, now: string) => boolean;
+    classifyError?: (error: unknown) => DurableCommandErrorCategory;
+    createId?: () => string;
+    execute: (command: Command, context: DurableCommandExecutionContext) => Promise<Result>;
+    initialState: State;
+    load: (scope: Scope) => Promise<State>;
+    now?: () => string;
+    project: (state: State, commands: readonly PendingWriteRecord<Command>[]) => State;
+    reconcile?: (state: State, command: Command, result: Result) => State;
+    shouldRetry?: (category: DurableCommandErrorCategory, command: Command) => boolean;
+    store: PendingWriteStore<Command>;
+}): DurableCommandStore<State, Command, Scope>;

package/dist-cjs/idbDriver.d.ts

@@ -0,0 +1,28 @@
+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;
+    indexedDB?: IDBFactory;
+    operationTimeoutMs: number;
+    /** Queue reads must throw; read caches may retain best-effort fallback. */
+    readFailureMode?: "fallback" | "throw";
+    storeName: string;
+};
+export declare class OfflineStorageError extends Error {
+    name: string;
+}
+export declare function createIdbKeyValueDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, readFailureMode, storeName, }: BrowserKeyValueDriverOptions): BrowserKeyValueDriver | null;

package/dist-cjs/idbDriver.js

@@ -7,16 +7,28 @@ class OfflineStorageError extends Error {
     name = "OfflineStorageError";
 }
 exports.OfflineStorageError = OfflineStorageError;
-function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, storeName, }) {
+function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, readFailureMode = "fallback", storeName, }) {
     if (!indexedDB) {
         return null;
     }
-    const databasePromise = openKeyValueDatabase({
-        databaseName,
-        databaseVersion,
-        indexedDB,
-        storeName,
-    });
+    let databasePromise = null;
+    function getDatabase() {
+        if (!databasePromise) {
+            const attempt = openKeyValueDatabase({
+                databaseName,
+                databaseVersion,
+                indexedDB: indexedDB,
+                storeName,
+            });
+            databasePromise = attempt;
+            // A transient failed open must not poison every later recovery read.
+            void attempt.catch(() => {
+                databasePromise = null;
+            });
+        }
+        return databasePromise;
+    }
+    getDatabase();
     function runMutation(operationName, mutate) {
         return runTransactionalStorageOperation({
             failureMode: "throw",
@@ -24,7 +36,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             operationName,
             storeName,
             operation: async (setTransaction, isCancelled) => {
-                const database = await databasePromise;
+                const database = await getDatabase();
                 if (isCancelled())
                     return;
                 const transaction = database.transaction(storeName, "readwrite");
@@ -45,7 +57,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
                 operationName: "close database",
                 storeName,
                 operation: async () => {
-                    const database = await databasePromise;
+                    const database = await getDatabase();
                     database.close();
                 },
                 timeoutMs: operationTimeoutMs,
@@ -56,7 +68,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         },
         async deleteIf(key, predicate) {
             return runConditionalStorageOperation({
-                databasePromise,
+                databasePromise: getDatabase(),
                 operationName: "conditionally delete key",
                 storeName,
                 timeoutMs: operationTimeoutMs,
@@ -71,11 +83,12 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         },
         async get(key) {
             return runBrowserStorageOperation({
+                failureMode: readFailureMode,
                 fallback: null,
                 operationName: "read key",
                 storeName,
                 operation: async () => {
-                    const database = await databasePromise;
+                    const database = await getDatabase();
                     return (await database.get(storeName, key)) ?? null;
                 },
                 timeoutMs: operationTimeoutMs,
@@ -83,11 +96,12 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         },
         async list() {
             return runBrowserStorageOperation({
+                failureMode: readFailureMode,
                 fallback: [],
                 operationName: "list object store",
                 storeName,
                 operation: async () => {
-                    const database = await databasePromise;
+                    const database = await getDatabase();
                     return database.getAll(storeName);
                 },
                 timeoutMs: operationTimeoutMs,
@@ -95,11 +109,12 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         },
         async listEntries() {
             return runBrowserStorageOperation({
+                failureMode: readFailureMode,
                 fallback: [],
                 operationName: "list object-store entries",
                 storeName,
                 operation: async () => {
-                    const database = await databasePromise;
+                    const database = await getDatabase();
                     // 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.
@@ -123,7 +138,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         },
         async setIf(key, value, predicate) {
             return runConditionalStorageOperation({
-                databasePromise,
+                databasePromise: getDatabase(),
                 operationName: "conditionally replace key",
                 storeName,
                 timeoutMs: operationTimeoutMs,

package/dist-cjs/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./readCache.js";
+export * from "./pendingWrites.js";
+export * from "./browserRecovery.js";
+export * from "./browserCoordination.js";
+export * from "./browserFallbackRecovery.js";
+export * from "./durableCommandStore.js";
+export { OfflineStorageError } from "./idbDriver.js";
+export * from "./readBoundary.js";
+export * from "./recoveryPolicy.js";
+export * from "./pendingWriteSupersession.js";

package/dist-cjs/index.js

@@ -23,3 +23,6 @@ __exportStar(require("./browserFallbackRecovery"), exports);
 __exportStar(require("./durableCommandStore"), exports);
 var idbDriver_1 = require("./idbDriver");
 Object.defineProperty(exports, "OfflineStorageError", { enumerable: true, get: function () { return idbDriver_1.OfflineStorageError; } });
+__exportStar(require("./readBoundary"), exports);
+__exportStar(require("./recoveryPolicy"), exports);
+__exportStar(require("./pendingWriteSupersession"), exports);

package/dist-cjs/pendingWriteSupersession.d.ts

@@ -0,0 +1,11 @@
+import type { PendingWriteRecord, PendingWriteStore } from "./pendingWrites.js";
+/**
+ * After remote acknowledgment, retire only rejected snapshots superseded by an
+ * explicit host-owned account/entity/field key. Never infer keys from payloads.
+ */
+export declare function clearSupersededPendingWriteFailures<Payload>({ acknowledged, getSupersessionKey, isRejected, store, }: {
+    acknowledged: PendingWriteRecord<Payload>;
+    getSupersessionKey: (record: PendingWriteRecord<Payload>) => string | null;
+    isRejected: (record: PendingWriteRecord<Payload>) => boolean;
+    store: PendingWriteStore<Payload>;
+}): Promise<number>;

package/dist-cjs/pendingWriteSupersession.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearSupersededPendingWriteFailures = clearSupersededPendingWriteFailures;
+/**
+ * After remote acknowledgment, retire only rejected snapshots superseded by an
+ * explicit host-owned account/entity/field key. Never infer keys from payloads.
+ */
+async function clearSupersededPendingWriteFailures({ acknowledged, getSupersessionKey, isRejected, store, }) {
+    const key = getSupersessionKey(acknowledged);
+    if (key === null)
+        return 0;
+    let cleared = 0;
+    for (const previous of await store.list()) {
+        const older = previous.savedAt.localeCompare(acknowledged.savedAt) ||
+            previous.id.localeCompare(acknowledged.id);
+        if (previous.id === acknowledged.id ||
+            older >= 0 ||
+            previous.syncStatus !== "failed" ||
+            previous.syncingAt ||
+            !isRejected(previous) ||
+            getSupersessionKey(previous) !== key)
+            continue;
+        // Snapshot fencing protects a correction or claim accepted during the scan.
+        if (await store.clearIfSnapshotId(previous.id, previous.snapshotId))
+            cleared++;
+    }
+    return cleared;
+}