@loro-extended/change 4.0.0 → 5.0.0

package/src/typed-refs/struct-ref-internals.ts

@@ -0,0 +1,195 @@
+import type {
+  Container,
+  LoroDoc,
+  LoroMap,
+  Subscription,
+  Value,
+} from "loro-crdt"
+import type { LoroMapRef } from "../loro.js"
+import type {
+  ContainerOrValueShape,
+  ContainerShape,
+  StructContainerShape,
+  ValueShape,
+} from "../shape.js"
+import { isValueShape } from "../utils/type-guards.js"
+import { BaseRefInternals, type TypedRef, type TypedRefParams } from "./base.js"
+import {
+  absorbCachedPlainValues,
+  assignPlainValueToTypedRef,
+  containerConstructor,
+  createContainerTypedRef,
+  hasContainerConstructor,
+} from "./utils.js"
+
+/**
+ * Internal implementation for StructRef.
+ * Contains all logic, state, and implementation details.
+ */
+export class StructRefInternals<
+  NestedShapes extends Record<string, ContainerOrValueShape>,
+> extends BaseRefInternals<any> {
+  private propertyCache = new Map<string, TypedRef<ContainerShape> | Value>()
+
+  /** Get typed ref params for creating child refs at a key */
+  getTypedRefParams(
+    key: string,
+    shape: ContainerShape,
+  ): TypedRefParams<ContainerShape> {
+    const placeholder = (this.getPlaceholder() as any)?.[key]
+
+    // AnyContainerShape is an escape hatch - it doesn't have a constructor
+    if (!hasContainerConstructor(shape._type)) {
+      throw new Error(
+        `Cannot create typed ref for shape type "${shape._type}". ` +
+          `Use Shape.any() only at the document root level.`,
+      )
+    }
+
+    const LoroContainer = containerConstructor[shape._type]
+    const container = this.getContainer() as LoroMap
+
+    return {
+      shape,
+      placeholder,
+      getContainer: () =>
+        container.getOrCreateContainer(key, new (LoroContainer as any)()),
+      autoCommit: this.getAutoCommit(),
+      batchedMutation: this.getBatchedMutation(),
+      getDoc: () => this.getDoc(),
+    }
+  }
+
+  /** Get or create a ref for a key */
+  getOrCreateRef<Shape extends ContainerShape | ValueShape>(
+    key: string,
+    shape?: Shape,
+  ): unknown {
+    const structShape = this.getShape() as StructContainerShape<NestedShapes>
+    const actualShape = shape || structShape.shapes[key]
+    const container = this.getContainer() as LoroMap
+
+    if (isValueShape(actualShape)) {
+      // When NOT in batchedMutation mode (direct access outside of change()), ALWAYS read fresh
+      // from container (NEVER cache). This ensures we always get the latest value
+      // from the CRDT, even when modified by a different ref instance (e.g., drafts from change())
+      //
+      // When in batchedMutation mode (inside change()), we cache value shapes so that
+      // mutations to nested objects persist back to the CRDT via absorbPlainValues()
+      if (!this.getBatchedMutation()) {
+        const containerValue = container.get(key)
+        if (containerValue !== undefined) {
+          return containerValue
+        }
+        // Only fall back to placeholder if the container doesn't have the value
+        const placeholder = (this.getPlaceholder() as any)?.[key]
+        if (placeholder === undefined) {
+          throw new Error("placeholder required")
+        }
+        return placeholder
+      }
+
+      // In batched mode (within change()), we cache value shapes so that
+      // mutations to nested objects persist back to the CRDT via absorbPlainValues()
+      let ref = this.propertyCache.get(key)
+      if (!ref) {
+        const containerValue = container.get(key)
+        if (containerValue !== undefined) {
+          // For objects, create a deep copy so mutations can be tracked
+          if (typeof containerValue === "object" && containerValue !== null) {
+            ref = JSON.parse(JSON.stringify(containerValue))
+          } else {
+            ref = containerValue as Value
+          }
+        } else {
+          // Only fall back to placeholder if the container doesn't have the value
+          const placeholder = (this.getPlaceholder() as any)?.[key]
+          if (placeholder === undefined) {
+            throw new Error("placeholder required")
+          }
+          ref = placeholder as Value
+        }
+        this.propertyCache.set(key, ref)
+      }
+      return ref
+    }
+
+    // Container shapes: safe to cache (handles)
+    let ref = this.propertyCache.get(key)
+    if (!ref) {
+      ref = createContainerTypedRef(
+        this.getTypedRefParams(key, actualShape as ContainerShape),
+      )
+      this.propertyCache.set(key, ref)
+    }
+
+    return ref as Shape extends ContainerShape ? TypedRef<Shape> : Value
+  }
+
+  /** Set a property value */
+  setPropertyValue(key: string, value: unknown): void {
+    const structShape = this.getShape() as StructContainerShape<NestedShapes>
+    const shape = structShape.shapes[key]
+    const container = this.getContainer() as LoroMap
+
+    if (!shape) {
+      throw new Error(`Unknown property: ${key}`)
+    }
+
+    if (isValueShape(shape)) {
+      container.set(key, value)
+      this.propertyCache.set(key, value as Value)
+      this.commitIfAuto()
+    } else {
+      // For container shapes, try to assign the plain value
+      const ref = this.getOrCreateRef(key, shape)
+      if (assignPlainValueToTypedRef(ref as TypedRef<any>, value)) {
+        this.commitIfAuto()
+        return
+      }
+      throw new Error(
+        "Cannot set container directly, modify the typed ref instead",
+      )
+    }
+  }
+
+  /** Delete a property */
+  deleteProperty(key: string): void {
+    const container = this.getContainer() as LoroMap
+    container.delete(key)
+    this.propertyCache.delete(key)
+    this.commitIfAuto()
+  }
+
+  /** Absorb mutated plain values back into Loro containers */
+  absorbPlainValues(): void {
+    absorbCachedPlainValues(
+      this.propertyCache,
+      () => this.getContainer() as LoroMap,
+    )
+  }
+
+  /** Create the loro namespace for struct */
+  protected override createLoroNamespace(): LoroMapRef {
+    const self = this
+    return {
+      get doc(): LoroDoc {
+        return self.getDoc()
+      },
+      get container(): LoroMap {
+        return self.getContainer() as LoroMap
+      },
+      subscribe(callback: (event: unknown) => void): Subscription {
+        return (self.getContainer() as LoroMap).subscribe(callback)
+      },
+      setContainer(key: string, container: Container): Container {
+        const result = (self.getContainer() as LoroMap).setContainer(
+          key,
+          container,
+        )
+        self.commitIfAuto()
+        return result
+      },
+    }
+  }
+}

