@loro-extended/change 0.8.1 → 0.9.0

package/src/typed-refs/json-compatibility.test.ts

@@ -0,0 +1,255 @@
+import { LoroDoc } from "loro-crdt"
+import { describe, expect, it, vi } from "vitest"
+import { Shape } from "../shape.js"
+import { createTypedDoc, TypedDoc } from "../typed-doc.js"
+
+const MessageSchema = Shape.map({
+  id: Shape.plain.string(),
+  content: Shape.text(),
+  timestamp: Shape.plain.number(),
+})
+
+const ChatSchema = Shape.doc({
+  messages: Shape.list(MessageSchema),
+  meta: Shape.map({
+    title: Shape.plain.string(),
+    count: Shape.counter(),
+  }),
+  tags: Shape.movableList(Shape.plain.string()),
+  settings: Shape.record(Shape.plain.boolean()),
+  // Tree support might be limited in current implementation
+  // tree: Shape.tree(Shape.map({ val: Shape.plain.number() }))
+})
+
+describe("JSON Compatibility", () => {
+  it("should support JSON.stringify on the whole doc", () => {
+    const doc = createTypedDoc(ChatSchema)
+
+    doc.change((root: any) => {
+      root.meta.title = "My Chat"
+      root.meta.count.increment(5)
+
+      root.messages.push({
+        id: "1",
+        content: "Hello",
+        timestamp: 123,
+      })
+
+      root.tags.push("work")
+      root.tags.push("important")
+
+      root.settings.set("notifications", true)
+      root.settings.set("sound", false)
+    })
+
+    const json = JSON.stringify(doc.value)
+    const parsed = JSON.parse(json)
+
+    expect(parsed).toEqual({
+      messages: [
+        {
+          id: "1",
+          content: "Hello",
+          timestamp: 123,
+        },
+      ],
+      meta: {
+        title: "My Chat",
+        count: 5,
+      },
+      tags: ["work", "important"],
+      settings: {
+        notifications: true,
+        sound: false,
+      },
+    })
+  })
+
+  it("should support Object.keys and Object.entries", () => {
+    const doc = createTypedDoc(ChatSchema)
+    doc.change((root: any) => {
+      root.meta.title = "Test"
+    })
+
+    const keys = Object.keys(doc.value)
+    expect(keys).toContain("messages")
+    expect(keys).toContain("meta")
+    expect(keys).toContain("tags")
+    expect(keys).toContain("settings")
+
+    const entries = Object.entries(doc.value.meta)
+    const entryMap = new Map(entries)
+    expect(entryMap.get("title")).toBe("Test")
+    expect(entryMap.get("count")).toBeDefined()
+  })
+
+  it("should support JSON.stringify on nested structures", () => {
+    const doc = createTypedDoc(ChatSchema)
+    doc.change((root: any) => {
+      root.messages.push({ id: "1", content: "A", timestamp: 1 })
+    })
+
+    const messagesJson = JSON.stringify(doc.value.messages)
+    expect(JSON.parse(messagesJson)).toEqual([
+      { id: "1", content: "A", timestamp: 1 },
+    ])
+  })
+
+  it("should support MovableList", () => {
+    const doc = createTypedDoc(ChatSchema)
+    doc.change((root: any) => {
+      root.tags.push("a")
+      root.tags.push("b")
+      root.tags.move(0, 1) // move 'a' to index 1
+    })
+
+    // After move: ["b", "a"]
+    const json = JSON.stringify(doc.value.tags)
+    expect(JSON.parse(json)).toEqual(["b", "a"])
+  })
+
+  it("should support Record", () => {
+    const doc = createTypedDoc(ChatSchema)
+    doc.change((root: any) => {
+      root.settings.set("dark_mode", true)
+    })
+
+    const json = JSON.stringify(doc.value.settings)
+    expect(JSON.parse(json)).toEqual({ dark_mode: true })
+  })
+
+  it("should support Readonly vs Mutable consistency", () => {
+    const doc = createTypedDoc(ChatSchema)
+    let mutableJson = ""
+
+    doc.change((root: any) => {
+      root.meta.title = "Draft"
+      mutableJson = JSON.stringify(root)
+    })
+
+    const readonlyJson = JSON.stringify(doc.value)
+    expect(readonlyJson).toBe(mutableJson)
+  })
+
+  it("should handle placeholders", () => {
+    const doc = createTypedDoc(ChatSchema)
+    // No changes made
+
+    const json = JSON.stringify(doc.value)
+    const parsed = JSON.parse(json)
+
+    expect(parsed.meta.title).toBe("") // Default string placeholder
+    expect(parsed.meta.count).toBe(0) // Default counter placeholder
+    expect(parsed.messages).toEqual([])
+  })
+
+  it("should support Array methods on Lists", () => {
+    const doc = createTypedDoc(ChatSchema)
+    doc.change((root: any) => {
+      root.messages.push({ id: "1", content: "A", timestamp: 10 })
+      root.messages.push({ id: "2", content: "B", timestamp: 20 })
+    })
+
+    const mapped = doc.value.messages.map(m => ({ id: m.id, txt: m.content }))
+    expect(JSON.stringify(mapped)).toBe(
+      '[{"id":"1","txt":"A"},{"id":"2","txt":"B"}]',
+    )
+
+    const filtered = doc.value.messages.filter(m => m.timestamp > 15)
+    expect(filtered).toHaveLength(1)
+    expect(filtered[0].id).toBe("2")
+    // filtered returns MutableItems (TypedRefs), so JSON.stringify should work on them
+    expect(JSON.stringify(filtered)).toBe(
+      '[{"id":"2","content":"B","timestamp":20}]',
+    )
+  })
+
+  it("should support Object.values", () => {
+    const doc = createTypedDoc(ChatSchema)
+    doc.change((root: any) => {
+      root.settings.set("a", true)
+      root.settings.set("b", false)
+    })
+
+    const values = Object.values(doc.value.settings)
+    expect(values).toContain(true)
+    expect(values).toContain(false)
+    expect(values).toHaveLength(2)
+  })
+
+  it("should be efficient (not access unrelated parts)", () => {
+    const loroDoc = new LoroDoc()
+    const doc = new TypedDoc(ChatSchema, loroDoc)
+
+    doc.change((root: any) => {
+      root.messages.push({ id: "1", content: "A", timestamp: 1 })
+      root.meta.title = "Test"
+    })
+
+    // Spy on LoroDoc methods
+    const getMapSpy = vi.spyOn(loroDoc, "getMap")
+    const getListSpy = vi.spyOn(loroDoc, "getList")
+
+    // Access messages and call toJSON
+    const messagesJson = doc.value.messages.toJSON()
+
+    expect(messagesJson).toHaveLength(1)
+
+    // Should have accessed "messages" list
+    expect(getListSpy).toHaveBeenCalledWith("messages")
+
+    // Should NOT have accessed "meta" map
+    expect(getMapSpy).not.toHaveBeenCalledWith("meta")
+
+    // Should NOT have accessed "settings" map (record)
+    expect(getMapSpy).not.toHaveBeenCalledWith("settings")
+  })
+
+  it("should allow calling toJSON() directly on refs", () => {
+    const doc = createTypedDoc(ChatSchema)
+    doc.change((root: any) => {
+      root.meta.title = "Direct"
+      root.meta.count.increment(10)
+      root.messages.push({ id: "1", content: "A", timestamp: 1 })
+      root.settings.set("opt", true)
+    })
+
+    // DocRef
+    expect(doc.value.toJSON()).toEqual(
+      expect.objectContaining({
+        meta: expect.objectContaining({ title: "Direct" }),
+      }),
+    )
+
+    // MapRef
+    expect(doc.value.meta.toJSON()).toEqual({
+      title: "Direct",
+      count: 10,
+    })
+
+    // ListRef
+    expect(doc.value.messages.toJSON()).toEqual([
+      { id: "1", content: "A", timestamp: 1 },
+    ])
+
+    // RecordRef
+    expect(doc.value.settings.toJSON()).toEqual({
+      opt: true,
+    })
+
+    doc.change((root: any) => {
+      // Inside change, these are mutable refs
+      expect(root.meta.toJSON()).toEqual({ title: "Direct", count: 10 })
+      expect(root.messages.toJSON()).toEqual([
+        { id: "1", content: "A", timestamp: 1 },
+      ])
+
+      // CounterRef
+      expect(root.meta.count.toJSON()).toBe(10)
+
+      // TextRef (inside message)
+      // root.messages[0] is a MapRef. content is TextRef.
+      expect(root.messages[0].content.toJSON()).toBe("A")
+    })
+  })
+})

