@bayonai/offline 0.1.0 → 0.3.0

package/dist/pendingWrites.d.ts

@@ -7,28 +7,55 @@ export type PendingWriteRecord<Payload = unknown> = {
     id: string;
     payload: Payload;
     savedAt: string;
+    snapshotId: string;
     syncStatus: PendingWriteStatus;
 };
+export type PendingWriteRecordInput<Payload = unknown> = Omit<PendingWriteRecord<Payload>, "snapshotId"> & {
+    snapshotId?: string;
+};
 export type PendingWritePayloadNormalizer<Payload = unknown> = (payload: unknown) => Payload | null;
 export type PendingWriteDriver = {
     clear: (key: string) => Promise<void>;
+    clearIf: (key: string, predicate: PendingWritePredicate) => Promise<boolean>;
     clearAll: () => Promise<void>;
     close?: () => Promise<void>;
     get: (key: string) => Promise<unknown | null>;
     list: () => Promise<unknown[]>;
     set: (key: string, value: unknown) => Promise<void>;
+    setIf: (key: string, value: unknown, predicate: PendingWritePredicate) => Promise<boolean>;
+};
+export type PendingWritePredicate = (value: unknown | null) => boolean;
+export type PendingWriteStoreChange<Payload = unknown> = {
+    record: PendingWriteRecord<Payload>;
+    type: "set";
+} | {
+    id: string;
+    type: "clear";
+} | {
+    type: "clearAll";
+} | {
+    record: PendingWriteRecord<Payload>;
+    type: "replace";
 };
+export type PendingWriteStoreChangeListener<Payload = unknown> = (change: PendingWriteStoreChange<Payload>) => void;
 export type PendingWriteStore<Payload = unknown> = {
     clear: (id: string) => Promise<void>;
     clearAll: () => Promise<void>;
-    clearIfSavedAt: (id: string, savedAt: string) => Promise<boolean>;
+    clearIfSnapshotId: (id: string, snapshotId: string) => Promise<boolean>;
     close: () => Promise<void>;
     get: (id: string) => Promise<PendingWriteRecord<Payload> | null>;
     list: () => Promise<Array<PendingWriteRecord<Payload>>>;
-    set: (record: PendingWriteRecord<Payload>) => Promise<void>;
+    replaceIfSnapshotId: (id: string, snapshotId: string, record: PendingWriteRecord<Payload>) => Promise<boolean>;
+    set: (record: PendingWriteRecordInput<Payload>) => Promise<PendingWriteRecord<Payload>>;
+    /**
+     * Observes changes made through this in-memory store instance. It deliberately
+     * does not claim cross-tab/process delivery.
+     */
+    subscribe: (listener: PendingWriteStoreChangeListener<Payload>) => () => void;
 };
 export type PendingWriteStoreOptions<Payload = unknown> = {
     keyPrefix: string;
+    normalizeLegacyRecord?: PendingWritePayloadNormalizer<PendingWriteRecordInput<Payload>>;
     normalizePayload?: PendingWritePayloadNormalizer<Payload>;
     schemaVersion?: number;
 };
@@ -51,13 +78,59 @@ export type SyncPendingWriteResult = {
     error: string;
     status: "failed";
 };
-export declare function createPendingWriteStore<Payload = unknown>(driver: PendingWriteDriver, { keyPrefix, normalizePayload, schemaVersion, }: PendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
+export type SyncPendingWritesResult = {
+    attempted: number;
+    failed: number;
+    idle: number;
+    /** Records still selected after this attempt, including newer superseding writes. */
+    remaining: number;
+    superseded: number;
+    synced: number;
+};
+export type PendingWriteSync<Payload> = (payload: Payload) => Promise<unknown>;
+export type RunPendingWriteResult<TResult, TQueued> = {
+    result: TResult;
+    status: "synced";
+} | {
+    queued: TQueued;
+    status: "queued";
+};
+export type PendingWriteSummary = {
+    failedCount: number;
+    pendingCount: number;
+    syncingCount: number;
+    totalCount: number;
+};
+export declare function createPendingWriteStore<Payload = unknown>(driver: PendingWriteDriver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion, }: PendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
 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, normalizePayload, operationTimeoutMs, schemaVersion, storeName, }: BrowserPendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
