@bayonai/offline 0.12.0 → 0.15.0

package/dist/readResourceBatch.js

@@ -0,0 +1,116 @@
+/** A mounted presentation barrier; child tasks retain sole network/cache ownership. */
+export function observeReadResourceBatch({ count, observe, freshForMs, now, current, canRetain, retiredError, subscribe, onUpdate }) {
+    let disposed = false;
+    let retired = false;
+    let presented = false;
+    let strict = false;
+    let initialRetry;
+    let pending;
+    let failure;
+    let stop = () => { };
+    const children = [];
+    const disposedChildren = new Set();
+    const detach = () => { const cleanup = stop; stop = () => { }; cleanup(); };
+    const disposeChildren = () => children.forEach(child => {
+        if (!disposedChildren.has(child)) {
+            disposedChildren.add(child);
+            child.dispose();
+        }
+    });
+    const values = new Array(count);
+    const received = new Set();
+    const ages = new Array(count).fill(-Infinity);
+    const active = () => !disposed && !retired && current();
+    const retire = () => { retired = true; detach(); disposeChildren(); };
+    for (let index = 0; index < count; index++) {
+        const child = observe(index, update => {
+            if (disposed || retired)
+                return;
+            if (update.status === "invalidated" || update.status === "expired") {
+                onUpdate({ status: "invalidated" });
+                retire();
+                return;
+            }
+            if (!current())
+                return;
+            if ("data" in update) {
+                received.add(index);
+                values[index] = update.data;
+                if (!canRetain(update.data))
+                    strict = true;
+            }
+            // Denial retires the group even before every initial source has settled.
+            if (update.status === "failed") {
+                onUpdate(update);
+                presented = false;
+                retire();
+                return;
+            }
+            if (update.status === "retry") {
+                if (presented)
+                    failure = update;
+                else
+                    initialRetry = { error: update.error };
+            }
+        }, createdAt => { ages[index] = createdAt; });
+        children.push(child);
+        if (retired) {
+            disposeChildren();
+            break;
+        }
+    }
+    const refresh = (force = false) => {
+        if (!active() || !presented || strict)
+            return Promise.resolve();
+        if (pending)
+            return pending;
+        if (!force && ages.every((age, index) => now() - age < freshForMs[index]))
+            return Promise.resolve();
+        // Claim the barrier before a presentation callback can request it again.
+        pending = Promise.resolve().then(async () => {
+            if (!active() || strict)
+                return;
+            failure = undefined;
+            onUpdate({ status: "refreshing" });
+            if (!active() || strict)
+                return;
+            await Promise.all(children.map(child => child.refresh?.({ force })));
+            if (!active())
+                return;
+            if (failure)
+                onUpdate(failure);
+            else {
+                // Never expose a successful sibling beside an older failed member.
+                onUpdate({ status: "fresh", data: [...values] });
+                if (strict)
+                    detach();
+            }
+        }).finally(() => { pending = undefined; });
+        return pending;
+    };
+    if (!retired)
+        stop = subscribe(() => refresh());
+    const promise = Promise.allSettled(children.map(child => child.promise)).then(results => {
+        if (!active())
+            throw retiredError();
+        const rejected = results.find(result => result.status === "rejected");
+        if (rejected?.status === "rejected")
+            throw rejected.reason;
+        const data = results.map(result => result.value);
+        data.forEach((value, index) => { if (!received.has(index))
+            values[index] = value; });
+        presented = true;
+        // Presentation follows accepted canonical updates, while the promise keeps
+        // each shared source caller's original result (including duplicate positions).
+        onUpdate({ status: initialRetry === undefined ? "fresh" : "retained", data: [...values] });
+        if (initialRetry !== undefined && active())
+            onUpdate({ status: "retry", error: initialRetry.error });
+        if (strict)
+            detach();
+        return data;
+    });
+    return { promise,
+        refresh: ({ force = true } = {}) => active() && presented && !strict ? refresh(force) : undefined,
+        dispose() { disposed = true; detach(); disposeChildren(); },
+    };
+}

package/dist/readResourceObserver.d.ts

