@loro-extended/change 3.0.0 → 4.0.0

package/README.md

@@ -570,7 +570,7 @@ const schema = Shape.doc({
 - `Shape.movableList(itemSchema)` - Collaborative reorderable lists
 - `Shape.struct(shape)` - Collaborative structs with fixed keys (uses LoroMap internally)
 - `Shape.record(valueSchema)` - Collaborative key-value maps with dynamic string keys
-- `Shape.tree(shape)` - Collaborative hierarchical tree structures (Note: incomplete implementation)
+- `Shape.tree(dataShape)` - Collaborative hierarchical tree structures with typed node metadata
 - `Shape.any()` - Escape hatch for untyped containers (see [Untyped Integration](#untyped-integration-with-external-libraries))
 
 #### Value Types
@@ -788,6 +788,121 @@ draft.metadata.values();
 const value = draft.metadata.get("key");
 ```
 
+### Tree Operations
+
+Trees are hierarchical structures where each node has typed metadata. Perfect for state machines, file systems, org charts, and nested data.
+
+```typescript
+// Define node data shape
+const StateNodeDataShape = Shape.struct({
+  name: Shape.text(),
+  facts: Shape.record(Shape.plain.any()),
+  rules: Shape.list(
+    Shape.plain.struct({
+      name: Shape.plain.string(),
+      rego: Shape.plain.string(),
+      description: Shape.plain.string().nullable(),
+    })
+  ),
+});
+
+const schema = Shape.doc({
+  states: Shape.tree(StateNodeDataShape),
+});
+
+const doc = createTypedDoc(schema);
+
+change(doc, (draft) => {
+  // Create root nodes
+  const idle = draft.states.createNode();
+  idle.data.name.insert(0, "idle");
+
+  const running = draft.states.createNode();
+  running.data.name.insert(0, "running");
+
+  // Create child nodes
+  const processing = idle.createNode();
+  processing.data.name.insert(0, "processing");
+
+  // Access typed node data
+  processing.data.rules.push({
+    name: "validate",
+    rego: "package validate",
+    description: null,
+  });
+
+  // Navigate the tree
+  const parent = processing.parent(); // Returns idle node
+  const children = idle.children(); // Returns [processing]
+
+  // Move nodes between parents
+  processing.move(running); // Move to different parent
+  processing.move(); // Move to root (no parent)
+
+  // Query the tree
+  const roots = draft.states.roots(); // All root nodes
+  const allNodes = draft.states.nodes(); // All nodes (flat)
+  const node = draft.states.getNodeByID(idle.id); // Find by ID
+  const exists = draft.states.has(idle.id); // Check existence
+
+  // Delete nodes (and all descendants)
+  draft.states.delete(running);
+
+  // Enable fractional indexing for ordering
+  draft.states.enableFractionalIndex(8);
+  const index = idle.index(); // Position among siblings
+  const fractionalIndex = idle.fractionalIndex(); // Fractional index string
+});
+
+// Serialize to JSON (nested structure)
+const json = doc.toJSON();
+// {
+//   states: [{
+//     id: "0@123",
+//     parent: null,
+//     index: 0,
+//     fractionalIndex: "80",
+//     data: { name: "idle", facts: {}, rules: [] },
+//     children: [...]
+//   }]
+// }
+
+// Get flat array representation
+change(doc, (draft) => {
+  const flatArray = draft.states.toArray();
+  // [{ id, parent, index, fractionalIndex, data }, ...]
+});
+```
+
+**Tree Node Properties:**
+
+- `node.id` - Unique TreeID for the node
+- `node.data` - Typed StructRef for node metadata (access like `node.data.name`)
+- `node.parent()` - Get parent node (or undefined for roots)
+- `node.children()` - Get child nodes in order
+- `node.index()` - Position among siblings
+- `node.fractionalIndex()` - Fractional index string for ordering
+- `node.isDeleted()` - Check if node has been deleted
+
+**Tree Node Methods:**
+
+- `node.createNode(initialData?, index?)` - Create child node
+- `node.move(newParent?, index?)` - Move to new parent (undefined = root)
+- `node.moveAfter(sibling)` - Move after sibling
+- `node.moveBefore(sibling)` - Move before sibling
+
+**TreeRef Methods:**
+
+- `tree.createNode(initialData?)` - Create root node
+- `tree.roots()` - Get all root nodes
+- `tree.nodes()` - Get all nodes (flat)
+- `tree.getNodeByID(id)` - Find node by TreeID
+- `tree.has(id)` - Check if node exists
+- `tree.delete(target)` - Delete node and descendants
+- `tree.enableFractionalIndex(jitter?)` - Enable ordering
+- `tree.toJSON()` - Nested JSON structure
+- `tree.toArray()` - Flat array representation
+
 ### JSON Serialization and Snapshots
 
 You can easily get a plain JavaScript object snapshot of any part of the document using `JSON.stringify()` or `.toJSON()`. This works for the entire document, nested containers, and even during loading states (placeholders).

package/dist/index.d.ts

@@ -1,7 +1,24 @@
-import { LoroDoc, LoroCounter, LoroList, LoroMovableList, Container, LoroMap, Value, LoroText, LoroTree } from 'loro-crdt';
+import { LoroDoc, LoroCounter, LoroList, LoroMovableList, Container, LoroMap, Value, LoroText, TreeID, LoroTree } from 'loro-crdt';
 
+type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+/**
+ * Expands a type to a reasonable depth for IDE display.
+ * Stops at depth 4 to avoid infinite recursion with self-referential types
+ * like tree nodes that have `children: TreeNodeJSON[]`.
+ *
+ * @example
+ * ```typescript
+ * // Without expansion, hover shows: TreeNodeJSON<StructContainerShape<...>>
+ * // With expansion, hover shows the actual structure:
+ * // { id: string; parent: string | null; data: { name: string; ... }; children: ... }
+ * ```
+ */
+type ExpandDeep<T, Depth extends number = 4> = Depth extends 0 ? T : T extends (...args: any[]) => any ? T : T extends object ? T extends infer O ? {
+    [K in keyof O]: ExpandDeep<O[K], Prev[Depth]>;
+} : never : T;
 /**
  * Infers the plain (JSON-serializable) type from any Shape.
+ * The result is fully expanded for better IDE hover display.
  *
  * This is the recommended way to extract types from shapes.
  * Works with DocShape, ContainerShape, and ValueShape.
@@ -29,7 +46,13 @@ import { LoroDoc, LoroCounter, LoroList, LoroMovableList, Container, LoroMap, Va
  * // Result: { name: string; cursor: { x: number; y: number } }
  * ```
  */
-type Infer<T> = T extends Shape<infer P, any, any> ? P : never;
+type Infer<T> = T extends Shape<infer P, any, any> ? ExpandDeep<P> : never;
+/**
+ * Infers the plain (JSON-serializable) type from any Shape without expansion.
+ * Use this if you prefer to see type alias names (like TreeNodeJSON) in hover displays,
+ * or if you need slightly faster type checking on very large schemas.
+ */
+type InferRaw<T> = T extends Shape<infer P, any, any> ? P : never;
 /**
  * Infers the mutable type from any Shape.
  * This is the type used within change() callbacks for mutation.
@@ -52,8 +75,8 @@ type TypedRefParams<Shape extends DocShape | ContainerShape> = {
     shape: Shape;
     placeholder?: Infer<Shape>;
     getContainer: () => ShapeToContainer<Shape>;
-    readonly?: boolean;
     autoCommit?: boolean;
+    batchedMutation?: boolean;
     getDoc?: () => LoroDoc;
 };
 declare abstract class TypedRef<Shape extends DocShape | ContainerShape> {
@@ -68,20 +91,14 @@ declare abstract class TypedRef<Shape extends DocShape | ContainerShape> {
     abstract toJSON(): Infer<Shape>;
     protected get shape(): Shape;
     protected get placeholder(): Infer<Shape> | undefined;
-    protected get readonly(): boolean;
     protected get autoCommit(): boolean;
+    protected get batchedMutation(): boolean;
     protected get doc(): LoroDoc | undefined;
     /**
      * Commits changes if autoCommit is enabled.
      * Call this after any mutation operation.
      */
     protected commitIfAuto(): void;
-    /**
-     * Throws an error if this ref is in readonly mode.
-     * Call this at the start of any mutating method.
-     * @deprecated Mutations are always allowed now; this will be removed.
-     */
-    protected assertMutable(): void;
     protected get container(): ShapeToContainer<Shape>;
 }
 
@@ -257,9 +274,45 @@ interface TextContainerShape extends Shape<string, TextRef, string> {
 interface CounterContainerShape extends Shape<number, CounterRef, number> {
     readonly _type: "counter";
 }
-interface TreeContainerShape<NestedShape = ContainerOrValueShape> extends Shape<any, any, never[]> {
+/**
+ * JSON representation of a tree node with typed data.
+ * Used for serialization (toJSON) of tree structures.
+ */
+type TreeNodeJSON<DataShape extends StructContainerShape> = {
+    id: TreeID;
+    parent: TreeID | null;
+    index: number;
+    fractionalIndex: string;
+    data: DataShape["_plain"];
+    children: TreeNodeJSON<DataShape>[];
+};
+/**
+ * Container shape for tree (forest) structures.
+ * Each node in the tree has typed metadata stored in a LoroMap.
+ *
+ * Note: The Mutable type (second generic parameter) is `any` here to avoid
+ * circular dependency with TreeRef. The actual type is resolved at runtime
+ * and through the InferMutableType helper.
+ *
+ * @example
+ * ```typescript
+ * const StateNodeDataShape = Shape.struct({
+ *   name: Shape.text(),
+ *   facts: Shape.record(Shape.plain.any()),
+ * })
+ *
+ * const Schema = Shape.doc({
+ *   states: Shape.tree(StateNodeDataShape),
+ * })
+ * ```
+ */
+interface TreeContainerShape<DataShape extends StructContainerShape = StructContainerShape> extends Shape<TreeNodeJSON<DataShape>[], any, never[]> {
     readonly _type: "tree";
-    readonly shape: NestedShape;
+    /**
+     * The shape of each node's data (metadata).
+     * This is a StructContainerShape that defines the typed properties on node.data.
+     */
+    readonly shape: DataShape;
 }
 interface ListContainerShape<NestedShape extends ContainerOrValueShape = ContainerOrValueShape> extends Shape<NestedShape["_plain"][], ListRef<NestedShape>, never[]> {
     readonly _type: "list";
@@ -460,7 +513,29 @@ declare const Shape: {
     record: <T extends ContainerOrValueShape>(shape: T) => RecordContainerShape<T>;
     movableList: <T extends ContainerOrValueShape>(shape: T) => MovableListContainerShape<T>;
     text: () => WithPlaceholder<TextContainerShape>;
-    tree: <T extends MapContainerShape | StructContainerShape>(shape: T) => TreeContainerShape;
+    /**
+     * Creates a tree container shape for hierarchical data structures.
+     * Each node in the tree has typed metadata defined by the data shape.
+     *
+     * @example
+     * ```typescript
+     * const StateNodeDataShape = Shape.struct({
+     *   name: Shape.text(),
+     *   facts: Shape.record(Shape.plain.any()),
+     * })
+     *
+     * const Schema = Shape.doc({
+     *   states: Shape.tree(StateNodeDataShape),
+     * })
+     *
+     * doc.$.change(draft => {
+     *   const root = draft.states.createNode({ name: "idle", facts: {} })
+     *   const child = root.createNode({ name: "running", facts: {} })
+     *   child.data.name = "active"
+     * })
+     * ```
+     */
+    tree: <T extends StructContainerShape>(shape: T) => TreeContainerShape<T>;
     plain: {
         string: <T extends string = string>(...options: T[]) => WithPlaceholder<StringValueShape<T>> & WithNullable<StringValueShape<T>>;
         number: () => WithPlaceholder<NumberValueShape> & WithNullable<NumberValueShape>;
@@ -921,4 +996,4 @@ declare function createPlaceholderProxy<T extends object>(target: T): T;
  */
 declare function validatePlaceholder<T extends DocShape>(placeholder: unknown, schema: T): Infer<T>;
 
-export { type AnyContainerShape, type AnyValueShape, type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, type DiscriminatedUnionValueShape, type DocShape, type Infer, type InferMutableType, type InferPlaceholderType, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type Mutable, type ObjectValueShape, type PathBuilder, type PathNode, type PathSegment, type PathSelector, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StructContainerShape, type StructValueShape, type TextContainerShape, type TreeContainerShape, type TypedDoc, type UnionValueShape, type ValueShape, type WithNullable, type WithPlaceholder, change, compileToJsonPath, createPathBuilder, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, evaluatePath, evaluatePathOnValue, getLoroDoc, hasWildcard, mergeValue, overlayPlaceholder, validatePlaceholder };
+export { type AnyContainerShape, type AnyValueShape, type ArrayValueShape, type ContainerOrValueShape, type ContainerShape, type CounterContainerShape, type DiscriminatedUnionValueShape, type DocShape, type Infer, type InferMutableType, type InferPlaceholderType, type InferRaw, type ListContainerShape, type MapContainerShape, type MovableListContainerShape, type Mutable, type ObjectValueShape, type PathBuilder, type PathNode, type PathSegment, type PathSelector, type RecordContainerShape, type RecordValueShape, type ContainerType as RootContainerType, Shape, type StructContainerShape, type StructValueShape, type TextContainerShape, type TreeContainerShape, type TypedDoc, type UnionValueShape, type ValueShape, type WithNullable, type WithPlaceholder, change, compileToJsonPath, createPathBuilder, createPlaceholderProxy, createTypedDoc, derivePlaceholder, deriveShapePlaceholder, evaluatePath, evaluatePathOnValue, getLoroDoc, hasWildcard, mergeValue, overlayPlaceholder, validatePlaceholder };