@multiplatform.one/frappe 6.0.0

package/dist/cjs/sync/mutationEngine.cjs

@@ -0,0 +1,781 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all) __defProp(target, name, {
+    get: all[name],
+    enumerable: true
+  });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    });
+  }
+  return to;
+};
+var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
+  value: true
+}), mod);
+var mutationEngine_exports = {};
+__export(mutationEngine_exports, {
+  MutationEngine: () => MutationEngine
+});
+module.exports = __toCommonJS(mutationEngine_exports);
+var import_pacer = require("@tanstack/pacer");
+var import_filters = require("./filters.cjs");
+var import_merge = require("./merge.cjs");
+var import_types = require("./types.cjs");
+var import_types2 = require("./types.cjs");
+class MutationEngine {
+  constructor(db, realtime, normalizedCache, mutationJournal, subscriptionManager, rehydrationManager, options = {}) {
+    this.db = db;
+    this.realtime = realtime;
+    this.normalizedCache = normalizedCache;
+    this.mutationJournal = mutationJournal;
+    this.subscriptionManager = subscriptionManager;
+    this.rehydrationManager = rehydrationManager;
+    this.options = options;
+    const batchDelay = options.batchDelay ?? 100;
+    this.batchDebouncer = new import_pacer.Debouncer(() => this.flushBatch(), {
+      wait: batchDelay
+    });
+  }
+  db;
+  realtime;
+  normalizedCache;
+  mutationJournal;
+  subscriptionManager;
+  rehydrationManager;
+  options;
+  temporaryIdToRealNameMap = /* @__PURE__ */new Map();
+  globalOptimisticDocIds = /* @__PURE__ */new Map();
+  /** Pending mutations waiting to be batched */
+  pendingBatch = [];
+  /** Debouncer for batch processing */
+  batchDebouncer;
+  /**
+   * Queue a mutation for batch processing.
+   * Returns a promise that resolves when the batch is processed.
+   */
+  queueForBatch(mutation) {
+    return new Promise((resolve, reject) => {
+      this.pendingBatch.push({
+        mutation,
+        resolve,
+        reject
+      });
+      const maxSize = this.options.batchMaxSize ?? 50;
+      if (this.pendingBatch.length >= maxSize) {
+        this.flushBatch();
+      } else {
+        this.batchDebouncer.maybeExecute();
+      }
+    });
+  }
+  /**
+   * Flush pending mutations as a batch.
+   */
+  async flushBatch() {
+    if (this.pendingBatch.length === 0) return;
+    const batch = [...this.pendingBatch];
+    this.pendingBatch = [];
+    try {
+      const batchMutations = batch.map(({
+        mutation
+      }) => {
+        const operationMap = {
+          [import_types2.Operation.Create]: "create",
+          [import_types2.Operation.Update]: "update",
+          [import_types2.Operation.Delete]: "delete"
+        };
+        return {
+          type: operationMap[mutation.operation],
+          doctype: mutation.doc.doctype,
+          name: mutation.doc.name,
+          data: mutation.operation === import_types2.Operation.Delete ? void 0 : mutation.doc
+        };
+      });
+      const results = await this.db.batchMutations({
+        mutations: batchMutations,
+        atomic: this.options.batchAtomic ?? false
+      });
+      for (let i = 0; i < batch.length; i++) {
+        const {
+          mutation,
+          resolve,
+          reject
+        } = batch[i];
+        const result = results[i];
+        if (result.success) {
+          this.mutationJournal.confirm(mutation.mutationId);
+          if (result.data) {
+            this.normalizedCache.upsert(result.data);
+            if (mutation.operation === import_types2.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 {
+          const error = new Error(result.error || "Batch mutation failed");
+          this.mutationJournal.fail(mutation.mutationId);
+          reject(error);
+        }
+      }
+    } catch (err) {
+      for (const {
+        mutation,
+        reject
+      } of batch) {
+        this.mutationJournal.fail(mutation.mutationId);
+        reject(err);
+      }
+    }
+  }
+  /**
+   * Force flush any pending batched mutations.
+   */
+  async forceBatchFlush() {
+    this.batchDebouncer.cancel();
+    await this.flushBatch();
+  }
+  async mutate(mutation) {
+    if (this.options.onMutationStart) this.options.onMutationStart(mutation);
+    const {
+      doc
+    } = mutation;
+    if ((mutation.operation === import_types2.Operation.Update || mutation.operation === import_types2.Operation.Delete) && !doc.name) {
+      throw new Error("docname is required for update/delete operations");
+    }
+    let version = mutation.version;
+    let cachedDoc = void 0;
+    if (doc.name) {
+      cachedDoc = this.normalizedCache.get({
+        doctype: doc.doctype,
+        name: doc.name
+      });
+    }
+    if (version === void 0 && doc.name) {
+      const versionField = this.options.versionFields?.[doc.doctype] || this.options.versionField || "modified";
+      const cachedVersion = cachedDoc ? cachedDoc[versionField] : void 0;
+      if (typeof cachedVersion === "string") version = cachedVersion;
+    }
+    if (mutation.operation === import_types2.Operation.Update && doc.name) {
+      await this.handleOptimisticUpdate(mutation, cachedDoc);
+    }
+    if (mutation.operation === import_types2.Operation.Create) {
+      await this.handleOptimisticCreate(mutation);
+    }
+    if (version === void 0 && doc.name && (mutation.operation === import_types2.Operation.Update || mutation.operation === import_types2.Operation.Delete) && !cachedDoc) {
+      try {
+        cachedDoc = await this.db.getDoc(doc.doctype, doc.name);
+        const versionField = this.options.versionFields?.[doc.doctype] || this.options.versionField || "modified";
+        const cachedVersion = cachedDoc ? cachedDoc[versionField] : void 0;
+        if (typeof cachedVersion === "string") version = cachedVersion;
+        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
+            }
+          });
+        }
+      }
+    }
+    const values = mutation.operation === import_types2.Operation.Delete ? void 0 : mutation.operation === import_types2.Operation.Create ? mutation.doc : mutation.doc;
+    this.mutationJournal.add(mutation.mutationId, {
+      doctype: doc.doctype,
+      docname: doc.name,
+      values,
+      operation: mutation.operation,
+      version,
+      status: import_types2.Status.Pending,
+      snapshot: doc.name ? cachedDoc : void 0
+    });
+    if (this.options.enableBatching) {
+      try {
+        await this.queueForBatch(mutation);
+        if (mutation.operation === import_types2.Operation.Create) {
+          for (const subscription of this.subscriptionManager.getAllSubscriptions().values()) {
+            if (subscription.query.doctype === mutation.doc.doctype) {
+              this.rehydrationManager.scheduleRehydration(subscription, import_types2.RehydrationReason.Create);
+            }
+          }
+        }
+      } catch (err) {
+        await this.handleMutationError(mutation, err);
+        throw err;
+      }
+      return;
+    }
+    try {
+      if (mutation.operation === import_types2.Operation.Create) {
+        await this.handleServerCreate(mutation);
+      } else if (mutation.operation === import_types2.Operation.Update && doc.name) {
+        await this.handleServerUpdate(mutation, version);
+      } else if (mutation.operation === import_types2.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 === import_types2.Operation.Create) {
+        for (const subscription of this.subscriptionManager.getAllSubscriptions().values()) {
+          if (subscription.query.doctype === mutation.doc.doctype) {
+            this.rehydrationManager.scheduleRehydration(subscription, import_types2.RehydrationReason.Create);
+          }
+        }
+      }
+      if (!this.realtime?.isHealthy()) {
+        await this.refetchAffectedDocs(mutation);
+      }
+    } catch (err) {
+      await this.handleMutationError(mutation, err);
+      throw err;
+    }
+  }
+  async handleOptimisticUpdate(mutation, cachedDoc) {
+    const 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);
+  }
+  async handleOptimisticCreate(mutation) {
+    const temporaryName = mutation.doc.name || `tmp_${cryptoRandomId()}`;
+    const 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());
+    }
+    const globalDocIds = this.globalOptimisticDocIds.get(mutation.doc.doctype);
+    for (const subscription of this.subscriptionManager.getAllSubscriptions().values()) {
+      if (subscription.query.doctype !== mutation.doc.doctype) continue;
+      const matches = (0, import_filters.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) {
+        const placement = this.determineOptimisticPlacement(subscription, optimisticDoc);
+        switch (placement) {
+          case import_types2.PlacementType.Before:
+            if (subscription.metadata) {
+              subscription.metadata.itemsBeforePage = (subscription.metadata.itemsBeforePage || 0) + 1;
+            }
+            continue;
+          case import_types2.PlacementType.After:
+            if (subscription.metadata) {
+              subscription.metadata.itemsAfterPage = (subscription.metadata.itemsAfterPage || 0) + 1;
+            }
+            continue;
+          case import_types2.PlacementType.Unknown:
+            subscription.pendingRehydration = import_types2.PendingRehydrationType.FullRefresh;
+            this.rehydrationManager.scheduleRehydration(subscription, import_types2.RehydrationReason.Uncertain);
+            break;
+          case import_types2.PlacementType.Within:
+            break;
+        }
+      }
+      if (!subscription.docIds.includes(temporaryName)) {
+        this.subscriptionManager.insertDocumentIntoSubscription(subscription, optimisticDoc);
+        globalDocIds.add(temporaryName);
+      }
+    }
+  }
+  async handleServerCreate(mutation) {
+    const created = await this.db.createDoc(mutation.doc);
+    const realName = created?.name;
+    const temporaryName = mutation.doc.name;
+    if (realName && temporaryName && realName !== temporaryName) {
+      this.handleTemporaryToRealMapping(mutation.doc.doctype, temporaryName, realName);
+      this.rehydrationManager.registerTempIdMapping(temporaryName, realName);
+    } else if (temporaryName) {
+      const globalDocs = this.globalOptimisticDocIds.get(mutation.doc.doctype);
+      if (globalDocs) {
+        globalDocs.delete(temporaryName);
+      }
+    }
+    if (!this.realtime?.isHealthy()) {
+      this.normalizedCache.upsert(created);
+    }
+  }
+  async handleServerUpdate(mutation, _version) {
+    await this.db.updateDoc(mutation.doc);
+  }
+  async handleServerDelete(mutation, _version) {
+    this.normalizedCache.remove({
+      doctype: mutation.doc.doctype,
+      name: mutation.doc.name
+    });
+    this.subscriptionManager.removeFromAllSubscriptions(mutation.doc.doctype, mutation.doc.name);
+    for (const subscription of this.subscriptionManager.getAllSubscriptions().values()) {
+      if (subscription.query.doctype === mutation.doc.doctype && subscription.docIds.includes(mutation.doc.name)) {
+        this.rehydrationManager.scheduleRehydration(subscription, import_types2.RehydrationReason.Delete);
+      }
+    }
+    await this.db.deleteDoc(mutation.doc);
+  }
+  handleTemporaryToRealMapping(doctype, temporaryName, realName) {
+    this.temporaryIdToRealNameMap.set(temporaryName, realName);
+    const globalDocs = this.globalOptimisticDocIds.get(doctype);
+    if (globalDocs) {
+      globalDocs.delete(temporaryName);
+    }
+    for (const subscription of this.subscriptionManager.getAllSubscriptions().values()) {
+      if (subscription.query.doctype !== doctype) continue;
+      subscription.docIds = subscription.docIds.map(x => x === temporaryName ? realName : x);
+    }
+    this.normalizedCache.remove({
+      doctype,
+      name: temporaryName
+    });
+  }
+  async refetchAffectedDocs(mutation) {
+    const targets = [];
+    const docname = mutation.doc.name;
+    const doctype = mutation.doc.doctype;
+    const realName = docname && this.temporaryIdToRealNameMap.get(docname) || docname;
+    if (realName) targets.push({
+      doctype,
+      name: realName
+    });
+    if (mutation.affected?.length) targets.push(...mutation.affected);
+    for (const target of targets) {
+      const fresh = await this.db.getDoc(target.doctype, target.name);
+      this.normalizedCache.upsert(fresh);
+    }
+  }
+  async handleMutationError(mutation, err) {
+    if (this.options.onMutationError) this.options.onMutationError({
+      mutation,
+      err
+    });
+    this.mutationJournal.fail(mutation.mutationId);
+    const entry = this.mutationJournal.get(mutation.mutationId);
+    const isOffline = typeof navigator !== "undefined" && navigator.onLine === false;
+    if (!isOffline) {
+      await this.rollbackOptimisticState(mutation, entry);
+    }
+    const errorWithStatus = err;
+    const docname = mutation.doc.name;
+    if (errorWithStatus && (errorWithStatus.status === 409 || errorWithStatus.status === 412) && docname) {
+      await this.handleConflict(mutation, entry);
+    }
+  }
+  /**
+   * Rolls back optimistic state when a mutation fails.
+   * Handles all operation types: create, update, and delete.
+   */
+  async rollbackOptimisticState(mutation, entry) {
+    const doctype = mutation.doc.doctype;
+    const docname = mutation.doc.name;
+    switch (mutation.operation) {
+      case import_types2.Operation.Create:
+        await this.handleFailedCreate(mutation);
+        if (docname) {
+          this.normalizedCache.remove({
+            doctype,
+            name: docname
+          });
+        }
+        break;
+      case import_types2.Operation.Update:
+        if (entry?.snapshot && docname) {
+          this.normalizedCache.upsert(entry.snapshot);
+          this.subscriptionManager.updateSubscriptionMembership(entry.snapshot);
+        }
+        break;
+      case import_types2.Operation.Delete:
+        if (entry?.snapshot && docname) {
+          this.normalizedCache.upsert(entry.snapshot);
+          const restoredDoc = entry.snapshot;
+          for (const subscription of this.subscriptionManager.getAllSubscriptions().values()) {
+            if (subscription.query.doctype !== doctype) continue;
+            const matches = (0, import_filters.matchesFilters)(restoredDoc, subscription.query.filters);
+            if (matches && !subscription.docIds.includes(docname)) {
+              this.subscriptionManager.insertDocumentIntoSubscription(subscription, restoredDoc);
+            }
+          }
+        }
+        break;
+    }
+  }
+  async handleFailedCreate(mutation) {
+    const temporaryName = mutation.doc.name;
+    const doctype = mutation.doc.doctype;
+    if (temporaryName) {
+      const globalDocs = this.globalOptimisticDocIds.get(doctype);
+      if (globalDocs) {
+        globalDocs.delete(temporaryName);
+      }
+      for (const subscription of this.subscriptionManager.getAllSubscriptions().values()) {
+        if (subscription.query.doctype !== doctype) continue;
+        subscription.docIds = subscription.docIds.filter(id => id !== temporaryName);
+      }
+    }
+  }
+  async handleConflict(mutation, entry) {
+    const doctype = mutation.doc.doctype;
+    const docname = mutation.doc.name;
+    if (!docname) return;
+    try {
+      const latest = await this.db.getDoc(doctype, docname);
+      const base = entry?.snapshot;
+      const clientPartial = (mutation.operation === import_types2.Operation.Delete ? void 0 : mutation.doc) || {};
+      const fullClient = base ? {
+        ...base,
+        ...clientPartial,
+        doctype,
+        name: docname
+      } : {
+        ...clientPartial,
+        doctype,
+        name: docname
+      };
+      const mergeConfig = this.buildMergeConfig();
+      const nonOverlap = (0, import_merge.merge)(base, fullClient, latest, mergeConfig, doctype);
+      if (!nonOverlap.hasConflicts) {
+        const versionField = this.options.versionFields?.[doctype] || this.options.versionField || "modified";
+        if (nonOverlap.merged) {
+          const newId = cryptoRandomId();
+          await this.db.updateDoc({
+            ...nonOverlap.merged,
+            client_mutation_id: newId,
+            base_modified: latest[versionField] || void 0
+          });
+        }
+        const refreshed = await this.db.getDoc(doctype, docname);
+        this.normalizedCache.upsert(refreshed);
+        this.mutationJournal.confirm(mutation.mutationId);
+        return;
+      }
+      this.normalizedCache.upsert(latest);
+    } catch {}
+    if (this.options.onConflict) this.options.onConflict({
+      doctype,
+      name: docname
+    });
+  }
+  /**
+   * 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.
+   */
+  determineOptimisticPlacement(subscription, candidate) {
+    const docIds = subscription.docIds;
+    if (!docIds.length) return import_types2.PlacementType.Unknown;
+    if (subscription.boundaries?.firstItem && subscription.boundaries?.lastItem) {
+      return this.determinePlacementWithBoundaries(subscription.boundaries, candidate, subscription.query.orderBy);
+    }
+    const order = subscription.query.orderBy;
+    if (!order) return import_types2.PlacementType.Unknown;
+    const doctype = subscription.query.doctype;
+    const first = this.normalizedCache.get({
+      doctype,
+      name: docIds[0]
+    });
+    const last = this.normalizedCache.get({
+      doctype,
+      name: docIds[docIds.length - 1]
+    });
+    if (!first || !last) return import_types2.PlacementType.Unknown;
+    const sortFields = this.parseSortFields(order);
+    for (const {
+      field,
+      isAsc
+    } of sortFields) {
+      const candidateValue = candidate[field];
+      const firstValue = first[field];
+      const lastValue = last[field];
+      if (candidateValue == null || firstValue == null || lastValue == null) {
+        continue;
+      }
+      if (isAsc) {
+        if (candidateValue < firstValue) return import_types2.PlacementType.Before;
+        if (candidateValue > lastValue) return import_types2.PlacementType.After;
+      } else {
+        if (candidateValue > firstValue) return import_types2.PlacementType.Before;
+        if (candidateValue < lastValue) return import_types2.PlacementType.After;
+      }
+      if (candidateValue !== firstValue && candidateValue !== lastValue) {
+        return import_types2.PlacementType.Within;
+      }
+    }
+    return import_types2.PlacementType.Within;
+  }
+  determinePlacementWithBoundaries(boundaries, candidate, orderBy) {
+    if (!boundaries.firstItem || !boundaries.lastItem) return import_types2.PlacementType.Unknown;
+    const sortFields = this.parseSortFields(orderBy);
+    for (const {
+      field,
+      isAsc
+    } of sortFields) {
+      const candidateValue = candidate[field];
+      const firstValue = boundaries.firstItem[field];
+      const lastValue = boundaries.lastItem[field];
+      if (candidateValue == null || firstValue == null || lastValue == null) {
+        continue;
+      }
+      if (isAsc) {
+        if (candidateValue < firstValue) return import_types2.PlacementType.Before;
+        if (candidateValue > lastValue) return import_types2.PlacementType.After;
+      } else {
+        if (candidateValue > firstValue) return import_types2.PlacementType.Before;
+        if (candidateValue < lastValue) return import_types2.PlacementType.After;
+      }
+      if (candidateValue !== firstValue && candidateValue !== lastValue) {
+        return import_types2.PlacementType.Within;
+      }
+    }
+    return import_types2.PlacementType.Within;
+  }
+  parseSortFields(orderBy) {
+    if (!orderBy) return [{
+      field: "name",
+      isAsc: true
+    }];
+    const orderByArray = Array.isArray(orderBy) ? orderBy : [orderBy];
+    const sortFields = orderByArray.map(ob => ({
+      field: ob.field,
+      isAsc: ob.order !== import_types.Order.Desc
+    }));
+    const hasNameField = sortFields.some(sf => sf.field === "name");
+    if (!hasNameField) {
+      sortFields.push({
+        field: "name",
+        isAsc: true
+      });
+    }
+    return sortFields;
+  }
+  /**
+   * 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 replayPending() {
+    let anyFailed = false;
+    if (this.options.onReplayStart) this.options.onReplayStart();
+    const pendingMutations = this.mutationJournal.listPending();
+    if (pendingMutations.length === 0) {
+      if (this.options.onReplayComplete) {
+        this.options.onReplayComplete({
+          anyFailed: false
+        });
+      }
+      return;
+    }
+    const rateLimit = this.options.replayRateLimit ?? 10;
+    const processMutation = async mutation => {
+      const {
+        id,
+        entry
+      } = mutation;
+      if (this.options.onRetry) {
+        this.options.onRetry({
+          id,
+          operation: entry.operation
+        });
+      }
+      try {
+        if (entry.operation === import_types2.Operation.Create) {
+          await this.db.createDoc({
+            ...entry.values,
+            client_mutation_id: id,
+            doctype: entry.doctype,
+            name: entry.docname || cryptoRandomId()
+          });
+        } else if (entry.operation === import_types2.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 === import_types2.Operation.Delete && entry.docname) {
+          await this.db.deleteDoc({
+            doctype: entry.doctype,
+            name: entry.docname,
+            client_mutation_id: id
+          });
+        }
+        this.mutationJournal.confirm(id);
+      } catch (err) {
+        const 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);
+        }
+      }
+    };
+    const delayMs = Math.ceil(1e3 / rateLimit);
+    for (const mutation of pendingMutations) {
+      await processMutation(mutation);
+      if (pendingMutations.indexOf(mutation) < pendingMutations.length - 1) {
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+      }
+    }
+    if (this.options.onReplayComplete) {
+      this.options.onReplayComplete({
+        anyFailed
+      });
+    }
+  }
+  /**
+   * Classifies errors for journal management.
+   */
+  classifyError(err) {
+    const errorWithStatus = err;
+    const status = errorWithStatus?.status || 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";
+  }
+  /**
+   * Helper to notify about mutation errors with proper typing
+   */
+  notifyMutationError(id, entry, err) {
+    if (!this.options.onMutationError) return;
+    let mutation;
+    if (entry.operation === import_types2.Operation.Create) {
+      const doc = entry.values || {
+        doctype: entry.doctype,
+        name: entry.docname
+      };
+      mutation = {
+        mutationId: id,
+        operation: import_types2.Operation.Create,
+        doc,
+        version: entry.version,
+        affected: []
+      };
+    } else if (entry.operation === import_types2.Operation.Update) {
+      mutation = {
+        mutationId: id,
+        operation: import_types2.Operation.Update,
+        doc: {
+          ...entry.values,
+          doctype: entry.doctype,
+          name: entry.docname
+        },
+        version: entry.version,
+        affected: []
+      };
+    } else {
+      mutation = {
+        mutationId: id,
+        operation: import_types2.Operation.Delete,
+        doc: {
+          doctype: entry.doctype,
+          name: entry.docname
+        },
+        version: entry.version,
+        affected: []
+      };
+    }
+    this.options.onMutationError({
+      mutation,
+      err
+    });
+  }
+  /**
+   * Converts SyncOptions.fieldMergeConfig into the MergeConfig format
+   * expected by the merge() function.
+   */
+  buildMergeConfig() {
+    const fmc = this.options.fieldMergeConfig;
+    if (!fmc) return void 0;
+    const doctypes = {};
+    for (const [dt, fields] of Object.entries(fmc)) {
+      doctypes[dt] = {
+        fields
+      };
+    }
+    return {
+      defaultStrategy: import_merge.MergeStrategy.ServerWins,
+      doctypes
+    };
+  }
+  /** Gets temporary to real name mapping. */
+  getTemporaryIdToRealNameMap() {
+    return this.temporaryIdToRealNameMap;
+  }
+  /** Clears all temporary mappings. */
+  clearTemporaryMappings() {
+    this.temporaryIdToRealNameMap.clear();
+    this.globalOptimisticDocIds.clear();
+  }
+  /**
+   * Disposes of resources.
+   */
+  dispose() {
+    this.batchDebouncer.cancel();
+    this.pendingBatch = [];
+    this.clearTemporaryMappings();
+  }
+}
+function cryptoRandomId() {
+  if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID();
+  return Math.random().toString(36).slice(2);
+}