@dabble/patches 0.5.17 → 0.5.18

package/dist/algorithms/client/collapsePendingChanges.d.ts

@@ -0,0 +1,30 @@
+import { Change } from '../../types.js';
+import '../../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../../json-patch/types.js';
+
+/**
+ * Collapses redundant pending changes before sync to reduce network traffic.
+ *
+ * This optimization automatically detects and collapses multiple "replace" operations
+ * on the same JSON path with primitive values (boolean, number, string, null) into
+ * a single change containing only the final value.
+ *
+ * Example: If a user toggles a folder's open state 100 times while offline,
+ * this collapses those 100 changes into just 1 change with the final state.
+ *
+ * Safety guarantees:
+ * - Only collapses single-op changes (multi-op changes are atomic, preserve intent)
+ * - Only collapses "replace" operations (not add, remove, move)
+ * - Only collapses primitive values (not objects/arrays)
+ * - Detects path invalidation from structural changes (remove, array shifts, move)
+ * - Respects the submission bookmark to never collapse already-submitted changes
+ *
+ * @param changes Array of pending changes to potentially collapse
+ * @param afterRev Optional revision bookmark - changes at or before this rev are not collapsed
+ *                 (they may have been partially submitted to the server)
+ * @returns Collapsed array of changes, maintaining correct ordering
+ */
+declare function collapsePendingChanges(changes: Change[], afterRev?: number): Change[];
+
+export { collapsePendingChanges };

package/dist/algorithms/client/collapsePendingChanges.js

@@ -0,0 +1,78 @@
+import "../../chunk-IZ2YBCUP.js";
+function collapsePendingChanges(changes, afterRev) {
+  if (changes.length <= 1) {
+    return changes;
+  }
+  const pathState = /* @__PURE__ */ new Map();
+  const outputSlots = new Array(changes.length).fill(null);
+  for (let i = 0; i < changes.length; i++) {
+    const change = changes[i];
+    if (afterRev !== void 0 && change.rev !== void 0 && change.rev <= afterRev) {
+      outputSlots[i] = change;
+      continue;
+    }
+    updatePathInvalidations(change, pathState);
+    if (!isCollapsibleChange(change)) {
+      outputSlots[i] = change;
+      continue;
+    }
+    const path = change.ops[0].path;
+    const existing = pathState.get(path);
+    if (existing) {
+      outputSlots[existing.lastIndex] = null;
+    }
+    pathState.set(path, { lastChange: change, lastIndex: i });
+    outputSlots[i] = change;
+  }
+  return outputSlots.filter((c) => c !== null);
+}
+function isCollapsibleChange(change) {
+  if (change.ops.length !== 1) {
+    return false;
+  }
+  const op = change.ops[0];
+  if (op.op !== "replace") {
+    return false;
+  }
+  return isPrimitiveValue(op.value);
+}
+function isPrimitiveValue(value) {
+  if (value === null) return true;
+  const type = typeof value;
+  return type === "boolean" || type === "number" || type === "string";
+}
+function updatePathInvalidations(change, pathState) {
+  for (const op of change.ops) {
+    if (op.op === "remove" || op.op === "move") {
+      invalidatePathAndChildren(op.path, pathState);
+      if (op.op === "move" && "from" in op) {
+        invalidatePathAndChildren(op.from, pathState);
+      }
+    }
+    if (op.op === "add" || op.op === "remove") {
+      invalidateShiftedArrayPaths(op.path, pathState);
+    }
+  }
+}
+function invalidatePathAndChildren(opPath, pathState) {
+  for (const trackedPath of pathState.keys()) {
+    if (trackedPath === opPath || trackedPath.startsWith(opPath + "/")) {
+      pathState.delete(trackedPath);
+    }
+  }
+}
+function invalidateShiftedArrayPaths(opPath, pathState) {
+  const segments = opPath.split("/");
+  const lastSegment = segments[segments.length - 1];
+  if (/^\d+$/.test(lastSegment)) {
+    const arrayPath = segments.slice(0, -1).join("/");
+    for (const trackedPath of pathState.keys()) {
+      if (trackedPath.startsWith(arrayPath + "/")) {
+        pathState.delete(trackedPath);
+      }
+    }
+  }
+}
+export {
+  collapsePendingChanges
+};

package/dist/algorithms/server/commitChanges.js

