@bayonai/offline 0.5.1 → 0.8.0

package/dist/pendingWrites.d.ts

@@ -6,6 +6,8 @@ export type PendingWriteStatus = "pending" | "syncing" | "failed";
 export type PendingWriteRecord<Payload = unknown> = {
     error?: string;
     id: string;
+    /** Do not execute this accepted command before this ISO timestamp. */
+    notBefore?: string;
     payload: Payload;
     savedAt: string;
     snapshotId: string;
@@ -80,6 +82,7 @@ export type SyncPendingWriteResult = {
     status: "superseded";
 } | {
     error: string;
+    failure: unknown;
     status: "failed";
 };
 export type SyncPendingWritesResult = {
@@ -91,7 +94,11 @@ export type SyncPendingWritesResult = {
     superseded: number;
     synced: number;
 };
-export type PendingWriteSync<Payload> = (payload: Payload) => Promise<unknown>;
+export type PendingWriteSyncContext = {
+    /** Stable durable-record identity; safe to use as a remote idempotency key. */
+    recordId: string;
+};
+export type PendingWriteSync<Payload, Result = unknown> = (payload: Payload, context: PendingWriteSyncContext) => Promise<Result>;
 export type RunPendingWriteResult<TResult, TQueued> = {
     result: TResult;
     status: "synced";
@@ -127,7 +134,7 @@ export declare function createMemoryPendingWriteDriver(): PendingWriteDriver;
 export declare function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: Omit<BrowserPendingWriteStoreOptions, "keyPrefix" | "normalizePayload" | "schemaVersion">): PendingWriteDriver | null;
 export declare function createBrowserPendingWriteStore<Payload = unknown>({ databaseName, databaseVersion, indexedDB, keyPrefix, normalizeLegacyRecord, normalizePayload, operationTimeoutMs, schemaVersion, storeName, }: BrowserPendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
 export declare function createPendingWriteKey({ id, prefix }: PendingWriteKeyOptions): string;
-export declare function createPendingWriteSnapshotId(): `${string}-${string}-${string}-${string}-${string}`;
+export declare function createPendingWriteSnapshotId(): string;
 export declare function syncPendingWrite<Payload>({ id, now, store, sync, }: {
     id: string;
     now?: () => string;
@@ -139,7 +146,8 @@ export declare function syncPendingWrite<Payload>({ id, now, store, sync, }: {
  * same store/scope. Callers own the selection predicate and idempotent remote
  * mutation semantics.
  */
-export declare function syncPendingWrites<Payload>({ scopeKey, select, stopOnFailure, store, sync, }: {
+export declare function syncPendingWrites<Payload>({ now, scopeKey, select, stopOnFailure, store, sync, }: {
+    now?: () => string;
     scopeKey?: string;
     select?: (record: PendingWriteRecord<Payload>) => boolean;
     /** Preserve caller ordering by leaving later records for a future retry. */
@@ -158,7 +166,8 @@ export declare function summarizePendingWrites<Payload>(records: Array<PendingWr
  * workspace. Use its `recover` method for background replay and `run` for new
  * writes so a newer remote mutation cannot overtake an older queued mutation.
  */
-export declare function createOrderedPendingWriteExecutor<Payload>({ scopeKey, select, store, sync, }: {
+export declare function createOrderedPendingWriteExecutor<Payload>({ now, scopeKey, select, store, sync, }: {
+    now?: () => string;
     scopeKey?: string;
     select?: (record: PendingWriteRecord<Payload>) => boolean;
     store: PendingWriteStore<Payload>;

package/dist/pendingWrites.js

@@ -1,4 +1,4 @@
-import { createIdbKeyValueDriver, } from "./idbDriver.js";
+import { createIdbKeyValueDriver, OfflineStorageError, } from "./idbDriver.js";
 export const pendingWriteSchemaVersion = 1;
 export const pendingWriteOperationTimeoutMs = 2_000;
 export const pendingWriteSyncLeaseTimeoutMs = 60_000;
@@ -148,19 +148,34 @@ export function createBrowserPendingWriteStore({ databaseName, databaseVersion,
         operationTimeoutMs,
         storeName,
     });
-    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion });
+    return createPendingWriteStore(driver ?? createUnavailablePendingWriteDriver(), { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion });
 }
 export function createPendingWriteKey({ id, prefix }) {
     return `${prefix}:${encodeURIComponent(id)}`;
 }
 export function createPendingWriteSnapshotId() {
-    return globalThis.crypto.randomUUID();
+    const randomId = globalThis.crypto?.randomUUID?.();
+    if (randomId)
+        return randomId;
+    pendingWriteSnapshotSequence += 1;
+    return [
+        "snapshot",
+        Date.now().toString(36),
+        pendingWriteSnapshotSequence.toString(36),
+        Math.random().toString(36).slice(2),
+    ].join("-");
 }
+let pendingWriteSnapshotSequence = 0;
 export async function syncPendingWrite({ id, now = () => new Date().toISOString(), store, sync, }) {
     const pending = await store.get(id);
     if (!pending) {
         return { status: "idle" };
     }
+    // A delayed command remains in its ordered lane until its grace period has
+    // elapsed. This makes cancellation survive UI unmounts and app restarts.
+    if (pending.notBefore && Date.parse(pending.notBefore) > Date.parse(now())) {
+        return { status: "idle" };
+    }
     const claimedSnapshotId = createPendingWriteSnapshotId();
     const claimed = await store.claimIfSnapshotId(id, pending.snapshotId, {
         ...pending,
@@ -173,7 +188,7 @@ export async function syncPendingWrite({ id, now = () => new Date().toISOString(
         return { status: "superseded" };
     }
     try {
-        await sync(pending.payload);
+        await sync(pending.payload, { recordId: pending.id });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unable to sync pending write.";
@@ -190,7 +205,7 @@ export async function syncPendingWrite({ id, now = () => new Date().toISOString(
             store,
         });
         return markedFailed
-            ? { error: message, status: "failed" }
+            ? { error: message, failure: error, status: "failed" }
             : { status: "superseded" };
     }
     return (await store.clearIfSnapshotId(id, claimedSnapshotId))
@@ -202,7 +217,7 @@ export async function syncPendingWrite({ id, now = () => new Date().toISOString(
  * same store/scope. Callers own the selection predicate and idempotent remote
  * mutation semantics.
  */
-export function syncPendingWrites({ scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
+export function syncPendingWrites({ now, scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
     let inFlightByScope = pendingWriteSyncs.get(store);
     if (!inFlightByScope) {
         inFlightByScope = new Map();
@@ -213,6 +228,7 @@ export function syncPendingWrites({ scopeKey = "all", select = () => true, stopO
         return existing;
     }
     const syncRun = performPendingWriteSync({
+        now,
         select,
         stopOnFailure,
         store,
@@ -259,7 +275,7 @@ export function summarizePendingWrites(records) {
     }, { failedCount: 0, pendingCount: 0, syncingCount: 0, totalCount: 0 });
 }
 const pendingWriteSyncs = new WeakMap();
-async function performPendingWriteSync({ select, stopOnFailure, store, sync, }) {
+async function performPendingWriteSync({ now, select, stopOnFailure, store, sync, }) {
     const summary = {
         attempted: 0,
         failed: 0,
@@ -272,6 +288,7 @@ async function performPendingWriteSync({ select, stopOnFailure, store, sync, })
     for (const record of records) {
         const result = await syncPendingWrite({
             id: record.id,
+            now,
             store,
             sync,
         });
@@ -280,7 +297,9 @@ async function performPendingWriteSync({ select, stopOnFailure, store, sync, })
         // Product decision: a superseded result can represent an older live claim.
         // Preserve strict ordering by leaving every later record for a future run.
         if (stopOnFailure &&
-            (result.status === "failed" || result.status === "superseded")) {
+            (result.status === "failed" ||
+                result.status === "idle" ||
+                result.status === "superseded")) {
             break;
         }
     }
@@ -305,7 +324,7 @@ function isPendingWriteSyncClaimAvailable(record, now) {
  * workspace. Use its `recover` method for background replay and `run` for new
  * writes so a newer remote mutation cannot overtake an older queued mutation.
  */
-export function createOrderedPendingWriteExecutor({ scopeKey = "all", select = () => true, store, sync, }) {
+export function createOrderedPendingWriteExecutor({ now, scopeKey = "all", select = () => true, store, sync, }) {
     let execution = Promise.resolve();
     function inOrder(operation) {
         const result = execution.then(operation, operation);
@@ -314,6 +333,7 @@ export function createOrderedPendingWriteExecutor({ scopeKey = "all", select = (
     }
     function recover() {
         return inOrder(() => syncPendingWrites({
+            now,
             scopeKey,
             select,
             stopOnFailure: true,
@@ -329,6 +349,7 @@ export function createOrderedPendingWriteExecutor({ scopeKey = "all", select = (
                     return runPendingWrite(options);
                 }
                 const replay = await syncPendingWrites({
+                    now,
                     scopeKey,
                     select,
                     stopOnFailure: true,
@@ -346,7 +367,8 @@ export function createOrderedPendingWriteExecutor({ scopeKey = "all", select = (
         },
     };
 }
-function createNoopPendingWriteDriver() {
+function createUnavailablePendingWriteDriver() {
+    const unavailable = () => new OfflineStorageError("IndexedDB is unavailable; the pending write was not stored.");
     return {
         async clear() { },
         async clearIf() {
@@ -360,9 +382,11 @@ function createNoopPendingWriteDriver() {
         async list() {
             return [];
         },
-        async set() { },
+        async set() {
+            throw unavailable();
+        },
         async setIf() {
-            return false;
+            throw unavailable();
         },
     };
 }
@@ -402,6 +426,9 @@ function normalizePendingWriteRecord(record, normalizePayload) {
     return {
         ...(typeof record.error === "string" ? { error: record.error } : {}),
         id: record.id,
+        ...(typeof record.notBefore === "string"
+            ? { notBefore: record.notBefore }
+            : {}),
         payload,
         savedAt: record.savedAt,
         snapshotId: record.snapshotId ?? createLegacyPendingWriteSnapshotId(record),
@@ -430,6 +457,7 @@ function isPendingWriteRecord(value) {
         typeof value === "object" &&
         "id" in value &&
         typeof value.id === "string" &&
+        (!("notBefore" in value) || typeof value.notBefore === "string") &&
         "savedAt" in value &&
         typeof value.savedAt === "string" &&
         (!("snapshotId" in value) || typeof value.snapshotId === "string") &&

package/dist/readCache.d.ts

@@ -3,7 +3,7 @@ export declare const readCacheSchemaVersion = 1;
 export declare const readCacheFreshnessMaxAgeMs = 30000;
 export declare const durableReadCacheFreshnessMaxAgeMs: number;
 export declare const identityReadCacheFreshnessMaxAgeMs: number;
-export declare const browserReadCacheOperationTimeoutMs = 2000;
+export declare const browserReadCacheOperationTimeoutMs = 1000;
 export type ReadCacheHit<T> = {
     fromCache: true;
     savedAt: string;

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) {
@@ -133,8 +135,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)
@@ -156,7 +157,15 @@ export async function readThroughCache({ cache, forceFresh = false, key, loadFre
     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);
+        try {
+            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);
@@ -170,7 +179,15 @@ export async function readThroughCache({ cache, forceFresh = false, key, loadFre
     }
     try {
         const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
-        await resourceCache.setIfVersion(key, fresh, version);
+        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,

package/dist-cjs/browserFallbackRecovery.js

@@ -12,6 +12,7 @@ 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;
@@ -23,7 +24,9 @@ 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;
         }
@@ -36,7 +39,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/durableCommandStore.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDurableCommandStore = createDurableCommandStore;
+const pendingWrites_1 = require("./pendingWrites");
+/**
+ * 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.
+ */
+function createDurableCommandStore({ canCancel = () => true, classifyError = () => "unexpected", createId = createDurableCommandId, execute, initialState, load, now = () => new Date().toISOString(), project, reconcile, shouldRetry = () => true, store, }) {
+    let baseState = initialState;
+    let baseStateGeneration = 0;
+    let savedAtMillis = 0;
+    let publishGeneration = 0;
+    let storedRecords = [];
+    let deferredRecoveryTimer = null;
+    const provisionalRecords = new Map();
+    const localStorageFailures = new Map();
+    let snapshot = {
+        operations: [],
+        state: initialState,
+    };
+    const listeners = new Set();
+    const executor = (0, pendingWrites_1.createOrderedPendingWriteExecutor)({
+        now,
+        scopeKey: "durable-command-store",
+        select: isActiveCommand,
+        store,
+        sync: async (command, { recordId }) => {
+            const result = await execute(command, { operationId: recordId });
+            // A completed remote write is newer than any read already in flight.
+            // Reconciliation is local-only: a projector bug must never retry a
+            // command whose remote effect may already have committed.
+            baseStateGeneration += 1;
+            if (reconcile) {
+                try {
+                    baseState = reconcile(baseState, command, result);
+                }
+                catch (error) {
+                    console.error("[Bayon offline] Unable to reconcile a confirmed durable command.", { error, operationId: recordId });
+                }
+            }
+        },
+    });
+    function notify() {
+        for (const listener of listeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error("[Bayon offline] Durable-command listener failed.", {
+                    error,
+                });
+            }
+        }
+    }
+    function classifyStoredError(error) {
+        return classifyError(new Error(error ?? "Unable to sync durable command."));
+    }
+    function isActiveCommand(record) {
+        return (record.syncStatus !== "failed" ||
+            shouldRetry(classifyStoredError(record.error), record.payload));
+    }
+    function scheduleDeferredRecovery(records) {
+        if (deferredRecoveryTimer) {
+            clearTimeout(deferredRecoveryTimer);
+            deferredRecoveryTimer = null;
+        }
+        const currentTime = Date.parse(now());
+        const nextDeadline = records.reduce((earliest, record) => {
+            const deadline = record.notBefore ? Date.parse(record.notBefore) : NaN;
+            if (!Number.isFinite(deadline) || deadline <= currentTime)
+                return earliest;
+            return earliest === null ? deadline : Math.min(earliest, deadline);
+        }, null);
+        if (nextDeadline === null)
+            return;
+        deferredRecoveryTimer = setTimeout(recoverInBackground, Math.max(0, nextDeadline - currentTime));
+    }
+    function currentRecords() {
+        const records = new Map(storedRecords.map((record) => [record.id, record]));
+        for (const record of provisionalRecords.values()) {
+            records.set(record.id, record);
+        }
+        return [...records.values()].sort((left, right) => left.savedAt.localeCompare(right.savedAt) ||
+            left.id.localeCompare(right.id));
+    }
+    function applySnapshot(records) {
+        snapshot = {
+            operations: [
+                ...records.map((record) => ({
+                    command: record.payload,
+                    ...(record.syncStatus === "failed"
+                        ? { error: classifyStoredError(record.error) }
+                        : {}),
+                    id: record.id,
+                    status: record.syncStatus === "failed"
+                        ? "failed"
+                        : record.syncStatus === "syncing"
+                            ? "syncing"
+                            : "accepted",
+                })),
+                ...[...localStorageFailures].map(([id, command]) => ({
+                    command,
+                    error: "local-storage",
+                    id,
+                    status: "failed",
+                })),
+            ],
+            state: project(baseState, records.filter(isActiveCommand)),
+        };
+        scheduleDeferredRecovery(records);
+    }
+    async function publish() {
+        const generation = ++publishGeneration;
+        const records = await store.list();
+        if (generation !== publishGeneration)
+            return;
+        storedRecords = records;
+        applySnapshot(currentRecords());
+        notify();
+    }
+    async function recover() {
+        await executor.recover();
+        await publish();
+    }
+    function recoverInBackground() {
+        void recover().catch((error) => {
+            console.error("[Bayon offline] Unable to recover durable commands.", {
+                error,
+            });
+        });
+    }
+    const unsubscribe = store.subscribe(() => {
+        void publish().catch((error) => {
+            console.error("[Bayon offline] Unable to publish durable commands.", {
+                error,
+            });
+        });
+    });
+    return {
+        async cancel(operationId) {
+            if (localStorageFailures.delete(operationId)) {
+                applySnapshot(currentRecords());
+                notify();
+                return true;
+            }
+            const record = await store.get(operationId);
+            if (!record ||
+                record.syncStatus === "syncing" ||
+                !canCancel(record.payload, now())) {
+                return false;
+            }
+            const cancelled = await store.clearIfSnapshotId(record.id, record.snapshotId);
+            if (cancelled)
+                await publish();
+            return cancelled;
+        },
+        close() {
+            if (deferredRecoveryTimer)
+                clearTimeout(deferredRecoveryTimer);
+            publishGeneration += 1;
+            unsubscribe();
+        },
+        dispatch(command, options = {}) {
+            const operationId = createId();
+            const timestamp = Math.max(Date.parse(now()), savedAtMillis + 1);
+            savedAtMillis = timestamp;
+            const record = {
+                id: operationId,
+                ...(options.notBefore ? { notBefore: options.notBefore } : {}),
+                payload: command,
+                savedAt: new Date(timestamp).toISOString(),
+                snapshotId: operationId,
+                syncStatus: "pending",
+            };
+            // Product decision: provisional records remain part of the same ordered
+            // projection as persisted retryable failures while storage settles.
+            provisionalRecords.set(operationId, record);
+            localStorageFailures.delete(operationId);
+            applySnapshot(currentRecords());
+            notify();
+            const accepted = store.set(record).then(async () => {
+                provisionalRecords.delete(operationId);
+                await publish();
+                recoverInBackground();
+            }, async (error) => {
+                provisionalRecords.delete(operationId);
+                localStorageFailures.set(operationId, command);
+                applySnapshot(currentRecords());
+                notify();
+                throw error;
+            });
+            return { accepted, operationId };
+        },
+        getSnapshot: () => snapshot,
+        async recover() {
+            await recover();
+        },
+        async refresh(scope) {
+            const generation = ++baseStateGeneration;
+            const loaded = await load(scope);
+            if (generation !== baseStateGeneration)
+                return;
+            baseState = loaded;
+            await publish();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+function createDurableCommandId() {
+    return globalThis.crypto?.randomUUID?.() ?? createFallbackDurableCommandId();
+}
+let fallbackDurableCommandSequence = 0;
+function createFallbackDurableCommandId() {
+    fallbackDurableCommandSequence += 1;
+    return [
+        "command",
+        Date.now().toString(36),
+        fallbackDurableCommandSequence.toString(36),
+        Math.random().toString(36).slice(2),
+    ].join("-");
+}