@bayonai/offline 0.7.0 → 0.9.0

package/dist/readCache.js

@@ -3,7 +3,9 @@ export const readCacheSchemaVersion = 1;
 export const readCacheFreshnessMaxAgeMs = 30_000;
 export const durableReadCacheFreshnessMaxAgeMs = 60 * 60_000;
 export const identityReadCacheFreshnessMaxAgeMs = 24 * 60 * 60_000;
-export const browserReadCacheOperationTimeoutMs = 2_000;
+// Cache reads are optional and should yield to the fresh loader quickly when
+// IndexedDB is blocked by a browser/WebView lifecycle or another tab.
+export const browserReadCacheOperationTimeoutMs = 1_000;
 const pendingFreshLoads = new WeakMap();
 const cachePruners = new WeakMap();
 export function createReadCache(driver) {
@@ -14,6 +16,10 @@ export function createReadCache(driver) {
     function getVersion(key) {
         return `${globalVersion}:${keyVersions.get(key) ?? 0}`;
     }
+    function invalidate(key) {
+        pendingLoads.delete(key);
+        keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+    }
     function enqueue(operation) {
         const next = operationQueue.then(operation, operation);
         operationQueue = next.then(() => undefined, () => undefined);
@@ -30,10 +36,10 @@ export function createReadCache(driver) {
             await enqueue(async () => driver.close?.());
         },
         async delete(key) {
-            pendingLoads.delete(key);
-            keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+            invalidate(key);
             await enqueue(() => driver.delete(key));
         },
+        invalidate,
         async get(key) {
             const envelope = toReadCacheEnvelope(await driver.get(key));
             return envelope
@@ -133,8 +139,7 @@ export function createBrowserReadCache({ databaseName, databaseVersion, indexedD
  */
 export function pruneReadCache({ cache, maxAgeMs, now = () => Date.now(), }) {
     const resourceCache = cache.capture?.() ?? cache;
-    return cachePruners.get(resourceCache)?.({ maxAgeMs, now }) ??
-        Promise.resolve(0);
+    return (cachePruners.get(resourceCache)?.({ maxAgeMs, now }) ?? Promise.resolve(0));
 }
 export function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
     const serializedParams = Object.entries(params)
@@ -151,58 +156,128 @@ export function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-export async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, }) {
+export async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, }) {
     const resourceCache = cache.capture?.() ?? cache;
+    const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
     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);
+        reportReadCacheOutcome(onOutcome, "forced-refresh");
+        // Built-in caches advance generation without deleting fallback data.
+        // Legacy custom adapters retain their old delete behavior.
+        try {
+            if (resourceCache.invalidate) {
+                resourceCache.invalidate(key);
+            }
+            else {
+                await resourceCache.delete(key);
+            }
+        }
+        catch (error) {
+            console.error("[Bayon offline] Unable to invalidate the read cache.", {
+                error: normalizeError(error),
+                key,
+            });
+        }
     }
     const version = resourceCache.getVersion(key);
-    const cached = await resourceCache.get(key);
-    if (cached && isCacheFresh(cached.savedAt, maxAgeMs)) {
+    const cached = forcedFallback ?? (await resourceCache.get(key));
+    const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
+    if (!forceFresh && retained && isCacheFresh(cached.savedAt, resolvedPolicy)) {
+        reportReadCacheOutcome(onOutcome, "fresh-hit");
         return {
             data: cached.value,
             error: null,
             fromCache: true,
             stale: false,
+            status: "fresh",
         };
     }
+    reportReadCacheOutcome(onOutcome, retained ? "stale-hit" : "cache-miss");
     try {
         const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
-        await resourceCache.setIfVersion(key, fresh, version);
+        reportReadCacheOutcome(onOutcome, "loader-success");
+        try {
+            await resourceCache.setIfVersion(key, fresh, version);
+        }
+        catch (error) {
+            console.error("[Bayon offline] Unable to refresh the read cache.", {
+                error: normalizeError(error),
+                key,
+            });
+        }
         return {
             data: fresh,
             error: null,
             fromCache: false,
             stale: false,
+            status: retained ? "fresh" : "miss",
         };
     }
     catch (error) {
-        if (cached) {
+        reportReadCacheOutcome(onOutcome, "loader-failure");
+        if (retained && resolvedPolicy.refreshFailure === "use-retained") {
             return {
                 data: cached.value,
                 error: normalizeError(error),
                 fromCache: true,
                 stale: true,
+                status: "stale",
             };
         }
         throw error;
     }
 }
-export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache = false, }) {
+export async function loadReadCacheResource({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache = false, }) {
     const resourceCache = cache.capture?.() ?? cache;
+    const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
+    if (forceFresh) {
+        reportReadCacheOutcome(onOutcome, "forced-refresh");
+        try {
+            if (resourceCache.invalidate) {
+                resourceCache.invalidate(key);
+            }
+            else {
+                await resourceCache.delete(key);
+            }
+        }
+        catch (error) {
+            console.error("[Bayon offline] Unable to invalidate the read cache.", {
+                error: normalizeError(error),
+                key,
+            });
+        }
+    }
     const version = resourceCache.getVersion(key);
-    const cached = skipCache ? null : await resourceCache.get(key);
-    if (cached) {
-        onUpdate({ data: cached.value, fromCache: true });
-        if (isCacheFresh(cached.savedAt, maxAgeMs)) {
+    const cached = skipCache
+        ? null
+        : (forcedFallback ?? (await resourceCache.get(key)));
+    const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
+    if (retained) {
+        const fresh = isCacheFresh(cached.savedAt, resolvedPolicy);
+        reportReadCacheOutcome(onOutcome, fresh && !forceFresh ? "fresh-hit" : "stale-hit");
+        onUpdate({
+            data: cached.value,
+            fromCache: true,
+            status: fresh && !forceFresh ? "fresh" : "stale",
+        });
+        if (fresh && !forceFresh) {
             return cached.value;
         }
     }
+    else {
+        reportReadCacheOutcome(onOutcome, "cache-miss");
+    }
     try {
         const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
-        onUpdate({ data: fresh, fromCache: false });
+        reportReadCacheOutcome(onOutcome, "loader-success");
+        if (resourceCache.getVersion(key) === version) {
+            onUpdate({
+                data: fresh,
+                fromCache: false,
+                status: retained ? "fresh" : "miss",
+            });
+        }
         void resourceCache.setIfVersion(key, fresh, version).catch((error) => {
             const normalizedError = normalizeError(error);
             console.error("[Bayon offline] Unable to refresh the read cache.", {
@@ -214,17 +289,32 @@ export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, o
         return fresh;
     }
     catch (error) {
-        if (!cached) {
+        reportReadCacheOutcome(onOutcome, "loader-failure");
+        if (!retained || resolvedPolicy.refreshFailure === "throw") {
             throw error;
         }
         onUpdate({
             data: cached.value,
             error: normalizeError(error),
             fromCache: true,
+            status: "stale",
         });
         return cached.value;
     }
 }
+function reportReadCacheOutcome(onOutcome, outcome) {
+    if (!onOutcome)
+        return;
+    try {
+        onOutcome(outcome);
+    }
+    catch (error) {
+        console.error("[Bayon offline] Read-cache outcome callback failed.", {
+            error: normalizeError(error),
+            outcome,
+        });
+    }
+}
 function createNoopReadCacheDriver() {
     return {
         async clear() { },
@@ -239,12 +329,33 @@ function createNoopReadCacheDriver() {
         async set() { },
     };
 }
-function isCacheFresh(savedAt, maxAgeMs) {
-    if (!maxAgeMs || maxAgeMs <= 0) {
+function isCacheFresh(savedAt, policy) {
+    if (policy.freshForMs <= 0) {
         return false;
     }
     const savedTime = Date.parse(savedAt);
-    return Number.isFinite(savedTime) && Date.now() - savedTime <= maxAgeMs;
+    return (Number.isFinite(savedTime) && Date.now() - savedTime <= policy.freshForMs);
+}
+function resolvePolicy(policy, maxAgeMs) {
+    if (policy) {
+        if (!Number.isFinite(policy.freshForMs) ||
+            policy.freshForMs < 0 ||
+            !Number.isFinite(policy.retainForMs) ||
+            policy.retainForMs < policy.freshForMs ||
+            !["use-retained", "throw"].includes(policy.refreshFailure)) {
+            throw new RangeError("[Bayon offline] Invalid read-cache policy: require finite non-negative durations, retainForMs >= freshForMs, and a supported refreshFailure mode.");
+        }
+        return policy;
+    }
+    return {
+        freshForMs: maxAgeMs ?? 0,
+        retainForMs: Number.POSITIVE_INFINITY,
+        refreshFailure: "use-retained",
+    };
+}
+function isCacheRetained(savedAt, policy) {
+    const savedTime = Date.parse(savedAt);
+    return (Number.isFinite(savedTime) && Date.now() - savedTime <= policy.retainForMs);
 }
 async function loadSharedFreshResource(cache, key, loadFresh) {
     const pendingLoads = getPendingFreshLoads(cache);

package/dist-cjs/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-cjs/browserFallbackRecovery.d.ts

@@ -0,0 +1,32 @@
+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 = {
+    /** Attempts recovery once. Repeated calls are ignored while navigation starts. */
+    retry: () => void;
+    start: () => void;
+    stop: () => void;
+};
+export type BrowserOfflineFallbackRecoveryOptions = {
+    control: OfflineFallbackRetryControl;
+    environment?: BrowserOfflineFallbackRecoveryEnvironment;
+    /** A host-native validation callback may dispatch this event after connectivity returns. */
+    retryEvent?: string;
+    retryingText?: string;
+    /** Set to `null` to omit touch pull-to-retry. */
+    pullThreshold?: number | null;
+};
+/**
+ * Owns generic recovery mechanics for a static offline fallback. Hosts retain
+ * all markup, copy, styling, and the choice of a native reconnect event.
+ */
+export declare function createBrowserOfflineFallbackRecovery({ control, environment, pullThreshold, retryEvent, retryingText, }: BrowserOfflineFallbackRecoveryOptions): BrowserOfflineFallbackRecovery;

package/dist-cjs/browserFallbackRecovery.js

@@ -12,9 +12,11 @@ function createBrowserOfflineFallbackRecovery({ control, environment = createDef
     let active = false;
     let retrying = false;
     let pullStartY = null;
+    const touchThreshold = pullThreshold === null ? Number.POSITIVE_INFINITY : pullThreshold;
     function retry() {
         if (retrying)
             return;
+        const previousText = control.textContent;
         retrying = true;
         control.disabled = true;
         control.textContent = retryingText;
@@ -23,9 +25,12 @@ function createBrowserOfflineFallbackRecovery({ control, environment = createDef
         }
         catch (error) {
             // A failed navigation must leave the recovery action visible and usable.
-            console.error("[Bayon offline] Offline fallback reload failed.", { error });
+            console.error("[Bayon offline] Offline fallback reload failed.", {
+                error,
+            });
             retrying = false;
             control.disabled = false;
+            control.textContent = previousText;
         }
     }
     function handleTouchStart(event) {
@@ -36,7 +41,7 @@ function createBrowserOfflineFallbackRecovery({ control, environment = createDef
         const touchY = getSingleTouchY(event, "changedTouches");
         if (pullStartY !== null &&
             touchY !== null &&
-            touchY - pullStartY >= (pullThreshold ?? Number.POSITIVE_INFINITY)) {
+            touchY - pullStartY >= touchThreshold) {
             retry();
         }
         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>;