@@ -37,7 +37,7 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis, option
   const laterPartOfAnInitialBatch = batchId && changes[0].rev > 1;
   if (baseRev === 0 && currentRev > 0 && !laterPartOfAnInitialBatch && changes[0].ops[0]?.path === "") {
     throw new Error(
-      `Document ${docId} already exists at rev ${currentRev}, but client is attempting to create it. Client needs to load the existing document.`
+      `Document ${docId} already exists (rev ${currentRev}). Cannot apply root-level replace (path: '') with baseRev 0 - this would overwrite the existing document. Load the existing document first, or use nested paths instead of replacing at root.`
     );
   }
   const lastChange = currentChanges[currentChanges.length - 1];

package/dist/client/InMemoryStore.d.ts

@@ -24,6 +24,8 @@ declare class InMemoryStore implements PatchesStore {
     deleteDoc(docId: string): Promise<void>;
     confirmDeleteDoc(docId: string): Promise<void>;
     close(): Promise<void>;
+    getLastAttemptedSubmissionRev(docId: string): Promise<number | undefined>;
+    setLastAttemptedSubmissionRev(docId: string, rev: number): Promise<void>;
 }
 
 export { InMemoryStore };

package/dist/client/InMemoryStore.js

@@ -91,6 +91,16 @@ class InMemoryStore {
   async close() {
     this.docs.clear();
   }
+  // ─── Submission Bookmark ───────────────────────────────────────────────
+  async getLastAttemptedSubmissionRev(docId) {
+    return this.docs.get(docId)?.lastAttemptedSubmissionRev;
+  }
+  async setLastAttemptedSubmissionRev(docId, rev) {
+    const buf = this.docs.get(docId);
+    if (buf) {
+      buf.lastAttemptedSubmissionRev = rev;
+    }
+  }
 }
 export {
   InMemoryStore

package/dist/client/IndexedDBStore.d.ts

@@ -1,4 +1,5 @@
 import { PatchesSnapshot, PatchesState, Change } from '../types.js';
+import { Deferred } from '../utils/deferred.js';
 import { PatchesStore, TrackedDoc } from './PatchesStore.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
@@ -17,12 +18,12 @@ import '../json-patch/types.js';
  * A snapshot will not be created if there are pending changes based on revisions older than the 200th committed change until those pending changes are committed.
  */
 declare class IndexedDBStore implements PatchesStore {
-    private db;
-    private dbName?;
-    private dbPromise;
+    protected db: IDBDatabase | null;
+    protected dbName?: string;
+    protected dbPromise: Deferred<IDBDatabase>;
     constructor(dbName?: string);
-    private initDB;
-    private getDB;
+    protected initDB(): Promise<void>;
+    protected getDB(): Promise<IDBDatabase>;
     /**
      * Set the name of the database, loads a new database connection.
      * @param dbName - The new name of the database.
@@ -35,7 +36,7 @@ declare class IndexedDBStore implements PatchesStore {
      */
     close(): Promise<void>;
     deleteDB(): Promise<void>;
-    private transaction;
+    protected transaction(storeNames: string[], mode: IDBTransactionMode): Promise<[IDBTransactionWrapper, ...IDBStoreWrapper[]]>;
     /**
      * Rebuilds a document snapshot + pending queue *without* loading
      * the full PatchesDoc into memory.
@@ -113,6 +114,38 @@ declare class IndexedDBStore implements PatchesStore {
      *   - build new patch: newChange.rev = pendingRev; baseRev = committedRev
      */
     getLastRevs(docId: string): Promise<[number, number]>;
+    /**
+     * Gets the last revision that was attempted to be submitted to the server.
+     * @param docId - The ID of the document.
+     * @returns The last attempted submission revision, or undefined if none.
+     */
+    getLastAttemptedSubmissionRev(docId: string): Promise<number | undefined>;
+    /**
+     * Sets the last revision that was attempted to be submitted to the server.
+     * @param docId - The ID of the document.
+     * @param rev - The revision being submitted.
+     */
+    setLastAttemptedSubmissionRev(docId: string, rev: number): Promise<void>;
+}
+declare class IDBTransactionWrapper {
+    protected tx: IDBTransaction;
+    protected promise: Promise<void>;
+    constructor(tx: IDBTransaction);
+    getStore(name: string): IDBStoreWrapper;
+    complete(): Promise<void>;
+}
+declare class IDBStoreWrapper {
+    protected store: IDBObjectStore;
+    constructor(store: IDBObjectStore);
+    protected createRange(lower?: any, upper?: any): IDBKeyRange | undefined;
+    getAll<T>(lower?: any, upper?: any, count?: number): Promise<T[]>;
+    get<T>(key: IDBValidKey): Promise<T | undefined>;
+    put<T>(value: T): Promise<IDBValidKey>;
+    delete(key: IDBValidKey): Promise<void>;
+    delete(lower: any, upper: any): Promise<void>;
+    count(lower?: any, upper?: any): Promise<number>;
+    getFirstFromCursor<T>(lower?: any, upper?: any): Promise<T | undefined>;
+    getLastFromCursor<T>(lower?: any, upper?: any): Promise<T | undefined>;
 }
 
 export { IndexedDBStore };

package/dist/client/IndexedDBStore.js

@@ -297,6 +297,31 @@ class IndexedDBStore {
     await tx.complete();
     return [lastCommitted?.rev ?? 0, lastPending?.rev ?? lastCommitted?.rev ?? 0];
   }
+  // ─── Submission Bookmark ───────────────────────────────────────────────
+  /**
+   * Gets the last revision that was attempted to be submitted to the server.
+   * @param docId - The ID of the document.
+   * @returns The last attempted submission revision, or undefined if none.
+   */
+  async getLastAttemptedSubmissionRev(docId) {
+    const [tx, docsStore] = await this.transaction(["docs"], "readonly");
+    const docMeta = await docsStore.get(docId);
+    await tx.complete();
+    return docMeta?.lastAttemptedSubmissionRev;
+  }
+  /**
+   * Sets the last revision that was attempted to be submitted to the server.
+   * @param docId - The ID of the document.
+   * @param rev - The revision being submitted.
+   */
+  async setLastAttemptedSubmissionRev(docId, rev) {
+    const [tx, docsStore] = await this.transaction(["docs"], "readwrite");
+    const docMeta = await docsStore.get(docId);
+    if (docMeta) {
+      await docsStore.put({ ...docMeta, lastAttemptedSubmissionRev: rev });
+    }
+    await tx.complete();
+  }
 }
 _init = __decoratorStart(null);
 __decorateElement(_init, 1, "getDoc", _getDoc_dec, IndexedDBStore);