+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 syncPendingWrite<Payload>({ id, store, sync, }: {
     id: string;
     store: PendingWriteStore<Payload>;
-    sync: (payload: Payload) => Promise<unknown>;
+    sync: PendingWriteSync<Payload>;
 }): Promise<SyncPendingWriteResult>;
+/**
+ * Replays selected writes oldest first and coalesces overlapping runs for the
+ * same store/scope. Callers own the selection predicate and idempotent remote
+ * mutation semantics.
+ */
+export declare function syncPendingWrites<Payload>({ scopeKey, select, store, sync, }: {
+    scopeKey?: string;
+    select?: (record: PendingWriteRecord<Payload>) => boolean;
+    store: PendingWriteStore<Payload>;
+    sync: PendingWriteSync<Payload>;
+}): Promise<SyncPendingWritesResult>;
+/**
+ * Attempts a remote write now and persists a caller-created durable fallback
+ * only when offline or when the supplied retry classifier accepts the error.
+ */
+export declare function runPendingWrite<TResult, TQueued>({ enqueue, isOnline, shouldQueue, write, }: {
+    enqueue: () => Promise<TQueued>;
+    isOnline: () => boolean;
+    shouldQueue: (error: unknown) => boolean;
+    write: () => Promise<TResult>;
+}): Promise<RunPendingWriteResult<TResult, TQueued>>;
+export declare function summarizePendingWrites<Payload>(records: Array<PendingWriteRecord<Payload>>): PendingWriteSummary;

package/dist/pendingWrites.js

@@ -1,41 +1,81 @@
 import { createIdbKeyValueDriver, } from "./idbDriver.js";
 export const pendingWriteSchemaVersion = 1;
 export const pendingWriteOperationTimeoutMs = 2_000;
