reptree 0.1.5 → 0.2.1

package/README.md

@@ -8,9 +8,10 @@ A tree data structure using CRDTs for seamless replication between peers.
 
 ## Description
 
-RepTree uses 2 conflict-free replicated data types (CRDTs) to manage seamless replication between peers:
+RepTree uses multiple conflict-free replicated data types (CRDTs) to manage seamless replication between peers:
 - A move tree CRDT is used for the tree structure (https://martin.kleppmann.com/papers/move-op.pdf).
 - A last writer wins (LWW) CRDT is used for properties.
+- Yjs integration for collaborative editing with various shared data types (Text, Array, Map, XML).
 
 RepTree can also be viewed as a hierarchical, distributed database. For more details on its database capabilities, see [RepTree as a Database](docs/database.md).
 
@@ -73,6 +74,51 @@ const ops = tree.getAllOps();
 otherTree.merge(ops);
 ```
 
+## Yjs Integration
+
+RepTree supports [Yjs](https://github.com/yjs/yjs) documents as vertex properties, enabling real-time collaborative editing with a variety of shared data types:
+
+```typescript
+import { RepTree } from 'reptree';
+import * as Y from 'yjs';
+
+// Create a tree with a root vertex
+const tree = new RepTree('peer1');
+const root = tree.createRoot();
+
+// Create a Yjs document
+const ydoc = new Y.Doc();
+const ytext = ydoc.getText('default');
+ytext.insert(0, 'Hello world');
+
+// Set the Yjs document as a property
+root.setProperty('content', ydoc);
+
+// Later, retrieve and modify the document
+const retrievedDoc = root.getProperty('content') as Y.Doc;
+retrievedDoc.getText('default').insert(retrievedDoc.getText('default').length, '!');
+
+// Sync operations with another tree
+const tree2 = new RepTree('peer2');
+tree2.merge(tree.popLocalOps());
+
+// Both trees now have the same Yjs document content
+const root2 = tree2.root;
+const doc2 = root2.getProperty('content') as Y.Doc;
+console.log(doc2.getText('default').toString()); // 'Hello world!'
+```
+
+This integration allows for:
+- Collaborative editing with multiple shared data types:
+  - **Y.Text** - For rich text editing with formatting attributes
+  - **Y.Array** - For ordered collections of data
+  - **Y.Map** - For key-value pairs and structured data
+  - **Y.XmlFragment/Y.XmlElement** - For XML-like structured content
+- Complex nested data structures (arrays within maps, maps within arrays, etc.)
+- Automatic CRDT synchronization between peers
+- Conflict-free concurrent editing
+- Integration with existing Yjs ecosystem (editors, frameworks, etc.)
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -26,8 +36,10 @@ __export(index_exports, {
   TreeState: () => TreeState,
   Vertex: () => Vertex,
   VertexState: () => VertexState,
+  isAnyPropertyOp: () => isAnyPropertyOp,
+  isLWWPropertyOp: () => isLWWPropertyOp,
+  isModifyPropertyOp: () => isModifyPropertyOp,
   isMoveVertexOp: () => isMoveVertexOp,
-  isSetPropertyOp: () => isSetPropertyOp,
   newMoveVertexOp: () => newMoveVertexOp,
   newSetTransientVertexPropertyOp: () => newSetTransientVertexPropertyOp,
   newSetVertexPropertyOp: () => newSetVertexPropertyOp,
@@ -89,9 +101,15 @@ var OpId = class _OpId {
 function isMoveVertexOp(op) {
   return "parentId" in op;
 }
-function isSetPropertyOp(op) {
+function isAnyPropertyOp(op) {
   return "key" in op;
 }
+function isLWWPropertyOp(op) {
+  return "key" in op && "value" in op && (!op.value || typeof op.value !== "object" || !("type" in op.value));
+}
+function isModifyPropertyOp(op) {
+  return "key" in op && "value" in op && typeof op.value === "object" && op.value !== null && "type" in op.value;
+}
 function newMoveVertexOp(clock, peerId, targetId, parentId) {
   return { id: new OpId(clock, peerId), targetId, parentId };
 }
@@ -694,6 +712,7 @@ var StateVector = class _StateVector {
 };
 
 // src/RepTree.ts
+var Y = __toESM(require("yjs"), 1);
 var _RepTree = class _RepTree {
   /**
    * @param peerId - The peer ID of the current client. Should be unique across all peers.
@@ -705,13 +724,13 @@ var _RepTree = class _RepTree {
     this.setPropertyOps = [];
     this.propertiesAndTheirOpIds = /* @__PURE__ */ new Map();
     this.transientPropertiesAndTheirOpIds = /* @__PURE__ */ new Map();
+    this.yjsObservers = /* @__PURE__ */ new Map();
     this.localOps = [];
     this.pendingMovesWithMissingParent = /* @__PURE__ */ new Map();
     this.pendingPropertiesWithMissingVertex = /* @__PURE__ */ new Map();
     this.knownOps = /* @__PURE__ */ new Set();
     this.parentIdBeforeMove = /* @__PURE__ */ new Map();
     this.opAppliedCallbacks = [];
-    this.maxDepth = _RepTree.DEFAULT_MAX_DEPTH;
     this._stateVectorEnabled = true;
     this.peerId = peerId;
     this.state = new TreeState();
@@ -743,6 +762,9 @@ var _RepTree = class _RepTree {
     }
     return new Vertex(this, rootVertex);
   }
+  replicate(newPeerId) {
+    return new _RepTree(newPeerId, this.getAllOps());
+  }
   getMoveOps() {
     return this.moveOps;
   }
@@ -795,14 +817,15 @@ var _RepTree = class _RepTree {
     }
     return vertex.getAllProperties();
   }
+  /**
+   * Returns all local operations and clears the local operations list.
+   * Can be used to get all operations that were generated from this peer and need to be sent to other peers.
+   */
   popLocalOps() {
     const ops = this.localOps;
     this.localOps = [];
     return ops;
   }
-  setMaxDepth(maxDepth) {
-    this.maxDepth = maxDepth;
-  }
   createRoot() {
     if (this.rootVertexId) {
       throw new Error("Root vertex already exists");
@@ -850,13 +873,35 @@ var _RepTree = class _RepTree {
   }
   setTransientVertexProperty(vertexId, key, value) {
     this.lamportClock++;
-    const op = newSetTransientVertexPropertyOp(this.lamportClock, this.peerId, vertexId, key, value);
+    let opValue;
+    if (value instanceof Y.Doc) {
+      const state = Y.encodeStateAsUpdate(value);
+      opValue = {
+        type: "yjs",
+        value: state
+      };
+      this.setupYjsObserver(value, vertexId, key);
+    } else {
+      opValue = value;
+    }
+    const op = newSetTransientVertexPropertyOp(this.lamportClock, this.peerId, vertexId, key, opValue);
     this.localOps.push(op);
     this.applyProperty(op);
   }
   setVertexProperty(vertexId, key, value) {
     this.lamportClock++;
-    const op = newSetVertexPropertyOp(this.lamportClock, this.peerId, vertexId, key, value);
+    let opValue;
+    if (value instanceof Y.Doc) {
+      const state = Y.encodeStateAsUpdate(value);
+      opValue = {
+        type: "yjs",
+        value: state
+      };
+      this.setupYjsObserver(value, vertexId, key);
+    } else {
+      opValue = value;
+    }
+    const op = newSetVertexPropertyOp(this.lamportClock, this.peerId, vertexId, key, opValue);
     this.localOps.push(op);
     this.applyProperty(op);
   }
@@ -902,6 +947,14 @@ var _RepTree = class _RepTree {
   merge(ops) {
     this.applyOps(ops);
   }
+  applyOps(ops) {
+    for (const op of ops) {
+      if (this.knownOps.has(op.id.toString())) {
+        continue;
+      }
+      this.applyOperation(op);
+    }
+  }
   /** Applies operations in an optimized way, sorting move ops by OpId to avoid undo-do-redo cycles */
   applyOpsOptimizedForLotsOfMoves(ops) {
     const newMoveOps = ops.filter((op) => isMoveVertexOp(op) && !this.knownOps.has(op.id.toString()));
@@ -913,7 +966,7 @@ var _RepTree = class _RepTree {
         this.applyMove(op);
       }
     }
-    const propertyOps = ops.filter((op) => isSetPropertyOp(op) && !this.knownOps.has(op.id.toString()));
+    const propertyOps = ops.filter((op) => isAnyPropertyOp(op) && !this.knownOps.has(op.id.toString()));
     for (let i = 0, len = propertyOps.length; i < len; i++) {
       const op = propertyOps[i];
       this.applyProperty(op);
@@ -945,16 +998,16 @@ var _RepTree = class _RepTree {
   isAncestor(childId, ancestorId) {
     let targetId = childId;
     let vertex;
-    let depth = 0;
+    const visitedVertices = /* @__PURE__ */ new Set();
     while (vertex = this.state.getVertex(targetId)) {
       if (vertex.parentId === ancestorId) return true;
       if (!vertex.parentId) return false;
-      if (depth > this.maxDepth) {
-        console.error(`isAncestor: max depth of ${this.maxDepth} reached. Perhaps, we have an infinite loop here.`);
-        return true;
+      if (visitedVertices.has(targetId)) {
+        console.error(`isAncestor: cycle detected in the tree structure.`);
+        return false;
       }
+      visitedVertices.add(targetId);
       targetId = vertex.parentId;
-      depth++;
     }
     return false;
   }
@@ -1008,7 +1061,16 @@ var _RepTree = class _RepTree {
       }
       for (const propA of propertiesA) {
         const propB = propertiesB.find((p) => p.key === propA.key);
-        if (!propB || propA.value !== propB.value) {
+        if (!propB) {
+          return false;
+        }
+        if (propA.value instanceof Y.Doc && propB.value instanceof Y.Doc) {
+          const snapshotA = Y.snapshot(propA.value);
+          const snapshotB = Y.snapshot(propB.value);
+          if (!Y.equalSnapshots(snapshotA, snapshotB)) {
+            return false;
+          }
+        } else if (propA.value !== propB.value) {
           return false;
         }
       }
@@ -1095,7 +1157,7 @@ var _RepTree = class _RepTree {
     }
     this.applyPendingMovesForParent(op.targetId);
   }
-  setPropertyAndItsOpId(op) {
+  setLLWPropertyAndItsOpId(op) {
     this.propertiesAndTheirOpIds.set(`${op.key}@${op.targetId}`, op.id);
     this.state.setProperty(op.targetId, op.key, op.value);
     this.reportOpAsApplied(op);
@@ -1105,6 +1167,40 @@ var _RepTree = class _RepTree {
     this.state.setTransientProperty(op.targetId, op.key, op.value);
     this.reportOpAsApplied(op);
   }
+  setupYjsObserver(doc, vertexId, key) {
+    const propertyKey = `${key}@${vertexId}`;
+    if (this.yjsObservers.has(propertyKey)) {
+      const existingDoc = this.getVertexProperty(vertexId, key);
+      if (existingDoc instanceof Y.Doc) {
+        existingDoc.off("update", this.yjsObservers.get(propertyKey));
+      }
+      this.yjsObservers.delete(propertyKey);
+    }
+    const ydocObserver = (update, origin, doc2, transaction) => {
+      if (!transaction.local) {
+        return;
+      }
+      const crdtValue = {
+        type: "yjs",
+        value: update
+      };
+      this.lamportClock++;
+      const op = newSetVertexPropertyOp(
+        this.lamportClock,
+        this.peerId,
+        vertexId,
+        key,
+        crdtValue
+      );
+      this.localOps.push(op);
+      this.applyProperty(op);
+      if (this._stateVectorEnabled) {
+        this.stateVector.updateFromOp(op);
+      }
+    };
+    doc.on("update", ydocObserver);
+    this.yjsObservers.set(propertyKey, ydocObserver);
+  }
   applyProperty(op) {
     const targetVertex = this.state.getVertex(op.targetId);
     if (!targetVertex) {
@@ -1118,13 +1214,19 @@ var _RepTree = class _RepTree {
       return;
     }
     this.updateLamportClock(op);
+    if (isModifyPropertyOp(op)) {
+      this.applyModifyProperty(op, targetVertex);
+    } else {
+      this.applyLLWProperty(op, targetVertex);
+    }
+  }
+  applyLLWProperty(op, targetVertex) {
     const prevTransientOpId = this.transientPropertiesAndTheirOpIds.get(`${op.key}@${op.targetId}`);
-    const prevProp = targetVertex.getProperty(op.key);
     const prevOpId = this.propertiesAndTheirOpIds.get(`${op.key}@${op.targetId}`);
     if (!op.transient) {
       this.setPropertyOps.push(op);
-      if (!prevProp || !prevOpId || op.id.isGreaterThan(prevOpId)) {
-        this.setPropertyAndItsOpId(op);
+      if (!prevOpId || op.id.isGreaterThan(prevOpId)) {
+        this.setLLWPropertyAndItsOpId(op);
       } else {
         this.knownOps.add(op.id.toString());
       }
@@ -1138,16 +1240,33 @@ var _RepTree = class _RepTree {
       }
     }
   }
-  applyOps(ops) {
-    for (const op of ops) {
-      if (this.knownOps.has(op.id.toString())) {
-        continue;
-      }
-      if (isMoveVertexOp(op)) {
-        this.applyMove(op);
-      } else if (isSetPropertyOp(op)) {
-        this.applyProperty(op);
-      }
+  applyModifyProperty(op, targetVertex) {
+    if (op.transient) {
+      console.warn("Not implemented: transient non LWW property");
+      return;
+    }
+    this.setPropertyOps.push(op);
+    const crdtValue = op.value;
+    if (crdtValue.type !== "yjs") {
+      throw new Error("Unknown CRDT type");
+    }
+    const ydoc = targetVertex.getProperty(op.key);
+    if (ydoc instanceof Y.Doc) {
+      Y.applyUpdate(ydoc, crdtValue.value);
+    } else {
+      const newDoc = new Y.Doc();
+      this.setupYjsObserver(newDoc, op.targetId, op.key);
+      this.state.setProperty(op.targetId, op.key, newDoc);
+      Y.applyUpdate(newDoc, crdtValue.value);
+    }
+    this.propertiesAndTheirOpIds.set(`${op.key}@${op.targetId}`, op.id);
+    this.reportOpAsApplied(op);
+  }
+  applyOperation(op) {
+    if (isMoveVertexOp(op)) {
+      this.applyMove(op);
+    } else if (isAnyPropertyOp(op)) {
+      this.applyProperty(op);
     }
   }
   reportOpAsApplied(op) {
@@ -1246,7 +1365,6 @@ var _RepTree = class _RepTree {
   }
 };
 _RepTree.NULL_VERTEX_ID = "0";
-_RepTree.DEFAULT_MAX_DEPTH = 1e5;
 var RepTree = _RepTree;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -1256,8 +1374,10 @@ var RepTree = _RepTree;
   TreeState,
   Vertex,
   VertexState,
+  isAnyPropertyOp,
+  isLWWPropertyOp,
+  isModifyPropertyOp,
   isMoveVertexOp,
-  isSetPropertyOp,
   newMoveVertexOp,
   newSetTransientVertexPropertyOp,
   newSetVertexPropertyOp,