package/src/{draft-nodes → typed-refs}/list-base.ts

@@ -7,15 +7,15 @@ import type {
   MovableListContainerShape,
 } from "../shape.js"
 import { isContainer, isValueShape } from "../utils/type-guards.js"
-import { DraftNode, type DraftNodeParams } from "./base.js"
-import { createContainerDraftNode } from "./utils.js"
+import { TypedRef, type TypedRefParams } from "./base.js"
+import { createContainerTypedRef } from "./utils.js"
 
 // Shared logic for list operations
-export abstract class ListDraftNodeBase<
+export abstract class ListRefBase<
   NestedShape extends ContainerOrValueShape,
   Item = NestedShape["_plain"],
-  DraftItem = NestedShape["_draft"],
-> extends DraftNode<any> {
+  MutableItem = NestedShape["_mutable"],
+> extends TypedRef<any> {
   // Cache for items returned by array methods to track mutations
   private itemCache = new Map<number, any>()
 
@@ -40,7 +40,7 @@ export abstract class ListDraftNodeBase<
           // For value shapes, delegate to subclass-specific absorption logic
           this.absorbValueAtIndex(index, cachedItem)
         } else {
-          // For container shapes, the item should be a draft node that handles its own absorption
+          // For container shapes, the item should be a typed ref that handles its own absorption
           if (
             cachedItem &&
             typeof cachedItem === "object" &&
@@ -78,10 +78,10 @@ export abstract class ListDraftNodeBase<
     }
   }
 
-  getDraftNodeParams(
+  getTypedRefParams(
     index: number,
     shape: ContainerShape,
-  ): DraftNodeParams<ContainerShape> {
+  ): TypedRefParams<ContainerShape> {
     return {
       shape,
       placeholder: undefined, // List items don't have placeholder
@@ -142,8 +142,8 @@ export abstract class ListDraftNodeBase<
     }
   }
 
-  // Get item for return values - returns DraftItem that can be mutated
-  protected getDraftItem(index: number): any {
+  // Get item for return values - returns MutableItem that can be mutated
+  protected getMutableItem(index: number): any {
     // Check if we already have a cached item for this index
     let cachedItem = this.itemCache.get(index)
     if (cachedItem) {
@@ -153,7 +153,7 @@ export abstract class ListDraftNodeBase<
     // Get the raw container item
     const containerItem = this.container.get(index)
     if (containerItem === undefined) {
-      return undefined as DraftItem
+      return undefined as MutableItem
     }
 
     if (isValueShape(this.shape.shape)) {
@@ -172,11 +172,11 @@ export abstract class ListDraftNodeBase<
       if (!this.readonly) {
         this.itemCache.set(index, cachedItem)
       }
-      return cachedItem as DraftItem
+      return cachedItem as MutableItem
     } else {
-      // For container shapes, create a proper draft node using the new pattern
-      cachedItem = createContainerDraftNode(
-        this.getDraftNodeParams(index, this.shape.shape as ContainerShape),
+      // For container shapes, create a proper typed ref using the new pattern
+      cachedItem = createContainerTypedRef(
+        this.getTypedRefParams(index, this.shape.shape as ContainerShape),
       )
       // Cache container nodes
       this.itemCache.set(index, cachedItem)
@@ -191,20 +191,20 @@ export abstract class ListDraftNodeBase<
         }
       }
 
-      return cachedItem as DraftItem
+      return cachedItem as MutableItem
     }
   }
 
   // Array-like methods for better developer experience
-  // DUAL INTERFACE: Predicates get Item (plain data), return values are DraftItem (mutable)
+  // DUAL INTERFACE: Predicates get Item (plain data), return values are MutableItem (mutable)
 
   find(
     predicate: (item: Item, index: number) => boolean,
-  ): DraftItem | undefined {
+  ): MutableItem | undefined {
     for (let i = 0; i < this.length; i++) {
       const predicateItem = this.getPredicateItem(i)
       if (predicate(predicateItem, i)) {
-        return this.getDraftItem(i) // Return mutable draft item
+        return this.getMutableItem(i) // Return mutable item
       }
     }
     return undefined
@@ -231,12 +231,12 @@ export abstract class ListDraftNodeBase<
     return result
   }
 
-  filter(predicate: (item: Item, index: number) => boolean): DraftItem[] {
-    const result: DraftItem[] = []
+  filter(predicate: (item: Item, index: number) => boolean): MutableItem[] {
+    const result: MutableItem[] = []
     for (let i = 0; i < this.length; i++) {
       const predicateItem = this.getPredicateItem(i)
       if (predicate(predicateItem, i)) {
-        result.push(this.getDraftItem(i)) // Return mutable draft items
+        result.push(this.getMutableItem(i)) // Return mutable items
       }
     }
     return result
@@ -269,41 +269,90 @@ export abstract class ListDraftNodeBase<
     return true
   }
 
+  slice(start?: number, end?: number): MutableItem[] {
+    const len = this.length
+
+    // Normalize start index (following JavaScript Array.prototype.slice semantics)
+    const startIndex =
+      start === undefined
+        ? 0
+        : start < 0
+          ? Math.max(len + start, 0)
+          : Math.min(start, len)
+
+    // Normalize end index
+    const endIndex =
+      end === undefined
+        ? len
+        : end < 0
+          ? Math.max(len + end, 0)
+          : Math.min(end, len)
+
+    const result: MutableItem[] = []
+    for (let i = startIndex; i < endIndex; i++) {
+      result.push(this.getMutableItem(i))
+    }
+    return result
+  }
+
   insert(index: number, item: Item): void {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     // Update cache indices before performing the insert operation
     this.updateCacheForInsert(index)
     this.insertWithConversion(index, item)
   }
 
   delete(index: number, len: number): void {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     // Update cache indices before performing the delete operation
     this.updateCacheForDelete(index, len)
     this.container.delete(index, len)
   }
 
   push(item: Item): void {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.pushWithConversion(item)
   }
 
   pushContainer(container: Container): Container {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     return this.container.pushContainer(container)
   }
 
   insertContainer(index: number, container: Container): Container {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     return this.container.insertContainer(index, container)
   }
 
-  get(index: number): DraftItem {
-    return this.getDraftItem(index)
+  get(index: number): MutableItem {
+    return this.getMutableItem(index)
   }
 
   toArray(): Item[] {
-    return this.container.toArray() as Item[]
+    const result: Item[] = []
+    for (let i = 0; i < this.length; i++) {
+      result.push(this.getPredicateItem(i))
+    }
+    return result
+  }
+
+  toJSON(): Item[] {
+    return this.toArray()
+  }
+
+  [Symbol.iterator](): IterableIterator<MutableItem> {
+    let index = 0
+    return {
+      next: (): IteratorResult<MutableItem> => {
+        if (index < this.length) {
+          return { value: this.getMutableItem(index++), done: false }
+        }
+        return { value: undefined, done: true }
+      },
+      [Symbol.iterator]() {
+        return this
+      },
+    }
   }
 
   get length(): number {

package/src/{draft-nodes → typed-refs}/list.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest"
 import { createTypedDoc, Shape } from "../index.js"
 
-describe("ListDraftNode", () => {
+describe("ListRef", () => {
   describe("set via index", () => {
     it("should allow setting a plain object for a list item via index", () => {
       const schema = Shape.doc({

package/src/{draft-nodes → typed-refs}/list.ts

@@ -1,12 +1,12 @@
 import type { LoroList } from "loro-crdt"
 import type { ContainerOrValueShape } from "../shape.js"
 import type { Infer } from "../types.js"
-import { ListDraftNodeBase } from "./list-base.js"
+import { ListRefBase } from "./list-base.js"
 
-// List draft node
-export class ListDraftNode<
+// List typed ref
+export class ListRef<
   NestedShape extends ContainerOrValueShape,
-> extends ListDraftNodeBase<NestedShape> {
+> extends ListRefBase<NestedShape> {
   [index: number]: Infer<NestedShape>
 
   protected get container(): LoroList {

package/src/{draft-nodes → typed-refs}/map.ts

@@ -15,11 +15,8 @@ import type {
   ValueShape,
 } from "../shape.js"
 import { isContainerShape, isValueShape } from "../utils/type-guards.js"
-import { DraftNode, type DraftNodeParams } from "./base.js"
-import {
-  assignPlainValueToDraftNode,
-  createContainerDraftNode,
-} from "./utils.js"
+import { TypedRef, type TypedRefParams } from "./base.js"
+import { assignPlainValueToTypedRef, createContainerTypedRef } from "./utils.js"
 
 const containerConstructor = {
   counter: LoroCounter,
@@ -31,13 +28,13 @@ const containerConstructor = {
   tree: LoroTree,
 } as const
 
-// Map draft node
-export class MapDraftNode<
+// Map typed ref
+export class MapRef<
   NestedShapes extends Record<string, ContainerOrValueShape>,
-> extends DraftNode<any> {
-  private propertyCache = new Map<string, DraftNode<ContainerShape> | Value>()
+> extends TypedRef<any> {
+  private propertyCache = new Map<string, TypedRef<ContainerShape> | Value>()
 
-  constructor(params: DraftNodeParams<MapContainerShape<NestedShapes>>) {
+  constructor(params: TypedRefParams<MapContainerShape<NestedShapes>>) {
     super(params)
     this.createLazyProperties()
   }
@@ -52,8 +49,8 @@ export class MapDraftNode<
 
   absorbPlainValues() {
     for (const [key, node] of this.propertyCache.entries()) {
-      if (node instanceof DraftNode) {
-        // Contains a DraftNode, not a plain Value: keep recursing
+      if (node instanceof TypedRef) {
+        // Contains a TypedRef, not a plain Value: keep recursing
         node.absorbPlainValues()
         continue
       }
@@ -63,10 +60,10 @@ export class MapDraftNode<
     }
   }
 
-  getDraftNodeParams<S extends ContainerShape>(
+  getTypedRefParams<S extends ContainerShape>(
     key: string,
     shape: S,
-  ): DraftNodeParams<ContainerShape> {
+  ): TypedRefParams<ContainerShape> {
     const placeholder = (this.placeholder as any)?.[key]
 
     const LoroContainer = containerConstructor[shape._type]
@@ -87,7 +84,7 @@ export class MapDraftNode<
     let node = this.propertyCache.get(key)
     if (!node) {
       if (isContainerShape(shape)) {
-        node = createContainerDraftNode(this.getDraftNodeParams(key, shape))
+        node = createContainerTypedRef(this.getTypedRefParams(key, shape))
         // We cache container nodes even in readonly mode because they are just handles
         this.propertyCache.set(key, node)
       } else {
@@ -129,7 +126,7 @@ export class MapDraftNode<
       }
     }
 
-    return node as Shape extends ContainerShape ? DraftNode<Shape> : Value
+    return node as Shape extends ContainerShape ? TypedRef<Shape> : Value
   }
 
   private createLazyProperties(): void {
@@ -138,7 +135,7 @@ export class MapDraftNode<
       Object.defineProperty(this, key, {
         get: () => this.getOrCreateNode(key, shape),
         set: value => {
-          if (this.readonly) throw new Error("Cannot modify readonly doc")
+          if (this.readonly) throw new Error("Cannot modify readonly ref")
           if (isValueShape(shape)) {
             this.container.set(key, value)
             this.propertyCache.set(key, value)
@@ -146,36 +143,50 @@ export class MapDraftNode<
             if (value && typeof value === "object") {
               const node = this.getOrCreateNode(key, shape)
 
-              if (assignPlainValueToDraftNode(node as DraftNode<any>, value)) {
+              if (assignPlainValueToTypedRef(node as TypedRef<any>, value)) {
                 return
               }
             }
             throw new Error(
-              "Cannot set container directly, modify the draft node instead",
+              "Cannot set container directly, modify the typed ref instead",
             )
           }
         },
+        enumerable: true,
       })
     }
   }
 
+  toJSON(): any {
+    const result: any = {}
+    for (const key in this.shape.shapes) {
+      const value = (this as any)[key]
+      if (value && typeof value === "object" && "toJSON" in value) {
+        result[key] = value.toJSON()
+      } else {
+        result[key] = value
+      }
+    }
+    return result
+  }
+
   // TOOD(duane): return correct type here
   get(key: string): any {
     return this.container.get(key)
   }
 
   set(key: string, value: Value): void {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.set(key, value)
   }
 
   setContainer<C extends Container>(key: string, container: C): C {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     return this.container.setContainer(key, container)
   }
 
   delete(key: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.delete(key)
   }
 

package/src/{draft-nodes → typed-refs}/movable-list.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest"
 import { createTypedDoc, Shape } from "../index.js"
 
-describe("MovableListDraftNode", () => {
+describe("MovableListRef", () => {
   describe("set via index", () => {
     it("should allow setting a plain object for a list item via index", () => {
       const schema = Shape.doc({

package/src/{draft-nodes → typed-refs}/movable-list.ts

@@ -1,13 +1,13 @@
 import type { Container, LoroMovableList } from "loro-crdt"
 import type { ContainerOrValueShape } from "../shape.js"
 import type { Infer } from "../types.js"
-import { ListDraftNodeBase } from "./list-base.js"
+import { ListRefBase } from "./list-base.js"
 
-// Movable list draft node
-export class MovableListDraftNode<
+// Movable list typed ref
+export class MovableListRef<
   NestedShape extends ContainerOrValueShape,
   Item = NestedShape["_plain"],
-> extends ListDraftNodeBase<NestedShape> {
+> extends ListRefBase<NestedShape> {
   [index: number]: Infer<NestedShape>
 
   protected get container(): LoroMovableList {
@@ -20,12 +20,12 @@ export class MovableListDraftNode<
   }
 
   move(from: number, to: number): void {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     this.container.move(from, to)
   }
 
   set(index: number, item: Exclude<Item, Container>) {
-    if (this.readonly) throw new Error("Cannot modify readonly doc")
+    if (this.readonly) throw new Error("Cannot modify readonly ref")
     return this.container.set(index, item)
   }
 }