@loro-extended/change 0.9.0 → 0.9.1

package/src/typed-refs/map.ts

@@ -1,13 +1,5 @@
-import {
-  type Container,
-  LoroCounter,
-  LoroList,
-  LoroMap,
-  LoroMovableList,
-  LoroText,
-  LoroTree,
-  type Value,
-} from "loro-crdt"
+import type { Container, LoroMap, Value } from "loro-crdt"
+import { mergeValue } from "../overlay.js"
 import type {
   ContainerOrValueShape,
   ContainerShape,
@@ -16,17 +8,14 @@ import type {
 } from "../shape.js"
 import { isContainerShape, isValueShape } from "../utils/type-guards.js"
 import { TypedRef, type TypedRefParams } from "./base.js"
-import { assignPlainValueToTypedRef, createContainerTypedRef } from "./utils.js"
-
-const containerConstructor = {
-  counter: LoroCounter,
-  list: LoroList,
-  map: LoroMap,
-  movableList: LoroMovableList,
-  record: LoroMap,
-  text: LoroText,
-  tree: LoroTree,
-} as const
+import {
+  absorbCachedPlainValues,
+  assignPlainValueToTypedRef,
+  containerConstructor,
+  createContainerTypedRef,
+  serializeRefToJSON,
+  unwrapReadonlyPrimitive,
+} from "./utils.js"
 
 // Map typed ref
 export class MapRef<
@@ -48,16 +37,7 @@ export class MapRef<
   }
 
   absorbPlainValues() {
-    for (const [key, node] of this.propertyCache.entries()) {
-      if (node instanceof TypedRef) {
-        // Contains a TypedRef, not a plain Value: keep recursing
-        node.absorbPlainValues()
-        continue
-      }
-
-      // Plain value!
-      this.container.set(key, node)
-    }
+    absorbCachedPlainValues(this.propertyCache, () => this.container)
   }
 
   getTypedRefParams<S extends ContainerShape>(
@@ -77,37 +57,37 @@ export class MapRef<
     }
   }
 
