@loro-extended/change 0.7.0 → 0.8.0

package/src/derive-placeholder.test.ts

@@ -0,0 +1,245 @@
+import { describe, expect, it } from "vitest"
+import { derivePlaceholder } from "./derive-placeholder.js"
+import { Shape } from "./shape.js"
+
+describe("derivePlaceholder", () => {
+  it("uses default values when no placeholder set", () => {
+    const schema = Shape.doc({
+      title: Shape.text(),
+      count: Shape.counter(),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      title: "",
+      count: 0,
+    })
+  })
+
+  it("uses placeholder values when set", () => {
+    const schema = Shape.doc({
+      title: Shape.text().placeholder("Untitled"),
+      count: Shape.counter().placeholder(100),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      title: "Untitled",
+      count: 100,
+    })
+  })
+
+  it("composes nested map placeholders", () => {
+    const schema = Shape.doc({
+      settings: Shape.map({
+        theme: Shape.plain.string().placeholder("dark"),
+        fontSize: Shape.plain.number().placeholder(14),
+      }),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      settings: {
+        theme: "dark",
+        fontSize: 14,
+      },
+    })
+  })
+
+  it("uses empty arrays for lists", () => {
+    const schema = Shape.doc({
+      items: Shape.list(Shape.plain.string()),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      items: [],
+    })
+  })
+
+  it("uses empty objects for records", () => {
+    const schema = Shape.doc({
+      data: Shape.record(Shape.plain.number()),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      data: {},
+    })
+  })
+
+  it("handles plain value shapes with defaults", () => {
+    const schema = Shape.doc({
+      config: Shape.map({
+        name: Shape.plain.string(),
+        count: Shape.plain.number(),
+        enabled: Shape.plain.boolean(),
+        nothing: Shape.plain.null(),
+      }),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      config: {
+        name: "",
+        count: 0,
+        enabled: false,
+        nothing: null,
+      },
+    })
+  })
+
+  it("handles plain value shapes with custom placeholders", () => {
+    const schema = Shape.doc({
+      config: Shape.map({
+        name: Shape.plain.string().placeholder("default-name"),
+        count: Shape.plain.number().placeholder(42),
+        enabled: Shape.plain.boolean().placeholder(true),
+      }),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      config: {
+        name: "default-name",
+        count: 42,
+        enabled: true,
+      },
+    })
+  })
+
+  it("handles nested plain objects", () => {
+    const schema = Shape.doc({
+      user: Shape.map({
+        profile: Shape.plain.object({
+          name: Shape.plain.string().placeholder("Anonymous"),
+          age: Shape.plain.number().placeholder(0),
+        }),
+      }),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      user: {
+        profile: {
+          name: "Anonymous",
+          age: 0,
+        },
+      },
+    })
+  })
+
+  it("handles plain arrays as empty", () => {
+    const schema = Shape.doc({
+      tags: Shape.map({
+        items: Shape.plain.array(Shape.plain.string()),
+      }),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      tags: {
+        items: [],
+      },
+    })
+  })
+
+  it("handles plain records as empty", () => {
+    const schema = Shape.doc({
+      metadata: Shape.map({
+        values: Shape.plain.record(Shape.plain.number()),
+      }),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      metadata: {
+        values: {},
+      },
+    })
+  })
+
+  it("handles union types by deriving from first variant", () => {
+    const schema = Shape.doc({
+      value: Shape.map({
+        data: Shape.plain.union([Shape.plain.string(), Shape.plain.null()]),
+      }),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      value: {
+        data: "", // First variant is string, default is ""
+      },
+    })
+  })
+
+  it("handles union types with explicit placeholder", () => {
+    const schema = Shape.doc({
+      value: Shape.map({
+        data: Shape.plain
+          .union([Shape.plain.string(), Shape.plain.null()])
+          .placeholder(null),
+      }),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      value: {
+        data: null,
+      },
+    })
+  })
+
+  it("handles movable lists as empty arrays", () => {
+    const schema = Shape.doc({
+      tasks: Shape.movableList(Shape.plain.string()),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      tasks: [],
+    })
+  })
+
+  it("handles tree containers as empty arrays", () => {
+    const schema = Shape.doc({
+      hierarchy: Shape.tree(Shape.map({ name: Shape.text() })),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      hierarchy: [],
+    })
+  })
+
+  it("handles complex nested structures", () => {
+    const schema = Shape.doc({
+      article: Shape.map({
+        title: Shape.text().placeholder("Untitled Article"),
+        metadata: Shape.map({
+          views: Shape.counter().placeholder(0),
+          author: Shape.plain.object({
+            name: Shape.plain.string().placeholder("Anonymous"),
+            email: Shape.plain.string(),
+          }),
+          tags: Shape.list(Shape.plain.string()),
+        }),
+      }),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      article: {
+        title: "Untitled Article",
+        metadata: {
+          views: 0,
+          author: {
+            name: "Anonymous",
+            email: "",
+          },
+          tags: [],
+        },
+      },
+    })
+  })
+
+  it("handles string literal options", () => {
+    const schema = Shape.doc({
+      status: Shape.map({
+        value: Shape.plain.string("active", "inactive", "pending"),
+      }),
+    })
+
+    expect(derivePlaceholder(schema)).toEqual({
+      status: {
+        value: "active", // First option is the default
+      },
+    })
+  })
+})

