@multiplatform.one/frappe 6.0.0

package/dist/esm/sync/mutationEngine.native.js

@@ -0,0 +1,1131 @@
+import { Debouncer } from "@tanstack/pacer";
+import { matchesFilters } from "./filters.native.js";
+import { merge, MergeStrategy } from "./merge.native.js";
+import { Order } from "./types.native.js";
+import { Operation, PendingRehydrationType, PlacementType, RehydrationReason, Status } from "./types.native.js";
+function _class_call_check(instance, Constructor) {
+  if (!(instance instanceof Constructor)) {
+    throw new TypeError("Cannot call a class as a function");
+  }
+}
+function _defineProperties(target, props) {
+  for (var i = 0; i < props.length; i++) {
+    var descriptor = props[i];
+    descriptor.enumerable = descriptor.enumerable || false;
+    descriptor.configurable = true;
+    if ("value" in descriptor) descriptor.writable = true;
+    Object.defineProperty(target, descriptor.key, descriptor);
+  }
+}
+function _create_class(Constructor, protoProps, staticProps) {
+  if (protoProps) _defineProperties(Constructor.prototype, protoProps);
+  if (staticProps) _defineProperties(Constructor, staticProps);
+  return Constructor;
+}
+function _define_property(obj, key, value) {
+  if (key in obj) {
+    Object.defineProperty(obj, key, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true
+    });
+  } else {
+    obj[key] = value;
+  }
+  return obj;
+}
+var MutationEngine = /* @__PURE__ */function () {
+  "use strict";
+
+  function MutationEngine2(db, realtime, normalizedCache, mutationJournal, subscriptionManager, rehydrationManager) {
+    var _this = this;
+    var options = arguments.length > 6 && arguments[6] !== void 0 ? arguments[6] : {};
+    _class_call_check(this, MutationEngine2);
+    var _options_batchDelay;
+    _define_property(this, "db", void 0);
+    _define_property(this, "realtime", void 0);
+    _define_property(this, "normalizedCache", void 0);
+    _define_property(this, "mutationJournal", void 0);
+    _define_property(this, "subscriptionManager", void 0);
+    _define_property(this, "rehydrationManager", void 0);
+    _define_property(this, "options", void 0);
+    _define_property(this, "temporaryIdToRealNameMap", void 0);
+    _define_property(this, "globalOptimisticDocIds", void 0);
+    _define_property(this, "pendingBatch", void 0);
+    _define_property(this, "batchDebouncer", void 0);
+    this.db = db;
+    this.realtime = realtime;
+    this.normalizedCache = normalizedCache;
+    this.mutationJournal = mutationJournal;
+    this.subscriptionManager = subscriptionManager;
+    this.rehydrationManager = rehydrationManager;
+    this.options = options;
+    this.temporaryIdToRealNameMap = /* @__PURE__ */new Map();
+    this.globalOptimisticDocIds = /* @__PURE__ */new Map();
+    this.pendingBatch = [];
+    var batchDelay = (_options_batchDelay = options.batchDelay) !== null && _options_batchDelay !== void 0 ? _options_batchDelay : 100;
+    this.batchDebouncer = new Debouncer(function () {
+      return _this.flushBatch();
+    }, {
+      wait: batchDelay
+    });
+  }
+  _create_class(MutationEngine2, [{
+    key: "queueForBatch",
+    value: (
+    /**
+    * Queue a mutation for batch processing.
+    * Returns a promise that resolves when the batch is processed.
+    */
+    function queueForBatch(mutation) {
+      var _this = this;
+      return new Promise(function (resolve, reject) {
+        var _this_options_batchMaxSize;
+        _this.pendingBatch.push({
+          mutation,
+          resolve,
+          reject
+        });
+        var maxSize = (_this_options_batchMaxSize = _this.options.batchMaxSize) !== null && _this_options_batchMaxSize !== void 0 ? _this_options_batchMaxSize : 50;
+        if (_this.pendingBatch.length >= maxSize) {
+          _this.flushBatch();
+        } else {
+          _this.batchDebouncer.maybeExecute();
+        }
+      });
+    })
+  }, {
+    key: "flushBatch",
+    value: (
+    /**
+    * Flush pending mutations as a batch.
+    */
+    async function flushBatch() {
+      if (this.pendingBatch.length === 0) return;
+      var batch = [...this.pendingBatch];
+      this.pendingBatch = [];
+      try {
+        var _this_options_batchAtomic;
+        var batchMutations = batch.map(function (param) {
+          var {
+            mutation: mutation2
+          } = param;
+          var operationMap = {
+            [Operation.Create]: "create",
+            [Operation.Update]: "update",
+            [Operation.Delete]: "delete"
+          };
+          return {
+            type: operationMap[mutation2.operation],
+            doctype: mutation2.doc.doctype,
+            name: mutation2.doc.name,
+            data: mutation2.operation === Operation.Delete ? void 0 : mutation2.doc
+          };
+        });
+        var results = await this.db.batchMutations({
+          mutations: batchMutations,
+          atomic: (_this_options_batchAtomic = this.options.batchAtomic) !== null && _this_options_batchAtomic !== void 0 ? _this_options_batchAtomic : false
+        });
+        for (var i = 0; i < batch.length; i++) {
+          var {
+            mutation,
+            resolve,
+            reject
+          } = batch[i];
+          var result = results[i];
+          if (result.success) {
+            this.mutationJournal.confirm(mutation.mutationId);
+            if (result.data) {
+              this.normalizedCache.upsert(result.data);
+              if (mutation.operation === Operation.Create && mutation.doc.name !== result.data.name) {
+                this.temporaryIdToRealNameMap.set(mutation.doc.name, result.data.name);
+                this.rehydrationManager.registerTempIdMapping(mutation.doc.name, result.data.name);
+              }
+            }
+            if (this.options.onMutationSuccess) {
+              this.options.onMutationSuccess(mutation);
+            }
+            resolve(result.data);
+          } else {
+            var error = new Error(result.error || "Batch mutation failed");
+            this.mutationJournal.fail(mutation.mutationId);
+            reject(error);
+          }
+        }
+      } catch (err) {
+        var _iteratorNormalCompletion = true,
+          _didIteratorError = false,
+          _iteratorError = void 0;
+        try {
+          for (var _iterator = batch[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+            var {
+              mutation: mutation1,
+              reject: reject1
+            } = _step.value;
+            this.mutationJournal.fail(mutation1.mutationId);
+            reject1(err);
+          }
+        } catch (err2) {
+          _didIteratorError = true;
+          _iteratorError = err2;
+        } finally {
+          try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+              _iterator.return();
+            }
+          } finally {
+            if (_didIteratorError) {
+              throw _iteratorError;
+            }
+          }
+        }
+      }
+    })
+  }, {
+    key: "forceBatchFlush",
+    value: (
+    /**
+    * Force flush any pending batched mutations.
+    */
+    async function forceBatchFlush() {
+      this.batchDebouncer.cancel();
+      await this.flushBatch();
+    })
+  }, {
+    key: "mutate",
+    value: async function mutate(mutation) {
+      if (this.options.onMutationStart) this.options.onMutationStart(mutation);
+      var {
+        doc
+      } = mutation;
+      if ((mutation.operation === Operation.Update || mutation.operation === Operation.Delete) && !doc.name) {
+        throw new Error("docname is required for update/delete operations");
+      }
+      var version = mutation.version;
+      var cachedDoc = void 0;
+      if (doc.name) {
+        cachedDoc = this.normalizedCache.get({
+          doctype: doc.doctype,
+          name: doc.name
+        });
+      }
+      if (version === void 0 && doc.name) {
+        var _this_options_versionFields;
+        var versionField = ((_this_options_versionFields = this.options.versionFields) === null || _this_options_versionFields === void 0 ? void 0 : _this_options_versionFields[doc.doctype]) || this.options.versionField || "modified";
+        var cachedVersion = cachedDoc ? cachedDoc[versionField] : void 0;
+        if (typeof cachedVersion === "string") version = cachedVersion;
+      }
+      if (mutation.operation === Operation.Update && doc.name) {
+        await this.handleOptimisticUpdate(mutation, cachedDoc);
+      }
+      if (mutation.operation === Operation.Create) {
+        await this.handleOptimisticCreate(mutation);
+      }
+      if (version === void 0 && doc.name && (mutation.operation === Operation.Update || mutation.operation === Operation.Delete) && !cachedDoc) {
+        try {
+          var _this_options_versionFields1;
+          cachedDoc = await this.db.getDoc(doc.doctype, doc.name);
+          var versionField1 = ((_this_options_versionFields1 = this.options.versionFields) === null || _this_options_versionFields1 === void 0 ? void 0 : _this_options_versionFields1[doc.doctype]) || this.options.versionField || "modified";
+          var cachedVersion1 = cachedDoc ? cachedDoc[versionField1] : void 0;
+          if (typeof cachedVersion1 === "string") version = cachedVersion1;
+          this.normalizedCache.upsert(cachedDoc);
+        } catch (err) {
+          if (this.options.onTrace) {
+            this.options.onTrace({
+              event: "version-fetch-failed",
+              details: {
+                doctype: doc.doctype,
+                name: doc.name,
+                error: err
+              }
+            });
+          }
+        }
+      }
+      var values = mutation.operation === Operation.Delete ? void 0 : mutation.operation === Operation.Create ? mutation.doc : mutation.doc;
+      this.mutationJournal.add(mutation.mutationId, {
+        doctype: doc.doctype,
+        docname: doc.name,
+        values,
+        operation: mutation.operation,
+        version,
+        status: Status.Pending,
+        snapshot: doc.name ? cachedDoc : void 0
+      });
+      if (this.options.enableBatching) {
+        try {
+          await this.queueForBatch(mutation);
+          if (mutation.operation === Operation.Create) {
+            var _iteratorNormalCompletion = true,
+              _didIteratorError = false,
+              _iteratorError = void 0;
+            try {
+              for (var _iterator = this.subscriptionManager.getAllSubscriptions().values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+                var subscription = _step.value;
+                if (subscription.query.doctype === mutation.doc.doctype) {
+                  this.rehydrationManager.scheduleRehydration(subscription, RehydrationReason.Create);
+                }
+              }
+            } catch (err) {
+              _didIteratorError = true;
+              _iteratorError = err;
+            } finally {
+              try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                  _iterator.return();
+                }
+              } finally {
+                if (_didIteratorError) {
+                  throw _iteratorError;
+                }
+              }
+            }
+          }
+        } catch (err) {
+          await this.handleMutationError(mutation, err);
+          throw err;
+        }
+        return;
+      }
+      try {
+        var _this_realtime;
+        if (mutation.operation === Operation.Create) {
+          await this.handleServerCreate(mutation);
+        } else if (mutation.operation === Operation.Update && doc.name) {
+          await this.handleServerUpdate(mutation, version);
+        } else if (mutation.operation === Operation.Delete && doc.name) {
+          await this.handleServerDelete(mutation, version);
+        }
+        this.mutationJournal.confirm(mutation.mutationId);
+        if (this.options.onMutationSuccess) {
+          this.options.onMutationSuccess(mutation);
+        }
+        if (mutation.operation === Operation.Create) {
+          var _iteratorNormalCompletion1 = true,
+            _didIteratorError1 = false,
+            _iteratorError1 = void 0;
+          try {
+            for (var _iterator1 = this.subscriptionManager.getAllSubscriptions().values()[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true) {
+              var subscription1 = _step1.value;
+              if (subscription1.query.doctype === mutation.doc.doctype) {
+                this.rehydrationManager.scheduleRehydration(subscription1, RehydrationReason.Create);
+              }
+            }
+          } catch (err) {
+            _didIteratorError1 = true;
+            _iteratorError1 = err;
+          } finally {
+            try {
+              if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                _iterator1.return();
+              }
+            } finally {
+              if (_didIteratorError1) {
+                throw _iteratorError1;
+              }
+            }
+          }
+        }
+        if (!((_this_realtime = this.realtime) === null || _this_realtime === void 0 ? void 0 : _this_realtime.isHealthy())) {
+          await this.refetchAffectedDocs(mutation);
+        }
+      } catch (err) {
+        await this.handleMutationError(mutation, err);
+        throw err;
+      }
+    }
+  }, {
+    key: "handleOptimisticUpdate",
+    value: async function handleOptimisticUpdate(mutation, cachedDoc) {
+      var doc = cachedDoc ? {
+        ...cachedDoc,
+        ...mutation.doc
+      } : mutation.doc;
+      this.normalizedCache.upsert(doc);
+      if (this.options.onOptimisticApply) {
+        this.options.onOptimisticApply({
+          doctype: mutation.doc.doctype,
+          name: mutation.doc.name,
+          operation: mutation.operation
+        });
+      }
+      this.subscriptionManager.updateSubscriptionMembership(doc);
+    }
+  }, {
+    key: "handleOptimisticCreate",
+    value: async function handleOptimisticCreate(mutation) {
+      var temporaryName = mutation.doc.name || `tmp_${cryptoRandomId()}`;
+      var optimisticDoc = {
+        ...mutation.doc,
+        name: temporaryName
+      };
+      this.normalizedCache.upsert(optimisticDoc);
+      if (!this.globalOptimisticDocIds.has(mutation.doc.doctype)) {
+        this.globalOptimisticDocIds.set(mutation.doc.doctype, /* @__PURE__ */new Set());
+      }
+      var globalDocIds = this.globalOptimisticDocIds.get(mutation.doc.doctype);
+      var _iteratorNormalCompletion = true,
+        _didIteratorError = false,
+        _iteratorError = void 0;
+      try {
+        for (var _iterator = this.subscriptionManager.getAllSubscriptions().values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+          var subscription = _step.value;
+          if (subscription.query.doctype !== mutation.doc.doctype) continue;
+          var matches = matchesFilters(optimisticDoc, subscription.query.filters);
+          if (!matches) continue;
+          if (globalDocIds.has(temporaryName)) {
+            continue;
+          }
+          if (subscription.query.orderBy && typeof subscription.query.limit === "number" && subscription.query.limit > 0 && subscription.docIds.length > 0) {
+            var placement = this.determineOptimisticPlacement(subscription, optimisticDoc);
+            switch (placement) {
+              case PlacementType.Before:
+                if (subscription.metadata) {
+                  subscription.metadata.itemsBeforePage = (subscription.metadata.itemsBeforePage || 0) + 1;
+                }
+                continue;
+              case PlacementType.After:
+                if (subscription.metadata) {
+                  subscription.metadata.itemsAfterPage = (subscription.metadata.itemsAfterPage || 0) + 1;
+                }
+                continue;
+              case PlacementType.Unknown:
+                subscription.pendingRehydration = PendingRehydrationType.FullRefresh;
+                this.rehydrationManager.scheduleRehydration(subscription, RehydrationReason.Uncertain);
+                break;
+              case PlacementType.Within:
+                break;
+            }
+          }
+          if (!subscription.docIds.includes(temporaryName)) {
+            this.subscriptionManager.insertDocumentIntoSubscription(subscription, optimisticDoc);
+            globalDocIds.add(temporaryName);
+          }
+        }
+      } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+      } finally {
+        try {
+          if (!_iteratorNormalCompletion && _iterator.return != null) {
+            _iterator.return();
+          }
+        } finally {
+          if (_didIteratorError) {
+            throw _iteratorError;
+          }
+        }
+      }
+    }
+  }, {
+    key: "handleServerCreate",
+    value: async function handleServerCreate(mutation) {
+      var _this_realtime;
+      var created = await this.db.createDoc(mutation.doc);
+      var realName = created === null || created === void 0 ? void 0 : created.name;
+      var temporaryName = mutation.doc.name;
+      if (realName && temporaryName && realName !== temporaryName) {
+        this.handleTemporaryToRealMapping(mutation.doc.doctype, temporaryName, realName);
+        this.rehydrationManager.registerTempIdMapping(temporaryName, realName);
+      } else if (temporaryName) {
+        var globalDocs = this.globalOptimisticDocIds.get(mutation.doc.doctype);
+        if (globalDocs) {
+          globalDocs.delete(temporaryName);
+        }
+      }
+      if (!((_this_realtime = this.realtime) === null || _this_realtime === void 0 ? void 0 : _this_realtime.isHealthy())) {
+        this.normalizedCache.upsert(created);
+      }
+    }
+  }, {
+    key: "handleServerUpdate",
+    value: async function handleServerUpdate(mutation, _version) {
+      await this.db.updateDoc(mutation.doc);
+    }
+  }, {
+    key: "handleServerDelete",
+    value: async function handleServerDelete(mutation, _version) {
+      this.normalizedCache.remove({
+        doctype: mutation.doc.doctype,
+        name: mutation.doc.name
+      });
+      this.subscriptionManager.removeFromAllSubscriptions(mutation.doc.doctype, mutation.doc.name);
+      var _iteratorNormalCompletion = true,
+        _didIteratorError = false,
+        _iteratorError = void 0;
+      try {
+        for (var _iterator = this.subscriptionManager.getAllSubscriptions().values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+          var subscription = _step.value;
+          if (subscription.query.doctype === mutation.doc.doctype && subscription.docIds.includes(mutation.doc.name)) {
+            this.rehydrationManager.scheduleRehydration(subscription, RehydrationReason.Delete);
+          }
+        }
+      } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+      } finally {
+        try {
+          if (!_iteratorNormalCompletion && _iterator.return != null) {
+            _iterator.return();
+          }
+        } finally {
+          if (_didIteratorError) {
+            throw _iteratorError;
+          }
+        }
+      }
+      await this.db.deleteDoc(mutation.doc);
+    }
+  }, {
+    key: "handleTemporaryToRealMapping",
+    value: function handleTemporaryToRealMapping(doctype, temporaryName, realName) {
+      this.temporaryIdToRealNameMap.set(temporaryName, realName);
+      var globalDocs = this.globalOptimisticDocIds.get(doctype);
+      if (globalDocs) {
+        globalDocs.delete(temporaryName);
+      }
+      var _iteratorNormalCompletion = true,
+        _didIteratorError = false,
+        _iteratorError = void 0;
+      try {
+        for (var _iterator = this.subscriptionManager.getAllSubscriptions().values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+          var subscription = _step.value;
+          if (subscription.query.doctype !== doctype) continue;
+          subscription.docIds = subscription.docIds.map(function (x) {
+            return x === temporaryName ? realName : x;
+          });
+        }
+      } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+      } finally {
+        try {
+          if (!_iteratorNormalCompletion && _iterator.return != null) {
+            _iterator.return();
+          }
+        } finally {
+          if (_didIteratorError) {
+            throw _iteratorError;
+          }
+        }
+      }
+      this.normalizedCache.remove({
+        doctype,
+        name: temporaryName
+      });
+    }
+  }, {
+    key: "refetchAffectedDocs",
+    value: async function refetchAffectedDocs(mutation) {
+      var _mutation_affected;
+      var targets = [];
+      var docname = mutation.doc.name;
+      var doctype = mutation.doc.doctype;
+      var realName = docname && this.temporaryIdToRealNameMap.get(docname) || docname;
+      if (realName) targets.push({
+        doctype,
+        name: realName
+      });
+      if ((_mutation_affected = mutation.affected) === null || _mutation_affected === void 0 ? void 0 : _mutation_affected.length) targets.push(...mutation.affected);
+      var _iteratorNormalCompletion = true,
+        _didIteratorError = false,
+        _iteratorError = void 0;
+      try {
+        for (var _iterator = targets[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+          var target = _step.value;
+          var fresh = await this.db.getDoc(target.doctype, target.name);
+          this.normalizedCache.upsert(fresh);
+        }
+      } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+      } finally {
+        try {
+          if (!_iteratorNormalCompletion && _iterator.return != null) {
+            _iterator.return();
+          }
+        } finally {
+          if (_didIteratorError) {
+            throw _iteratorError;
+          }
+        }
+      }
+    }
+  }, {
+    key: "handleMutationError",
+    value: async function handleMutationError(mutation, err) {
+      if (this.options.onMutationError) this.options.onMutationError({
+        mutation,
+        err
+      });
+      this.mutationJournal.fail(mutation.mutationId);
+      var entry = this.mutationJournal.get(mutation.mutationId);
+      var isOffline = typeof navigator !== "undefined" && navigator.onLine === false;
+      if (!isOffline) {
+        await this.rollbackOptimisticState(mutation, entry);
+      }
+      var errorWithStatus = err;
+      var docname = mutation.doc.name;
+      if (errorWithStatus && (errorWithStatus.status === 409 || errorWithStatus.status === 412) && docname) {
+        await this.handleConflict(mutation, entry);
+      }
+    }
+  }, {
+    key: "rollbackOptimisticState",
+    value: (
+    /**
+    * Rolls back optimistic state when a mutation fails.
+    * Handles all operation types: create, update, and delete.
+    */
+    async function rollbackOptimisticState(mutation, entry) {
+      var doctype = mutation.doc.doctype;
+      var docname = mutation.doc.name;
+      switch (mutation.operation) {
+        case Operation.Create:
+          await this.handleFailedCreate(mutation);
+          if (docname) {
+            this.normalizedCache.remove({
+              doctype,
+              name: docname
+            });
+          }
+          break;
+        case Operation.Update:
+          if ((entry === null || entry === void 0 ? void 0 : entry.snapshot) && docname) {
+            this.normalizedCache.upsert(entry.snapshot);
+            this.subscriptionManager.updateSubscriptionMembership(entry.snapshot);
+          }
+          break;
+        case Operation.Delete:
+          if ((entry === null || entry === void 0 ? void 0 : entry.snapshot) && docname) {
+            this.normalizedCache.upsert(entry.snapshot);
+            var restoredDoc = entry.snapshot;
+            var _iteratorNormalCompletion = true,
+              _didIteratorError = false,
+              _iteratorError = void 0;
+            try {
+              for (var _iterator = this.subscriptionManager.getAllSubscriptions().values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+                var subscription = _step.value;
+                if (subscription.query.doctype !== doctype) continue;
+                var matches = matchesFilters(restoredDoc, subscription.query.filters);
+                if (matches && !subscription.docIds.includes(docname)) {
+                  this.subscriptionManager.insertDocumentIntoSubscription(subscription, restoredDoc);
+                }
+              }
+            } catch (err) {
+              _didIteratorError = true;
+              _iteratorError = err;
+            } finally {
+              try {
+                if (!_iteratorNormalCompletion && _iterator.return != null) {
+                  _iterator.return();
+                }
+              } finally {
+                if (_didIteratorError) {
+                  throw _iteratorError;
+                }
+              }
+            }
+          }
+          break;
+      }
+    })
+  }, {
+    key: "handleFailedCreate",
+    value: async function handleFailedCreate(mutation) {
+      var temporaryName = mutation.doc.name;
+      var doctype = mutation.doc.doctype;
+      if (temporaryName) {
+        var globalDocs = this.globalOptimisticDocIds.get(doctype);
+        if (globalDocs) {
+          globalDocs.delete(temporaryName);
+        }
+        var _iteratorNormalCompletion = true,
+          _didIteratorError = false,
+          _iteratorError = void 0;
+        try {
+          for (var _iterator = this.subscriptionManager.getAllSubscriptions().values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+            var subscription = _step.value;
+            if (subscription.query.doctype !== doctype) continue;
+            subscription.docIds = subscription.docIds.filter(function (id) {
+              return id !== temporaryName;
+            });
+          }
+        } catch (err) {
+          _didIteratorError = true;
+          _iteratorError = err;
+        } finally {
+          try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+              _iterator.return();
+            }
+          } finally {
+            if (_didIteratorError) {
+              throw _iteratorError;
+            }
+          }
+        }
+      }
+    }
+  }, {
+    key: "handleConflict",
+    value: async function handleConflict(mutation, entry) {
+      var doctype = mutation.doc.doctype;
+      var docname = mutation.doc.name;
+      if (!docname) return;
+      try {
+        var latest = await this.db.getDoc(doctype, docname);
+        var base = entry === null || entry === void 0 ? void 0 : entry.snapshot;
+        var clientPartial = (mutation.operation === Operation.Delete ? void 0 : mutation.doc) || {};
+        var fullClient = base ? {
+          ...base,
+          ...clientPartial,
+          doctype,
+          name: docname
+        } : {
+          ...clientPartial,
+          doctype,
+          name: docname
+        };
+        var mergeConfig = this.buildMergeConfig();
+        var nonOverlap = merge(base, fullClient, latest, mergeConfig, doctype);
+        if (!nonOverlap.hasConflicts) {
+          var _this_options_versionFields;
+          var versionField = ((_this_options_versionFields = this.options.versionFields) === null || _this_options_versionFields === void 0 ? void 0 : _this_options_versionFields[doctype]) || this.options.versionField || "modified";
+          if (nonOverlap.merged) {
+            var newId = cryptoRandomId();
+            await this.db.updateDoc({
+              ...nonOverlap.merged,
+              client_mutation_id: newId,
+              base_modified: latest[versionField] || void 0
+            });
+          }
+          var refreshed = await this.db.getDoc(doctype, docname);
+          this.normalizedCache.upsert(refreshed);
+          this.mutationJournal.confirm(mutation.mutationId);
+          return;
+        }
+        this.normalizedCache.upsert(latest);
+      } catch (unused) {}
+      if (this.options.onConflict) this.options.onConflict({
+        doctype,
+        name: docname
+      });
+    }
+  }, {
+    key: "determineOptimisticPlacement",
+    value: (
+    /**
+    * Determines optimal placement for an optimistic item based on sort fields.
+    * Supports multi-column sorting with proper tie-breaking.
+    *
+    * @param subscription - The subscription to check placement against
+    * @param candidate - The document to place
+    * @returns Placement relative to current page:
+    *   - 'before': Item belongs on a previous page
+    *   - 'within': Item belongs on the current page
+    *   - 'after': Item belongs on a later page
+    *   - 'unknown': Cannot determine placement (needs full refresh)
+    *
+    * @remarks
+    * Uses page boundaries when available for O(1) placement checks.
+    * Falls back to comparing against first/last items in current page.
+    * Supports multi-field sorting with tie-breaking.
+    */
+    function determineOptimisticPlacement(subscription, candidate) {
+      var _subscription_boundaries, _subscription_boundaries1;
+      var docIds = subscription.docIds;
+      if (!docIds.length) return PlacementType.Unknown;
+      if (((_subscription_boundaries = subscription.boundaries) === null || _subscription_boundaries === void 0 ? void 0 : _subscription_boundaries.firstItem) && ((_subscription_boundaries1 = subscription.boundaries) === null || _subscription_boundaries1 === void 0 ? void 0 : _subscription_boundaries1.lastItem)) {
+        return this.determinePlacementWithBoundaries(subscription.boundaries, candidate, subscription.query.orderBy);
+      }
+      var order = subscription.query.orderBy;
+      if (!order) return PlacementType.Unknown;
+      var doctype = subscription.query.doctype;
+      var first = this.normalizedCache.get({
+        doctype,
+        name: docIds[0]
+      });
+      var last = this.normalizedCache.get({
+        doctype,
+        name: docIds[docIds.length - 1]
+      });
+      if (!first || !last) return PlacementType.Unknown;
+      var sortFields = this.parseSortFields(order);
+      var _iteratorNormalCompletion = true,
+        _didIteratorError = false,
+        _iteratorError = void 0;
+      try {
+        for (var _iterator = sortFields[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+          var {
+            field,
+            isAsc
+          } = _step.value;
+          var candidateValue = candidate[field];
+          var firstValue = first[field];
+          var lastValue = last[field];
+          if (candidateValue == null || firstValue == null || lastValue == null) {
+            continue;
+          }
+          if (isAsc) {
+            if (candidateValue < firstValue) return PlacementType.Before;
+            if (candidateValue > lastValue) return PlacementType.After;
+          } else {
+            if (candidateValue > firstValue) return PlacementType.Before;
+            if (candidateValue < lastValue) return PlacementType.After;
+          }
+          if (candidateValue !== firstValue && candidateValue !== lastValue) {
+            return PlacementType.Within;
+          }
+        }
+      } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+      } finally {
+        try {
+          if (!_iteratorNormalCompletion && _iterator.return != null) {
+            _iterator.return();
+          }
+        } finally {
+          if (_didIteratorError) {
+            throw _iteratorError;
+          }
+        }
+      }
+      return PlacementType.Within;
+    })
+  }, {
+    key: "determinePlacementWithBoundaries",
+    value:
+    // All sort fields match boundaries
+    function determinePlacementWithBoundaries(boundaries, candidate, orderBy) {
+      if (!boundaries.firstItem || !boundaries.lastItem) return PlacementType.Unknown;
+      var sortFields = this.parseSortFields(orderBy);
+      var _iteratorNormalCompletion = true,
+        _didIteratorError = false,
+        _iteratorError = void 0;
+      try {
+        for (var _iterator = sortFields[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+          var {
+            field,
+            isAsc
+          } = _step.value;
+          var candidateValue = candidate[field];
+          var firstValue = boundaries.firstItem[field];
+          var lastValue = boundaries.lastItem[field];
+          if (candidateValue == null || firstValue == null || lastValue == null) {
+            continue;
+          }
+          if (isAsc) {
+            if (candidateValue < firstValue) return PlacementType.Before;
+            if (candidateValue > lastValue) return PlacementType.After;
+          } else {
+            if (candidateValue > firstValue) return PlacementType.Before;
+            if (candidateValue < lastValue) return PlacementType.After;
+          }
+          if (candidateValue !== firstValue && candidateValue !== lastValue) {
+            return PlacementType.Within;
+          }
+        }
+      } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+      } finally {
+        try {
+          if (!_iteratorNormalCompletion && _iterator.return != null) {
+            _iterator.return();
+          }
+        } finally {
+          if (_didIteratorError) {
+            throw _iteratorError;
+          }
+        }
+      }
+      return PlacementType.Within;
+    }
+  }, {
+    key: "parseSortFields",
+    value: function parseSortFields(orderBy) {
+      if (!orderBy) return [{
+        field: "name",
+        isAsc: true
+      }];
+      var orderByArray = Array.isArray(orderBy) ? orderBy : [orderBy];
+      var sortFields = orderByArray.map(function (ob) {
+        return {
+          field: ob.field,
+          isAsc: ob.order !== Order.Desc
+        };
+      });
+      var hasNameField = sortFields.some(function (sf) {
+        return sf.field === "name";
+      });
+      if (!hasNameField) {
+        sortFields.push({
+          field: "name",
+          isAsc: true
+        });
+      }
+      return sortFields;
+    }
+  }, {
+    key: "replayPending",
+    value: (
+    /**
+    * Replays pending mutations with simplified error handling and rate limiting.
+    *
+    * Since HTTP client now handles retries automatically for transient errors,
+    * we only need to handle:
+    * - Success → confirm and remove from journal
+    * - Conflict (409/412) → attempt merge resolution, then retry
+    * - Auth (401/403) → notify user, keep in journal for later retry
+    * - Permanent (4xx validation) → fail and remove from journal
+    * - Failed (exhausted retries) → keep in journal but notify
+    *
+    * The replay path uses plain CRUD without optimistic writes,
+    * since optimistic state is already reflected in the cache.
+    *
+    * Rate limiting is applied to prevent hammering the server when replaying
+    * large numbers of queued mutations after coming back online.
+    */
+    async function replayPending() {
+      var _this = this;
+      var _this_options_replayRateLimit;
+      var anyFailed = false;
+      if (this.options.onReplayStart) this.options.onReplayStart();
+      var pendingMutations = this.mutationJournal.listPending();
+      if (pendingMutations.length === 0) {
+        if (this.options.onReplayComplete) {
+          this.options.onReplayComplete({
+            anyFailed: false
+          });
+        }
+        return;
+      }
+      var rateLimit = (_this_options_replayRateLimit = this.options.replayRateLimit) !== null && _this_options_replayRateLimit !== void 0 ? _this_options_replayRateLimit : 10;
+      var processMutation = async function processMutation2(mutation2) {
+        var {
+          id,
+          entry
+        } = mutation2;
+        if (_this.options.onRetry) {
+          _this.options.onRetry({
+            id,
+            operation: entry.operation
+          });
+        }
+        try {
+          if (entry.operation === Operation.Create) {
+            await _this.db.createDoc({
+              ...entry.values,
+              client_mutation_id: id,
+              doctype: entry.doctype,
+              name: entry.docname || cryptoRandomId()
+            });
+          } else if (entry.operation === Operation.Update && entry.docname) {
+            await _this.db.updateDoc({
+              ...entry.values,
+              client_mutation_id: id,
+              base_modified: entry.version,
+              doctype: entry.doctype,
+              name: entry.docname
+            });
+          } else if (entry.operation === Operation.Delete && entry.docname) {
+            await _this.db.deleteDoc({
+              doctype: entry.doctype,
+              name: entry.docname,
+              client_mutation_id: id
+            });
+          }
+          _this.mutationJournal.confirm(id);
+        } catch (err) {
+          var errorClass = _this.classifyError(err);
+          anyFailed = true;
+          if (errorClass === "conflict") {
+            if (_this.options.onConflict) {
+              _this.options.onConflict({
+                doctype: entry.doctype,
+                name: entry.docname
+              });
+            }
+          } else if (errorClass === "auth") {} else if (errorClass === "permanent") {
+            _this.mutationJournal.fail(id);
+            _this.notifyMutationError(id, entry, err);
+          } else if (errorClass === "failed") {
+            _this.mutationJournal.fail(id);
+            _this.notifyMutationError(id, entry, err);
+          }
+        }
+      };
+      var delayMs = Math.ceil(1e3 / rateLimit);
+      var _iteratorNormalCompletion = true,
+        _didIteratorError = false,
+        _iteratorError = void 0;
+      try {
+        for (var _iterator = pendingMutations[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+          var mutation = _step.value;
+          await processMutation(mutation);
+          if (pendingMutations.indexOf(mutation) < pendingMutations.length - 1) {
+            await new Promise(function (resolve) {
+              return setTimeout(resolve, delayMs);
+            });
+          }
+        }
+      } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+      } finally {
+        try {
+          if (!_iteratorNormalCompletion && _iterator.return != null) {
+            _iterator.return();
+          }
+        } finally {
+          if (_didIteratorError) {
+            throw _iteratorError;
+          }
+        }
+      }
+      if (this.options.onReplayComplete) {
+        this.options.onReplayComplete({
+          anyFailed
+        });
+      }
+    })
+  }, {
+    key: "classifyError",
+    value: (
+    /**
+    * Classifies errors for journal management.
+    */
+    function classifyError(err) {
+      var _errorWithStatus_response;
+      var errorWithStatus = err;
+      var status = (errorWithStatus === null || errorWithStatus === void 0 ? void 0 : errorWithStatus.status) || (errorWithStatus === null || errorWithStatus === void 0 ? void 0 : (_errorWithStatus_response = errorWithStatus.response) === null || _errorWithStatus_response === void 0 ? void 0 : _errorWithStatus_response.status);
+      if (status === 409 || status === 412) return "conflict";
+      if (status === 401 || status === 403) return "auth";
+      if (status && status >= 400 && status < 500) return "permanent";
+      return "failed";
+    })
+  }, {
+    key: "notifyMutationError",
+    value: (
+    /**
+    * Helper to notify about mutation errors with proper typing
+    */
+    function notifyMutationError(id, entry, err) {
+      if (!this.options.onMutationError) return;
+      var mutation;
+      if (entry.operation === Operation.Create) {
+        var doc = entry.values || {
+          doctype: entry.doctype,
+          name: entry.docname
+        };
+        mutation = {
+          mutationId: id,
+          operation: Operation.Create,
+          doc,
+          version: entry.version,
+          affected: []
+        };
+      } else if (entry.operation === Operation.Update) {
+        mutation = {
+          mutationId: id,
+          operation: Operation.Update,
+          doc: {
+            ...entry.values,
+            doctype: entry.doctype,
+            name: entry.docname
+          },
+          version: entry.version,
+          affected: []
+        };
+      } else {
+        mutation = {
+          mutationId: id,
+          operation: Operation.Delete,
+          doc: {
+            doctype: entry.doctype,
+            name: entry.docname
+          },
+          version: entry.version,
+          affected: []
+        };
+      }
+      this.options.onMutationError({
+        mutation,
+        err
+      });
+    })
+  }, {
+    key: "buildMergeConfig",
+    value: (
+    /**
+    * Converts SyncOptions.fieldMergeConfig into the MergeConfig format
+    * expected by the merge() function.
+    */
+    function buildMergeConfig() {
+      var fmc = this.options.fieldMergeConfig;
+      if (!fmc) return void 0;
+      var doctypes = {};
+      var _iteratorNormalCompletion = true,
+        _didIteratorError = false,
+        _iteratorError = void 0;
+      try {
+        for (var _iterator = Object.entries(fmc)[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+          var [dt, fields] = _step.value;
+          doctypes[dt] = {
+            fields
+          };
+        }
+      } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+      } finally {
+        try {
+          if (!_iteratorNormalCompletion && _iterator.return != null) {
+            _iterator.return();
+          }
+        } finally {
+          if (_didIteratorError) {
+            throw _iteratorError;
+          }
+        }
+      }
+      return {
+        defaultStrategy: MergeStrategy.ServerWins,
+        doctypes
+      };
+    })
+  }, {
+    /** Gets temporary to real name mapping. */
+    key: "getTemporaryIdToRealNameMap",
+    value: function getTemporaryIdToRealNameMap() {
+      return this.temporaryIdToRealNameMap;
+    }
+  }, {
+    /** Clears all temporary mappings. */
+    key: "clearTemporaryMappings",
+    value: function clearTemporaryMappings() {
+      this.temporaryIdToRealNameMap.clear();
+      this.globalOptimisticDocIds.clear();
+    }
+  }, {
+    /**
+    * Disposes of resources.
+    */
+    key: "dispose",
+    value: function dispose() {
+      this.batchDebouncer.cancel();
+      this.pendingBatch = [];
+      this.clearTemporaryMappings();
+    }
+  }]);
+  return MutationEngine2;
+}();
+function cryptoRandomId() {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID();
+  return Math.random().toString(36).slice(2);
+}
+export { MutationEngine };
+//# sourceMappingURL=mutationEngine.native.js.map