@bayonai/offline 0.5.1 → 0.8.0

package/dist-cjs/idbDriver.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineStorageError = void 0;
 exports.createIdbKeyValueDriver = createIdbKeyValueDriver;
 const idb_1 = require("idb");
+class OfflineStorageError extends Error {
+    name = "OfflineStorageError";
+}
+exports.OfflineStorageError = OfflineStorageError;
 function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, storeName, }) {
     if (!indexedDB) {
         return null;
@@ -12,22 +17,33 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         indexedDB,
         storeName,
     });
+    function runMutation(operationName, mutate) {
+        return runTransactionalStorageOperation({
+            failureMode: "throw",
+            fallback: undefined,
+            operationName,
+            storeName,
+            operation: async (setTransaction, isCancelled) => {
+                const database = await databasePromise;
+                if (isCancelled())
+                    return;
+                const transaction = database.transaction(storeName, "readwrite");
+                setTransaction(transaction);
+                await mutate(transaction.objectStore(storeName));
+                await transaction.done;
+            },
+            timeoutMs: operationTimeoutMs,
+        });
+    }
     return {
         async clear() {
-            await runBrowserStorageOperation({
-                fallback: undefined,
-                operationName: "clear object store",
-                operation: async () => {
-                    const database = await databasePromise;
-                    await database.clear(storeName);
-                },
-                timeoutMs: operationTimeoutMs,
-            });
+            await runMutation("clear object store", (objectStore) => objectStore.clear());
         },
         async close() {
             await runBrowserStorageOperation({
                 fallback: undefined,
                 operationName: "close database",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     database.close();
@@ -36,15 +52,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             });
         },
         async delete(key) {
-            await runBrowserStorageOperation({
-                fallback: undefined,
-                operationName: "delete key",
-                operation: async () => {
-                    const database = await databasePromise;
-                    await database.delete(storeName, key);
-                },
-                timeoutMs: operationTimeoutMs,
-            });
+            await runMutation("delete key", (objectStore) => objectStore.delete(key));
         },
         async deleteIf(key, predicate) {
             return runConditionalStorageOperation({
@@ -65,6 +73,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             return runBrowserStorageOperation({
                 fallback: null,
                 operationName: "read key",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     return (await database.get(storeName, key)) ?? null;
@@ -76,6 +85,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             return runBrowserStorageOperation({
                 fallback: [],
                 operationName: "list object store",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     return database.getAll(storeName);
@@ -87,6 +97,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             return runBrowserStorageOperation({
                 fallback: [],
                 operationName: "list object-store entries",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     // Keys and values must come from one transaction. Separate database
@@ -108,15 +119,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             });
         },
         async set(key, value) {
-            await runBrowserStorageOperation({
-                fallback: undefined,
-                operationName: "write key",
-                operation: async () => {
-                    const database = await databasePromise;
-                    await database.put(storeName, value, key);
-                },
-                timeoutMs: operationTimeoutMs,
-            });
+            await runMutation("write key", (objectStore) => objectStore.put(value, key));
         },
         async setIf(key, value, predicate) {
             return runConditionalStorageOperation({
@@ -149,18 +152,27 @@ async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB,
     }
     return database;
 }
-async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation, operationName, timeoutMs, }) {
+async function runBrowserStorageOperation({ cancelOnTimeout, failureMode = "fallback", fallback, operation, operationName, storeName, timeoutMs, }) {
     let timeoutId = null;
+    const startedAt = Date.now();
     try {
         return await Promise.race([
             operation(),
-            new Promise((resolve) => {
+            new Promise((resolve, reject) => {
                 timeoutId = setTimeout(() => {
-                    console.error(`IndexedDB timed out while trying to ${operationName}.`, {
+                    console.warn("[Bayon offline] IndexedDB operation timed out.", {
+                        elapsedMs: Date.now() - startedAt,
+                        operationName,
+                        storeName,
                         timeoutMs,
                     });
                     if (!cancelOnTimeout || cancelOnTimeout()) {
-                        resolve(fallback);
+                        if (failureMode === "throw") {
+                            reject(new OfflineStorageError(`IndexedDB timed out while attempting to ${operationName} in ${storeName}.`));
+                        }
+                        else {
+                            resolve(fallback);
+                        }
                     }
                 }, timeoutMs);
             }),
@@ -168,6 +180,11 @@ async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation
     }
     catch (error) {
         console.error(`IndexedDB failed to ${operationName}.`, { error });
+        if (failureMode === "throw") {
+            if (error instanceof OfflineStorageError)
+                throw error;
+            throw new OfflineStorageError(`IndexedDB failed to ${operationName} in ${storeName}.`, { cause: error });
+        }
         return fallback;
     }
     finally {
@@ -176,12 +193,46 @@ async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation
         }
     }
 }
+async function runTransactionalStorageOperation({ failureMode, fallback, operation, operationName, storeName, timeoutMs, }) {
+    let transaction;
+    let cancelled = false;
+    return runBrowserStorageOperation({
+        failureMode,
+        fallback,
+        operationName,
+        storeName,
+        timeoutMs,
+        cancelOnTimeout() {
+            cancelled = true;
+            if (!transaction)
+                return true;
+            try {
+                transaction.abort();
+                return true;
+            }
+            catch (error) {
+                console.warn("[Bayon offline] IndexedDB transaction already settling at timeout.", { error, operationName });
+                return false;
+            }
+        },
+        operation: async () => {
+            return operation((nextTransaction) => {
+                transaction = nextTransaction;
+                // Aborting can reject transaction.done. The operation also awaits it,
+                // but observing it here prevents a race from becoming unhandled.
+                void transaction.done.catch(() => undefined);
+            }, () => cancelled);
+        },
+    });
+}
 async function runConditionalStorageOperation({ apply, databasePromise, operationName, storeName, timeoutMs, }) {
     let transaction;
     let cancelled = false;
     return runBrowserStorageOperation({
+        failureMode: "throw",
         fallback: false,
         operationName,
+        storeName,
         timeoutMs,
         cancelOnTimeout() {
             cancelled = true;

package/dist-cjs/index.js

@@ -14,8 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineStorageError = void 0;
 __exportStar(require("./readCache"), exports);
 __exportStar(require("./pendingWrites"), exports);
 __exportStar(require("./browserRecovery"), exports);
 __exportStar(require("./browserCoordination"), exports);
 __exportStar(require("./browserFallbackRecovery"), exports);
+__exportStar(require("./durableCommandStore"), exports);
+var idbDriver_1 = require("./idbDriver");
+Object.defineProperty(exports, "OfflineStorageError", { enumerable: true, get: function () { return idbDriver_1.OfflineStorageError; } });

package/dist-cjs/pendingWrites.js

@@ -162,19 +162,34 @@ function createBrowserPendingWriteStore({ databaseName, databaseVersion, indexed
         operationTimeoutMs,
         storeName,
     });
-    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion });
+    return createPendingWriteStore(driver ?? createUnavailablePendingWriteDriver(), { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion });
 }
 function createPendingWriteKey({ id, prefix }) {
     return `${prefix}:${encodeURIComponent(id)}`;
 }
 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;
 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,
@@ -187,7 +202,7 @@ async function syncPendingWrite({ id, now = () => new Date().toISOString(), stor
         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.";
@@ -204,7 +219,7 @@ async function syncPendingWrite({ id, now = () => new Date().toISOString(), stor
             store,
         });
         return markedFailed
-            ? { error: message, status: "failed" }
+            ? { error: message, failure: error, status: "failed" }
             : { status: "superseded" };
     }
     return (await store.clearIfSnapshotId(id, claimedSnapshotId))
@@ -216,7 +231,7 @@ async function syncPendingWrite({ id, now = () => new Date().toISOString(), stor
  * same store/scope. Callers own the selection predicate and idempotent remote
  * mutation semantics.
  */
-function syncPendingWrites({ scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
+function syncPendingWrites({ now, scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
     let inFlightByScope = pendingWriteSyncs.get(store);
     if (!inFlightByScope) {
         inFlightByScope = new Map();
@@ -227,6 +242,7 @@ function syncPendingWrites({ scopeKey = "all", select = () => true, stopOnFailur
         return existing;
     }
     const syncRun = performPendingWriteSync({
+        now,
         select,
         stopOnFailure,
         store,
@@ -273,7 +289,7 @@ 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,
@@ -286,6 +302,7 @@ async function performPendingWriteSync({ select, stopOnFailure, store, sync, })
     for (const record of records) {
         const result = await syncPendingWrite({
             id: record.id,
+            now,
             store,
             sync,
         });
@@ -294,7 +311,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;
         }
     }
@@ -319,7 +338,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.
  */
-function createOrderedPendingWriteExecutor({ scopeKey = "all", select = () => true, store, sync, }) {
+function createOrderedPendingWriteExecutor({ now, scopeKey = "all", select = () => true, store, sync, }) {
     let execution = Promise.resolve();
     function inOrder(operation) {
         const result = execution.then(operation, operation);
@@ -328,6 +347,7 @@ function createOrderedPendingWriteExecutor({ scopeKey = "all", select = () => tr
     }
     function recover() {
         return inOrder(() => syncPendingWrites({
+            now,
             scopeKey,
             select,
             stopOnFailure: true,
@@ -343,6 +363,7 @@ function createOrderedPendingWriteExecutor({ scopeKey = "all", select = () => tr
                     return runPendingWrite(options);
                 }
                 const replay = await syncPendingWrites({
+                    now,
                     scopeKey,
                     select,
                     stopOnFailure: true,
@@ -360,7 +381,8 @@ function createOrderedPendingWriteExecutor({ scopeKey = "all", select = () => tr
         },
     };
 }
-function createNoopPendingWriteDriver() {
+function createUnavailablePendingWriteDriver() {
+    const unavailable = () => new idbDriver_1.OfflineStorageError("IndexedDB is unavailable; the pending write was not stored.");
     return {
         async clear() { },
         async clearIf() {
@@ -374,9 +396,11 @@ function createNoopPendingWriteDriver() {
         async list() {
             return [];
         },
-        async set() { },
+        async set() {
+            throw unavailable();
+        },
         async setIf() {
-            return false;
+            throw unavailable();
         },
     };
 }
@@ -416,6 +440,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),
@@ -444,6 +471,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-cjs/readCache.js

@@ -13,7 +13,9 @@ exports.readCacheSchemaVersion = 1;
 exports.readCacheFreshnessMaxAgeMs = 30_000;
 exports.durableReadCacheFreshnessMaxAgeMs = 60 * 60_000;
 exports.identityReadCacheFreshnessMaxAgeMs = 24 * 60 * 60_000;
-exports.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.
+exports.browserReadCacheOperationTimeoutMs = 1_000;
 const pendingFreshLoads = new WeakMap();
 const cachePruners = new WeakMap();
 function createReadCache(driver) {
@@ -143,8 +145,7 @@ function createBrowserReadCache({ databaseName, databaseVersion, indexedDB = glo
  */
 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));
 }
 function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
     const serializedParams = Object.entries(params)
@@ -166,7 +167,15 @@ async function readThroughCache({ cache, forceFresh = false, key, loadFresh, max
     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);
@@ -180,7 +189,15 @@ async function readThroughCache({ cache, forceFresh = false, key, loadFresh, max
     }
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.5.1",
+  "version": "0.8.0",
   "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",
@@ -56,7 +56,7 @@
   },
   "devDependencies": {
     "fake-indexeddb": "^6.2.5",
-    "typescript": "^5",
-    "vitest": "^4.1.6"
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1"
   }
 }