@loro-extended/change 0.9.0 → 1.0.0

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>(
@@ -79,85 +59,94 @@ export class RecordRef<
       getContainer: () =>
         this.container.getOrCreateContainer(key, new (LoroContainer as any)()),
       readonly: this.readonly,
+      autoCommit: this._params.autoCommit,
+      getDoc: this._params.getDoc,
     }
   }
 
-  getOrCreateNode(key: string): any {
-    // For readonly mode with container shapes, check if the key exists first
+  /**
+   * Gets an existing ref for a key, or returns undefined if the key doesn't exist.
+   * Used for reading operations where we want optional chaining to work.
+   */
+  getRef(key: string): any {
+    // For 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
-    if (this.readonly && isContainerShape(this.shape.shape)) {
+    if (isContainerShape(this.shape.shape)) {
       const existing = this.container.get(key)
       if (existing === undefined) {
         return undefined
       }
     }
 
-    let node = this.nodeCache.get(key)
-    if (!node) {
+    return this.getOrCreateRef(key)
+  }
+
+  /**
+   * Gets or creates a ref for a key.
+   * Always creates the container if it doesn't exist.
+   * This is the method used for write operations.
+   */
+  getOrCreateRef(key: string): any {
+    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.getRef(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)
+      this.commitIfAuto()
     } 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)
-
-        if (assignPlainValueToTypedRef(node, value)) {
-          return
-        }
+      // For container shapes, try to assign the plain value
+      // Use getOrCreateRef to ensure the container is created
+      const ref = this.getOrCreateRef(key)
+      if (assignPlainValueToTypedRef(ref, value)) {
+        this.commitIfAuto()
+        return
       }
-
       throw new Error(
         "Cannot set container directly, modify the typed ref instead",
       )
@@ -165,14 +154,17 @@ export class RecordRef<
   }
 
   setContainer<C extends Container>(key: string, container: C): C {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
-    return this.container.setContainer(key, container)
+    this.assertMutable()
+    const result = this.container.setContainer(key, container)
+    this.commitIfAuto()
+    return result
   }
 
   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)
+    this.commitIfAuto()
   }
 
   has(key: string): boolean {
@@ -191,16 +183,29 @@ export class RecordRef<
     return this.container.size
   }
 
-  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
+  toJSON(): Record<string, Infer<NestedShape>> {
+    // 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, Infer<NestedShape>> = {}
+      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,
+        ) as Infer<NestedShape>
       }
+      return result
     }
-    return result
+
+    return serializeRefToJSON(this, this.keys()) as Record<
+      string,
+      Infer<NestedShape>
+    >
   }
 }

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

@@ -1,46 +1,39 @@
-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,
-  MapContainerShape,
+  StructContainerShape,
   ValueShape,
 } from "../shape.js"
+import type { Infer } 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
-
-// Map typed ref
-export class MapRef<
+import {
+  absorbCachedPlainValues,
+  assignPlainValueToTypedRef,
+  containerConstructor,
+  createContainerTypedRef,
+  serializeRefToJSON,
+  unwrapReadonlyPrimitive,
+} from "./utils.js"
+
+/**
+ * Typed ref for struct containers (objects with fixed keys).
+ * Uses LoroMap as the underlying container.
+ */
+export class StructRef<
   NestedShapes extends Record<string, ContainerOrValueShape>,
 > extends TypedRef<any> {
   private propertyCache = new Map<string, TypedRef<ContainerShape> | Value>()
 
-  constructor(params: TypedRefParams<MapContainerShape<NestedShapes>>) {
+  constructor(params: TypedRefParams<StructContainerShape<NestedShapes>>) {
     super(params)
     this.createLazyProperties()
   }
 
-  protected get shape(): MapContainerShape<NestedShapes> {
-    return super.shape as MapContainerShape<NestedShapes>
+  protected get shape(): StructContainerShape<NestedShapes> {
+    return super.shape as StructContainerShape<NestedShapes>
   }
 
   protected get container(): LoroMap {
@@ -48,16 +41,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>(
@@ -74,40 +58,42 @@ export class MapRef<
       getContainer: () =>
         this.container.getOrCreateContainer(key, new (LoroContainer as any)()),
       readonly: this.readonly,
+      autoCommit: this._params.autoCommit,
+      getDoc: this._params.getDoc,
     }
   }
 
-  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,34 +104,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)
-
-              if (assignPlainValueToTypedRef(node as TypedRef<any>, value)) {
-                return
-              }
+            // For container shapes, try to assign the plain value
+            const ref = this.getOrCreateRef(key, shape)
+            if (assignPlainValueToTypedRef(ref as TypedRef<any>, value)) {
+              return
             }
             throw new Error(
               "Cannot set container directly, modify the typed ref instead",
@@ -157,37 +136,46 @@ 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
-      }
+  toJSON(): Infer<StructContainerShape<NestedShapes>> {
+    // 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,
+      ) as Infer<StructContainerShape<NestedShapes>>
     }
-    return result
+
+    return serializeRefToJSON(
+      this as any,
+      Object.keys(this.shape.shapes),
+    ) as Infer<StructContainerShape<NestedShapes>>
   }
 