-export function createPendingWriteStore(driver, { keyPrefix, normalizePayload, schemaVersion = pendingWriteSchemaVersion, }) {
+export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion = 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 clearIfSavedAt(id, savedAt) {
-            const current = await this.get(id);
-            if (!current || current.savedAt !== savedAt) {
-                return false;
+        async clearIfSnapshotId(id, snapshotId) {
+            const cleared = await driver.clearIf(createPendingWriteKey({ id, prefix: keyPrefix }), (value) => toPendingWriteEnvelope(value, schemaVersion, {
+                normalizeLegacyRecord,
+                normalizePayload,
+            })?.record.snapshotId === snapshotId);
+            if (cleared) {
+                notify({ id, type: "clear" });
             }
-            await this.clear(id);
-            return true;
+            return cleared;
         },
         async close() {
             await driver.close?.();
         },
         async get(id) {
-            return (toPendingWriteEnvelope(await driver.get(createPendingWriteKey({ id, prefix: keyPrefix })), schemaVersion, { normalizePayload })?.record ?? null);
+            return (toPendingWriteEnvelope(await driver.get(createPendingWriteKey({ id, prefix: keyPrefix })), schemaVersion, { normalizeLegacyRecord, normalizePayload })?.record ?? null);
         },
         async list() {
             return (await driver.list())
                 .map((value) => toPendingWriteEnvelope(value, schemaVersion, {
+                normalizeLegacyRecord,
                 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) {
+            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 = {
+                ...record,
+                snapshotId: record.snapshotId ?? createPendingWriteSnapshotId(),
+            };
             await driver.set(createPendingWriteKey({ id: record.id, prefix: keyPrefix }), {
-                record,
+                record: storedRecord,
                 schemaVersion,
             });
+            notify({ record: storedRecord, type: "set" });
+            return storedRecord;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
         },
     };
 }
@@ -45,6 +85,14 @@ export function createMemoryPendingWriteDriver() {
         async clear(key) {
             records.delete(key);
         },
+        async clearIf(key, predicate) {
+            const current = records.get(key) ?? null;
+            if (!predicate(current)) {
+                return false;
+            }
+            records.delete(key);
+            return true;
+        },
         async clearAll() {
             records.clear();
         },
@@ -58,6 +106,13 @@ export function createMemoryPendingWriteDriver() {
         async set(key, value) {
             records.set(key, value);
         },
+        async setIf(key, value, predicate) {
+            if (!predicate(records.get(key) ?? null)) {
+                return false;
+            }
+            records.set(key, value);
+            return true;
+        },
     };
 }
 export function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, operationTimeoutMs = pendingWriteOperationTimeoutMs, storeName, }) {
@@ -70,7 +125,7 @@ export function createBrowserPendingWriteDriver({ databaseName, databaseVersion,
     });
     return driver ? toPendingWriteDriver(driver) : null;
 }
-export function createBrowserPendingWriteStore({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, keyPrefix, normalizePayload, operationTimeoutMs = pendingWriteOperationTimeoutMs, schemaVersion = pendingWriteSchemaVersion, storeName, }) {
+export function createBrowserPendingWriteStore({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, keyPrefix, normalizeLegacyRecord, normalizePayload, operationTimeoutMs = pendingWriteOperationTimeoutMs, schemaVersion = pendingWriteSchemaVersion, storeName, }) {
     const driver = createBrowserPendingWriteDriver({
         databaseName,
         databaseVersion,
@@ -78,11 +133,14 @@ export function createBrowserPendingWriteStore({ databaseName, databaseVersion,
         operationTimeoutMs,
         storeName,
     });
-    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizePayload, schemaVersion });
+    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion });
 }
 export function createPendingWriteKey({ id, prefix }) {
     return `${prefix}:${encodeURIComponent(id)}`;
 }
+export function createPendingWriteSnapshotId() {
+    return globalThis.crypto.randomUUID();
+}
 export async function syncPendingWrite({ id, store, sync, }) {
     const pending = await store.get(id);
     if (!pending) {
@@ -91,7 +149,7 @@ export async function syncPendingWrite({ id, store, sync, }) {
     await markPendingSnapshot({
         id,
         nextRecord: { ...pending, error: undefined, syncStatus: "syncing" },
-        savedAt: pending.savedAt,
+        snapshotId: pending.snapshotId,
         store,
     });
     try {
@@ -102,18 +160,100 @@ export async function syncPendingWrite({ id, store, sync, }) {
         await markPendingSnapshot({
             id,
             nextRecord: { ...pending, error: message, syncStatus: "failed" },
-            savedAt: pending.savedAt,
+            snapshotId: pending.snapshotId,
             store,
         });
         return { error: message, status: "failed" };
     }
-    return (await store.clearIfSavedAt(id, pending.savedAt))
+    return (await store.clearIfSnapshotId(id, pending.snapshotId))
         ? { 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.
+ */
+export 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.
+ */
+export 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" };
+    }
+}
+export 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() { },
+        async clearIf() {
+            return false;
+        },
         async clearAll() { },
         async close() { },
         async get() {
@@ -123,43 +263,41 @@ function createNoopPendingWriteDriver() {
             return [];
         },
         async set() { },
+        async setIf() {
+            return false;
+        },
     };
 }
 function toPendingWriteDriver(driver) {
     return {
         clear: driver.delete,
+        clearIf: driver.deleteIf,
         clearAll: driver.clear,
         close: driver.close,
         get: driver.get,
         list: driver.list,
         set: driver.set,
+        setIf: driver.setIf,
     };
 }
-async function markPendingSnapshot({ id, nextRecord, savedAt, store, }) {
-    const current = await store.get(id);
-    if (current?.savedAt !== savedAt) {
-        return false;
-    }
-    await store.set(nextRecord);
-    return true;
+async function markPendingSnapshot({ id, nextRecord, snapshotId, store, }) {
+    return store.replaceIfSnapshotId(id, snapshotId, nextRecord);
 }
-function toPendingWriteEnvelope(value, schemaVersion, { normalizePayload }) {
-    if (!value ||
-        typeof value !== "object" ||
-        !("schemaVersion" in value) ||
-        value.schemaVersion !== schemaVersion ||
-        !("record" in value) ||
-        !isPendingWriteRecord(value.record)) {
-        return null;
-    }
-    const record = normalizePendingWriteRecord(value.record, normalizePayload);
+function toPendingWriteEnvelope(value, schemaVersion, { normalizeLegacyRecord, normalizePayload }) {
+    const envelopeRecord = readPendingWriteEnvelopeRecord(value, schemaVersion);
+    const legacyRecord = envelopeRecord
+        ? null
+        : (normalizeLegacyRecord?.(value) ?? null);
+    const record = normalizePendingWriteRecord(envelopeRecord ?? legacyRecord, normalizePayload);
     return record ? { record, schemaVersion } : null;
 }
 function normalizePendingWriteRecord(record, normalizePayload) {
-    if (!normalizePayload) {
-        return record;
+    if (!record) {
+        return null;
     }
-    const payload = normalizePayload(record.payload);
+    const payload = normalizePayload
+        ? normalizePayload(record.payload)
+        : record.payload;
     if (payload === null) {
         return null;
     }
@@ -168,9 +306,24 @@ function normalizePendingWriteRecord(record, normalizePayload) {
         id: record.id,
         payload,
         savedAt: record.savedAt,
+        snapshotId: record.snapshotId ?? createLegacyPendingWriteSnapshotId(record),
         syncStatus: record.syncStatus,
     };
 }
+function readPendingWriteEnvelopeRecord(value, schemaVersion) {
+    if (!value ||
+        typeof value !== "object" ||
+        !("schemaVersion" in value) ||
+        value.schemaVersion !== schemaVersion ||
+        !("record" in value) ||
+        !isPendingWriteRecord(value.record)) {
+        return null;
+    }
+    return value.record;
+}
+function createLegacyPendingWriteSnapshotId(record) {
+    return `legacy:${encodeURIComponent(record.id)}:${encodeURIComponent(record.savedAt)}`;
+}
 function isPendingWriteRecord(value) {
     return (value !== null &&
         typeof value === "object" &&
@@ -178,6 +331,7 @@ function isPendingWriteRecord(value) {
         typeof value.id === "string" &&
         "savedAt" in value &&
         typeof value.savedAt === "string" &&
+        (!("snapshotId" in value) || typeof value.snapshotId === "string") &&
         "syncStatus" in value &&
         (value.syncStatus === "pending" ||
             value.syncStatus === "syncing" ||

package/dist/readCache.d.ts

@@ -1,6 +1,8 @@
 import { type BrowserKeyValueDriverOptions } from "./idbDriver";
 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 type ReadCacheHit<T> = {
     fromCache: true;
@@ -10,14 +12,27 @@ export type ReadCacheHit<T> = {
 export type ReadCacheDriver = {
     clear: () => Promise<void>;
     close?: () => Promise<void>;
+    delete: (key: string) => Promise<void>;
     get: (key: string) => Promise<unknown | null>;
+    listEntries?: () => Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
     set: (key: string, value: unknown) => Promise<void>;
 };
 export type ReadCache = {
+    /**
+     * Resolves a stable cache for the duration of a resource load. Dynamic
+     * adapters use this to pin the active account before asynchronous work.
+     */
+    capture?: () => ReadCache;
     clear: () => Promise<void>;
     close: () => Promise<void>;
+    delete: (key: string) => Promise<void>;
     get: <T>(key: string) => Promise<ReadCacheHit<T> | null>;
+    getVersion: (key: string) => string;
     set: <T>(key: string, value: T) => Promise<void>;
+    setIfVersion: <T>(key: string, value: T, version: string) => Promise<boolean>;
 };
 export type ReadThroughCacheResult<T> = {
     data: T;
@@ -44,16 +59,33 @@ export type ReadCacheKeyOptions = {
 export declare function createReadCache(driver: ReadCacheDriver): ReadCache;
 export declare function createMemoryReadCacheDriver(): ReadCacheDriver;
 export declare function createBrowserReadCache({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: BrowserReadCacheOptions): ReadCache;
+/**
+ * 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.
+ */
+export declare function pruneReadCache({ cache, maxAgeMs, now, }: {
+    cache: ReadCache;
+    maxAgeMs: number;
+    now?: () => number;
+}): Promise<number>;
 export declare function createReadCacheKey({ namespace, params, prefix, scope, }: ReadCacheKeyOptions): string;
-export declare function readThroughCache<T>({ cache, key, loadFresh, }: {
+export declare function readThroughCache<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, }: {
     cache: ReadCache;
+    /**
+     * Invalidates the current value before loading. Use after a successful write
+     * when a cached or earlier in-flight response must not become authoritative.
+     */
+    forceFresh?: boolean;
     key: string;
     loadFresh: () => Promise<T>;
+    maxAgeMs?: number;
 }): Promise<ReadThroughCacheResult<T>>;
-export declare function loadReadCacheResource<T>({ cache, key, loadFresh, maxAgeMs, onUpdate, }: {
+export declare function loadReadCacheResource<T>({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache, }: {
     cache: ReadCache;
     key: string;
     loadFresh: () => Promise<T>;
     maxAgeMs?: number;
+    onCacheWriteError?: (error: Error) => void;
     onUpdate: (update: ReadCacheResourceUpdate<T>) => void;
+    skipCache?: boolean;
 }): Promise<T>;