@procedures/store 0.14.0 → 0.15.0

package/dist/storage/hybrid.js

@@ -15,6 +15,9 @@
  * - The queue is durable through the `queueStore` that the application gives.
  * - A sync asks for the changes since a version when the remote has `getChangesSince`.
  * - With `versionOf`, a conflict is a change on both sides, and `conflictResolution` decides.
+ * - With `versionOf`, the push of a queued write sends its base version as `expectedVersion`
+ *   (roadmap CLI-16). A `VERSION_CONFLICT` of the remote goes to `conflictResolution`, as a
+ *   conflict of a pull does. The option `sendBaseVersions: false` stops it.
  * - `pullInterval` keeps the local copy fresh.
  * - Each write takes a copy of the value (`structuredClone`), for the local copy, the queue and the
  *   remote. The reads give the copies of the local copy, or of the remote in `remote-only` mode.
@@ -40,8 +43,8 @@
  *   remote delta and a full sync never run at the same time (Graph R18).
  */
 import { InMemoryStorage, StorageListeners } from "@procedures/collections";
-import { queryEntries, queryOptionsProblems, selectorProblems, } from "@procedures/client/query";
-import { optionalMs, realClock } from "@procedures/client";
+import { queryEntries, queryOptionsProblems, selectorProblems, versionConflictsOf, } from "@procedures/client/query";
+import { optionalMs, realClock } from "@procedures/client/browser";
 import { backoffDelay } from "@mark1russell7/service/backoff";
 import { MemoryQueueStore, idsOf, withoutId } from "./queue.js";
 import { isSyncState } from "./sync-state.js";
@@ -233,6 +236,15 @@ function checkMode(mode) {
     }
     return mode;
 }