-  // 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)
+    this.commitIfAuto()
   }
 
   setContainer<C extends Container>(key: string, container: C): C {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
-    return this.container.setContainer(key, container)
+    this.assertMutable()
+    const result = this.container.setContainer(key, container)
+    this.commitIfAuto()
+    return result
   }
 
   delete(key: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
     this.container.delete(key)
+    this.commitIfAuto()
   }
 
   has(key: string): boolean {

package/src/typed-refs/text.ts

@@ -1,44 +1,83 @@
+import type { LoroText } from "loro-crdt"
 import type { TextContainerShape } from "../shape.js"
 import { TypedRef } from "./base.js"
 
 // Text typed ref
 export class TextRef extends TypedRef<TextContainerShape> {
+  // Track if we've materialized the container (made any changes)
+  private _materialized = false
+
+  protected get container(): LoroText {
+    return super.container as LoroText
+  }
+
   absorbPlainValues() {
     // no plain values contained within
   }
 
   // Text methods
   insert(index: number, content: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
+    this._materialized = true
     this.container.insert(index, content)
+    this.commitIfAuto()
   }
 
   delete(index: number, len: number): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
+    this._materialized = true
     this.container.delete(index, len)
+    this.commitIfAuto()
   }
 
+  /**
+   * Returns the text content.
+   * If the text hasn't been materialized (no operations performed),
+   * returns the placeholder value if available.
+   */
   toString(): string {
-    return this.container.toString()
+    const containerValue = this.container.toString()
+    if (containerValue !== "" || this._materialized) {
+      return containerValue
+    }
+    // Return placeholder if available and container is at default state
+    if (this.placeholder !== undefined) {
+      return this.placeholder as string
+    }
+    return containerValue
+  }
+
+  valueOf(): string {
+    return this.toString()
   }
 
   toJSON(): string {
     return this.toString()
   }
 
+  [Symbol.toPrimitive](_hint: string): string {
+    return this.toString()
+  }
+
   update(text: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
+    this._materialized = true
     this.container.update(text)
+    this.commitIfAuto()
   }
 
   mark(range: { start: number; end: number }, key: string, value: any): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
+    this._materialized = true
     this.container.mark(range, key, value)
+    this.commitIfAuto()
   }
 
   unmark(range: { start: number; end: number }, key: string): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
+    this._materialized = true
     this.container.unmark(range, key)
+    this.commitIfAuto()
   }
 
   toDelta(): any[] {
@@ -46,8 +85,10 @@ export class TextRef extends TypedRef<TextContainerShape> {
   }
 
   applyDelta(delta: any[]): void {
-    if (this.readonly) throw new Error("Cannot modify readonly ref")
+    this.assertMutable()
+    this._materialized = true
     this.container.applyDelta(delta)
+    this.commitIfAuto()
   }
 
   get length(): number {

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)
   }