@bayonai/offline 0.12.0 → 0.15.0

package/dist-cjs/readResourceBatch.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observeReadResourceBatch = observeReadResourceBatch;
+/** A mounted presentation barrier; child tasks retain sole network/cache ownership. */
+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-cjs/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-cjs/readResourceObserver.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReadResourceObserver = createReadResourceObserver;
+/**
+ * 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.
+ */
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.12.0",
+  "version": "0.15.0",
   "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",