@bayonai/offline 0.1.1 → 0.4.0

package/dist-cjs/idbDriver.js

@@ -90,6 +90,30 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
                 timeoutMs: operationTimeoutMs,
             });
         },
+        async listEntries() {
+            return runBrowserStorageOperation({
+                fallback: [],
+                operationName: "list object-store entries",
+                operation: async () => {
+                    const database = await databasePromise;
+                    // Keys and values must come from one transaction. Separate database
+                    // reads could pair a key from one cross-tab storage state with a
+                    // value from another, causing retention code to delete the wrong key.
+                    const transaction = database.transaction(storeName, "readonly");
+                    const objectStore = transaction.objectStore(storeName);
+                    const [keys, values] = await Promise.all([
+                        objectStore.getAllKeys(),
+                        objectStore.getAll(),
+                    ]);
+                    await transaction.done;
+                    return keys.map((key, index) => ({
+                        key: String(key),
+                        value: values[index],
+                    }));
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
         async set(key, value) {
             await runBrowserStorageOperation({
                 fallback: undefined,

package/dist-cjs/index.js

@@ -16,3 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./readCache"), exports);
 __exportStar(require("./pendingWrites"), exports);
+__exportStar(require("./browserRecovery"), exports);
+__exportStar(require("./browserCoordination"), exports);

package/dist-cjs/pendingWrites.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pendingWriteOperationTimeoutMs = exports.pendingWriteSchemaVersion = void 0;
+exports.pendingWriteSyncLeaseTimeoutMs = exports.pendingWriteOperationTimeoutMs = exports.pendingWriteSchemaVersion = void 0;
 exports.createPendingWriteStore = createPendingWriteStore;
 exports.createMemoryPendingWriteDriver = createMemoryPendingWriteDriver;
 exports.createBrowserPendingWriteDriver = createBrowserPendingWriteDriver;
@@ -8,22 +8,61 @@ exports.createBrowserPendingWriteStore = createBrowserPendingWriteStore;
 exports.createPendingWriteKey = createPendingWriteKey;
 exports.createPendingWriteSnapshotId = createPendingWriteSnapshotId;
 exports.syncPendingWrite = syncPendingWrite;
+exports.syncPendingWrites = syncPendingWrites;
+exports.runPendingWrite = runPendingWrite;
+exports.summarizePendingWrites = summarizePendingWrites;
+exports.createOrderedPendingWriteExecutor = createOrderedPendingWriteExecutor;
 const idbDriver_1 = require("./idbDriver");
 exports.pendingWriteSchemaVersion = 1;
 exports.pendingWriteOperationTimeoutMs = 2_000;
+exports.pendingWriteSyncLeaseTimeoutMs = 60_000;
 function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion = exports.pendingWriteSchemaVersion, }) {
+    const listeners = new Set();
+    const notify = (change) => {
+        for (const listener of listeners) {
+            try {
+                listener(change);
+            }
+            catch (error) {
+                console.error("[Bayon offline] Pending-write store listener failed.", {
+                    error,
+                    type: change.type,
+                });
+            }
+        }
+    };
     return {
+        async claimIfSnapshotId(id, snapshotId, record, now) {
+            const claimed = await driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => {
+                const current = toPendingWriteEnvelope(value, schemaVersion, {
+                    normalizeLegacyRecord,
+                    normalizePayload,
+                })?.record;
+                return (current?.snapshotId === snapshotId &&
+                    isPendingWriteSyncClaimAvailable(current, now));
+            });
+            if (claimed) {
+                notify({ record, type: "replace" });
+            }
+            return claimed;
+        },
         async clear(id) {
             await driver.clear(createPendingWriteKey({ id, prefix: keyPrefix }));
+            notify({ id, type: "clear" });
         },
         async clearAll() {
             await driver.clearAll();
+            notify({ type: "clearAll" });
         },
         async clearIfSnapshotId(id, snapshotId) {
-            return driver.clearIf(createPendingWriteKey({ id, prefix: keyPrefix }), (value) => toPendingWriteEnvelope(value, schemaVersion, {
+            const cleared = await driver.clearIf(createPendingWriteKey({ id, prefix: keyPrefix }), (value) => toPendingWriteEnvelope(value, schemaVersion, {
                 normalizeLegacyRecord,
                 normalizePayload,
             })?.record.snapshotId === snapshotId);
+            if (cleared) {
+                notify({ id, type: "clear" });
+            }
+            return cleared;
         },
         async close() {
             await driver.close?.();
@@ -38,13 +77,18 @@ function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, nor
                 normalizePayload,
             })?.record)
                 .filter((record) => Boolean(record))
-                .sort((left, right) => left.savedAt.localeCompare(right.savedAt));
+                .sort((left, right) => left.savedAt.localeCompare(right.savedAt) ||
+                left.id.localeCompare(right.id));
         },
         async replaceIfSnapshotId(id, snapshotId, record) {
-            return driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => toPendingWriteEnvelope(value, schemaVersion, {
+            const replaced = await driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => toPendingWriteEnvelope(value, schemaVersion, {
                 normalizeLegacyRecord,
                 normalizePayload,
             })?.record.snapshotId === snapshotId);
+            if (replaced) {
+                notify({ record, type: "replace" });
+            }
+            return replaced;
         },
         async set(record) {
             const storedRecord = {
@@ -55,8 +99,13 @@ function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, nor
                 record: storedRecord,
                 schemaVersion,
             });
+            notify({ record: storedRecord, type: "set" });
             return storedRecord;
         },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
     };
 }
 function createMemoryPendingWriteDriver() {
@@ -121,34 +170,193 @@ function createPendingWriteKey({ id, prefix }) {
 function createPendingWriteSnapshotId() {
     return globalThis.crypto.randomUUID();
 }
-async function syncPendingWrite({ id, store, sync, }) {
+async function syncPendingWrite({ id, now = () => new Date().toISOString(), store, sync, }) {
     const pending = await store.get(id);
     if (!pending) {
         return { status: "idle" };
     }
-    await markPendingSnapshot({
-        id,
-        nextRecord: { ...pending, error: undefined, syncStatus: "syncing" },
-        snapshotId: pending.snapshotId,
-        store,
-    });
+    const claimedSnapshotId = createPendingWriteSnapshotId();
+    const claimed = await store.claimIfSnapshotId(id, pending.snapshotId, {
+        ...pending,
+        error: undefined,
+        snapshotId: claimedSnapshotId,
+        syncingAt: now(),
+        syncStatus: "syncing",
+    }, now());
+    if (!claimed) {
+        return { status: "superseded" };
+    }
     try {
         await sync(pending.payload);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unable to sync pending write.";
-        await markPendingSnapshot({
+        const { syncingAt: _syncingAt, ...pendingWithoutSyncClaim } = pending;
+        const markedFailed = await markPendingSnapshot({
             id,
-            nextRecord: { ...pending, error: message, syncStatus: "failed" },
-            snapshotId: pending.snapshotId,
+            nextRecord: {
+                ...pendingWithoutSyncClaim,
+                error: message,
+                snapshotId: claimedSnapshotId,
+                syncStatus: "failed",
+            },
+            snapshotId: claimedSnapshotId,
             store,
         });
-        return { error: message, status: "failed" };
+        return markedFailed
+            ? { error: message, status: "failed" }
+            : { status: "superseded" };
     }
-    return (await store.clearIfSnapshotId(id, pending.snapshotId))
+    return (await store.clearIfSnapshotId(id, claimedSnapshotId))
         ? { status: "synced" }
         : { 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.
+ */
+function syncPendingWrites({ scopeKey = "all", select = () => true, 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;
+    }
+    const syncRun = performPendingWriteSync({
+        select,
+        stopOnFailure,
+        store,
+        sync,
+    });
+    inFlightByScope.set(scopeKey, syncRun);
+    const clearInFlight = () => {
+        inFlightByScope.delete(scopeKey);
+    };
+    void syncRun.then(clearInFlight, clearInFlight);
+    return syncRun;
+}
+/**
+ * Attempts a remote write now and persists a caller-created durable fallback
+ * only when offline or when the supplied retry classifier accepts the error.
+ */
+async function runPendingWrite({ enqueue, isOnline, shouldQueue, write, }) {
+    if (!isOnline()) {
+        return { queued: await enqueue(), status: "queued" };
+    }
+    try {
+        return { result: await write(), status: "synced" };
+    }
+    catch (error) {
+        if (!shouldQueue(error)) {
+            throw error;
+        }
+        return { queued: await enqueue(), status: "queued" };
+    }
+}
+function summarizePendingWrites(records) {
+    return records.reduce((summary, record) => {
+        summary.totalCount += 1;
+        if (record.syncStatus === "failed") {
+            summary.failedCount += 1;
+        }
+        else if (record.syncStatus === "syncing") {
+            summary.syncingCount += 1;
+        }
+        else {
+            summary.pendingCount += 1;
+        }
+        return summary;
+    }, { failedCount: 0, pendingCount: 0, syncingCount: 0, totalCount: 0 });
+}
+const pendingWriteSyncs = new WeakMap();
+async function performPendingWriteSync({ select, stopOnFailure, store, sync, }) {
+    const summary = {
+        attempted: 0,
+        failed: 0,
+        idle: 0,
+        remaining: 0,
+        superseded: 0,
+        synced: 0,
+    };
+    const records = (await store.list()).filter(select);
+    for (const record of records) {
+        const result = await syncPendingWrite({
+            id: record.id,
+            store,
+            sync,
+        });
+        summary.attempted += 1;
+        summary[result.status] += 1;
+        if (stopOnFailure && result.status === "failed") {
+            break;
+        }
+    }
+    summary.remaining = (await store.list()).filter(select).length;
+    return summary;
+}
+function isPendingWriteSyncClaimAvailable(record, now) {
+    if (record.syncStatus !== "syncing") {
+        return true;
+    }
+    if (!record.syncingAt) {
+        return true;
+    }
+    const startedAt = Date.parse(record.syncingAt);
+    const currentTime = Date.parse(now);
+    return (!Number.isFinite(startedAt) ||
+        !Number.isFinite(currentTime) ||
+        currentTime - startedAt >= exports.pendingWriteSyncLeaseTimeoutMs);
+}
+/**
+ * Creates a serial execution lane for a durable scope such as one user or
+ * 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, }) {
+    let execution = Promise.resolve();
+    function inOrder(operation) {
+        const result = execution.then(operation, operation);
+        execution = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    function recover() {
+        return inOrder(() => syncPendingWrites({
+            scopeKey,
+            select,
+            stopOnFailure: true,
+            store,
+            sync,
+        }));
+    }
+    return {
+        recover,
+        run(options) {
+            return inOrder(async () => {
+                if (!options.isOnline()) {
+                    return runPendingWrite(options);
+                }
+                const replay = await syncPendingWrites({
+                    scopeKey,
+                    select,
+                    stopOnFailure: true,
+                    store,
+                    sync,
+                });
+                // Product decision: unresolved older records retain their position in
+                // this scope. Queue the later write rather than letting it overtake a
+                // replay whose remote effect may be ambiguous.
+                if (replay.remaining > 0) {
+                    return { queued: await options.enqueue(), status: "queued" };
+                }
+                return runPendingWrite(options);
+            });
+        },
+    };
+}
 function createNoopPendingWriteDriver() {
     return {
         async clear() { },
@@ -208,6 +416,9 @@ function normalizePendingWriteRecord(record, normalizePayload) {
         payload,
         savedAt: record.savedAt,
         snapshotId: record.snapshotId ?? createLegacyPendingWriteSnapshotId(record),
+        ...(typeof record.syncingAt === "string"
+            ? { syncingAt: record.syncingAt }
+            : {}),
         syncStatus: record.syncStatus,
     };
 }
@@ -233,6 +444,7 @@ function isPendingWriteRecord(value) {
         "savedAt" in value &&
         typeof value.savedAt === "string" &&
         (!("snapshotId" in value) || typeof value.snapshotId === "string") &&
+        (!("syncingAt" in value) || typeof value.syncingAt === "string") &&
         "syncStatus" in value &&
         (value.syncStatus === "pending" ||
             value.syncStatus === "syncing" ||

package/dist-cjs/readCache.js

@@ -4,6 +4,7 @@ exports.browserReadCacheOperationTimeoutMs = exports.identityReadCacheFreshnessM
 exports.createReadCache = createReadCache;
 exports.createMemoryReadCacheDriver = createMemoryReadCacheDriver;
 exports.createBrowserReadCache = createBrowserReadCache;
+exports.pruneReadCache = pruneReadCache;
 exports.createReadCacheKey = createReadCacheKey;
 exports.readThroughCache = readThroughCache;
 exports.loadReadCacheResource = loadReadCacheResource;
@@ -14,6 +15,7 @@ exports.durableReadCacheFreshnessMaxAgeMs = 60 * 60_000;
 exports.identityReadCacheFreshnessMaxAgeMs = 24 * 60 * 60_000;
 exports.browserReadCacheOperationTimeoutMs = 2_000;
 const pendingFreshLoads = new WeakMap();
+const cachePruners = new WeakMap();
 function createReadCache(driver) {
     let globalVersion = 0;
     const keyVersions = new Map();
@@ -78,6 +80,21 @@ function createReadCache(driver) {
         },
     };
     pendingFreshLoads.set(cache, pendingLoads);
+    cachePruners.set(cache, async ({ maxAgeMs, now }) => {
+        if (!driver.listEntries || maxAgeMs < 0) {
+            return 0;
+        }
+        const cutoff = now() - maxAgeMs;
+        const expiredKeys = (await driver.listEntries())
+            .filter(({ value }) => {
+            const envelope = toReadCacheEnvelope(value);
+            const savedAt = envelope ? Date.parse(envelope.savedAt) : Number.NaN;
+            return Number.isFinite(savedAt) && savedAt < cutoff;
+        })
+            .map(({ key }) => key);
+        await Promise.all(expiredKeys.map((key) => cache.delete(key)));
+        return expiredKeys.length;
+    });
     return cache;
 }
 function createMemoryReadCacheDriver() {
@@ -93,6 +110,9 @@ function createMemoryReadCacheDriver() {
         async get(key) {
             return records.get(key) ?? null;
         },
+        async listEntries() {
+            return [...records.entries()].map(([key, value]) => ({ key, value }));
+        },
         async set(key, value) {
             records.set(key, value);
         },
@@ -106,7 +126,25 @@ function createBrowserReadCache({ databaseName, databaseVersion, indexedDB = glo
         operationTimeoutMs,
         storeName,
     });
-    return createReadCache(driver ?? createNoopReadCacheDriver());
+    return createReadCache(driver
+        ? {
+            clear: driver.clear,
+            close: driver.close,
+            delete: driver.delete,
+            get: driver.get,
+            listEntries: driver.listEntries,
+            set: driver.set,
+        }
+        : createNoopReadCacheDriver());
+}
+/**
+ * Deletes only valid read-cache envelopes older than the supplied age. It is
+ * opt-in and returns zero for custom cache adapters that cannot enumerate keys.
+ */
+function pruneReadCache({ cache, maxAgeMs, now = () => Date.now(), }) {
+    const resourceCache = cache.capture?.() ?? cache;
+    return cachePruners.get(resourceCache)?.({ maxAgeMs, now }) ??
+        Promise.resolve(0);
 }
 function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
     const serializedParams = Object.entries(params)
@@ -123,8 +161,13 @@ function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-async function readThroughCache({ cache, key, loadFresh, maxAgeMs, }) {
+async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, }) {
     const resourceCache = cache.capture?.() ?? cache;
+    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);
+    }
     const version = resourceCache.getVersion(key);
     const cached = await resourceCache.get(key);
     if (cached && isCacheFresh(cached.savedAt, maxAgeMs)) {
@@ -136,7 +179,7 @@ async function readThroughCache({ cache, key, loadFresh, maxAgeMs, }) {
         };
     }
     try {
-        const fresh = await loadFresh();
+        const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
         await resourceCache.setIfVersion(key, fresh, version);
         return {
             data: fresh,
@@ -200,6 +243,9 @@ function createNoopReadCacheDriver() {
         async get() {
             return null;
         },
+        async listEntries() {
+            return [];
+        },
         async set() { },
     };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.1.1",
-  "description": "Reusable offline read-cache and pending-write primitives.",
+  "version": "0.4.0",
+  "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",
   "homepage": "https://github.com/toledoroy/bounded/tree/main/packages/offline#readme",