+/** True when two values have the same JSON. A value without JSON is never the same. */
+function sameJson(a, b) {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
 /** A change with an origin, when there is one. */
 function withOrigin(change, origin) {
     return origin === undefined ? change : { ...change, origin };
@@ -555,7 +567,10 @@ export class HybridStorage {
         conflicts: 0,
     };
     constructor(remote, options = {}) {
-        this.local = options.local ?? new InMemoryStorage();
+        // The local copy tests the preconditions of the callers (roadmap CLI-16): it gets `versionOf`
+        this.local =
+            options.local ??
+                new InMemoryStorage(options.versionOf !== undefined ? { versionOf: options.versionOf } : {});
         this.remote = remote;
         this.queueStore = options.queueStore ?? new MemoryQueueStore();
         this.mode = checkMode(options.mode ?? options.writeStrategy ?? "write-through");
@@ -564,6 +579,7 @@ export class HybridStorage {
             ...(options.mergeFn !== undefined && { mergeFn: options.mergeFn }),
             keyOf: options.keyOf ?? defaultKeyOf,
             ...(options.versionOf !== undefined && { versionOf: options.versionOf }),
+            sendBaseVersions: options.sendBaseVersions ?? true,
             syncInterval: optionalMs(options.syncInterval, "syncInterval") ?? 5000,
             pullInterval: optionalMs(options.pullInterval, "pullInterval") ?? 0,
             syncOnInit: options.syncOnInit ?? true,
@@ -1303,21 +1319,32 @@ export class HybridStorage {
      * This method sets an item. The storage takes a copy of the value, so a later change of the
      * value does not change the local copy, the queue or the remote write. The origin of the options
      * goes to the batches of `observe()`. The local copy and the remote get the origin of the storage.
+     *
+     * An `expectedVersion` (roadmap CLI-16) is a precondition on the item as the storage reads it.
+     * The local copy tests it (the default local copy needs `versionOf`). In `write-through` mode, the
+     * remote write also gets it. In `remote-only` mode, only the remote tests it.
      */
     async set(id, written, options) {
         const value = structuredClone(written);
         const origin = options?.origin;
+        const expected = this.expectedOf(options);
         await this.write("set", { id, value }, [id], origin, async () => {
             this.bump(id);
-            await this.localSet(id, value, origin);
-        }, () => this.remote.set(id, value, this.own));
+            await this.localSet(id, value, origin, expected);
+        }, () => this.remote.set(id, value, { ...this.own, ...expected }));
     }
+    /** This method deletes an item. An `expectedVersion` is a precondition, as for `set`. */
     async delete(id, options) {
         const origin = options?.origin;
+        const expected = this.expectedOf(options);
         return this.write("delete", { id }, [id], origin, async () => {
             this.bump(id);
-            return this.localDelete(id, origin);
-        }, () => this.remote.delete(id, this.own));
+            return this.localDelete(id, origin, expected);
+        }, () => this.remote.delete(id, { ...this.own, ...expected }));
+    }
+    /** The precondition of the caller: the field `expectedVersion`, or no field. */
+    expectedOf(options) {
+        return options?.expectedVersion === undefined ? {} : { expectedVersion: options.expectedVersion };
     }
     async clear(options) {
         const origin = options?.origin;
@@ -1329,15 +1356,19 @@ export class HybridStorage {
     //
     // ═══ Bulk Operations ═══
     //
-    /** This method sets several items. The storage takes a copy of each value, as `set` does. */
+    /**
+     * This method sets several items. The storage takes a copy of each value, as `set` does. The
+     * `expectedVersions` are preconditions, as `expectedVersion` of `set` is.
+     */
     async setBatch(written, options) {
         const items = written.map(([id, value]) => [id, structuredClone(value)]);
         const origin = options?.origin;
+        const expected = options?.expectedVersions !== undefined && options.expectedVersions.length > 0 ? { expectedVersions: options.expectedVersions } : {};
         await this.write("setBatch", { items }, items.map(([id]) => id), origin, async () => {
             for (const [id] of items)
                 this.bump(id);
-            await this.localSetBatch(items, origin);
-        }, () => this.remote.setBatch(items, this.own));
+            await this.localSetBatch(items, origin, expected);
+        }, () => this.remote.setBatch(items, { ...this.own, ...expected }));
     }
     async deleteBatch(ids, options) {
         const origin = options?.origin;
@@ -1942,19 +1973,21 @@ export class HybridStorage {
     }
     // The writes of the local copy have the origin of this storage, so the capture does not queue
     // them. The observers get each change with the origin of the caller.
-    async localSet(id, value, origin) {
-        await this.writeLocal(() => [[id, this.recordedVersion(value)]], () => this.local.set(id, value, this.own));
+    // A precondition of a caller goes to the local copy, which tests it and writes in one step
+    // (roadmap CLI-16).
+    async localSet(id, value, origin, expected = {}) {
+        await this.writeLocal(() => [[id, this.recordedVersion(value)]], () => this.local.set(id, value, { ...this.own, ...expected }));
         if (this.observers.size > 0)
             this.emit([setChange(id, value, origin)]);
     }
-    async localDelete(id, origin) {
-        const existed = await this.writeLocal(() => [[id, undefined]], () => this.local.delete(id, this.own));
+    async localDelete(id, origin, expected = {}) {
+        const existed = await this.writeLocal(() => [[id, undefined]], () => this.local.delete(id, { ...this.own, ...expected }));
         if (existed)
             this.emit([withOrigin({ type: "delete", id }, origin)]);
         return existed;
     }
-    async localSetBatch(items, origin) {
-        await this.writeLocal(() => items.map(([id, value]) => [id, this.recordedVersion(value)]), () => this.local.setBatch(items, this.own));
+    async localSetBatch(items, origin, expected = {}) {
+        await this.writeLocal(() => items.map(([id, value]) => [id, this.recordedVersion(value)]), () => this.local.setBatch(items, { ...this.own, ...expected }));
         if (this.observers.size > 0)
             this.emit(items.map(([id, value]) => setChange(id, value, origin)));
     }
@@ -2282,6 +2315,8 @@ export class HybridStorage {
     async pushQueue() {
         this.pushing = true;
         let sent = 0;
+        // The operations whose conflicts this push resolved once (roadmap CLI-16)
+        const resolved = new Set();
         try {
             while (this.offlineOps.length > 0) {
                 const op = this.offlineOps[0];
@@ -2295,8 +2330,17 @@ export class HybridStorage {
                     await this.executeOperation(op);
                 }
                 catch (error) {
+                    // The remote refused a base version: the conflict policy decides, then the push goes on
+                    const conflicts = this.sendsBaseVersions() ? versionConflictsOf(error) : undefined;
+                    if (conflicts !== undefined && conflicts.length > 0 && !resolved.has(op)) {
+                        resolved.add(op);
+                        this.isOnline = true;
+                        await this.resolvePushConflicts(op, conflicts);
+                        continue;
+                    }
                     // This operation and the later ones stay queued
-                    this.isOnline = false;
+                    if (conflicts === undefined)
+                        this.isOnline = false;
                     throw error;
                 }
                 this.noteRemoteWrite(op);
@@ -2627,13 +2671,13 @@ export class HybridStorage {
         const data = op.data;
         switch (op.type) {
             case "set":
-                await this.remote.set(data.id, data.value, this.own);
+                await this.remote.set(data.id, data.value, this.withBase(data.id));
                 break;
             case "delete":
-                await this.remote.delete(data.id, this.own);
+                await this.remote.delete(data.id, this.withBase(data.id));
                 break;
             case "setBatch":
-                await this.remote.setBatch(data.items, this.own);
+                await this.remote.setBatch(data.items, this.withBases(data.items));
                 break;
             case "deleteBatch":
                 await this.remote.deleteBatch(data.ids, this.own);
@@ -2643,6 +2687,130 @@ export class HybridStorage {
                 break;
         }
     }
+    //
+    // ═══ The base versions as preconditions (roadmap CLI-16) ═══
+    //
+    /** True when a push sends the base versions of its operations as expected versions. */
+    sendsBaseVersions() {
+        return this.options.sendBaseVersions && this.options.versionOf !== undefined;
+    }
+    /**
+     * The options of the push of a set or a delete of one id: the base version of the id as its
+     * expected version. The first queued operation of an id changes the remote version in `bases`.
+     * An id without a known base version gets no precondition: the queued write wins, as before.
+     */
+    withBase(id) {
+        if (!this.sendsBaseVersions())
+            return this.own;
+        const base = this.bases.get(id);
+        return base === undefined ? this.own : { ...this.own, expectedVersion: base };
+    }
+    /** The options of the push of a batch: the base version of each id that has one. */
+    withBases(items) {
+        if (!this.sendsBaseVersions())
+            return this.own;
+        const expectedVersions = [];
+        for (const id of new Set(items.map(([id]) => id))) {
+            const base = this.bases.get(id);
+            if (base !== undefined)
+                expectedVersions.push([id, base]);
+        }
+        return expectedVersions.length === 0 ? this.own : { ...this.own, expectedVersions };
+    }
+    /**
+     * The value that a queued operation writes for an id: the value of the last item of the id, or
+     * `null` for a delete. Undefined when the operation does not write the id.
+     */
+    writtenValue(op, id) {
+        const data = op.data;
+        switch (op.type) {
+            case "set":
+                return data.id === id ? { value: data.value } : undefined;
+            case "setBatch": {
+                const item = data.items.findLast(([itemId]) => itemId === id);
+                return item ? { value: item[1] } : undefined;
+            }
+            case "delete":
+                return data.id === id ? null : undefined;
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * This method applies the conflicts of a push that the remote refused (`VERSION_CONFLICT`). Each
+     * conflict goes to `conflictResolution`, as a conflict of a pull does:
+     *
+     * - The remote item is the value of the operation itself: an earlier send of it reached the
+     *   remote, and its answer was lost. The base becomes the current version, and the push sends
+     *   the operation again.
+     * - `remote`: the remote item replaces the local item, and the queued writes of the id go.
+     * - `merge`: the merged item replaces the local item, and a new queued write sends it.
+     * - `local`: the base becomes the current version, so the next send replaces the remote item.
+     * - `error`: the queue keeps the operation, and the push throws `ConflictError` with the ids.
+     */
+    async resolvePushConflicts(op, conflicts) {
+        const ids = [];
+        let queueChanged = false;
+        for (const conflict of conflicts) {
+            const { id } = conflict;
+            const written = this.writtenValue(op, id);
+            if (written === undefined)
+                continue;
+            if (conflict.found) {
+                const remoteItem = conflict.value;
+                const remoteVersion = conflict.version ?? this.versionOfItem(remoteItem);
+                // The echo of this operation, or a remote item without a version: the queued write wins
+                if (remoteVersion === undefined || (written !== null && sameJson(written.value, remoteItem))) {
+                    if (remoteVersion === undefined)
+                        this.bases.delete(id);
+                    else
+                        this.bases.set(id, remoteVersion);
+                    continue;
+                }
+                const localItem = await this.readLocal(id);
+                if (await this.resolvePending(id, localItem, remoteItem, remoteVersion, ids))
+                    queueChanged = true;
+                continue;
+            }
+            // The remote has no item: the echo of a delete, or a delete of another writer
+            if (written === null) {
+                this.bases.set(id, null);
+                continue;
+            }
+            if (await this.resolveRemoteDelete(id, ids))
+                queueChanged = true;
+        }
+        if (queueChanged) {
+            this.storeDirty = true;
+            // The status gets the failure of the queue store. A later direct write repairs the store first.
+            await this.persistAll().catch(() => undefined);
+        }
+        if (ids.length > 0)
+            throw new ConflictError(ids);
+    }
+    /**
+     * A queued write of an id that the remote deleted: a conflict, and the policy decides, as for
+     * a delete of a pull. True when the queue changed.
+     */
+    async resolveRemoteDelete(id, conflicts) {
+        this.stats.conflicts++;
+        switch (this.options.conflictResolution) {
+            case "remote":
+                if (!this.dropQueued(id))
+                    break;
+                await this.localDelete(id, this.syncOrigin);
+                this.bases.set(id, null);
+                return true;
+            case "error":
+                conflicts.push(id);
+                return false;
+            default:
+                // "local", and "merge" with one deleted side: the queued write wins
+                break;
+        }
+        this.bases.set(id, null);
+        return false;
+    }
     /**
      * Get current online status.
      */