package/dist/client/PatchesStore.d.ts

@@ -10,6 +10,8 @@ interface TrackedDoc {
     committedRev: number;
     /** Optional flag indicating the document has been locally deleted. */
     deleted?: true;
+    /** The last revision that was attempted to be submitted to the server. */
+    lastAttemptedSubmissionRev?: number;
 }
 /**
  * Pluggable persistence layer contract used by Patches + PatchesSync.
@@ -217,6 +219,35 @@ interface PatchesStore {
      * // Store is no longer usable
      */
     close(): Promise<void>;
+    /**
+     * Gets the last revision that was attempted to be submitted to the server.
+     *
+     * This bookmark is used by change collapsing to avoid modifying changes that
+     * may have been partially committed by the server. Returns undefined if no
+     * submission has been attempted yet.
+     *
+     * @param docId Document identifier
+     * @returns The last attempted submission revision, or undefined if none
+     * @example
+     * const lastAttempted = await store.getLastAttemptedSubmissionRev('my-document');
+     * // Use this to protect changes from collapsing
+     */
+    getLastAttemptedSubmissionRev?(docId: string): Promise<number | undefined>;
+    /**
+     * Sets the last revision that was attempted to be submitted to the server.
+     *
+     * Called before sending changes to the server to mark them as "in flight".
+     * This prevents change collapsing from modifying these changes in case the
+     * server commits them but the client doesn't receive confirmation.
+     *
+     * @param docId Document identifier
+     * @param rev The revision being submitted
+     * @example
+     * // Before sending batch to server
+     * await store.setLastAttemptedSubmissionRev('my-document', lastChange.rev);
+     * await sendToServer(batch);
+     */
+    setLastAttemptedSubmissionRev?(docId: string, rev: number): Promise<void>;
 }
 
 export type { PatchesStore, TrackedDoc };

package/dist/client/index.d.ts

@@ -8,6 +8,7 @@ import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../json-patch/types.js';
+import '../utils/deferred.js';
 import '../event-signal.js';
 import '../algorithms/shared/changeBatching.js';
 import '../net/protocol/types.js';

package/dist/index.d.ts

@@ -26,5 +26,6 @@ export { move } from './json-patch/ops/move.js';
 export { remove } from './json-patch/ops/remove.js';
 export { replace } from './json-patch/ops/replace.js';
 export { test } from './json-patch/ops/test.js';
+import './utils/deferred.js';
 import './algorithms/shared/changeBatching.js';
 import './net/protocol/types.js';

package/dist/json-patch/JSONPatch.d.ts

@@ -10,8 +10,14 @@ import { JSONPatchOp, JSONPatchOpHandlerMap, ApplyJSONPatchOptions } from './typ
  * (c) 2022 Jacob Wright
  *
  *
