reptree 0.4.0-alpha.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