reptree 0.4.0 → 0.5.0

package/README.md

@@ -1,98 +1,97 @@
-# RepTree
+# RepTree - replicated trees with properties
 
-A tree data structure using CRDTs for seamless replication between peers.
+A JavaScript tree data structure for storing and syncing app state. It can be used both to represent and persist the state in the frontend and backend.
 
-> 🚧 **Work in Progress**: This package is under active development and APIs may change.
->
-> RepTree was created for the [Supa](https://github.com/supaorg/supa) project, an open-source alternative to ChatGPT.
+RepTree uses [CRDTs](https://crdt.tech/) for seamless replication between users.
 
-## Description
+> RepTree was created for the [Sila](https://github.com/silaorg/sila) project, an open-source alternative to ChatGPT.
 
-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).
+## What it solves
 
-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).
+If you have a tree structure in your app where each vertex/node/leaf can be moved independently by multiple users, you need a solution that resolves conflicts when the same vertex is moved in different ways. Otherwise your tree can diverge or form loops. This includes folder structures (people creating and moving folders), 2D/3D scenes with objects being moved and parented, and Notion‑like documents where blocks with text and other properties are edited by users.
 
-## Installation
+You probably also want properties on each vertex/node/leaf and to have them sync correctly between peers without conflicts. RepTree syncs properties too.
+
+## Getting started
 
 ```bash
 npm install reptree
 ```
 
-## Usage
-
-### Reactive vertex with Zod (optional)
-
+### Example 1 
 ```ts
-import { RepTree } from 'reptree';
-import { z } from 'zod';
+import { RepTree } from "reptree";
 
-const tree = new RepTree('peer1');
-const root = tree.createRoot();
-const v = root.newChild();
-
-const Person = z.object({ name: z.string(), age: z.number().int().min(0) });
+// Create a tree with a root
+const tree = new RepTree("company-org-1");
+const company = tree.createRoot();
 
-const person = v.bind(Person);
+// Create a node (we call them vertices in RepTree) in the root of our new tree
+const devs = company.newNamedChild("developers");
+const qa = company.newNamedChild("qa");
 
-person.name = 'Alice'; // validated and persisted
-person.age = 33;       // validated and persisted
-```
+// Create a vertex in another vertex
+const alice = qa.newChild();
 
-#### Aliases for internal fields
+// Set properties
+alice.setProperty("name", "Alice");
+alice.setProperty("age", 32);
 
-- `name` ↔ `_n`
-- `createdAt` ↔ `_c` (Date exposed, ISO stored)
+// Move the vertex inside a different vertex
+alice.moveTo(devs);
 
-These aliases are applied by default when using `vertex.bind()`.
+// Bind a vertex to a type to set its properties like regular fields
+const bob = qa.newChild().bind<{ name: string; age: number }>();
+bob.name = "Bob";
+bob.age = 33;
 
-```ts
-person.name = 'Alice';          // writes _n
-person.createdAt = new Date();  // writes _c (ISO)
-console.log(person.createdAt instanceof Date); // true
+// Use a Zod type for runtime type checks
+import { z } from "zod";
+const Person = z.object({ name: z.string(), age: z.number().int().min(0) });
+const casey = devs.newNamedChild("Casey").bind(Person);
+casey.name = "Casey";
+casey.age = 34;
 ```
 
-For more, see `docs/reactive-vertices.md`. 
+### Example 2
 
 ```typescript
-import { RepTree } from 'reptree';
+import { RepTree } from "reptree";
 
 // Create a new tree
-const tree = new RepTree('peer1');
+const tree = new RepTree("peer1");
 const root = tree.createRoot();
-root.name = 'Project';
+root.name = "Project";
 
 // Create a folder structure with properties
-const docsFolder = root.newNamedChild('Docs');
+const docsFolder = root.newNamedChild("Docs");
 docsFolder.setProperties({
-  type: 'folder',
-  icon: 'folder-icon'
+  type: "folder",
+  icon: "folder-icon",
 });
 
-const imagesFolder = root.newNamedChild('Images');
+const imagesFolder = root.newNamedChild("Images");
 imagesFolder.setProperties({
-  type: 'folder',
-  icon: 'image-icon'
+  type: "folder",
+  icon: "image-icon",
 });
 
 // Add files to folders
-const readmeFile = docsFolder.newNamedChild('README.md');
+const readmeFile = docsFolder.newNamedChild("README.md");
 readmeFile.setProperties({
-  type: 'file',
+  type: "file",
   size: 2048,
-  lastModified: '2023-10-15T14:22:10Z',
-  s3Path: 's3://my-bucket/docs/README.md'
+  lastModified: "2023-10-15T14:22:10Z",
+  s3Path: "s3://my-bucket/docs/README.md",
 });
 
-const logoFile = imagesFolder.newNamedChild('logo.png');
+const logoFile = imagesFolder.newNamedChild("logo.png");
 logoFile.setProperties({
-  type: 'file',
+  type: "file",
   size: 15360,
-  dimensions: '512x512',
-  format: 'png',
-  s3Path: 's3://my-bucket/images/logo.png'
+  dimensions: "512x512",
+  format: "png",
+  s3Path: "s3://my-bucket/images/logo.png",
 });
 
 // Move a file to a different folder
@@ -102,65 +101,17 @@ logoFile.moveTo(docsFolder);
 const docsFolderContents = docsFolder.children;
 
 // Syncing between trees
-const otherTree = new RepTree('peer2');
+const otherTree = new RepTree("peer2");
 const ops = tree.getAllOps();
 otherTree.merge(ops);
 ```
 
-### Creating children with normalized props
-
-`vertex.newChild(props)` and `vertex.newNamedChild(name, props)` accept plain objects. RepTree will:
-
-- Map `name` → `_n`, `createdAt` (Date) → `_c` (ISO)
-- Filter unsupported types (non-primitive objects except Y.Doc)
-- Ignore `props.name` if `newNamedChild` has an explicit `name`
-- Forbid nested children in props for now
-
-## 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!'
-```
+## CRDTs
 
-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.)
+RepTree uses two conflict-free replicated data types (CRDTs):
+- A move tree CRDT for the tree structure (https://martin.kleppmann.com/papers/move-op.pdf).
+- A last-writer-wins (LWW) CRDT is for properties.
 
 ## License
 
-MIT
+MIT

package/dist/index.cjs

@@ -1,9 +1,7 @@
 "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)
@@ -17,14 +15,6 @@ 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
@@ -38,8 +28,6 @@ __export(index_exports, {
   bindVertex: () => bindVertex,
   defaultAliases: () => defaultAliases,
   isAnyPropertyOp: () => isAnyPropertyOp,
-  isLWWPropertyOp: () => isLWWPropertyOp,
-  isModifyPropertyOp: () => isModifyPropertyOp,
   isMoveVertexOp: () => isMoveVertexOp,
   newMoveVertexOp: () => newMoveVertexOp,
   newSetTransientVertexPropertyOp: () => newSetTransientVertexPropertyOp,
@@ -102,12 +90,6 @@ function isMoveVertexOp(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: createOpId(clock, peerId), targetId, parentId };
 }
@@ -550,7 +532,6 @@ function bindVertex(tree, id, schemaOrOptions) {
 }
 
 // src/Vertex.ts
-var Y = __toESM(require("yjs"), 1);
 var Vertex = class _Vertex {
   constructor(tree, state) {
     this.tree = tree;
@@ -724,10 +705,8 @@ var Vertex = class _Vertex {
           continue;
         }
       } else if (typeof value === "object" && value !== null) {
-        if (!(value instanceof Y.Doc)) {
-          skipped.push(rawKey);
-          continue;
-        }
+        skipped.push(rawKey);
+        continue;
       } else if (!isPrimitive(value)) {
         skipped.push(rawKey);
         continue;
@@ -927,7 +906,6 @@ var StateVector = class _StateVector {
 };
 
 // src/RepTree.ts
-var Y2 = __toESM(require("yjs"), 1);
 var _RepTree = class _RepTree {
   /**
    * @param peerId - The peer ID of the current client. Should be unique across all peers.
@@ -939,7 +917,7 @@ var _RepTree = class _RepTree {
     this.setPropertyOps = [];
     this.propertiesAndTheirOpIds = /* @__PURE__ */ new Map();
     this.transientPropertiesAndTheirOpIds = /* @__PURE__ */ new Map();
-    this.yjsObservers = /* @__PURE__ */ new Map();
+    // Observers for non-structural properties are not used
     this.localOps = [];
     this.pendingMovesWithMissingParent = /* @__PURE__ */ new Map();
     this.pendingPropertiesWithMissingVertex = /* @__PURE__ */ new Map();
@@ -1041,6 +1019,12 @@ var _RepTree = class _RepTree {
     this.localOps = [];
     return ops;
   }
+  /**
+   * This is the first vertex that will contain all other vertices.
+   * If you plan to replicate a tree then don't use this method and instead merge
+   * in the ops from another tree (that will also contain the root vertex).
+   * @returns The root vertex
+   */
   createRoot() {
     if (this.rootVertexId) {
       throw new Error("Root vertex already exists");
@@ -1088,21 +1072,15 @@ var _RepTree = class _RepTree {
   }
   setTransientVertexProperty(vertexId, key, value) {
     this.lamportClock++;
-    let opValue;
-    if (value instanceof Y2.Doc) {
-      const state = Y2.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);
+    const op = newSetTransientVertexPropertyOp(this.lamportClock, this.peerId, vertexId, key, value);
     this.localOps.push(op);
     this.applyProperty(op);
   }
+  /**
+   * Promotes all transient (temporary) properties to persistent properties.
+   * @param vertexId - The ID of the vertex to commit transients for.
+   * @returns 
+   */
   commitTransients(vertexId) {
     const vertex = this.state.getVertex(vertexId);
     if (!vertex) {
@@ -1119,18 +1097,7 @@ var _RepTree = class _RepTree {
   }
   setVertexProperty(vertexId, key, value) {
     this.lamportClock++;
-    let opValue;
-    if (value instanceof Y2.Doc) {
-      const state = Y2.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);
+    const op = newSetVertexPropertyOp(this.lamportClock, this.peerId, vertexId, key, value);
     this.localOps.push(op);
     this.applyProperty(op);
   }
@@ -1293,13 +1260,7 @@ var _RepTree = class _RepTree {
         if (!propB) {
           return false;
         }
-        if (propA.value instanceof Y2.Doc && propB.value instanceof Y2.Doc) {
-          const snapshotA = Y2.snapshot(propA.value);
-          const snapshotB = Y2.snapshot(propB.value);
-          if (!Y2.equalSnapshots(snapshotA, snapshotB)) {
-            return false;
-          }
-        } else if (propA.value !== propB.value) {
+        if (propA.value !== propB.value) {
           return false;
         }
       }
@@ -1396,40 +1357,6 @@ 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 Y2.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) {
@@ -1443,11 +1370,7 @@ var _RepTree = class _RepTree {
       return;
     }
     this.updateLamportClock(op);
-    if (isModifyPropertyOp(op)) {
-      this.applyModifyProperty(op, targetVertex);
-    } else {
-      this.applyLLWProperty(op, targetVertex);
-    }
+    this.applyLLWProperty(op, targetVertex);
   }
   applyLLWProperty(op, targetVertex) {
     const prevTransientOpId = this.transientPropertiesAndTheirOpIds.get(`${op.key}@${op.targetId}`);
@@ -1469,28 +1392,7 @@ var _RepTree = class _RepTree {
       }
     }
   }
-  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 Y2.Doc) {
-      Y2.applyUpdate(ydoc, crdtValue.value);
-    } else {
-      const newDoc = new Y2.Doc();
-      this.setupYjsObserver(newDoc, op.targetId, op.key);
-      this.state.setProperty(op.targetId, op.key, newDoc);
-      Y2.applyUpdate(newDoc, crdtValue.value);
-    }
-    this.propertiesAndTheirOpIds.set(`${op.key}@${op.targetId}`, op.id);
-    this.reportOpAsApplied(op);
-  }
+  // Non-LWW modify-property flow removed
   applyOperation(op) {
     if (isMoveVertexOp(op)) {
       this.applyMove(op);
@@ -1616,8 +1518,6 @@ var RepTree = _RepTree;
   bindVertex,
   defaultAliases,
   isAnyPropertyOp,
-  isLWWPropertyOp,
-  isModifyPropertyOp,
   isMoveVertexOp,
   newMoveVertexOp,
   newSetTransientVertexPropertyOp,