package/src/typed-refs/{struct-value-updates.test.ts → struct-ref.test.ts}

@@ -123,9 +123,11 @@ describe("Struct value updates across change() calls", () => {
 
       // Update the struct's value properties
       change(doc, draft => {
-        const user = draft.users.getOrCreateRef("user1")
-        user.name = "Bob"
-        user.age = 25
+        const user = draft.users.get("user1")
+        if (user) {
+          user.name = "Bob"
+          user.age = 25
+        }
       })
       expect(doc.users.user1?.name).toBe("Bob") // FAILS: returns "Alice"
       expect(doc.users.user1?.age).toBe(25) // FAILS: returns 30

package/src/typed-refs/struct-ref.ts

@@ -0,0 +1,257 @@
+import type { Container, LoroMap, Value } from "loro-crdt"
+import { LORO_SYMBOL } from "../loro.js"
+import type { ContainerOrValueShape, StructContainerShape } from "../shape.js"
+import type { Infer } from "../types.js"
+import {
+  INTERNAL_SYMBOL,
+  type RefInternalsBase,
+  TypedRef,
+  type TypedRefParams,
+} from "./base.js"
+import { StructRefInternals } from "./struct-ref-internals.js"
+import { serializeRefToJSON } from "./utils.js"
+
+/**
+ * Internal implementation class for struct containers.
+ * The actual StructRef is a Proxy wrapping this class.
+ */
+class StructRefImpl<
+  NestedShapes extends Record<string, ContainerOrValueShape>,
+> extends TypedRef<any> {
+  [INTERNAL_SYMBOL]: StructRefInternals<NestedShapes>
+
+  constructor(params: TypedRefParams<any>) {
+    super()
+    this[INTERNAL_SYMBOL] = new StructRefInternals(params)
+  }
+
+  get structShape(): StructContainerShape<NestedShapes> {
+    return this[
+      INTERNAL_SYMBOL
+    ].getShape() as StructContainerShape<NestedShapes>
+  }
+
+  toJSON(): Infer<StructContainerShape<NestedShapes>> {
+    return serializeRefToJSON(
+      this as any,
+      Object.keys(this.structShape.shapes),
+    ) as Infer<StructContainerShape<NestedShapes>>
+  }
+
+  // Deprecated methods - kept for backward compatibility
+  // @deprecated Use property access instead: obj.key
+  get(key: string): any {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    return container.get(key)
+  }
+
+  // @deprecated Use property assignment instead: obj.key = value
+  set(key: string, value: Value): void {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    container.set(key, value)
+    this[INTERNAL_SYMBOL].commitIfAuto()
+  }
+
+  // @deprecated Use loro(struct).setContainer() instead
+  setContainer<C extends Container>(key: string, container: C): C {
+    const loroContainer = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    const result = loroContainer.setContainer(key, container)
+    this[INTERNAL_SYMBOL].commitIfAuto()
+    return result
+  }
+
+  // @deprecated Use delete obj.key instead
+  delete(key: string): void {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    container.delete(key)
+    this[INTERNAL_SYMBOL].commitIfAuto()
+  }
+
+  // @deprecated Use 'key' in obj instead
+  has(key: string): boolean {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    return container.get(key) !== undefined
+  }
+
+  // @deprecated Use Object.keys(obj) instead
+  keys(): string[] {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    return container.keys()
+  }
+
+  // @deprecated Use Object.values(obj) instead
+  values(): any[] {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    return container.values()
+  }
+
+  // @deprecated Not standard for objects
+  get size(): number {
+    const container = this[INTERNAL_SYMBOL].getContainer() as LoroMap
+    return container.size
+  }
+}
+
+/**
+ * Creates a StructRef wrapped in a Proxy for JavaScript-native object behavior.
+ * Supports:
+ * - Property access: obj.key
+ * - Property assignment: obj.key = value
+ * - Object.keys(obj)
+ * - 'key' in obj
+ * - delete obj.key
+ * - toJSON()
+ * - loro(obj) for CRDT access
+ */
+export function createStructRef<
+  NestedShapes extends Record<string, ContainerOrValueShape>,
+>(
+  params: TypedRefParams<StructContainerShape<NestedShapes>>,
+): StructRef<NestedShapes> {
+  const impl = new StructRefImpl<NestedShapes>(params)
+
+  const proxy = new Proxy(impl, {
+    get(target, prop, receiver) {
+      // Handle Symbol access (loro(), internal, etc.)
+      if (prop === LORO_SYMBOL) {
+        return target[INTERNAL_SYMBOL].getLoroNamespace()
+      }
+
+      // Handle INTERNAL_SYMBOL for internal methods
+      if (prop === INTERNAL_SYMBOL) {
+        return target[INTERNAL_SYMBOL]
+      }
+
+      // Handle toJSON - use serializeRefToJSON with the proxy (receiver) so property access goes through the proxy
+      if (prop === "toJSON") {
+        return () =>
+          serializeRefToJSON(receiver, Object.keys(target.structShape.shapes))
+      }
+
+      // Handle shape access (internal - needed for assignPlainValueToTypedRef)
+      if (prop === "shape") {
+        return target.structShape
+      }
+
+      // Schema property access
+      if (typeof prop === "string" && prop in target.structShape.shapes) {
+        const shape = target.structShape.shapes[prop]
+        return target[INTERNAL_SYMBOL].getOrCreateRef(prop, shape)
+      }
+
+      return undefined
+    },
+
+    set(target, prop, value) {
+      if (typeof prop === "string" && prop in target.structShape.shapes) {
+        target[INTERNAL_SYMBOL].setPropertyValue(prop, value)
+        return true
+      }
+      return false
+    },
+
+    has(target, prop) {
+      if (
+        prop === LORO_SYMBOL ||
+        prop === INTERNAL_SYMBOL ||
+        prop === "toJSON" ||
+        prop === "shape"
+      ) {
+        return true
+      }
+      if (typeof prop === "string") {
+        return prop in target.structShape.shapes
+      }
+      return false
+    },
+
+    deleteProperty(target, prop) {
+      if (typeof prop === "string" && prop in target.structShape.shapes) {
+        target[INTERNAL_SYMBOL].deleteProperty(prop)
+        return true
+      }
+      return false
+    },
+
+    ownKeys(target) {
+      // Return only schema keys, not internal methods
+      return Object.keys(target.structShape.shapes)
+    },
+
+    getOwnPropertyDescriptor(target, prop) {
+      if (typeof prop === "string" && prop in target.structShape.shapes) {
+        const shape = target.structShape.shapes[prop]
+        return {
+          configurable: true,
+          enumerable: true,
+          value: target[INTERNAL_SYMBOL].getOrCreateRef(prop, shape),
+        }
+      }
+      return undefined
+    },
+  }) as unknown as StructRef<NestedShapes>
+
+  return proxy
+}
+
+/**
+ * Typed ref for struct containers (objects with fixed keys).
+ * Uses LoroMap as the underlying container.
+ *
+ * Supports JavaScript-native object behavior:
+ * - Property access: obj.key
+ * - Property assignment: obj.key = value
+ * - Object.keys(obj)
+ * - 'key' in obj
+ * - delete obj.key
+ *
+ * @example
+ * ```typescript
+ * const schema = Shape.doc({
+ *   settings: Shape.struct({
+ *     darkMode: Shape.plain.boolean().placeholder(false),
+ *     fontSize: Shape.plain.number().placeholder(14),
+ *   }),
+ * });
+ *
+ * const doc = createTypedDoc(schema);
+ *
+ * // Property access
+ * doc.settings.darkMode = true;
+ * console.log(doc.settings.darkMode); // true
+ *
+ * // Object.keys()
+ * console.log(Object.keys(doc.settings)); // ['darkMode', 'fontSize']
+ *
+ * // 'key' in obj
+ * console.log('darkMode' in doc.settings); // true
+ *
+ * // delete obj.key
+ * delete doc.settings.darkMode;
+ *
+ * // CRDT access via loro()
+ * import { loro } from "@loro-extended/change";
+ * loro(doc.settings).setContainer('nested', loroMap);
+ * loro(doc.settings).subscribe(callback);
+ * ```
+ */
+export type StructRef<
+  NestedShapes extends Record<string, ContainerOrValueShape>,
+> = {
+  [K in keyof NestedShapes]: NestedShapes[K]["_mutable"]
+} & {
+  /**
+   * Serializes the struct to a plain JSON-compatible object.
+   */
+  toJSON(): Infer<StructContainerShape<NestedShapes>>
+
+  /**
+   * Internal methods accessed via INTERNAL_SYMBOL.
+   * @internal
+   */
+  [INTERNAL_SYMBOL]: RefInternalsBase
+}
+
+// Re-export for backward compatibility
+// The old class-based StructRef is now replaced by the proxy-based version
+export { StructRefImpl as StructRefClass }

package/src/typed-refs/text-ref-internals.ts

@@ -0,0 +1,100 @@
+import type { LoroDoc, LoroText, Subscription } from "loro-crdt"
+import type { LoroTextRef } from "../loro.js"
+import type { TextContainerShape } from "../shape.js"
+import { BaseRefInternals } from "./base.js"
+
+/**
+ * Internal implementation for TextRef.
+ * Contains all logic, state, and implementation details.
+ */
+export class TextRefInternals extends BaseRefInternals<TextContainerShape> {
+  private materialized = false
+
+  /** Insert text at the given index */
+  insert(index: number, content: string): void {
+    this.materialized = true
+    ;(this.getContainer() as LoroText).insert(index, content)
+    this.commitIfAuto()
+  }
+
+  /** Delete text at the given index */
+  delete(index: number, len: number): void {
+    this.materialized = true
+    ;(this.getContainer() as LoroText).delete(index, len)
+    this.commitIfAuto()
+  }
+
+  /** Update the entire text content */
+  update(text: string): void {
+    this.materialized = true
+    ;(this.getContainer() as LoroText).update(text)
+    this.commitIfAuto()
+  }
+
+  /** Mark a range of text with a key-value pair */
+  mark(range: { start: number; end: number }, key: string, value: any): void {
+    this.materialized = true
+    ;(this.getContainer() as LoroText).mark(range, key, value)
+    this.commitIfAuto()
+  }
+
+  /** Remove a mark from a range of text */
+  unmark(range: { start: number; end: number }, key: string): void {
+    this.materialized = true
+    ;(this.getContainer() as LoroText).unmark(range, key)
+    this.commitIfAuto()
+  }
+
+  /** Apply a delta to the text */
+  applyDelta(delta: any[]): void {
+    this.materialized = true
+    ;(this.getContainer() as LoroText).applyDelta(delta)
+    this.commitIfAuto()
+  }
+
+  /** Get the text as a string */
+  getStringValue(): string {
+    const container = this.getContainer() as LoroText
+    const containerValue = container.toString()
+    if (containerValue !== "" || this.materialized) {
+      return containerValue
+    }
+    // Return placeholder if available and container is at default state
+    const placeholder = this.getPlaceholder()
+    if (placeholder !== undefined) {
+      return placeholder as string
+    }
+    return containerValue
+  }
+
+  /** Get the text as a delta */
+  toDelta(): any[] {
+    return (this.getContainer() as LoroText).toDelta()
+  }
+
+  /** Get the length of the text */
+  getLength(): number {
+    return (this.getContainer() as LoroText).length
+  }
+
+  /** No plain values in text */
+  absorbPlainValues(): void {
+    // no plain values contained within
+  }
+
+  /** Create the loro namespace for text */
+  protected override createLoroNamespace(): LoroTextRef {
+    const self = this
+    return {
+      get doc(): LoroDoc {
+        return self.getDoc()
+      },
+      get container(): LoroText {
+        return self.getContainer() as LoroText
+      },
+      subscribe(callback: (event: unknown) => void): Subscription {
+        return (self.getContainer() as LoroText).subscribe(callback)
+      },
+    }
+  }
+}

package/src/typed-refs/text-ref.ts

@@ -0,0 +1,72 @@
+import type { TextContainerShape } from "../shape.js"
+import { INTERNAL_SYMBOL, TypedRef, type TypedRefParams } from "./base.js"
+import { TextRefInternals } from "./text-ref-internals.js"
+
+/**
+ * Text typed ref - thin facade that delegates to TextRefInternals.
+ */
+export class TextRef extends TypedRef<TextContainerShape> {
+  [INTERNAL_SYMBOL]: TextRefInternals
+
+  constructor(params: TypedRefParams<TextContainerShape>) {
+    super()
+    this[INTERNAL_SYMBOL] = new TextRefInternals(params)
+  }
+
+  /** Insert text at the given index */
+  insert(index: number, content: string): void {
+    this[INTERNAL_SYMBOL].insert(index, content)
+  }
+
+  /** Delete text at the given index */
+  delete(index: number, len: number): void {
+    this[INTERNAL_SYMBOL].delete(index, len)
+  }
+
+  /** Update the entire text content */
+  update(text: string): void {
+    this[INTERNAL_SYMBOL].update(text)
+  }
+
+  /** Mark a range of text with a key-value pair */
+  mark(range: { start: number; end: number }, key: string, value: any): void {
+    this[INTERNAL_SYMBOL].mark(range, key, value)
+  }
+
+  /** Remove a mark from a range of text */
+  unmark(range: { start: number; end: number }, key: string): void {
+    this[INTERNAL_SYMBOL].unmark(range, key)
+  }
+
+  /** Apply a delta to the text */
+  applyDelta(delta: any[]): void {
+    this[INTERNAL_SYMBOL].applyDelta(delta)
+  }
+
+  /** Get the text as a string */
+  toString(): string {
+    return this[INTERNAL_SYMBOL].getStringValue()
+  }
+
+  valueOf(): string {
+    return this.toString()
+  }
+
+  toJSON(): string {
+    return this.toString()
+  }
+
+  [Symbol.toPrimitive](_hint: string): string {
+    return this.toString()
+  }
+
+  /** Get the text as a delta */
+  toDelta(): any[] {
+    return this[INTERNAL_SYMBOL].toDelta()
+  }
+
+  /** Get the length of the text */
+  get length(): number {
+    return this[INTERNAL_SYMBOL].getLength()
+  }
+}