@@ -0,0 +1,57 @@
+export type ReadResourceUpdate<T> = {
+    status: "retained" | "fresh";
+    data: T;
+} | {
+    status: "refreshing";
+} | {
+    status: "retry";
+    error: unknown;
+} | {
+    status: "failed";
+    error: unknown;
+} | {
+    status: "expired";
+} | {
+    status: "invalidated";
+};
+export type ReadResourceSnapshot<T> = {
+    data: T;
+    confirmedAt: number;
+};
+export type ReadResourceObservation<T> = {
+    promise: Promise<T>;
+    refresh?: (options?: {
+        force?: boolean;
+    }) => Promise<void> | undefined;
+    dispose: () => void;
+};
+/**
+ * Mounted presentation only: hosts retain cache, transport, identity and initial
+ * read policy. Accepting a snapshot preserves its source age; a successful
+ * refresh does not require persistence to have survived an unrelated write.
+ */
+export declare function createReadResourceObserver<T, Snapshot>({ enabled, current, now, freshForMs, canRetain, isConnected, canonical, captureSnapshot, read, retireSnapshot, classifyFailure, subscribeWake, onUpdate, onData, onError, }: {
+    enabled?: boolean;
+    current: () => boolean;
+    now: () => number;
+    freshForMs: number;
+    canRetain: (data: T) => boolean;
+    isConnected?: () => boolean;
+    canonical: () => ReadResourceSnapshot<T> | undefined;
+    captureSnapshot: () => Snapshot;
+    read: () => Promise<ReadResourceSnapshot<T>>;
+    retireSnapshot: (snapshot: Snapshot) => Promise<void>;
+    classifyFailure: (error: unknown) => "transient" | "terminal" | "superseded" | "retired";
+    subscribeWake?: (listener: () => Promise<void>) => () => void;
+    onUpdate: (update: ReadResourceUpdate<T>) => void;
+    onData?: (data: T) => void;
+    onError?: (error: unknown) => void;
+}): {
+    accept: (update: ReadResourceUpdate<T>, age?: number) => void;
+    canRefresh: () => boolean;
+    refresh: ({ force }?: {
+        force?: boolean | undefined;
+    }) => Promise<void> | undefined;
+    retire(): void;
+    dispose(): void;
+};

package/dist/readResourceObserver.js

@@ -0,0 +1,108 @@
+/**
+ * Mounted presentation only: hosts retain cache, transport, identity and initial
+ * read policy. Accepting a snapshot preserves its source age; a successful
+ * refresh does not require persistence to have survived an unrelated write.
+ */
+export function createReadResourceObserver({ enabled = true, current, now, freshForMs, canRetain, isConnected = () => true, canonical, captureSnapshot, read, retireSnapshot, classifyFailure, subscribeWake, onUpdate, onData, onError, }) {
+    let disposed = false;
+    let retired = false;
+    let confirmedAt;
+    let retainable = true;
+    let pending;
+    let stop = () => { };
+    const detach = () => { const cleanup = stop; stop = () => { }; cleanup(); };
+    const active = () => !disposed && !retired && current();
+    const canRefresh = () => enabled && active() && retainable && confirmedAt !== undefined;
+    const accept = (update, age = now()) => {
+        if (!active())
+            return;
+        if ("data" in update) {
+            confirmedAt = age;
+            retainable = canRetain(update.data);
+            onData?.(update.data);
+        }
+        if (active())
+            onUpdate(update);
+    };
+    const adoptCanonical = () => {
+        const snapshot = canonical();
+        if (!snapshot || !active() || now() - snapshot.confirmedAt >= freshForMs)
+            return false;
+        accept({ status: "fresh", data: snapshot.data }, snapshot.confirmedAt);
+        return true;
+    };
+    const run = async (force) => {
+        if (!canRefresh())
+            return;
+        if (!force && now() - confirmedAt < freshForMs)
+            return;
+        if (!isConnected()) {
+            accept({ status: "retry", error: new Error("Resource unavailable while disconnected") });
+            return;
+        }
+        if (!force && adoptCanonical())
+            return;
+        accept({ status: "refreshing" });
+        if (!canRefresh())
+            return;
+        const snapshot = captureSnapshot();
+        let result;
+        try {
+            result = await read();
+        }
+        catch (error) {
+            if (!active())
+                return;
+            const failure = classifyFailure(error);
+            if (failure === "superseded") {
+                adoptCanonical();
+                return;
+            }
+            if (failure === "retired")
+                return;
+            if (onError)
+                onError(error);
+            else
+                console.error("[Bayon offline] Mounted resource refresh failed.", { error });
+            if (failure === "transient")
+                accept({ status: "retry", error });
+            else {
+                try {
+                    await retireSnapshot(snapshot);
+                }
+                catch (storageError) {
+                    // Storage cleanup cannot turn a known denial into retained presentation.
+                    console.error("[Bayon offline] Unable to retire a mounted read snapshot.", { error: storageError });
+                }
+                if (!active())
+                    return;
+                confirmedAt = undefined;
+                accept({ status: "failed", error });
+            }
+            return;
+        }
+        accept({ status: "fresh", data: result.data }, result.confirmedAt);
+    };
+    const refresh = ({ force = true } = {}) => {
+        if (!canRefresh())
+            return;
+        // Install ownership before callbacks can synchronously request another read.
+        if (!pending)
+            pending = Promise.resolve().then(() => run(force)).finally(() => { pending = undefined; });
+        return pending;
+    };
+    if (enabled && subscribeWake)
+        stop = subscribeWake(() => refresh({ force: false }) ?? Promise.resolve());
+    return {
+        accept, canRefresh, refresh,
+        retire() {
+            if (disposed || retired)
+                return;
+            retired = true;
+            detach();
+            // Clearing protected presentation is safe even after the host changed scope.
+            onUpdate({ status: "invalidated" });
+        },
+        dispose() { disposed = true; detach(); },
+    };
+}

