@gonvex/client 0.5.2-staging.2 → 0.5.2-staging.20

package/dist/outbox.js

@@ -1,3 +1,11 @@
+/** Entries whose optimistic prediction is still part of the local overlay. */
+export function outboxEntryIsLive(entry) {
+    return entry.state !== "rejected";
+}
+/** Entries that still wait for delivery without user action. */
+export function outboxEntryIsQueued(entry) {
+    return entry.state === "pending" || entry.state === "inflight" || entry.state === "committed";
+}
 /**
  * A durable, totally ordered reducer queue.
  *
@@ -38,13 +46,17 @@ export class DexieReducerOutbox {
             idempotencyKey: reducer.idempotencyKey ?? createIdempotencyKey(),
             entityKeys: [...(reducer.entityKeys ?? [])],
             patches: reducer.patches?.map(clonePatch),
+            ...(reducer.localExecution ? { localExecution: cloneValue(reducer.localExecution) } : {}),
             createdAt,
             attempts: 0,
             nextAttemptAt: createdAt,
             state: reducer.state ?? "pending",
         };
-        if (this.memoryOnly)
+        if (this.memoryOnly) {
+            if (reducer.localExecution)
+                throw new Error("Durable storage is required for local reducer execution");
             return this.enqueueInMemory(entry);
+        }
         try {
             const database = await this.open();
             const id = await database.entries.add(entry);
@@ -53,7 +65,9 @@ export class DexieReducerOutbox {
             this.notify();
             return cloneEntry(stored);
         }
-        catch {
+        catch (error) {
+            if (reducer.localExecution)
+                throw new Error("Could not persist local reducer; no changes were staged", { cause: error });
             this.degradeToMemory();
             return this.enqueueInMemory(entry);
         }
@@ -86,6 +100,26 @@ export class DexieReducerOutbox {
             return this.loadAllFromMemory(scope);
         }
     }
+    async list(scope) {
+        if (this.memoryOnly)
+            return this.sortedMemoryEntries(scope).map(cloneEntry);
+        const entries = await (await this.open()).entries.where("scope").equals(scope).sortBy("id");
+        this.replaceMemoryEntriesForScope(scope, entries);
+        return entries.map(cloneEntry);
+    }
+    async updateLocal(id, patches, execution) {
+        if (this.memoryOnly)
+            throw new Error("Durable storage is required for local reducer replay");
+        const database = await this.open();
+        await database.transaction("rw", database.entries, async () => {
+            const entry = await database.entries.get(id);
+            if (!entry)
+                return;
+            const updated = { ...entry, patches: patches.map(clonePatch), localExecution: cloneValue(execution) };
+            await database.entries.put(updated);
+            this.remember(updated);
+        });
+    }
     async nextReady(scope, now) {
         if (this.memoryOnly)
             return cloneOptionalEntry(firstReady(this.sortedMemoryEntries(scope), now));
@@ -101,29 +135,8 @@ export class DexieReducerOutbox {
         }
     }
     async markInflight(id) {
-        if (this.memoryOnly) {
-            this.markInflightInMemory(id);
-            return;
-        }
-        try {
-            const database = await this.open();
-            let updated;
-            await database.transaction("rw", database.entries, async () => {
-                const entry = await database.entries.get(id);
-                if (!entry || entry.state === "inflight")
-                    return;
-                updated = { ...entry, state: "inflight" };
-                await database.entries.put(updated);
-            });
-            if (!updated)
-                return;
-            this.remember(updated);
-            this.notify();
-        }
-        catch {
-            this.degradeToMemory();
-            this.markInflightInMemory(id);
-        }
+        const { before, after } = await this.transition(id, markInflightChange);
+        return (after ?? before)?.state === "inflight";
     }
     async markPending(id) {
         if (this.memoryOnly) {
@@ -135,7 +148,7 @@ export class DexieReducerOutbox {
             let updated;
             await database.transaction("rw", database.entries, async () => {
                 const entry = await database.entries.get(id);
-                if (!entry || entry.state === "pending")
+                if (!entry || entry.state === "pending" || isParked(entry))
                     return;
                 updated = {
                     ...entry,
@@ -199,40 +212,45 @@ export class DexieReducerOutbox {
             this.ackInMemory(id);
         }
     }
-    async fail(id, error) {
-        if (this.memoryOnly) {
-            this.failInMemory(id, error);
-            return;
-        }
+    async fail(id, error, options = {}) {
+        const now = Date.now();
+        const { after } = await this.transition(id, (entry) => failChange(entry, error, now, options));
+        return after ?? undefined;
+    }
+    async reject(id, error) {
+        const now = Date.now();
+        const { after } = await this.transition(id, (entry) => rejectChange(entry, error, now));
+        return after ?? undefined;
+    }
+    async retry(id) {
+        const now = Date.now();
+        const { after } = await this.transition(id, (entry) => retryChange(entry, now));
+        return after ?? undefined;
+    }
+    async discard(id, states) {
+        const { before, after } = await this.transition(id, (entry) => (states.includes(entry.state) ? null : undefined));
+        return after === null ? before : undefined;
+    }
+    async listScopes() {
+        if (this.memoryOnly)
+            return summarizeScopes(this.sortedMemoryEntries());
         try {
-            const database = await this.open();
-            let updated;
-            await database.transaction("rw", database.entries, async () => {
-                const entry = await database.entries.get(id);
-                if (!entry)
-                    return;
-                updated = failedEntry(entry, error, Date.now());
-                await database.entries.put(updated);
-            });
-            if (!updated)
-                return;
-            this.remember(updated);
-            this.notify();
+            return summarizeScopes(await (await this.open()).entries.toArray());
         }
         catch {
             this.degradeToMemory();
-            this.failInMemory(id, error);
+            return summarizeScopes(this.sortedMemoryEntries());
         }
     }
     async count(scope) {
         if (this.memoryOnly)
-            return this.sortedMemoryEntries(scope).length;
+            return this.sortedMemoryEntries(scope).filter(outboxEntryIsQueued).length;
         try {
-            return await (await this.open()).entries.where("scope").equals(scope).count();
+            return await (await this.open()).entries.where("scope").equals(scope).filter(outboxEntryIsQueued).count();
         }
         catch {
             this.degradeToMemory();
-            return this.sortedMemoryEntries(scope).length;
+            return this.sortedMemoryEntries(scope).filter(outboxEntryIsQueued).length;
         }
     }
     async clear(scope) {
@@ -253,6 +271,27 @@ export class DexieReducerOutbox {
         }
         this.notify();
     }
+    async purgeScope(scope) {
+        let removed = 0;
+        for (const [id, entry] of this.memoryEntries) {
+            if (entry.scope !== scope)
+                continue;
+            this.memoryEntries.delete(id);
+            removed += 1;
+        }
+        if (!this.memoryOnly) {
+            try {
+                // Foreign scopes are never hydrated into memory, so delete by index.
+                removed = Math.max(removed, await (await this.open()).entries.where("scope").equals(scope).delete());
+            }
+            catch {
+                this.degradeToMemory();
+            }
+        }
+        if (removed > 0)
+            this.notify();
+        return removed;
+    }
     subscribe(listener) {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
@@ -277,16 +316,9 @@ export class DexieReducerOutbox {
             this.notify();
         return this.sortedMemoryEntries(scope).map(cloneEntry);
     }
-    markInflightInMemory(id) {
-        const entry = this.memoryEntries.get(id);
-        if (!entry || entry.state === "inflight")
-            return;
-        this.memoryEntries.set(id, { ...entry, state: "inflight" });
-        this.notify();
-    }
     markPendingInMemory(id) {
         const entry = this.memoryEntries.get(id);
-        if (!entry || entry.state === "pending")
+        if (!entry || entry.state === "pending" || isParked(entry))
             return;
         this.memoryEntries.set(id, {
             ...entry,
@@ -308,12 +340,53 @@ export class DexieReducerOutbox {
             return;
         this.notify();
     }
-    failInMemory(id, error) {
+    /**
+     * Apply one atomic read-modify-write. `change` returns the replacement,
+     * `null` to delete the entry, or `undefined` to leave it untouched.
+     */
+    async transition(id, change) {
+        if (this.memoryOnly)
+            return this.transitionInMemory(id, change);
+        try {
+            const database = await this.open();
+            let before;
+            let after;
+            await database.transaction("rw", database.entries, async () => {
+                const entry = await database.entries.get(id);
+                if (!entry)
+                    return;
+                before = entry;
+                after = change(cloneEntry(entry));
+                if (after === null)
+                    await database.entries.delete(id);
+                else if (after)
+                    await database.entries.put(after);
+            });
+            if (after === null)
+                this.memoryEntries.delete(id);
+            else if (after)
+                this.remember(after);
+            if (after !== undefined)
+                this.notify();
+            return { before: before && cloneEntry(before), after: after ? cloneEntry(after) : after };
+        }
+        catch {
+            this.degradeToMemory();
+            return this.transitionInMemory(id, change);
+        }
+    }
+    transitionInMemory(id, change) {
         const entry = this.memoryEntries.get(id);
         if (!entry)
-            return;
-        this.memoryEntries.set(id, failedEntry(entry, error, Date.now()));
-        this.notify();
+            return {};
+        const after = change(cloneEntry(entry));
+        if (after === null)
+            this.memoryEntries.delete(id);
+        else if (after)
+            this.memoryEntries.set(id, cloneEntry(after));
+        if (after !== undefined)
+            this.notify();
+        return { before: cloneEntry(entry), after: after ? cloneEntry(after) : after };
     }
     sortedMemoryEntries(scope) {
         return [...this.memoryEntries.values()]
@@ -405,31 +478,47 @@ export class StoreReducerOutbox {
     constructor(store, options = {}) {
         this.store = store;
         this.memoryOnly = options.enabled === false;
-        this.ready = this.memoryOnly ? Promise.resolve() : this.hydrate();
+        this.ready = this.memoryOnly || store.shared ? Promise.resolve() : this.hydrate();
     }
     async enqueue(reducer) {
         await this.ready;
         const createdAt = Date.now();
-        const entry = {
-            id: this.nextId++,
+        const draft = {
             scope: reducer.scope,
             path: reducer.path,
             args: cloneValue(reducer.args),
             idempotencyKey: reducer.idempotencyKey ?? createIdempotencyKey(),
             entityKeys: [...(reducer.entityKeys ?? [])],
             patches: reducer.patches?.map(clonePatch),
+            ...(reducer.localExecution ? { localExecution: cloneValue(reducer.localExecution) } : {}),
             createdAt,
             attempts: 0,
             nextAttemptAt: createdAt,
             state: reducer.state ?? "pending",
         };
+        let entry;
+        if (reducer.localExecution && this.memoryOnly)
+            throw new Error("Durable storage is required for local reducer execution");
+        if (reducer.localExecution && this.store.append) {
+            entry = await this.store.append(draft);
+        }
+        else {
+            entry = { ...draft, id: this.store.allocateId ? await this.store.allocateId() : this.nextId++ };
+            if (reducer.localExecution)
+                await this.store.put(cloneEntry(entry));
+            else
+                await this.persistPut(entry);
+        }
         this.entries.set(entry.id, entry);
-        await this.persistPut(entry);
         this.notify();
         return cloneEntry(entry);
     }
     async loadAll(scope) {
         await this.ready;
+        await this.refreshShared(scope);
+        // Only the holder of the cross-tab delivery lock may recover inflight work.
+        if (this.store.shared)
+            return this.sortedEntries(scope).map(cloneEntry);
         const recovered = [];
         for (const [id, entry] of this.entries) {
             if (entry.scope !== scope || entry.state !== "inflight")
@@ -443,24 +532,45 @@ export class StoreReducerOutbox {
             this.notify();
         return this.sortedEntries(scope).map(cloneEntry);
     }
-    async nextReady(scope, now) {
+    async list(scope) {
         await this.ready;
-        return cloneOptionalEntry(firstReady(this.sortedEntries(scope), now));
+        await this.refreshShared(scope);
+        return this.sortedEntries(scope).map(cloneEntry);
     }
-    async markInflight(id) {
+    async updateLocal(id, patches, execution) {
         await this.ready;
+        if (this.memoryOnly)
+            throw new Error("Durable storage is required for local reducer replay");
+        if (this.store.update) {
+            await this.updateShared(id, entry => ({ ...entry, patches: patches.map(clonePatch), localExecution: cloneValue(execution) }));
+            return;
+        }
         const entry = this.entries.get(id);
-        if (!entry || entry.state === "inflight")
+        if (!entry)
             return;
-        const updated = { ...entry, state: "inflight" };
+        const updated = { ...entry, patches: patches.map(clonePatch), localExecution: cloneValue(execution) };
+        await this.store.put(cloneEntry(updated));
         this.entries.set(id, updated);
-        await this.persistPut(updated);
-        this.notify();
+    }
+    async nextReady(scope, now) {
+        await this.ready;
+        await this.refreshShared(scope);
+        return cloneOptionalEntry(firstReady(this.sortedEntries(scope), now));
+    }
+    async markInflight(id) {
+        await this.ready;
+        const { before, after } = await this.transition(id, markInflightChange);
+        return (after ?? before)?.state === "inflight";
     }
     async markPending(id) {
         await this.ready;
+        if (this.store.update) {
+            await this.updateShared(id, entry => isParked(entry) ? entry : ({ ...entry, state: 'pending', nextAttemptAt: Date.now(), lastError: undefined }));
+            this.notify();
+            return;
+        }
         const entry = this.entries.get(id);
-        if (!entry || entry.state === "pending")
+        if (!entry || entry.state === "pending" || isParked(entry))
             return;
         const updated = {
             ...entry,
@@ -474,6 +584,11 @@ export class StoreReducerOutbox {
     }
     async markCommitted(id) {
         await this.ready;
+        if (this.store.update) {
+            await this.updateShared(id, entry => ({ ...entry, state: 'committed' }));
+            this.notify();
+            return;
+        }
         const entry = this.entries.get(id);
         if (!entry || entry.state === "committed")
             return;
@@ -484,27 +599,48 @@ export class StoreReducerOutbox {
     }
     async ack(id) {
         await this.ready;
-        if (!this.entries.delete(id))
+        if (!this.entries.delete(id) && !this.store.shared)
             return;
         await this.persistDelete(id);
         this.notify();
     }
-    async fail(id, error) {
+    async fail(id, error, options = {}) {
         await this.ready;
-        const entry = this.entries.get(id);
-        if (!entry)
-            return;
-        const updated = failedEntry(entry, error, Date.now());
-        this.entries.set(id, updated);
-        await this.persistPut(updated);
-        this.notify();
+        const now = Date.now();
+        const { after } = await this.transition(id, (entry) => failChange(entry, error, now, options));
+        return after ?? undefined;
+    }
+    async reject(id, error) {
+        await this.ready;
+        const now = Date.now();
+        const { after } = await this.transition(id, (entry) => rejectChange(entry, error, now));
+        return after ?? undefined;
+    }
+    async retry(id) {
+        await this.ready;
+        const now = Date.now();
+        const { after } = await this.transition(id, (entry) => retryChange(entry, now));
+        return after ?? undefined;
+    }
+    async discard(id, states) {
+        await this.ready;
+        const { before, after } = await this.transition(id, (entry) => (states.includes(entry.state) ? null : undefined));
+        return after === null ? before : undefined;
+    }
+    async listScopes() {
+        await this.ready;
+        if (this.store.shared && !this.memoryOnly)
+            return summarizeScopes(await this.store.load());
+        return summarizeScopes([...this.entries.values()]);
     }
     async count(scope) {
         await this.ready;
-        return this.sortedEntries(scope).length;
+        await this.refreshShared(scope);
+        return this.sortedEntries(scope).filter(outboxEntryIsQueued).length;
     }
     async clear(scope) {
         await this.ready;
+        await this.refreshShared(scope);
         // Delete by snapshotted id, never scope-wide, so an enqueue racing this
         // clear is not swallowed by a later store delete.
         const ids = [];
@@ -517,10 +653,104 @@ export class StoreReducerOutbox {
         await Promise.all(ids.map((id) => this.persistDelete(id)));
         this.notify();
     }
+    async purgeScope(scope) {
+        await this.ready;
+        const persisted = this.store.shared && !this.memoryOnly ? await this.store.load(scope) : [];
+        const ids = new Set(persisted.filter((entry) => entry.scope === scope).map((entry) => entry.id));
+        for (const [id, entry] of this.entries) {
+            if (entry.scope !== scope)
+                continue;
+            this.entries.delete(id);
+            ids.add(id);
+        }
+        if (!this.memoryOnly) {
+            try {
+                await this.store.clear(scope);
+            }
+            catch (error) {
+                if (this.store.strictPersistence)
+                    throw error;
+                this.degradeToMemory();
+            }
+        }
+        if (ids.size > 0)
+            this.notify();
+        return ids.size;
+    }
     subscribe(listener) {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
     }
+    async recoverInflight(scope) {
+        await this.ready;
+        await this.refreshShared(scope);
+        for (const entry of this.sortedEntries(scope))
+            if (entry.state === 'inflight')
+                await this.markPending(entry.id);
+    }
+    async refreshShared(scope) {
+        if (!this.store.shared || this.memoryOnly)
+            return;
+        const entries = await this.store.load(scope);
+        this.entries.clear();
+        for (const entry of entries)
+            this.entries.set(entry.id, cloneEntry(entry));
+    }
+    /**
+     * Apply one atomic read-modify-write. `change` returns the replacement,
+     * `null` to delete the entry, or `undefined` to leave it untouched.
+     * Shared stores run the decision inside their own transaction so another
+     * tab's delivery cannot interleave; a deletion first fences the entry as
+     * `rejected` (never sendable), then removes it.
+     */
+    async transition(id, change) {
+        if (this.store.update && !this.memoryOnly) {
+            let before;
+            let decided;
+            const stored = await this.store.update(id, (entry) => {
+                before = cloneEntry(entry);
+                decided = change(cloneEntry(entry));
+                if (decided === undefined)
+                    return entry;
+                if (decided === null)
+                    return { ...entry, state: "rejected", lastError: entry.lastError ?? "Discarded" };
+                return decided;
+            });
+            if (decided === null) {
+                this.entries.delete(id);
+                await this.persistDelete(id);
+            }
+            else if (stored)
+                this.entries.set(id, cloneEntry(stored));
+            else
+                this.entries.delete(id);
+            if (decided !== undefined)
+                this.notify();
+            return { before, after: decided === null ? null : decided === undefined ? undefined : stored && cloneEntry(stored) };
+        }
+        const entry = this.entries.get(id);
+        if (!entry)
+            return {};
+        const after = change(cloneEntry(entry));
+        if (after === null) {
+            this.entries.delete(id);
+            await this.persistDelete(id);
+        }
+        else if (after) {
+            this.entries.set(id, after);
+            await this.persistPut(after);
+        }
+        if (after !== undefined)
+            this.notify();
+        return { before: cloneEntry(entry), after: after ? cloneEntry(after) : after };
+    }
+    async updateShared(id, change) {
+        const entry = await this.store.update(id, change);
+        if (entry)
+            this.entries.set(id, cloneEntry(entry));
+        else
+            this.entries.delete(id);
+    }
     async hydrate() {
         try {
             for (const entry of await this.store.load()) {
@@ -528,7 +758,9 @@ export class StoreReducerOutbox {
                 this.nextId = Math.max(this.nextId, entry.id + 1);
             }
         }
-        catch {
+        catch (error) {
+            if (this.store.strictPersistence)
+                throw error;
             this.degradeToMemory();
         }
     }
@@ -538,7 +770,9 @@ export class StoreReducerOutbox {
         try {
             await this.store.put(cloneEntry(entry));
         }
-        catch {
+        catch (error) {
+            if (this.store.strictPersistence)
+                throw error;
             this.degradeToMemory();
         }
     }
@@ -548,7 +782,9 @@ export class StoreReducerOutbox {
         try {
             await this.store.delete(id);
         }
-        catch {
+        catch (error) {
+            if (this.store.strictPersistence)
+                throw error;
             this.degradeToMemory();
         }
     }
@@ -590,6 +826,11 @@ function firstReady(entries, now) {
         // a newer pending write to the same entity.
         if (entry.state === "committed")
             continue;
+        // Parked (failed) and rejected records wait for the app, not the server.
+        // They must not hold every later intent hostage. Later intents that truly
+        // depended on them are validated by the server and rejected on their own.
+        if (entry.state === "failed" || entry.state === "rejected")
+            continue;
         if (entry.state === "pending"
             && entry.nextAttemptAt <= now
             && !entry.entityKeys.some((key) => blockedEntityKeys.has(key))) {
@@ -600,16 +841,76 @@ function firstReady(entries, now) {
     }
     return undefined;
 }
-function failedEntry(entry, error, now) {
-    const attempts = entry.attempts + 1;
+export const DEFAULT_OUTBOX_MAX_BACKOFF_MS = 30_000;
+/** Exponential backoff after `attempts` counted failures. */
+export function outboxBackoffMs(attempts, maxBackoffMs = DEFAULT_OUTBOX_MAX_BACKOFF_MS) {
+    return Math.min(maxBackoffMs, 1_000 * (2 ** Math.min(attempts, 30)));
+}
+function failedEntry(entry, error, now, options = {}) {
+    const counted = options.countAttempt !== false;
+    const attempts = counted ? entry.attempts + 1 : entry.attempts;
+    const park = counted
+        && options.maxAttempts !== undefined
+        && attempts >= options.maxAttempts;
     return {
         ...entry,
         attempts,
-        state: "pending",
-        nextAttemptAt: now + Math.min(30_000, 1_000 * (2 ** attempts)),
+        state: park ? "failed" : "pending",
+        nextAttemptAt: now + (options.delayMs ?? outboxBackoffMs(attempts, options.maxBackoffMs)),
+        lastError: error,
+        ...(options.errorClass ? { lastErrorClass: options.errorClass } : {}),
+        ...(park ? { settledAt: now } : {}),
+    };
+}
+/** Failed and rejected records leave their state only through retry(). */
+function isParked(entry) {
+    return entry.state === "failed" || entry.state === "rejected";
+}
+function markInflightChange(entry) {
+    // A parked or rejected record only leaves its state through retry().
+    if (entry.state === "inflight" || entry.state === "failed" || entry.state === "rejected")
+        return undefined;
+    return { ...entry, state: "inflight" };
+}
+function failChange(entry, error, now, options) {
+    // A concurrent discard/reject/commit already decided this entry's fate.
+    if (isParked(entry) || entry.state === "committed")
+        return undefined;
+    return failedEntry(entry, error, now, options);
+}
+function rejectChange(entry, error, now) {
+    return {
+        ...entry,
+        state: "rejected",
         lastError: error,
+        lastErrorClass: "rejected",
+        nextAttemptAt: now,
+        settledAt: now,
     };
 }
+function retryChange(entry, now) {
+    if (entry.state !== "failed" && entry.state !== "rejected")
+        return undefined;
+    const { lastError: _error, lastErrorClass: _class, settledAt: _settled, ...rest } = entry;
+    // Same id, same idempotency key: the server replays instead of re-applying
+    // if an earlier attempt did commit before its response was lost.
+    return { ...rest, state: "pending", attempts: 0, nextAttemptAt: now };
+}
+function summarizeScopes(entries) {
+    const scopes = new Map();
+    for (const entry of entries) {
+        if (typeof entry.scope !== "string")
+            continue;
+        const summary = scopes.get(entry.scope);
+        if (summary) {
+            summary.count += 1;
+            summary.oldestCreatedAt = Math.min(summary.oldestCreatedAt, entry.createdAt);
+        }
+        else
+            scopes.set(entry.scope, { scope: entry.scope, count: 1, oldestCreatedAt: entry.createdAt });
+    }
+    return [...scopes.values()].sort((left, right) => left.oldestCreatedAt - right.oldestCreatedAt);
+}
 function createIdempotencyKey() {
     if (globalThis.crypto?.randomUUID)
         return globalThis.crypto.randomUUID();
@@ -621,6 +922,7 @@ function cloneEntry(entry) {
         args: cloneValue(entry.args),
         entityKeys: [...entry.entityKeys],
         patches: entry.patches?.map(clonePatch),
+        ...(entry.localExecution ? { localExecution: cloneValue(entry.localExecution) } : {}),
     };
 }
 function cloneOptionalEntry(entry) {