package/src/derive-placeholder.ts

@@ -0,0 +1,132 @@
+import type { ContainerOrValueShape, DocShape, ValueShape } from "./shape.js"
+import type { InferPlaceholderType } from "./types.js"
+
+/**
+ * Derives the placeholder state from a schema by composing placeholder values.
+ *
+ * For leaf nodes (text, counter, values): uses _placeholder directly
+ * For containers (map, list, record): recurses into nested shapes
+ */
+export function derivePlaceholder<T extends DocShape>(
+  schema: T,
+): InferPlaceholderType<T> {
+  const result: Record<string, unknown> = {}
+
+  for (const [key, shape] of Object.entries(schema.shapes)) {
+    result[key] = deriveShapePlaceholder(shape)
+  }
+
+  return result as InferPlaceholderType<T>
+}
+
+/**
+ * Derives placeholder for a single shape.
+ *
+ * Leaf nodes: return _placeholder directly
+ * Containers: recurse into nested shapes (ignore _placeholder on containers)
+ */
+export function deriveShapePlaceholder(shape: ContainerOrValueShape): unknown {
+  switch (shape._type) {
+    // Leaf containers - use _placeholder directly
+    case "text":
+      return shape._placeholder
+    case "counter":
+      return shape._placeholder
+
+    // Dynamic containers - always empty (no per-entry merging)
+    case "list":
+    case "movableList":
+    case "tree":
+      return []
+    case "record":
+      return {}
+
+    // Structured container - recurse into nested shapes
+    case "map": {
+      const result: Record<string, unknown> = {}
+      for (const [key, nestedShape] of Object.entries(shape.shapes)) {
+        result[key] = deriveShapePlaceholder(nestedShape)
+      }
+      return result
+    }
+
+    case "value":
+      return deriveValueShapePlaceholder(shape)
+
+    default:
+      return undefined
+  }
+}
+
+function deriveValueShapePlaceholder(shape: ValueShape): unknown {
+  switch (shape.valueType) {
+    // Leaf values - use _placeholder directly
+    case "string":
+      return shape._placeholder
+    case "number":
+      return shape._placeholder
+    case "boolean":
+      return shape._placeholder
+    case "null":
+      return null
+    case "undefined":
+      return undefined
+    case "uint8array":
+      return shape._placeholder
+
+    // Structured value - recurse into nested shapes (like map)
+    case "object": {
+      const result: Record<string, unknown> = {}
+      for (const [key, nestedShape] of Object.entries(shape.shape)) {
+        result[key] = deriveValueShapePlaceholder(nestedShape)
+      }
+      return result
+    }
+
+    // Dynamic values - always empty
+    case "array":
+      return []
+    case "record":
+      return {}
+
+    // Unions - use _placeholder if explicitly set, otherwise derive from first variant
+    case "union": {
+      // Check if _placeholder was explicitly set (not the default empty object)
+      // We need to check if it's a primitive value OR a non-empty object
+      const placeholder = shape._placeholder
+      if (placeholder !== undefined) {
+        // If it's a primitive (null, string, number, boolean), use it
+        if (placeholder === null || typeof placeholder !== "object") {
+          return placeholder
+        }
+        // If it's an object with keys, use it
+        if (Object.keys(placeholder as object).length > 0) {
+          return placeholder
+        }
+      }
+      // Otherwise derive from first variant
+      return deriveValueShapePlaceholder(shape.shapes[0])
+    }
+
+    case "discriminatedUnion": {
+      // Check if _placeholder was explicitly set (not the default empty object)
+      const placeholder = shape._placeholder
+      if (placeholder !== undefined) {
+        // If it's a primitive (null, string, number, boolean), use it
+        if (placeholder === null || typeof placeholder !== "object") {
+          return placeholder
+        }
+        // If it's an object with keys, use it
+        if (Object.keys(placeholder as object).length > 0) {
+          return placeholder
+        }
+      }
+      // Otherwise derive from first variant
+      const firstKey = Object.keys(shape.variants)[0]
+      return deriveValueShapePlaceholder(shape.variants[firstKey])
+    }
+
+    default:
+      return undefined
+  }
+}