package/dist-cjs/browserReadLifecycle.d.ts

@@ -0,0 +1,5 @@
+/** Native wake binding only; hosts own visibility, eligibility and request sharing. */
+export declare function bindBrowserReadLifecycle(targets: {
+    window: EventTarget;
+    document: EventTarget;
+}, notify: () => Promise<void>): () => void;

package/dist-cjs/browserReadLifecycle.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindBrowserReadLifecycle = bindBrowserReadLifecycle;
+/** Native wake binding only; hosts own visibility, eligibility and request sharing. */
+function bindBrowserReadLifecycle(targets, notify) {
+    const report = (error) => console.error("[Bayon offline] Browser read refresh failed.", { error });
+    const wake = () => {
+        try {
+            void notify().catch(report);
+        }
+        catch (error) {
+            report(error);
+        }
+    };
+    targets.window.addEventListener("focus", wake);
+    targets.window.addEventListener("online", wake);
+    targets.document.addEventListener("visibilitychange", wake);
+    let stopped = false;
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        targets.window.removeEventListener("focus", wake);
+        targets.window.removeEventListener("online", wake);
+        targets.document.removeEventListener("visibilitychange", wake);
+    };
+}

package/dist-cjs/index.d.ts

@@ -1,4 +1,7 @@
 export * from "./readCache.js";
+export * from "./readResourceObserver.js";
+export * from "./readResourceBatch.js";
+export * from "./browserReadLifecycle.js";
 export * from "./pendingWrites.js";
 export * from "./browserRecovery.js";
 export * from "./browserCoordination.js";

package/dist-cjs/index.js

@@ -16,6 +16,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.projectPendingWriteFinalState = exports.OfflineStorageError = void 0;
 __exportStar(require("./readCache"), exports);
+__exportStar(require("./readResourceObserver"), exports);
+__exportStar(require("./readResourceBatch"), exports);
+__exportStar(require("./browserReadLifecycle"), exports);
 __exportStar(require("./pendingWrites"), exports);
 __exportStar(require("./browserRecovery"), exports);
 __exportStar(require("./browserCoordination"), exports);

package/dist-cjs/pendingWriteConsolidation.js