- * WARNING: using /array/- syntax to indicate the end of the array makes it impossible to transform arrays correctly in
- * all situaions. Please avoid using this syntax when using Operational Transformations.
+ * NOTE ON ARRAY APPEND SYNTAX: The /array/- path syntax (append to end) has limitations with
+ * Operational Transformations. It's safe when:
+ * - The appended value won't be modified by subsequent operations, OR
+ * - The append commits to the server before any operations reference the item by index
+ *
+ * It causes problems when you append with /items/- then reference by index (e.g., /items/3/name)
+ * in uncommitted operations — the index can be transformed but the - cannot, causing them to
+ * target different items after concurrent changes. See docs/json-patch.md for details.
  */
 
 type PathLike = string | {

package/dist/json-patch/JSONPatch.js

@@ -8,8 +8,14 @@ import "../chunk-IZ2YBCUP.js";
  * (c) 2022 Jacob Wright
  *
  *
- * WARNING: using /array/- syntax to indicate the end of the array makes it impossible to transform arrays correctly in
- * all situaions. Please avoid using this syntax when using Operational Transformations.
+ * NOTE ON ARRAY APPEND SYNTAX: The /array/- path syntax (append to end) has limitations with
+ * Operational Transformations. It's safe when:
+ * - The appended value won't be modified by subsequent operations, OR
+ * - The append commits to the server before any operations reference the item by index
+ *
+ * It causes problems when you append with /items/- then reference by index (e.g., /items/3/name)
+ * in uncommitted operations — the index can be transformed but the - cannot, causing them to
+ * target different items after concurrent changes. See docs/json-patch.md for details.
  */
 import { Delta } from "@dabble/delta";
 import { applyPatch } from "./applyPatch.js";

package/dist/json-patch/ops/add.js

@@ -29,7 +29,12 @@ const add = {
       pluckWithShallowCopy(state, keys, true, true).splice(index, 0, value);
     } else {
       if (!deepEqual(target[lastKey], value)) {
-        pluckWithShallowCopy(state, keys, true, true)[lastKey] = value;
+        const container = pluckWithShallowCopy(state, keys, true, true);
+        if (Array.isArray(container) && lastKey === "-") {
+          container.push(value);
+        } else {
+          container[lastKey] = value;
+        }
       }
     }
   },

package/dist/json-patch/transformPatch.d.ts

@@ -9,8 +9,14 @@ import { JSONPatchOp, JSONPatchOpHandlerMap } from './types.js';
  * (c) 2022 Jacob Wright
  *
  *
- * WARNING: using /array/- syntax to indicate the end of the array makes it impossible to transform arrays correctly in
- * all situaions. Please avoid using this syntax when using Operational Transformations.
+ * NOTE ON ARRAY APPEND SYNTAX: The /array/- path syntax (append to end) has limitations with
+ * Operational Transformations. It's safe when:
+ * - The appended value won't be modified by subsequent operations, OR
+ * - The append commits to the server before any operations reference the item by index
+ *
+ * It causes problems when you append with /items/- then reference by index (e.g., /items/3/name)
+ * in uncommitted operations — the index can be transformed but the - cannot, causing them to
+ * target different items after concurrent changes. See docs/json-patch.md for details.
  */
 
 /**

package/dist/json-patch/transformPatch.js

@@ -8,8 +8,14 @@ import "../chunk-IZ2YBCUP.js";
  * (c) 2022 Jacob Wright
  *
  *
- * WARNING: using /array/- syntax to indicate the end of the array makes it impossible to transform arrays correctly in
- * all situaions. Please avoid using this syntax when using Operational Transformations.
+ * NOTE ON ARRAY APPEND SYNTAX: The /array/- path syntax (append to end) has limitations with
+ * Operational Transformations. It's safe when:
+ * - The appended value won't be modified by subsequent operations, OR
+ * - The append commits to the server before any operations reference the item by index
+ *
+ * It causes problems when you append with /items/- then reference by index (e.g., /items/3/name)
+ * in uncommitted operations — the index can be transformed but the - cannot, causing them to
+ * target different items after concurrent changes. See docs/json-patch.md for details.
  */
 import { getTypes } from "./ops/index.js";
 import { runWithObject } from "./state.js";

package/dist/json-patch/utils/pluck.js

