@bayonai/offline 0.11.0 → 0.13.0

package/dist-cjs/pendingChangeTracker.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupPendingChangeItems = groupPendingChangeItems;
+exports.createPendingChangeSnapshot = createPendingChangeSnapshot;
+exports.createPendingChangeTracker = createPendingChangeTracker;
+const recoveryPolicy_1 = require("./recoveryPolicy");
+/** Groups host-scoped rows without imposing account or domain semantics. */
+function groupPendingChangeItems(items) {
+    const groups = new Map();
+    for (const item of items) {
+        let group = groups.get(item.groupKey);
+        if (!group) {
+            group = { key: item.groupKey, title: item.groupTitle, items: [] };
+            groups.set(item.groupKey, group);
+        }
+        group.items.push(item);
+    }
+    return [...groups.values()];
+}
+/** Same-ID captured edits replace durable rows; insertion order remains stable. */
+function createPendingChangeSnapshot({ accountKey, items, isOffline = false, loading = false, readError = null, }) {
+    const unique = new Map();
+    for (const item of items) {
+        if (accountKey !== null && item.accountKey === accountKey)
+            unique.set(item.id, { ...item });
+    }
+    const rows = [...unique.values()];
+    const groups = groupPendingChangeItems(rows);
+    const draftCount = rows.filter((item) => item.status === "draft").length;
+    const readyCount = rows.filter((item) => item.status === "waiting" || item.status === "sending").length;
+    const attentionCount = rows.filter((item) => item.needsAttention || item.status === "attention").length;
+    const storageErrorCount = rows.filter((item) => item.storageError || item.status === "storage-error").length;
+    return {
+        accountKey,
+        items: rows,
+        groups,
+        count: rows.length,
+        draftCount,
+        readyCount,
+        attentionCount,
+        storageErrorCount,
+        sendingCount: rows.filter((item) => item.sending || item.status === "sending").length,
+        guidance: readError !== null
+            ? "Pending changes could not be read. Your last known changes are preserved."
+            : (0, recoveryPolicy_1.getPendingChangesGuidance)({
+                hasReadyChanges: readyCount > 0,
+                hasDrafts: draftCount > 0,
+                hasErrors: attentionCount > 0 || storageErrorCount > 0 || readError !== null,
+                isOffline,
+            }),
+        loading,
+        readError,
+    };
+}
+/**
+ * Observes existing host queues, never persists or replays changes. Reads fail
+ * closed across accounts but retain the current account's last known rows.
+ * Hosts must notify for draft, command-store and connectivity source changes.
+ */
+function createPendingChangeTracker(options) {
+    let accountKey = options.accountKey ?? null;
+    let isOffline = options.isOffline ?? false;
+    let durable = [];
+    let captured = [];
+    let durableReadError = null;
+    let captureReadError = null;
+    let loading = false;
+    let generation = 0;
+    let closed = false;
+    const listeners = new Set();
+    let snapshot = createPendingChangeSnapshot({
+        accountKey,
+        items: [],
+        isOffline,
+    });
+    const report = (error) => {
+        try {
+            if (options.onError)
+                options.onError(error);
+            else
+                console.error("Pending-change tracker could not read host changes; retaining the last known account snapshot.", error);
+        }
+        catch (callbackError) {
+            console.error("Pending-change tracker error reporter failed while reporting a host source failure.", callbackError, error);
+        }
+    };
+    const publish = () => {
+        const publishingGeneration = generation;
+        snapshot = createPendingChangeSnapshot({
+            accountKey,
+            items: [...durable, ...captured],
+            isOffline,
+            loading,
+            readError: durableReadError ?? captureReadError,
+        });
+        for (const listener of [...listeners]) {
+            if (closed || publishingGeneration !== generation)
+                return;
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error("Pending-change tracker subscriber failed; other subscribers will still receive updates.", error);
+            }
+        }
+    };
+    const refresh = async () => {
+        if (closed)
+            return;
+        const request = ++generation;
+        const requestedAccount = accountKey;
+        const current = () => !closed && request === generation && requestedAccount === accountKey;
+        if (requestedAccount === null)
+            return;
+        // Capture callbacks may notify sources or switch accounts synchronously.
+        const capture = () => {
+            try {
+                const rows = options.capture?.(requestedAccount) ?? [];
+                if (!current())
+                    return;
+                captured = rows;
+                captureReadError = null;
+            }
+            catch (error) {
+                if (!current())
+                    return;
+                captureReadError = error;
+                report(error);
+            }
+        };
+        capture();
+        if (!current())
+            return;
+        loading = true;
+        publish();
+        if (!current())
+            return;
+        try {
+            const rows = await options.load(requestedAccount);
+            if (!current())
+                return;
+            // A successful capture cannot prove durable storage recovered.
+            durableReadError = null;
+            durable = rows;
+            // A durable read may retire host acceptance receipts without emitting an
+            // event. Recapture after proof so drained receipts cannot become ghosts.
+            capture();
+        }
+        catch (error) {
+            if (!current())
+                return;
+            durableReadError = error;
+            report(error);
+        }
+        if (!current())
+            return;
+        loading = false;
+        publish();
+    };
+    const unsubscribe = options.subscribe?.(() => {
+        void refresh();
+    });
+    const tracker = {
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => {
+            if (closed)
+                return () => { };
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        refresh,
+        setAccountKey: (next) => {
+            if (closed || next === accountKey)
+                return;
+            ++generation;
+            accountKey = next;
+            durable = [];
+            captured = [];
+            durableReadError = null;
+            captureReadError = null;
+            loading = false;
+            publish();
+            void refresh();
+        },
+        setOffline: (next) => {
+            if (closed || next === isOffline)
+                return;
+            isOffline = next;
+            publish();
+        },
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            ++generation;
+            unsubscribe?.();
+            listeners.clear();
+        },
+    };
+    void refresh();
+    return tracker;
+}

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/readCache.d.ts

@@ -13,12 +13,14 @@ 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 = {
     /**
@@ -29,12 +31,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 +47,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 +59,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 +105,31 @@ 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, forceFresh, includeProvenance, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache, requireSource, }: {
     cache: ReadCache;
     /** 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>;