-  getOrCreateNode<Shape extends ContainerShape | ValueShape>(
+  getOrCreateRef<Shape extends ContainerShape | ValueShape>(
     key: string,
     shape: Shape,
   ): any {
-    let node = this.propertyCache.get(key)
-    if (!node) {
+    let ref = this.propertyCache.get(key)
+    if (!ref) {
       if (isContainerShape(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)
+        ref = createContainerTypedRef(this.getTypedRefParams(key, shape))
+        // We cache container refs even in readonly mode because they are just handles
+        this.propertyCache.set(key, ref)
       } else {
         // For value shapes, first try to get the value from the container
         const containerValue = this.container.get(key)
         if (containerValue !== undefined) {
-          node = containerValue as Value
+          ref = containerValue as Value
         } else {
           // Only fall back to placeholder if the container doesn't have the value
           const placeholder = (this.placeholder as any)?.[key]
           if (placeholder === undefined) {
             throw new Error("placeholder required")
           }
-          node = placeholder as Value
+          ref = placeholder as Value
         }
 
         // In readonly mode, we DO NOT cache primitive values.
         // This ensures we always get the latest value from the CRDT on next access.
         if (!this.readonly) {
-          this.propertyCache.set(key, node)
+          this.propertyCache.set(key, ref)
         }
       }
-      if (node === undefined) throw new Error("no container made")
+      if (ref === undefined) throw new Error("no container made")
     }
 
     if (this.readonly && isContainerShape(shape)) {
@@ -118,32 +98,27 @@ export class MapRef<
         return (this.placeholder as any)?.[key]
       }
 
-      if (shape._type === "counter") {
-        return (node as any).value
-      }
-      if (shape._type === "text") {
-        return (node as any).toString()
-      }
+      return unwrapReadonlyPrimitive(ref as TypedRef<any>, shape)
     }
 
-    return node as Shape extends ContainerShape ? TypedRef<Shape> : Value
+    return ref as Shape extends ContainerShape ? TypedRef<Shape> : Value
   }
 
   private createLazyProperties(): void {
     for (const key in this.shape.shapes) {
       const shape = this.shape.shapes[key]
       Object.defineProperty(this, key, {
-        get: () => this.getOrCreateNode(key, shape),
+        get: () => this.getOrCreateRef(key, shape),
         set: value => {
-          if (this.readonly) throw new Error("Cannot modify readonly ref")
+          this.assertMutable()
           if (isValueShape(shape)) {
             this.container.set(key, value)
             this.propertyCache.set(key, value)
           } else {
             if (value && typeof value === "object") {
-              const node = this.getOrCreateNode(key, shape)
+              const ref = this.getOrCreateRef(key, shape)
 
-              if (assignPlainValueToTypedRef(node as TypedRef<any>, value)) {
+              if (assignPlainValueToTypedRef(ref as TypedRef<any>, value)) {
                 return
               }
             }
@@ -158,35 +133,33 @@ export class MapRef<
   }
 
   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
-      }
+    // Fast path: readonly mode
+    if (this.readonly) {
+      const nativeJson = this.container.toJSON() as Value
+      // Overlay placeholders for missing properties
+      return mergeValue(this.shape, nativeJson, this.placeholder as Value)
     }
-    return result
+
+    return serializeRefToJSON(this as any, Object.keys(this.shape.shapes))
   }
 
-  // TOOD(duane): return correct type here
+  // TODO(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 ref")
+    this.assertMutable()
     this.container.set(key, value)
   }
 
   setContainer<C extends Container>(key: string, container: C): C {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     return this.container.setContainer(key, container)
   }
 
   delete(key: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.delete(key)
   }
 

package/src/typed-refs/movable-list.ts

@@ -20,12 +20,12 @@ export class MovableListRef<
   }
 
   move(from: number, to: number): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.move(from, to)
   }
 
   set(index: number, item: Exclude<Item, Container>) {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     return this.container.set(index, item)
   }
 }

package/src/typed-refs/record.test.ts

@@ -11,8 +11,8 @@ describe("Record Types", () => {
       const doc = new TypedDoc(schema)
 
       doc.change(draft => {
-        draft.scores.getOrCreateNode("alice").increment(10)
-        draft.scores.getOrCreateNode("bob").increment(5)
+        draft.scores.getOrCreateRef("alice").increment(10)
+        draft.scores.getOrCreateRef("bob").increment(5)
       })
 
       expect(doc.toJSON().scores).toEqual({
@@ -21,7 +21,7 @@ describe("Record Types", () => {
       })
 
       doc.change(draft => {
-        draft.scores.getOrCreateNode("alice").increment(5)
+        draft.scores.getOrCreateRef("alice").increment(5)
         draft.scores.delete("bob")
       })
 
@@ -38,8 +38,8 @@ describe("Record Types", () => {
       const doc = new TypedDoc(schema)
 
       doc.change(draft => {
-        draft.notes.getOrCreateNode("todo").insert(0, "Buy milk")
-        draft.notes.getOrCreateNode("reminders").insert(0, "Call mom")
+        draft.notes.getOrCreateRef("todo").insert(0, "Buy milk")
+        draft.notes.getOrCreateRef("reminders").insert(0, "Call mom")
       })
 
       expect(doc.toJSON().notes).toEqual({
@@ -56,11 +56,11 @@ describe("Record Types", () => {
       const doc = new TypedDoc(schema)
 
       doc.change(draft => {
-        const groupA = draft.groups.getOrCreateNode("groupA")
+        const groupA = draft.groups.getOrCreateRef("groupA")
         groupA.push("alice")
         groupA.push("bob")
 
-        const groupB = draft.groups.getOrCreateNode("groupB")
+        const groupB = draft.groups.getOrCreateRef("groupB")
         groupB.push("charlie")
       })
 
@@ -170,11 +170,11 @@ describe("Record Types", () => {
       const doc = new TypedDoc(schema)
 
       doc.change(draft => {
-        const alice = draft.users.getOrCreateNode("u1")
+        const alice = draft.users.getOrCreateRef("u1")
         alice.name = "Alice"
         alice.age = 30
 
-        const bob = draft.users.getOrCreateNode("u2")
+        const bob = draft.users.getOrCreateRef("u2")
         bob.name = "Bob"
         bob.age = 25
       })

package/src/typed-refs/record.ts

@@ -1,40 +1,29 @@
-import {
-  type Container,
-  LoroCounter,
-  LoroList,
-  LoroMap,
-  LoroMovableList,
-  LoroText,
-  LoroTree,
-  type Value,
-} from "loro-crdt"
+import type { Container, LoroMap, Value } from "loro-crdt"
 import { deriveShapePlaceholder } from "../derive-placeholder.js"
+import { mergeValue } from "../overlay.js"
 import type {
   ContainerOrValueShape,
   ContainerShape,
   RecordContainerShape,
 } from "../shape.js"
-import type { Infer, InferDraftType } from "../types.js"
+import type { Infer, InferMutableType } from "../types.js"
 import { isContainerShape, isValueShape } from "../utils/type-guards.js"
 import { TypedRef, type TypedRefParams } from "./base.js"
-import { assignPlainValueToTypedRef, createContainerTypedRef } from "./utils.js"
-
-const containerConstructor = {
-  counter: LoroCounter,
-  list: LoroList,
-  map: LoroMap,
-  movableList: LoroMovableList,
-  record: LoroMap,
-  text: LoroText,
-  tree: LoroTree,
-} as const
+import {
+  absorbCachedPlainValues,
+  assignPlainValueToTypedRef,
+  containerConstructor,
+  createContainerTypedRef,
+  serializeRefToJSON,
+  unwrapReadonlyPrimitive,
+} from "./utils.js"
 
 // Record typed ref
 export class RecordRef<
   NestedShape extends ContainerOrValueShape,
 > extends TypedRef<any> {
   [key: string]: Infer<NestedShape> | any
-  private nodeCache = new Map<string, TypedRef<ContainerShape> | Value>()
+  private refCache = new Map<string, TypedRef<ContainerShape> | Value>()
 
   protected get shape(): RecordContainerShape<NestedShape> {
     return super.shape as RecordContainerShape<NestedShape>
@@ -45,16 +34,7 @@ export class RecordRef<
   }
 
   absorbPlainValues() {
-    for (const [key, node] of this.nodeCache.entries()) {
-      if (node instanceof TypedRef) {
-        // Contains a TypedRef, not a plain Value: keep recursing
-        node.absorbPlainValues()
-        continue
-      }
-
-      // Plain value!
-      this.container.set(key, node)
-    }
+    absorbCachedPlainValues(this.refCache, () => this.container)
   }
 
   getTypedRefParams<S extends ContainerShape>(
@@ -82,7 +62,7 @@ export class RecordRef<
     }
   }
 
-  getOrCreateNode(key: string): any {
+  getOrCreateRef(key: string): any {
     // For readonly mode with container shapes, check if the key exists first
     // This allows optional chaining (?.) to work correctly for non-existent keys
     // Similar to how ListRefBase.getMutableItem() handles non-existent indices
@@ -93,67 +73,64 @@ export class RecordRef<
       }
     }
 
-    let node = this.nodeCache.get(key)
-    if (!node) {
+    let ref = this.refCache.get(key)
+    if (!ref) {
       const shape = this.shape.shape
       if (isContainerShape(shape)) {
-        node = createContainerTypedRef(
+        ref = createContainerTypedRef(
           this.getTypedRefParams(key, shape as ContainerShape),
         )
-        // Cache container nodes
-        this.nodeCache.set(key, node)
+        // Cache container refs
+        this.refCache.set(key, ref)
       } else {
         // For value shapes, first try to get the value from the container
         const containerValue = this.container.get(key)
         if (containerValue !== undefined) {
-          node = containerValue as Value
+          ref = containerValue as Value
         } else {
           // Only fall back to placeholder if the container doesn't have the value
           const placeholder = (this.placeholder as any)?.[key]
           if (placeholder === undefined) {
             // If it's a value type and not in container or placeholder,
             // fallback to the default value from the shape
-            node = (shape as any)._plain
+            ref = (shape as any)._plain
           } else {
-            node = placeholder as Value
+            ref = placeholder as Value
           }
         }
         // Only cache primitive values if NOT readonly
-        if (node !== undefined && !this.readonly) {
-          this.nodeCache.set(key, node)
+        if (ref !== undefined && !this.readonly) {
+          this.refCache.set(key, ref)
         }
       }
     }
 
     if (this.readonly && isContainerShape(this.shape.shape)) {
-      const shape = this.shape.shape as ContainerShape
-      if (shape._type === "counter") {
-        return (node as any).value
-      }
-      if (shape._type === "text") {
-        return (node as any).toString()
-      }
+      return unwrapReadonlyPrimitive(
+        ref as TypedRef<any>,
+        this.shape.shape as ContainerShape,
+      )
     }
 
-    return node as any
+    return ref as any
   }
 
-  get(key: string): InferDraftType<NestedShape> {
-    return this.getOrCreateNode(key)
+  get(key: string): InferMutableType<NestedShape> {
+    return this.getOrCreateRef(key)
   }
 
   set(key: string, value: any): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     if (isValueShape(this.shape.shape)) {
       this.container.set(key, value)
-      this.nodeCache.set(key, value)
+      this.refCache.set(key, value)
     } else {
       // For containers, we can't set them directly usually.
       // But if the user passes a plain object that matches the shape, maybe we should convert it?
       if (value && typeof value === "object") {
-        const node = this.getOrCreateNode(key)
+        const ref = this.getOrCreateRef(key)
 
-        if (assignPlainValueToTypedRef(node, value)) {
+        if (assignPlainValueToTypedRef(ref, value)) {
           return
         }
       }
@@ -165,14 +142,14 @@ export class RecordRef<
   }
 
   setContainer<C extends Container>(key: string, container: C): C {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     return this.container.setContainer(key, container)
   }
 
   delete(key: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.delete(key)
-    this.nodeCache.delete(key)
+    this.refCache.delete(key)
   }
 
   has(key: string): boolean {
@@ -192,15 +169,25 @@ export class RecordRef<
   }
 
   toJSON(): Record<string, any> {
-    const result: Record<string, any> = {}
-    for (const key of this.keys()) {
-      const value = this.get(key)
-      if (value && typeof value === "object" && "toJSON" in value) {
-        result[key] = (value as any).toJSON()
-      } else {
-        result[key] = value
+    // Fast path: readonly mode
+    if (this.readonly) {
+      const nativeJson = this.container.toJSON() as Record<string, any>
+      // For records, we need to overlay placeholders for each entry's nested shape
+      const result: Record<string, any> = {}
+      for (const key of Object.keys(nativeJson)) {
+        // For records, the placeholder is always {}, so we need to derive
+        // the placeholder for the nested shape on the fly
+        const nestedPlaceholderValue = deriveShapePlaceholder(this.shape.shape)
+
+        result[key] = mergeValue(
+          this.shape.shape,
+          nativeJson[key],
+          nestedPlaceholderValue as Value,
+        )
       }
+      return result
     }
-    return result
+
+    return serializeRefToJSON(this, this.keys())
   }
 }

package/src/typed-refs/text.ts

@@ -9,12 +9,12 @@ export class TextRef extends TypedRef<TextContainerShape> {
 
   // Text methods
   insert(index: number, content: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.insert(index, content)
   }
 
   delete(index: number, len: number): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.delete(index, len)
   }
 
@@ -27,17 +27,17 @@ export class TextRef extends TypedRef<TextContainerShape> {
   }
 
   update(text: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.update(text)
   }
 
   mark(range: { start: number; end: number }, key: string, value: any): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.mark(range, key, value)
   }
 
   unmark(range: { start: number; end: number }, key: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.unmark(range, key)
   }
 
@@ -46,7 +46,7 @@ export class TextRef extends TypedRef<TextContainerShape> {
   }
 
   applyDelta(delta: any[]): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.applyDelta(delta)
   }
 

package/src/typed-refs/tree.ts

@@ -8,17 +8,17 @@ export class TreeRef<T extends TreeContainerShape> extends TypedRef<T> {
   }
 
   createNode(parent?: any, index?: number): any {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     return this.container.createNode(parent, index)
   }
 
   move(target: any, parent?: any, index?: number): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.move(target, parent, index)
   }
 
   delete(target: any): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.delete(target)
   }