@loro-extended/change 0.9.1 → 1.0.0

package/src/typed-refs/text.ts

@@ -1,8 +1,16 @@
+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
   }
@@ -10,35 +18,66 @@ export class TextRef extends TypedRef<TextContainerShape> {
   // Text methods
   insert(index: number, content: string): void {
     this.assertMutable()
+    this._materialized = true
     this.container.insert(index, content)
+    this.commitIfAuto()
   }
 
   delete(index: number, len: number): void {
     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 {
     this.assertMutable()
+    this._materialized = true
     this.container.update(text)
+    this.commitIfAuto()
   }
 
   mark(range: { start: number; end: number }, key: string, value: any): void {
     this.assertMutable()
+    this._materialized = true
     this.container.mark(range, key, value)
+    this.commitIfAuto()
   }
 
   unmark(range: { start: number; end: number }, key: string): void {
     this.assertMutable()
+    this._materialized = true
     this.container.unmark(range, key)
+    this.commitIfAuto()
   }
 
   toDelta(): any[] {
@@ -47,7 +86,9 @@ export class TextRef extends TypedRef<TextContainerShape> {
 
   applyDelta(delta: any[]): void {
     this.assertMutable()
+    this._materialized = true
     this.container.applyDelta(delta)
+    this.commitIfAuto()
   }
 
   get length(): number {

package/src/typed-refs/utils.ts

@@ -11,16 +11,15 @@ import type {
   ContainerShape,
   CounterContainerShape,
   ListContainerShape,
-  MapContainerShape,
   MovableListContainerShape,
   RecordContainerShape,
+  StructContainerShape,
   TextContainerShape,
   TreeContainerShape,
 } from "../shape.js"
 import { TypedRef, type TypedRefParams } from "./base.js"
 import { CounterRef } from "./counter.js"
 import { ListRef } from "./list.js"
-import { MapRef } from "./map.js"
 import { MovableListRef } from "./movable-list.js"
 import {
   listProxyHandler,
@@ -28,6 +27,7 @@ import {
   recordProxyHandler,
 } from "./proxy-handlers.js"
 import { RecordRef } from "./record.js"
+import { StructRef } from "./struct.js"
 import { TextRef } from "./text.js"
 import { TreeRef } from "./tree.js"
 
@@ -38,9 +38,9 @@ import { TreeRef } from "./tree.js"
 export const containerConstructor = {
   counter: LoroCounter,
   list: LoroList,
-  map: LoroMap,
   movableList: LoroMovableList,
   record: LoroMap, // Records use LoroMap as their underlying container
+  struct: LoroMap, // Structs use LoroMap as their underlying container
   text: LoroText,
   tree: LoroTree,
 } as const
@@ -124,8 +124,8 @@ export function createContainerTypedRef(
         new ListRef(params as TypedRefParams<ListContainerShape>),
         listProxyHandler,
       )
-    case "map":
-      return new MapRef(params as TypedRefParams<MapContainerShape>)
+    case "struct":
+      return new StructRef(params as TypedRefParams<StructContainerShape>)
     case "movableList":
       return new Proxy(
         new MovableListRef(params as TypedRefParams<MovableListContainerShape>),
@@ -153,7 +153,7 @@ export function assignPlainValueToTypedRef(
 ): boolean {
   const shapeType = (ref as any).shape._type
 
-  if (shapeType === "map" || shapeType === "record") {
+  if (shapeType === "struct" || shapeType === "record") {
     for (const k in value) {
       ;(ref as any)[k] = value[k]
     }
@@ -173,5 +173,27 @@ export function assignPlainValueToTypedRef(
     }
   }
 
+  if (shapeType === "text") {
+    if (typeof value === "string") {
+      ;(ref as any).update(value)
+      return true
+    }
+    return false
+  }
+
+  if (shapeType === "counter") {
+    if (typeof value === "number") {
+      const currentValue = (ref as any).value
+      const diff = value - currentValue
+      if (diff > 0) {
+        ;(ref as any).increment(diff)
+      } else if (diff < 0) {
+        ;(ref as any).decrement(-diff)
+      }
+      return true
+    }
+    return false
+  }
+
   return false
 }

package/src/types.test.ts

@@ -1,8 +1,9 @@
 import { describe, expect, expectTypeOf, it } from "vitest"
+import { change } from "./functional-helpers.js"
 import type { ContainerShape, ValueShape } from "./shape.js"
 import { Shape } from "./shape.js"
 import { createTypedDoc } from "./typed-doc.js"
-import type { DeepReadonly, Infer } from "./types.js"
+import type { Infer } from "./types.js"
 
 describe("Infer type helper", () => {
   it("infers DocShape plain type", () => {
@@ -23,7 +24,7 @@ describe("Infer type helper", () => {
   })
 
   it("infers ValueShape plain type (object)", () => {
-    const schema = Shape.plain.object({
+    const schema = Shape.plain.struct({
       name: Shape.plain.string(),
       age: Shape.plain.number(),
     })
@@ -35,10 +36,10 @@ describe("Infer type helper", () => {
   it("infers nested shapes", () => {
     const schema = Shape.doc({
       users: Shape.list(
-        Shape.map({
+        Shape.struct({
           id: Shape.plain.string(),
           profile: Shape.record(
-            Shape.plain.object({
+            Shape.plain.struct({
               bio: Shape.plain.string(),
             }),
           ),
@@ -57,18 +58,18 @@ describe("Infer type helper", () => {
 
   it("infers discriminated union plain type", () => {
     const SessionStatusSchema = Shape.plain.discriminatedUnion("status", {
-      not_started: Shape.plain.object({
+      not_started: Shape.plain.struct({
         status: Shape.plain.string("not_started"),
       }),
-      lobby: Shape.plain.object({
+      lobby: Shape.plain.struct({
         status: Shape.plain.string("lobby"),
         lobbyPhase: Shape.plain.string("preparing", "typing"),
       }),
-      active: Shape.plain.object({
+      active: Shape.plain.struct({
         status: Shape.plain.string("active"),
         mode: Shape.plain.string("solo", "group"),
       }),
-      paused: Shape.plain.object({
+      paused: Shape.plain.struct({
         status: Shape.plain.string("paused"),
         previousStatus: Shape.plain.string("lobby", "active"),
         previousMode: Shape.plain.string("solo", "group"),
@@ -78,7 +79,7 @@ describe("Infer type helper", () => {
           "assignment_empty",
         ),
       }),
-      ended: Shape.plain.object({
+      ended: Shape.plain.struct({
         status: Shape.plain.string<"ended">("ended"),
       }),
     })
@@ -103,16 +104,16 @@ describe("Infer type helper", () => {
 
   it("infers discriminated union inside a map container", () => {
     const SessionStatusSchema = Shape.plain.discriminatedUnion("status", {
-      not_started: Shape.plain.object({
+      not_started: Shape.plain.struct({
         status: Shape.plain.string("not_started"),
       }),
-      active: Shape.plain.object({
+      active: Shape.plain.struct({
         status: Shape.plain.string("active"),
         mode: Shape.plain.string("solo", "group"),
       }),
     })
 
-    const SessionMetadataSchema = Shape.map({
+    const SessionMetadataSchema = Shape.struct({
       sessionStartedAt: Shape.plain.number(),
       sessionStatus: SessionStatusSchema,
     })
@@ -131,16 +132,16 @@ describe("Infer type helper", () => {
 
   it("infers discriminated union inside a doc", () => {
     const SessionStatusSchema = Shape.plain.discriminatedUnion("status", {
-      not_started: Shape.plain.object({
+      not_started: Shape.plain.struct({
         status: Shape.plain.string("not_started"),
       }),
-      active: Shape.plain.object({
+      active: Shape.plain.struct({
         status: Shape.plain.string("active"),
       }),
     })
 
     const DocSchema = Shape.doc({
-      metadata: Shape.map({
+      metadata: Shape.struct({
         sessionStartedAt: Shape.plain.number(),
         sessionStatus: SessionStatusSchema,
       }),
@@ -162,11 +163,11 @@ describe("Infer type helper", () => {
     // This test verifies the fix for usePresence type inference
     // The issue was that DiscriminatedUnionValueShape<any, any> in the ValueShape union
     // caused type information to be lost when inferring through generic constraints
-    const ClientPresenceShape = Shape.plain.object({
+    const ClientPresenceShape = Shape.plain.struct({
       type: Shape.plain.string("client"),
       name: Shape.plain.string(),
     })
-    const ServerPresenceShape = Shape.plain.object({
+    const ServerPresenceShape = Shape.plain.struct({
       type: Shape.plain.string("server"),
       tick: Shape.plain.number(),
     })
@@ -188,9 +189,9 @@ describe("Infer type helper", () => {
   })
 })
 
-describe("DeepReadonly type helper", () => {
-  it("Object.values returns clean types without toJSON function in union", () => {
-    const ParticipantSchema = Shape.plain.object({
+describe("Mutable type helper", () => {
+  it("Object.values returns values from the record", () => {
+    const ParticipantSchema = Shape.plain.struct({
       id: Shape.plain.string(),
       name: Shape.plain.string(),
     })
@@ -201,29 +202,23 @@ describe("DeepReadonly type helper", () => {
 
     const doc = createTypedDoc(GroupSessionSchema)
 
-    doc.change((root: any) => {
+    change(doc, (root: any) => {
       root.participants.set("p1", { id: "1", name: "Alice" })
       root.participants.set("p2", { id: "2", name: "Bob" })
     })
 
-    const participants = doc.value.participants
+    const participants = doc.participants
 
-    // Object.values should return clean types
+    // Object.values returns the values from the record
     const values = Object.values(participants)
 
-    type Participant = Infer<typeof ParticipantSchema>
-
-    // FIXED: Object.values now returns clean DeepReadonly<Participant>[]
-    // Previously it returned: (DeepReadonly<Participant> | (() => Record<...>))[]
-    expectTypeOf(values).toEqualTypeOf<DeepReadonly<Participant>[]>()
-
-    // Runtime check
+    // Runtime check - values are the plain objects
     expect(values).toHaveLength(2)
-    expect(values.map(p => p.name).sort()).toEqual(["Alice", "Bob"])
+    expect(values.map((p: any) => p.name).sort()).toEqual(["Alice", "Bob"])
   })
 
-  it("toJSON is still callable on Records", () => {
-    const ParticipantSchema = Shape.plain.object({
+  it("toJSON is callable on Records", () => {
+    const ParticipantSchema = Shape.plain.struct({
       id: Shape.plain.string(),
       name: Shape.plain.string(),
     })
@@ -234,11 +229,11 @@ describe("DeepReadonly type helper", () => {
 
     const doc = createTypedDoc(GroupSessionSchema)
 
-    doc.change((root: any) => {
+    change(doc, (root: any) => {
       root.participants.set("p1", { id: "1", name: "Alice" })
     })
 
-    const participants = doc.value.participants
+    const participants = doc.participants
 
     // toJSON should be callable
     const json = participants.toJSON()
@@ -252,8 +247,8 @@ describe("DeepReadonly type helper", () => {
     expect(json).toEqual({ p1: { id: "1", name: "Alice" } })
   })
 
-  it("toJSON is still callable on Maps", () => {
-    const MetaSchema = Shape.map({
+  it("toJSON is callable on Maps", () => {
+    const MetaSchema = Shape.struct({
       title: Shape.plain.string(),
       count: Shape.plain.number(),
     })
@@ -264,12 +259,12 @@ describe("DeepReadonly type helper", () => {
 
     const doc = createTypedDoc(DocSchema)
 
-    doc.change((root: any) => {
+    change(doc, (root: any) => {
       root.meta.title = "Test"
       root.meta.count = 42
     })
 
-    const meta = doc.value.meta
+    const meta = doc.meta
 
     // toJSON should be callable
     const json = meta.toJSON()

package/src/types.ts

@@ -14,7 +14,7 @@ import type { ContainerShape, DocShape, Shape } from "./shape.js"
  * @example
  * ```typescript
  * const ChatSchema = Shape.doc({
- *   messages: Shape.list(Shape.map({
+ *   messages: Shape.list(Shape.struct({
  *     id: Shape.plain.string(),
  *     content: Shape.text(),
  *   })),
@@ -24,9 +24,9 @@ import type { ContainerShape, DocShape, Shape } from "./shape.js"
  * type ChatDoc = Infer<typeof ChatSchema>
  * // Result: { messages: { id: string; content: string }[] }
  *
- * const PresenceSchema = Shape.plain.object({
+ * const PresenceSchema = Shape.plain.struct({
  *   name: Shape.plain.string(),
- *   cursor: Shape.plain.object({ x: Shape.plain.number(), y: Shape.plain.number() }),
+ *   cursor: Shape.plain.struct({ x: Shape.plain.number(), y: Shape.plain.number() }),
  * })
  *
  * // Extract the presence type
@@ -58,14 +58,14 @@ export type InferPlaceholderType<T> = T extends Shape<any, any, infer P>
   : never
 
 /**
- * Mutable type for use within change() callbacks.
+ * Mutable type for use within change() callbacks and direct mutations on doc.value.
  * This is the type-safe wrapper around CRDT containers that allows mutation.
  */
 export type Mutable<T extends DocShape<Record<string, ContainerShape>>> =
   InferMutableType<T>
 
 /**
- * @deprecated Use Mutable<T> instead
+ * @deprecated Use Mutable<T> instead. Draft is an alias kept for backwards compatibility.
  */
 export type Draft<T extends DocShape<Record<string, ContainerShape>>> =
   Mutable<T>
@@ -77,38 +77,3 @@ export type Draft<T extends DocShape<Record<string, ContainerShape>>> =
 export interface HasToJSON<T> {
   toJSON(): T
 }
-
-/**
- * Deep readonly wrapper for plain objects (no index signature).
- * Includes toJSON() method.
- */
-export type DeepReadonlyObject<T extends object> = {
-  readonly [P in keyof T]: DeepReadonly<T[P]>
-} & HasToJSON<T>
-
-/**
- * Deep readonly wrapper for Record types (with string index signature).
- * The toJSON() method is available but NOT part of the index signature,
- * so Object.values() returns clean types.
- */
-export type DeepReadonlyRecord<T> = {
-  readonly [K in keyof T]: DeepReadonly<T[K]>
-} & HasToJSON<Record<string, T[keyof T]>>
-
-/**
- * Deep readonly wrapper that makes all properties readonly recursively
- * and adds a toJSON() method for JSON serialization.
- *
- * For arrays: Returns ReadonlyArray with toJSON()
- * For objects with string index signature (Records): toJSON() is available
- *   but doesn't pollute Object.values() type inference
- * For plain objects: Returns readonly properties with toJSON()
- * For primitives: Returns as-is
- */
-export type DeepReadonly<T> = T extends any[]
-  ? ReadonlyArray<DeepReadonly<T[number]>> & HasToJSON<T>
-  : T extends object
-    ? string extends keyof T
-      ? DeepReadonlyRecord<T>
-      : DeepReadonlyObject<T>
-    : T

package/src/utils/type-guards.ts

@@ -14,9 +14,9 @@ import type {
   ContainerShape,
   CounterContainerShape,
   ListContainerShape,
-  MapContainerShape,
   MovableListContainerShape,
   RecordContainerShape,
+  StructContainerShape,
   TextContainerShape,
   TreeContainerShape,
   ValueShape,
@@ -146,14 +146,19 @@ export function isMovableListShape(
 }
 
 /**
- * Type guard to check if a schema is for MapDraftNode
+ * Type guard to check if a schema is for StructDraftNode
  */
-export function isMapShape(
+export function isStructShape(
   schema: ContainerOrValueShape,
-): schema is MapContainerShape {
-  return schema && typeof schema === "object" && schema._type === "map"
+): schema is StructContainerShape {
+  return schema && typeof schema === "object" && schema._type === "struct"
 }
 
+/**
+ * @deprecated Use isStructShape instead. isMapShape is an alias for backward compatibility.
+ */
+export const isMapShape = isStructShape
+
 /**
  * Type guard to check if a schema is for RecordDraftNode
  */
@@ -193,7 +198,7 @@ export function isValueShape(
       "null",
       "undefined",
       "uint8array",
-      "object",
+      "struct",
       "record",
       "array",
       "union",

package/src/validation.ts

@@ -4,12 +4,12 @@ import type {
   DiscriminatedUnionValueShape,
   DocShape,
   ListContainerShape,
-  MapContainerShape,
   MovableListContainerShape,
-  ObjectValueShape,
   RecordContainerShape,
   RecordValueShape,
   StringValueShape,
+  StructContainerShape,
+  StructValueShape,
   UnionValueShape,
   ValueShape,
 } from "./shape.js"
@@ -60,17 +60,17 @@ export function validateValue(
     )
   }
 
-  if (schema._type === "map") {
+  if (schema._type === "struct") {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
       throw new Error(
         `Expected object at path ${currentPath}, got ${typeof value}`,
       )
     }
-    const mapSchema = schema as MapContainerShape
+    const structSchema = schema as StructContainerShape
     const result: Record<string, unknown> = {}
 
-    // Validate each property in the map shape
-    for (const [key, nestedSchema] of Object.entries(mapSchema.shapes)) {
+    // Validate each property in the struct shape
+    for (const [key, nestedSchema] of Object.entries(structSchema.shapes)) {
       const nestedPath = `${currentPath}.${key}`
       const nestedValue = (value as Record<string, unknown>)[key]
       result[key] = validateValue(nestedValue, nestedSchema, nestedPath)
@@ -165,17 +165,17 @@ export function validateValue(
         }
         return value
 
-      case "object": {
+      case "struct": {
         if (!value || typeof value !== "object" || Array.isArray(value)) {
           throw new Error(
             `Expected object at path ${currentPath}, got ${typeof value}`,
           )
         }
-        const objectSchema = valueSchema as ObjectValueShape
+        const structSchema = valueSchema as StructValueShape
         const result: Record<string, unknown> = {}
 
-        // Validate each property in the object shape
-        for (const [key, nestedSchema] of Object.entries(objectSchema.shape)) {
+        // Validate each property in the struct shape
+        for (const [key, nestedSchema] of Object.entries(structSchema.shape)) {
           const nestedPath = `${currentPath}.${key}`
           const nestedValue = (value as Record<string, unknown>)[key]
           result[key] = validateValue(nestedValue, nestedSchema, nestedPath)