@bayonai/offline 0.1.1 → 0.3.0

package/dist-cjs/pendingWrites.js

@@ -8,22 +8,45 @@ exports.createBrowserPendingWriteStore = createBrowserPendingWriteStore;
 exports.createPendingWriteKey = createPendingWriteKey;
 exports.createPendingWriteSnapshotId = createPendingWriteSnapshotId;
 exports.syncPendingWrite = syncPendingWrite;
+exports.syncPendingWrites = syncPendingWrites;
+exports.runPendingWrite = runPendingWrite;
+exports.summarizePendingWrites = summarizePendingWrites;
 const idbDriver_1 = require("./idbDriver");
 exports.pendingWriteSchemaVersion = 1;
 exports.pendingWriteOperationTimeoutMs = 2_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 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 +61,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 +83,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() {
@@ -149,6 +182,85 @@ async function syncPendingWrite({ id, store, sync, }) {
         ? { 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, 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, 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, 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;
+    }
+    summary.remaining = (await store.list()).filter(select).length;
+    return summary;
+}
 function createNoopPendingWriteDriver() {
     return {
         async clear() { },

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.3.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",