@@ -38,7 +38,8 @@ function projectPendingWriteFinalState(records, getKey, { isBarrier = () => true
         const previous = latest.get(key);
         if (previous) {
             superseded.add(previous);
-            for (const effect of dependents.get(key) ?? [])
+            // Every latest entry creates its matching dependency list below.
+            for (const effect of dependents.get(key))
                 superseded.add(effect);
         }
         latest.set(key, record);

package/dist-cjs/pendingWrites.d.ts

@@ -151,9 +151,9 @@ export declare function syncPendingWrite<Payload>({ id, now, store, sync, }: {
     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.
+ * Replays selected writes oldest first. Identical overlapping calls coalesce;
+ * calls with different options run serially for the same store and scope.
+ * Callers own the selection predicate and idempotent remote mutation semantics.
  */
 export declare function syncPendingWrites<Payload>({ now, scopeKey, select, stopOnFailure, store, sync, }: {
     now?: () => string;

package/dist-cjs/pendingWrites.js

@@ -299,30 +299,34 @@ async function syncPendingWrite({ id, now = () => new Date().toISOString(), stor
         : { 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.
+ * Replays selected writes oldest first. Identical overlapping calls coalesce;
+ * calls with different options run serially for the same store and scope.
+ * Callers own the selection predicate and idempotent remote mutation semantics.
  */
-function syncPendingWrites({ now, scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
+function syncPendingWrites({ now, scopeKey = "all", select = selectAllPendingWrites, 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;
+    if (existing &&
+        existing.select === select &&
+        existing.sync === sync &&
+        existing.now === now &&
+        existing.stopOnFailure === stopOnFailure) {
+        return existing.promise;
     }
-    const syncRun = performPendingWriteSync({
-        now,
-        select,
-        stopOnFailure,
-        store,
-        sync,
-    });
-    inFlightByScope.set(scopeKey, syncRun);
+    const run = () => performPendingWriteSync({ now, select, stopOnFailure, store, sync });
+    // Product decision: distinct filters must never share counts or run in
+    // parallel; each waits for the preceding scope run and uses its own policy.
+    const syncRun = existing ? existing.promise.then(run, run) : run();
+    const entry = { now, select, stopOnFailure, sync, promise: syncRun };
+    inFlightByScope.set(scopeKey, entry);
     const clearInFlight = () => {
-        inFlightByScope.delete(scopeKey);
+        if (inFlightByScope.get(scopeKey) === entry) {
+            inFlightByScope.delete(scopeKey);
+        }
     };
     void syncRun.then(clearInFlight, clearInFlight);
     return syncRun;
@@ -360,6 +364,7 @@ function summarizePendingWrites(records) {
         return summary;
     }, { failedCount: 0, pendingCount: 0, syncingCount: 0, totalCount: 0 });
 }
+const selectAllPendingWrites = () => true;
 const pendingWriteSyncs = new WeakMap();
 async function performPendingWriteSync({ now, select, stopOnFailure, store, sync, }) {
     const summary = {

package/dist-cjs/readCache.d.ts

@@ -13,14 +13,21 @@ export type ReadCacheDriver = {
     clear: () => Promise<void>;
     close?: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    deleteIf?: (key: string, predicate: (value: unknown | null) => boolean) => Promise<boolean>;
     get: (key: string) => Promise<unknown | null>;
     listEntries?: () => Promise<Array<{
         key: string;
         value: unknown;
     }>>;
     set: (key: string, value: unknown) => Promise<void>;
+    setIf?: (key: string, value: unknown, predicate: (value: unknown | null) => boolean) => Promise<boolean>;
 };
 export type ReadCache = {
+    /** Atomic ownership proof for opt-in canonical presentation; version is captured at commit. */
+    commitIfVersion?: <T>(key: string, value: T, version: string, snapshot: ReadCacheHit<unknown> | null, confirmedAt?: string) => Promise<{
+        written: boolean;
+        version: string;
+    }>;
     /**
      * Resolves a stable cache for the duration of a resource load. Dynamic
      * adapters use this to pin the active account before asynchronous work.
@@ -29,12 +36,15 @@ export type ReadCache = {
     clear: () => Promise<void>;
     close: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    /** Retire only a snapshot still owned by the captured generation. */
+    deleteIfVersion?: (key: string, version: string, snapshot: ReadCacheHit<unknown>) => Promise<boolean>;
     /** Advances a key's generation without deleting its retained value. */
     invalidate?: (key: string) => void;
     get: <T>(key: string) => Promise<ReadCacheHit<T> | null>;
     getVersion: (key: string) => string;
     set: <T>(key: string, value: T) => Promise<void>;
-    setIfVersion: <T>(key: string, value: T, version: string) => Promise<boolean>;
+    setIfVersion: <T>(key: string, value: T, version: string, snapshot?: ReadCacheHit<unknown> | null, confirmedAt?: string) => Promise<boolean>;
+    setIfVersionAt?: <T>(key: string, value: T, version: string, snapshot: ReadCacheHit<unknown> | null, confirmedAt: string) => Promise<boolean>;
 };
 export type ReadCachePolicy = {
     /** Time that a cached value can suppress a remote read. */
@@ -42,9 +52,10 @@ export type ReadCachePolicy = {
     /** Maximum age at which cached data remains eligible as an offline fallback. */
     retainForMs: number;
     /** Behavior when revalidation fails while retained data is available. */
-    refreshFailure: "use-retained" | "throw";
+    refreshFailure: "use-retained" | "throw" | ((error: unknown) => "use-retained" | "throw" | "retire");
 };
 export type ReadCacheStatus = "fresh" | "stale" | "miss";
+export type ReadCacheProvenance = "cache-hit" | "source-confirmed" | "retained-fallback";
 /** Payload-free cache lifecycle events suitable for host-owned telemetry. */
 export type ReadCacheOutcome = "fresh-hit" | "stale-hit" | "cache-miss" | "forced-refresh" | "loader-success" | "loader-failure";
 export type ReadThroughCacheResult<T> = {
@@ -53,12 +64,27 @@ export type ReadThroughCacheResult<T> = {
     fromCache: boolean;
     stale: boolean;
     status: ReadCacheStatus;
+    provenance?: ReadCacheProvenance;
+    confirmedAt?: string;
+    savedAt?: string;
+    originalError?: unknown;
 };
 export type ReadCacheResourceUpdate<T> = {
     data: T;
     error?: Error;
     fromCache: boolean;
     status: ReadCacheStatus;
+    provenance?: ReadCacheProvenance;
+    confirmedAt?: string;
+    savedAt?: string;
+    originalError?: unknown;
+};
+export type ReadCacheLoader<T> = {
+    loadFresh: () => Promise<T>;
+    loadFreshResult?: never;
+} | {
+    loadFresh?: never;
+    loadFreshResult: () => Promise<ReadThroughCacheResult<T>>;
 };
 export type BrowserReadCacheOptions = Partial<Pick<BrowserKeyValueDriverOptions, "databaseVersion" | "indexedDB">> & {
     databaseName: string;
@@ -84,29 +110,33 @@ export declare function pruneReadCache({ cache, maxAgeMs, now, }: {
     now?: () => number;
 }): Promise<number>;
 export declare function createReadCacheKey({ namespace, params, prefix, scope, }: ReadCacheKeyOptions): string;
-export declare function readThroughCache<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, onOutcome, policy, }: {
+export declare function readThroughCache<T>({ cache, forceFresh, includeProvenance, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, requireSource, }: {
     cache: ReadCache;
     /**
      * Revalidates after advancing the key generation, retaining the prior value
      * as a possible fallback if refresh fails.
      */
     forceFresh?: boolean;
+    includeProvenance?: boolean;
     key: string;
-    loadFresh: () => Promise<T>;
     maxAgeMs?: number;
     onOutcome?: (outcome: ReadCacheOutcome) => void;
     policy?: ReadCachePolicy;
-}): Promise<ReadThroughCacheResult<T>>;
-export declare function loadReadCacheResource<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache, }: {
+    requireSource?: boolean;
+} & ReadCacheLoader<T>): Promise<ReadThroughCacheResult<T>>;
+export declare function loadReadCacheResource<T>({ cache, deliveryPolicy, forceFresh, includeProvenance, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache, requireSource, }: {
     cache: ReadCache;
+    /** Opt in to presenting the eligible canonical cache after conditional persistence. */
+    deliveryPolicy?: "immediate" | "cache-current";
     /** Revalidate while retaining eligible data as fallback on loader failure. */
     forceFresh?: boolean;
+    includeProvenance?: boolean;
     key: string;
-    loadFresh: () => Promise<T>;
     maxAgeMs?: number;
     onOutcome?: (outcome: ReadCacheOutcome) => void;
     policy?: ReadCachePolicy;
     onCacheWriteError?: (error: Error) => void;
     onUpdate: (update: ReadCacheResourceUpdate<T>) => void;
     skipCache?: boolean;
-}): Promise<T>;
+    requireSource?: boolean;
+} & ReadCacheLoader<T>): Promise<T>;