package/src/discriminated-union.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest"
-import { TypedDoc } from "./change.js"
 import { mergeValue } from "./overlay.js"
 import { Shape } from "./shape.js"
+import { TypedDoc } from "./typed-doc.js"
 import { validateValue } from "./validation.js"
 
 describe("discriminatedUnion", () => {
@@ -107,7 +107,7 @@ describe("discriminatedUnion", () => {
       EmptyClientPresence,
     )
 
-    // Should use client variant based on emptyState's type
+    // Should use client variant based on placeholder's type
     expect(result).toEqual({
       type: "client",
       name: "Bob",
@@ -216,15 +216,11 @@ describe("discriminatedUnion", () => {
       it("should allow setting a discriminated union property in a MapDraftNode", () => {
         const DocSchema = Shape.doc({
           state: Shape.map({
-            presence: GamePresenceSchema,
+            presence: GamePresenceSchema.placeholder(EmptyClientPresence),
           }),
         })
 
-        const doc = new TypedDoc(DocSchema, {
-          state: {
-            presence: EmptyClientPresence,
-          },
-        })
+        const doc = new TypedDoc(DocSchema)
 
         doc.change(draft => {
           // This should work now that MapDraftNode recognizes discriminatedUnion as a value shape
@@ -235,7 +231,7 @@ describe("discriminatedUnion", () => {
           }
         })
 
-        expect(doc.value.state.presence).toEqual({
+        expect(doc.toJSON().state.presence).toEqual({
           type: "server",
           cars: { p1: { x: 10, y: 20 } },
           tick: 100,

package/src/draft-nodes/base.ts

@@ -1,10 +1,11 @@
 import type { ContainerShape, DocShape, ShapeToContainer } from "../shape.js"
-import type { InferPlainType } from "../types.js"
+import type { Infer } from "../types.js"
 
 export type DraftNodeParams<Shape extends DocShape | ContainerShape> = {
   shape: Shape
-  emptyState?: InferPlainType<Shape>
+  placeholder?: Infer<Shape>
   getContainer: () => ShapeToContainer<Shape>
+  readonly?: boolean
 }
 
 // Base class for all draft nodes
@@ -19,8 +20,12 @@ export abstract class DraftNode<Shape extends DocShape | ContainerShape> {
     return this._params.shape
   }
 
-  protected get emptyState(): InferPlainType<Shape> | undefined {
-    return this._params.emptyState
+  protected get placeholder(): Infer<Shape> | undefined {
+    return this._params.placeholder
+  }
+
+  protected get readonly(): boolean {
+    return !!this._params.readonly
   }
 
   protected get container(): ShapeToContainer<Shape> {

package/src/draft-nodes/counter.md

@@ -0,0 +1,31 @@
+### Summary: The `getCounter` Side-Effect & Read-Only Access
+
+We have uncovered a subtle and unexpected between Loro's API and our `TypedDoc` "empty state" logic.
+
+#### 1. The Problem
+
+A test expects a LoroConter at `doc.value.counter` to return `1` (from `emptyState`), but it returns `0`.
+
+- **`doc.toJSON()`** works correctly: It sees the doc is empty, so it overlays `emptyState` (`{ counter: 1 }`).
+- **`doc.value`** fails: It returns `0`.
+
+#### 2. The Root Cause: "Heisenberg" Observation
+
+Accessing a root container in Loro changes it.
+
+- **Observation:** Calling `doc.getCounter("counter")` **materializes** the container in the CRDT with a default value of `0`.
+- **Consequence:** `DraftDoc` calls `getCounter` to read the value. This inadvertently "writes" a `0` to the document.
+- **Result:** The "empty" state is lost. The document now effectively contains `counter: 0`.
+
+#### 3. The Solution: `getShallowValue()`
+
+We need to peek at the document to see if a container exists _before_ we try to retrieve (and thus create) it.
+
+- **Investigation:** We verified that `doc.getShallowValue()` returns a list of existing root containers _without_ creating new ones.
+- **Strategy:**
+  1.  In `DraftDoc` (which handles root properties), check `readonly` mode.
+  2.  Call `doc.getShallowValue()`.
+  3.  **If key is missing:** Return the `emptyState` value directly.
+  4.  **If key exists:** Safe to call `doc.getCounter()` (or others) to get the actual CRDT value.
+
+This ensures `doc.value` remains a pure, non-destructive view that respects the "virtual" empty state.

package/src/draft-nodes/counter.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest"
+import { Shape } from "../shape.js"
+import { createTypedDoc } from "../typed-doc.js"
+
+describe("Counter Draft Node", () => {
+  it("should return placeholder value without materializing the container", () => {
+    const schema = Shape.doc({
+      counter: Shape.counter().placeholder(10),
+    })
+    const doc = createTypedDoc(schema)
+
+    // Accessing the value should return placeholder
+    expect(doc.value.counter).toBe(10)
+
+    // Verify it is NOT materialized in the underlying doc
+    const shallow = doc.loroDoc.getShallowValue()
+    expect(shallow.counter).toBeUndefined()
+  })
+
+  it("should materialize the container after modification", () => {
+    const schema = Shape.doc({
+      counter: Shape.counter().placeholder(10),
+    })
+    const doc = createTypedDoc(schema)
+
+    doc.change(draft => {
+      draft.counter.increment(5)
+    })
+
+    // Value should be updated
+    // Note: placeholder is NOT applied to the CRDT. It is only a read-time overlay.
+    // When we modify the counter, we are modifying the underlying CRDT counter which starts at 0.
+    // So 0 + 5 = 5. The placeholder (10) is lost once the container exists.
+    expect(doc.value.counter).toBe(5)
+
+    // Verify it IS materialized in the underlying doc
+    const shallow = doc.loroDoc.getShallowValue()
+    expect(shallow.counter).toBeDefined()
+  })
+
+  it("should respect placeholder even if accessed multiple times", () => {
+    const schema = Shape.doc({
+      counter: Shape.counter().placeholder(10),
+    })
+    const doc = createTypedDoc(schema)
+
+    expect(doc.value.counter).toBe(10)
+    expect(doc.value.counter).toBe(10)
+
+    // Still not materialized
+    expect(doc.loroDoc.getShallowValue().counter).toBeUndefined()
+  })
+})

package/src/draft-nodes/doc.ts

@@ -1,5 +1,5 @@
 import type { LoroDoc } from "loro-crdt"
-import type { InferPlainType } from "../index.js"
+import type { Infer } from "../index.js"
 import type { ContainerShape, DocShape } from "../shape.js"
 import { DraftNode, type DraftNodeParams } from "./base.js"
 import { createContainerDraftNode } from "./utils.js"
@@ -18,7 +18,7 @@ const containerGetter = {
 export class DraftDoc<Shape extends DocShape> extends DraftNode<Shape> {
   private doc: LoroDoc
   private propertyCache = new Map<string, DraftNode<ContainerShape>>()
-  private requiredEmptyState!: InferPlainType<Shape>
+  private requiredPlaceholder!: Infer<Shape>
 
   constructor(
     _params: Omit<DraftNodeParams<Shape>, "getContainer"> & { doc: LoroDoc },
@@ -29,9 +29,9 @@ export class DraftDoc<Shape extends DocShape> extends DraftNode<Shape> {
         throw new Error("can't get container on DraftDoc")
       },
     })
-    if (!_params.emptyState) throw new Error("emptyState required")
+    if (!_params.placeholder) throw new Error("placeholder required")
     this.doc = _params.doc
-    this.requiredEmptyState = _params.emptyState
+    this.requiredPlaceholder = _params.placeholder
     this.createLazyProperties()
   }
 
@@ -43,15 +43,27 @@ export class DraftDoc<Shape extends DocShape> extends DraftNode<Shape> {
 
     return {
       shape,
-      emptyState: this.requiredEmptyState[key],
+      placeholder: this.requiredPlaceholder[key],
       getContainer: () => getter(key),
+      readonly: this.readonly,
     }
   }
 
   getOrCreateDraftNode(
     key: string,
     shape: ContainerShape,
-  ): DraftNode<ContainerShape> {
+  ): DraftNode<ContainerShape> | number | string {
+    if (
+      this.readonly &&
+      (shape._type === "counter" || shape._type === "text")
+    ) {
+      // Check if the container exists in the doc without creating it
+      const shallow = this.doc.getShallowValue()
+      if (!shallow[key]) {
+        return this.requiredPlaceholder[key] as any
+      }
+    }
+
     let node = this.propertyCache.get(key)
 
     if (!node) {
@@ -59,6 +71,15 @@ export class DraftDoc<Shape extends DocShape> extends DraftNode<Shape> {
       this.propertyCache.set(key, node)
     }
 
+    if (this.readonly) {
+      if (shape._type === "counter") {
+        return (node as any).value
+      }
+      if (shape._type === "text") {
+        return (node as any).toString()
+      }
+    }
+
     return node
   }
 

package/src/draft-nodes/list-base.ts

@@ -84,7 +84,7 @@ export abstract class ListDraftNodeBase<
   ): DraftNodeParams<ContainerShape> {
     return {
       shape,
-      emptyState: undefined, // List items don't have empty state
+      placeholder: undefined, // List items don't have placeholder
       getContainer: () => {
         const containerItem = this.container.get(index)
         if (!containerItem || !isContainer(containerItem)) {
@@ -92,6 +92,7 @@ export abstract class ListDraftNodeBase<
         }
         return containerItem
       },
+      readonly: this.readonly,
     }
   }
 
@@ -142,7 +143,7 @@ export abstract class ListDraftNodeBase<
   }
 
   // Get item for return values - returns DraftItem that can be mutated
-  protected getDraftItem(index: number): DraftItem {
+  protected getDraftItem(index: number): any {
     // Check if we already have a cached item for this index
     let cachedItem = this.itemCache.get(index)
     if (cachedItem) {
@@ -167,14 +168,29 @@ export abstract class ListDraftNodeBase<
         // For primitives, just use the value directly
         cachedItem = containerItem
       }
-      this.itemCache.set(index, cachedItem)
+      // Only cache primitive values if NOT readonly
+      if (!this.readonly) {
+        this.itemCache.set(index, cachedItem)
+      }
       return cachedItem as DraftItem
     } else {
       // For container shapes, create a proper draft node using the new pattern
       cachedItem = createContainerDraftNode(
         this.getDraftNodeParams(index, this.shape.shape as ContainerShape),
       )
+      // Cache container nodes
       this.itemCache.set(index, cachedItem)
+
+      if (this.readonly) {
+        const shape = this.shape.shape as ContainerShape
+        if (shape._type === "counter") {
+          return (cachedItem as any).value
+        }
+        if (shape._type === "text") {
+          return (cachedItem as any).toString()
+        }
+      }
+
       return cachedItem as DraftItem
     }
   }
@@ -254,26 +270,31 @@ export abstract class ListDraftNodeBase<
   }
 
   insert(index: number, item: Item): void {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     // 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")
     // 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")
     this.pushWithConversion(item)
   }
 
   pushContainer(container: Container): Container {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     return this.container.pushContainer(container)
   }
 
   insertContainer(index: number, container: Container): Container {
+    if (this.readonly) throw new Error("Cannot modify readonly doc")
     return this.container.insertContainer(index, container)
   }