@loro-extended/change 5.2.0 → 5.4.0

package/dist/index.js

@@ -99,6 +99,11 @@ function deriveValueShapePlaceholder(shape) {
   }
 }
 
+// src/functional-helpers.ts
+import {
+  LoroDoc as LoroDoc2
+} from "loro-crdt";
+
 // src/loro.ts
 var LORO_SYMBOL = /* @__PURE__ */ Symbol.for("loro-extended:loro");
 function loro(refOrDoc) {
@@ -112,7 +117,9 @@ function loro(refOrDoc) {
 }
 
 // src/typed-doc.ts
-import { LoroDoc } from "loro-crdt";
+import {
+  LoroDoc
+} from "loro-crdt";
 
 // src/json-patch.ts
 function normalizePath(path) {
@@ -495,6 +502,7 @@ var BaseRefInternals = class {
   }
   cachedContainer;
   loroNamespace;
+  _suppressAutoCommit = false;
   /** Get the underlying Loro container (cached) */
   getContainer() {
     if (!this.cachedContainer) {
@@ -502,12 +510,23 @@ var BaseRefInternals = class {
     }
     return this.cachedContainer;
   }
-  /** Commit changes if autoCommit is enabled */
+  /** Commit changes if autoCommit is enabled and not suppressed */
   commitIfAuto() {
-    if (this.params.autoCommit) {
+    if (this.params.autoCommit && !this._suppressAutoCommit) {
       this.params.getDoc().commit();
     }
   }
+  /**
+   * Temporarily suppress auto-commit during batch operations.
+   * Used by assignPlainValueToTypedRef() to batch multiple property assignments.
+   */
+  setSuppressAutoCommit(suppress) {
+    this._suppressAutoCommit = suppress;
+  }
+  /** Check if auto-commit is currently suppressed */
+  isSuppressAutoCommit() {
+    return this._suppressAutoCommit;
+  }
   /** Get the shape for this ref */
   getShape() {
     return this.params.shape;
@@ -552,6 +571,10 @@ var BaseRefInternals = class {
     }
     return this.loroNamespace;
   }
+  /** Force materialization of the container and its nested containers */
+  materialize() {
+    this.getContainer();
+  }
   /** Create the loro() namespace object - subclasses override for specific types */
   createLoroNamespace() {
     const self = this;
@@ -722,17 +745,38 @@ function convertStructInput(value, shape) {
     return value;
   }
   const map = new LoroMap();
-  for (const [k, v] of Object.entries(value)) {
+  for (const k of Object.keys(shape.shapes)) {
     const nestedSchema = shape.shapes[k];
-    if (nestedSchema) {
+    const v = value[k];
+    if (v !== void 0) {
       const convertedValue = convertInputToRef(v, nestedSchema);
       if (isContainer(convertedValue)) {
         map.setContainer(k, convertedValue);
       } else {
         map.set(k, convertedValue);
       }
-    } else {
-      map.set(k, value);
+    } else if (isContainerShape(nestedSchema)) {
+      let emptyValue;
+      if (nestedSchema._type === "struct" || nestedSchema._type === "record") {
+        emptyValue = {};
+      } else if (nestedSchema._type === "list" || nestedSchema._type === "movableList") {
+        emptyValue = [];
+      } else if (nestedSchema._type === "text") {
+        emptyValue = "";
+      } else if (nestedSchema._type === "counter") {
+        emptyValue = 0;
+      }
+      if (emptyValue !== void 0) {
+        const convertedValue = convertInputToRef(emptyValue, nestedSchema);
+        if (isContainer(convertedValue)) {
+          map.setContainer(k, convertedValue);
+        }
+      }
+    }
+  }
+  for (const [k, v] of Object.entries(value)) {
+    if (!shape.shapes[k]) {
+      map.set(k, v);
     }
   }
   return map;
@@ -1368,7 +1412,6 @@ var RecordRefInternals = class extends BaseRefInternals {
     } else {
       const ref = this.getOrCreateRef(key);
       if (assignPlainValueToTypedRef(ref, value)) {
-        this.commitIfAuto();
         return;
       }
       throw new Error(
@@ -1383,6 +1426,80 @@ var RecordRefInternals = class extends BaseRefInternals {
     this.refCache.delete(key);
     this.commitIfAuto();
   }
+  /**
+   * Replace entire contents with new values.
+   * Keys not in `values` are removed.
+   */
+  replace(values) {
+    const container = this.getContainer();
+    const currentKeys = new Set(container.keys());
+    const newKeys = new Set(Object.keys(values));
+    const wasSuppressed = this.isSuppressAutoCommit();
+    if (!wasSuppressed) {
+      this.setSuppressAutoCommit(true);
+    }
+    try {
+      for (const key of currentKeys) {
+        if (!newKeys.has(key)) {
+          container.delete(key);
+          this.refCache.delete(key);
+        }
+      }
+      for (const key of newKeys) {
+        this.set(key, values[key]);
+      }
+    } finally {
+      if (!wasSuppressed) {
+        this.setSuppressAutoCommit(false);
+      }
+    }
+    this.commitIfAuto();
+  }
+  /**
+   * Merge values into record.
+   * Existing keys not in `values` are kept.
+   */
+  merge(values) {
+    const wasSuppressed = this.isSuppressAutoCommit();
+    if (!wasSuppressed) {
+      this.setSuppressAutoCommit(true);
+    }
+    try {
+      for (const key of Object.keys(values)) {
+        this.set(key, values[key]);
+      }
+    } finally {
+      if (!wasSuppressed) {
+        this.setSuppressAutoCommit(false);
+      }
+    }
+    this.commitIfAuto();
+  }
+  /**
+   * Remove all entries from the record.
+   */
+  clear() {
+    const container = this.getContainer();
+    const keys = container.keys();
+    if (keys.length === 0) {
+      return;
+    }
+    const wasSuppressed = this.isSuppressAutoCommit();
+    if (!wasSuppressed) {
+      this.setSuppressAutoCommit(true);
+    }
+    try {
+      for (const key of keys) {
+        container.delete(key);
+        this.refCache.delete(key);
+      }
+    } finally {
+      if (!wasSuppressed) {
+        this.setSuppressAutoCommit(false);
+      }
+    }
+    this.commitIfAuto();
+  }
   /** Absorb mutated plain values back into Loro containers */
   absorbPlainValues() {
     absorbCachedPlainValues(this.refCache, () => this.getContainer());
@@ -1447,14 +1564,77 @@ var RecordRef = class extends TypedRef {
     const container = this[INTERNAL_SYMBOL].getContainer();
     return container.keys();
   }
+  /**
+   * Returns an array of all values in the record.
+   * For container-valued records, returns properly typed refs.
+   */
   values() {
-    const container = this[INTERNAL_SYMBOL].getContainer();
-    return container.values();
+    return this.keys().map(
+      (key) => this.get(key)
+    );
+  }
+  /**
+   * Returns an array of [key, value] pairs.
+   * For container-valued records, values are properly typed refs.
+   */
+  entries() {
+    return this.keys().map((key) => [
+      key,
+      this.get(key)
+    ]);
   }
   get size() {
     const container = this[INTERNAL_SYMBOL].getContainer();
     return container.size;
   }
+  /**
+   * Replace entire contents with new values.
+   * Keys not in `values` are removed.
+   *
+   * @example
+   * ```typescript
+   * doc.change(draft => {
+   *   draft.players.replace({
+   *     alice: { score: 100 },
+   *     bob: { score: 50 }
+   *   })
+   * })
+   * ```
+   */
+  replace(values) {
+    this[INTERNAL_SYMBOL].replace(values);
+  }
+  /**
+   * Merge values into record.
+   * Existing keys not in `values` are kept.
+   *
+   * @example
+   * ```typescript
+   * doc.change(draft => {
+   *   // Adds charlie, updates alice, keeps bob unchanged
+   *   draft.players.merge({
+   *     alice: { score: 150 },
+   *     charlie: { score: 25 }
+   *   })
+   * })
+   * ```
+   */
+  merge(values) {
+    this[INTERNAL_SYMBOL].merge(values);
+  }
+  /**
+   * Remove all entries from the record.
+   *
+   * @example
+   * ```typescript
+   * doc.change(draft => {
+   *   draft.players.clear()
+   * })
+   * ```
+   */
+  clear() {
+    this[INTERNAL_SYMBOL].clear();
+  }
   toJSON() {
     return serializeRefToJSON(this, this.keys());
   }
@@ -1543,7 +1723,6 @@ var StructRefInternals = class extends BaseRefInternals {
     } else {
       const ref = this.getOrCreateRef(key, shape);
       if (assignPlainValueToTypedRef(ref, value)) {
-        this.commitIfAuto();
         return;
       }
       throw new Error(
@@ -1565,6 +1744,18 @@ var StructRefInternals = class extends BaseRefInternals {
       () => this.getContainer()
     );
   }
+  /** Force materialization of the container and its nested containers */
+  materialize() {
+    this.getContainer();
+    const structShape = this.getShape();
+    for (const key in structShape.shapes) {
+      const shape = structShape.shapes[key];
+      if (!isValueShape(shape)) {
+        const ref = this.getOrCreateRef(key, shape);
+        ref[INTERNAL_SYMBOL].materialize();
+      }
+    }
+  }
   /** Create the loro namespace for struct */
   createLoroNamespace() {
     const self = this;
@@ -1920,6 +2111,11 @@ var TreeNodeRefInternals = class {
       this.dataRef[INTERNAL_SYMBOL].absorbPlainValues();
     }
   }
+  /** Force materialization of the container and its nested containers */
+  materialize() {
+    const dataRef = this.getOrCreateDataRef();
+    dataRef[INTERNAL_SYMBOL].materialize();
+  }
   /** Get the loro namespace (cached) */
   getLoroNamespace() {
     if (!this.loroNamespace) {
@@ -2371,24 +2567,54 @@ function createContainerTypedRef(params) {
       );
   }
 }
-function assignPlainValueToTypedRef(ref, value) {
-  const shape = ref[INTERNAL_SYMBOL]?.getShape?.() ?? ref.shape;
+function assignPlainValueToTypedRef(ref, value, skipCommit = false) {
+  const internals = ref[INTERNAL_SYMBOL];
+  if (internals) {
+    internals.materialize();
+  }
+  const shape = internals?.getShape?.() ?? ref.shape;
   const shapeType = shape?._type;
   if (shapeType === "struct" || shapeType === "record") {
-    for (const k in value) {
-      ;
-      ref[k] = value[k];
+    const wasSuppressed = internals?.isSuppressAutoCommit?.() ?? false;
+    if (internals && !wasSuppressed) {
+      internals.setSuppressAutoCommit(true);
+    }
+    try {
+      for (const k in value) {
+        ;
+        ref[k] = value[k];
+      }
+    } finally {
+      if (internals && !wasSuppressed) {
+        internals.setSuppressAutoCommit(false);
+      }
+    }
+    if (!skipCommit && internals?.getAutoCommit?.()) {
+      internals.getDoc().commit();
     }
     return true;
   }
   if (shapeType === "list" || shapeType === "movableList") {
     if (Array.isArray(value)) {
       const listRef = ref;
-      if (listRef.length > 0) {
-        listRef.delete(0, listRef.length);
+      const wasSuppressed = internals?.isSuppressAutoCommit?.() ?? false;
+      if (internals && !wasSuppressed) {
+        internals.setSuppressAutoCommit(true);
+      }
+      try {
+        if (listRef.length > 0) {
+          listRef.delete(0, listRef.length);
+        }
+        for (const item of value) {
+          listRef.push(item);
+        }
+      } finally {
+        if (internals && !wasSuppressed) {
+          internals.setSuppressAutoCommit(false);
+        }
       }
-      for (const item of value) {
-        listRef.push(item);
+      if (!skipCommit && internals?.getAutoCommit?.()) {
+        internals.getDoc().commit();
       }
       return true;
     }
@@ -2861,9 +3087,10 @@ function createTypedDoc(shape, existingDoc) {
         return true;
       return Reflect.has(target, prop);
     },
-    // Support Object.keys() - don't include change, forkAt, or LORO_SYMBOL in enumeration
+    // Support Object.keys() - filter out Symbol properties to allow proxies to be used
+    // in place of plain objects. This prevents React's "Object keys must be strings" error.
     ownKeys(target) {
-      return Reflect.ownKeys(target);
+      return Reflect.ownKeys(target).filter((key) => typeof key === "string");
     },
     getOwnPropertyDescriptor(target, prop) {
       if (prop === "change") {
@@ -2927,12 +3154,34 @@ function getLoroDoc(docOrRef) {
 function getLoroContainer(ref) {
   return loro(ref).container;
 }
+function fork(doc, options) {
+  const loroDoc = loro(doc).doc;
+  const forkedLoroDoc = loroDoc.fork();
+  const shape = loro(doc).docShape;
+  if (options?.preservePeerId) {
+    forkedLoroDoc.setPeerId(loroDoc.peerId);
+  }
+  return createTypedDoc(shape, forkedLoroDoc);
+}
 function forkAt(doc, frontiers) {
   const loroDoc = loro(doc).doc;
   const forkedLoroDoc = loroDoc.forkAt(frontiers);
   const shape = loro(doc).docShape;
   return createTypedDoc(shape, forkedLoroDoc);
 }
+function shallowForkAt(doc, frontiers, options) {
+  const loroDoc = loro(doc).doc;
+  const shape = loro(doc).docShape;
+  const shallowBytes = loroDoc.export({
+    mode: "shallow-snapshot",
+    frontiers
+  });
+  const shallowLoroDoc = LoroDoc2.fromSnapshot(shallowBytes);
+  if (options?.preservePeerId) {
+    shallowLoroDoc.setPeerId(loroDoc.peerId);
+  }
+  return createTypedDoc(shape, shallowLoroDoc);
+}
 
 // src/path-builder.ts
 function createPathSelector(segments) {
@@ -3104,6 +3353,134 @@ function createPlaceholderProxy(target) {
   });
 }
 
+// src/replay-diff.ts
+function replayDiff(doc, diff) {
+  const containerMap = /* @__PURE__ */ new Map();
+  for (const [containerId, containerDiff] of diff) {
+    let container = containerMap.get(containerId);
+    if (!container) {
+      container = doc.getContainerById(containerId);
+    }
+    if (!container) {
+      continue;
+    }
+    switch (containerDiff.type) {
+      case "text":
+        replayTextDiff(container, containerDiff);
+        break;
+      case "list":
+        replayListDiff(
+          container,
+          containerDiff,
+          containerMap
+        );
+        break;
+      case "map":
+        replayMapDiff(container, containerDiff, containerMap);
+        break;
+      case "tree":
+        replayTreeDiff(container, containerDiff);
+        break;
+      case "counter":
+        replayCounterDiff(container, containerDiff);
+        break;
+    }
+  }
+}
+function replayTextDiff(text, diff) {
+  text.applyDelta(diff.diff);
+}
+function replayListDiff(list, diff, containerMap) {
+  let index = 0;
+  for (const delta of diff.diff) {
+    if (delta.retain !== void 0) {
+      index += delta.retain;
+    } else if (delta.delete !== void 0) {
+      list.delete(index, delta.delete);
+    } else if (delta.insert !== void 0) {
+      const values = delta.insert;
+      for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+        if (isContainer2(value)) {
+          const newContainer = createContainerOfSameType(value);
+          const insertedContainer = list.insertContainer(
+            index + i,
+            newContainer
+          );
+          containerMap.set(value.id, insertedContainer);
+        } else {
+          ;
+          list.insert(
+            index + i,
+            value
+          );
+        }
+      }
+      index += values.length;
+    }
+  }
+}
+function replayMapDiff(map, diff, containerMap) {
+  for (const [key, value] of Object.entries(diff.updated)) {
+    if (value === void 0) {
+      map.delete(key);
+    } else if (isContainer2(value)) {
+      const newContainer = createContainerOfSameType(value);
+      const insertedContainer = map.setContainer(key, newContainer);
+      containerMap.set(value.id, insertedContainer);
+    } else {
+      map.set(key, value);
+    }
+  }
+}
+function replayTreeDiff(tree, diff) {
+  for (const item of diff.diff) {
+    replayTreeDiffItem(tree, item);
+  }
+}
+function replayTreeDiffItem(tree, item) {
+  switch (item.action) {
+    case "create":
+      tree.createNode(item.parent, item.index);
+      break;
+    case "delete":
+      tree.delete(item.target);
+      break;
+    case "move":
+      tree.move(item.target, item.parent, item.index);
+      break;
+  }
+}
+function replayCounterDiff(counter, diff) {
+  if (diff.increment > 0) {
+    counter.increment(diff.increment);
+  } else if (diff.increment < 0) {
+    counter.decrement(-diff.increment);
+  }
+}
+function isContainer2(value) {
+  return value !== null && typeof value === "object" && "kind" in value && typeof value.kind === "function";
+}
+function createContainerOfSameType(container) {
+  const kind = container.kind();
+  switch (kind) {
+    case "List":
+      return new container.constructor();
+    case "Map":
+      return new container.constructor();
+    case "Text":
+      return new container.constructor();
+    case "Tree":
+      return new container.constructor();
+    case "Counter":
+      return new container.constructor();
+    case "MovableList":
+      return new container.constructor();
+    default:
+      throw new Error(`Unknown container kind: ${kind}`);
+  }
+}
+
 // src/shape.ts
 function makeNullable(shape) {
   const nullShape = {
@@ -3543,6 +3920,7 @@ export {
   deriveShapePlaceholder,
   evaluatePath,
   evaluatePathOnValue,
+  fork,
   forkAt,
   getLoroContainer,
   getLoroDoc,
@@ -3550,6 +3928,8 @@ export {
   loro,
   mergeValue,
   overlayPlaceholder,
+  replayDiff,
+  shallowForkAt,
   validatePlaceholder
 };
 //# sourceMappingURL=index.js.map