@@ -17,8 +17,18 @@ function pluckWithShallowCopy(state, keys, createMissingObjects, createMissingAr
   let object = state.root;
   for (let i = 0, imax = keys.length - 1; i < imax; i++) {
     const key = keys[i];
-    const container = createMissingArrays && keys[i + 1] === "0" ? EMPTY_ARRAY : EMPTY;
-    object = object[key] = createMissingObjects && !object[key] ? getValue(state, container) : getValue(state, object[key]);
+    const container = createMissingArrays && (keys[i + 1] === "0" || keys[i + 1] === "-") ? EMPTY_ARRAY : EMPTY;
+    if (key === "-" && Array.isArray(object)) {
+      if (createMissingObjects && object.length === 0) {
+        const newItem = getValue(state, container);
+        object.push(newItem);
+        object = newItem;
+      } else {
+        object = getValue(state, object[object.length - 1]);
+      }
+    } else {
+      object = object[key] = createMissingObjects && !object[key] ? getValue(state, container) : getValue(state, object[key]);
+    }
   }
   return object;
 }

package/dist/net/PatchesSync.d.ts

@@ -134,14 +134,6 @@ declare class PatchesSync {
      * Helper to detect DOC_DELETED (410) errors from the server.
      */
     protected _isDocDeletedError(err: unknown): boolean;
-    /**
-     * Helper to detect "document already exists" errors from the server.
-     */
-    private _isDocExistsError;
-    /**
-     * Recovers from a "document already exists" error by fetching server state and retrying.
-     */
-    private _recoverFromDocExists;
 }
 
 export { PatchesSync, type PatchesSyncOptions, type PatchesSyncState };

package/dist/net/PatchesSync.js

@@ -8,6 +8,7 @@ import {
 var __receiveCommittedChanges_dec, _syncDoc_dec, _init;
 import { isEqual } from "@dabble/delta";
 import { applyCommittedChanges } from "../algorithms/client/applyCommittedChanges.js";
+import { collapsePendingChanges } from "../algorithms/client/collapsePendingChanges.js";
 import { breakChangesIntoBatches } from "../algorithms/shared/changeBatching.js";
 import { Patches } from "../client/Patches.js";
 import { signal } from "../event-signal.js";
@@ -217,6 +218,13 @@ class PatchesSync {
       if (!pending.length) {
         return;
       }
+      if (this.store.getLastAttemptedSubmissionRev && this.store.setLastAttemptedSubmissionRev) {
+        const afterRev = await this.store.getLastAttemptedSubmissionRev(docId);
+        pending = collapsePendingChanges(pending, afterRev);
+        if (!pending.length) {
+          return;
+        }
+      }
       const batches = breakChangesIntoBatches(pending, {
         maxPayloadBytes: this.maxPayloadBytes,
         maxStorageBytes: this.maxStorageBytes,
@@ -226,6 +234,10 @@ class PatchesSync {
         if (!this.state.connected) {
           throw new Error("Disconnected during flush");
         }
+        if (this.store.setLastAttemptedSubmissionRev) {
+          const lastRevInBatch = batch[batch.length - 1].rev;
+          await this.store.setLastAttemptedSubmissionRev(docId, lastRevInBatch);
+        }
         const range = [batch[0].rev, batch[batch.length - 1].rev];
         const committed = await this.ws.commitChanges(docId, batch);
         await this._applyServerChangesToDoc(docId, committed, range);
@@ -236,10 +248,6 @@ class PatchesSync {
         await this._handleRemoteDocDeleted(docId);
         return;
       }
-      if (this._isDocExistsError(err)) {
-        await this._recoverFromDocExists(docId);
-        return;
-      }
       console.error(`Flush failed for doc ${docId}:`, err);
       this.onError.emit(err, { docId });
       throw err;
@@ -368,23 +376,6 @@ class PatchesSync {
   _isDocDeletedError(err) {
     return typeof err === "object" && err !== null && "code" in err && err.code === 410;
   }
-  /**
-   * Helper to detect "document already exists" errors from the server.
-   */
-  _isDocExistsError(err) {
-    const message = err?.message ?? "";
-    return message.includes("already exists");
-  }
-  /**
-   * Recovers from a "document already exists" error by fetching server state and retrying.
-   */
-  async _recoverFromDocExists(docId) {
-    const serverChanges = await this.ws.getChangesSince(docId, 0);
-    const rebasedPending = await this._applyServerChangesToDoc(docId, serverChanges);
-    if (rebasedPending.length > 0) {
-      await this.flushDoc(docId, rebasedPending);
-    }
-  }
 }
 _init = __decoratorStart(null);
 __decorateElement(_init, 1, "syncDoc", _syncDoc_dec, PatchesSync);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.5.17",
+  "version": "0.5.18",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {