@loro-extended/change 4.0.0 → 5.1.0

package/src/typed-refs/utils.ts

@@ -17,19 +17,19 @@ import type {
   TextContainerShape,
   TreeContainerShape,
 } from "../shape.js"
-import type { TypedRef, TypedRefParams } from "./base.js"
-import { CounterRef } from "./counter.js"
-import { ListRef } from "./list.js"
-import { MovableListRef } from "./movable-list.js"
+import { INTERNAL_SYMBOL, type TypedRef, type TypedRefParams } from "./base.js"
+import { CounterRef } from "./counter-ref.js"
+import { ListRef } from "./list-ref.js"
+import { MovableListRef } from "./movable-list-ref.js"
 import {
   listProxyHandler,
   movableListProxyHandler,
   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"
+import { RecordRef } from "./record-ref.js"
+import { createStructRef } from "./struct-ref.js"
+import { TextRef } from "./text-ref.js"
+import { TreeRef } from "./tree-ref.js"
 
 /**
  * Mapping from container shape types to their Loro constructor classes.
@@ -77,22 +77,17 @@ export function unwrapReadonlyPrimitive(
 }
 
 /**
- * Type guard to check if a value has an absorbPlainValues method.
+ * Type guard to check if a value has internal methods via INTERNAL_SYMBOL.
  */
-function hasAbsorbPlainValues(
+function hasInternalSymbol(
   value: unknown,
-): value is { absorbPlainValues(): void } {
-  return (
-    value !== null &&
-    typeof value === "object" &&
-    "absorbPlainValues" in value &&
-    typeof (value as any).absorbPlainValues === "function"
-  )
+): value is { [INTERNAL_SYMBOL]: { absorbPlainValues(): void } } {
+  return value !== null && typeof value === "object" && INTERNAL_SYMBOL in value
 }
 
 /**
  * Absorbs cached plain values back into a LoroMap container.
- * For TypedRef entries (or any object with absorbPlainValues), recursively calls absorbPlainValues().
+ * For TypedRef entries (or any object with INTERNAL_SYMBOL), recursively calls absorbPlainValues().
  * For plain Value entries, sets them directly on the container.
  */
 export function absorbCachedPlainValues(
@@ -102,9 +97,9 @@ export function absorbCachedPlainValues(
   let container: LoroMap | undefined
 
   for (const [key, ref] of cache.entries()) {
-    if (hasAbsorbPlainValues(ref)) {
+    if (hasInternalSymbol(ref)) {
       // Contains a TypedRef or TreeRef, not a plain Value: keep recursing
-      ref.absorbPlainValues()
+      ref[INTERNAL_SYMBOL].absorbPlainValues()
     } else {
       // Plain value!
       if (!container) container = getContainer()
@@ -152,7 +147,9 @@ export function createContainerTypedRef(
         listProxyHandler,
       )
     case "struct":
-      return new StructRef(params as TypedRefParams<StructContainerShape>)
+      return createStructRef(
+        params as TypedRefParams<StructContainerShape>,
+      ) as unknown as TypedRef<ContainerShape>
     case "movableList":
       return new Proxy(
         new MovableListRef(params as TypedRefParams<MovableListContainerShape>),
@@ -171,7 +168,6 @@ export function createContainerTypedRef(
         shape: treeShape,
         placeholder: params.placeholder as never[],
         getContainer: params.getContainer as () => LoroTree,
-        readonly: params.readonly,
         autoCommit: params.autoCommit,
         getDoc: params.getDoc,
       })
@@ -187,7 +183,9 @@ export function assignPlainValueToTypedRef(
   ref: TypedRef<any>,
   value: any,
 ): boolean {
-  const shapeType = (ref as any).shape._type
+  // Access shape via INTERNAL_SYMBOL or fallback to direct property access for StructRef proxy
+  const shape = ref[INTERNAL_SYMBOL]?.getShape?.() ?? (ref as any).shape
+  const shapeType = shape?._type
 
   if (shapeType === "struct" || shapeType === "record") {
     for (const k in value) {

package/src/typed-refs/counter.ts

@@ -1,62 +0,0 @@
-import type { LoroCounter } from "loro-crdt"
-import type { CounterContainerShape } from "../shape.js"
-import { TypedRef } from "./base.js"
-
-// Counter typed ref
-export class CounterRef extends TypedRef<CounterContainerShape> {
-  // Track if we've materialized the container (made any changes)
-  private _materialized = false
-
-  protected get container(): LoroCounter {
-    return super.container as LoroCounter
-  }
-
-  absorbPlainValues() {
-    // no plain values contained within
-  }
-
-  increment(value: number = 1): void {
-    this._materialized = true
-    this.container.increment(value)
-    this.commitIfAuto()
-  }
-
-  decrement(value: number = 1): void {
-    this._materialized = true
-    this.container.decrement(value)
-    this.commitIfAuto()
-  }
-
-  /**
-   * Returns the counter value.
-   * If the counter hasn't been materialized (no operations performed),
-   * returns the placeholder value if available.
-   */
-  get value(): number {
-    // Check if the container has any value (non-zero means it was modified)
-    const containerValue = this.container.value
-    if (containerValue !== 0 || this._materialized) {
-      return containerValue
-    }
-    // Return placeholder if available and container is at default state
-    if (this.placeholder !== undefined) {
-      return this.placeholder as number
-    }
-    return containerValue
-  }
-
-  valueOf(): number {
-    return this.value
-  }
-
-  toJSON(): number {
-    return this.value
-  }
-
-  [Symbol.toPrimitive](hint: string): number | string {
-    if (hint === "string") {
-      return String(this.value)
-    }
-    return this.value
-  }
-}

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

@@ -1,32 +0,0 @@
-import type { Container, LoroMovableList } from "loro-crdt"
-import type { ContainerOrValueShape } from "../shape.js"
-import type { InferMutableType } from "../types.js"
-import { ListRefBase } from "./list-base.js"
-
-// Movable list typed ref
-export class MovableListRef<
-  NestedShape extends ContainerOrValueShape,
-  Item = NestedShape["_plain"],
-> extends ListRefBase<NestedShape> {
-  [index: number]: InferMutableType<NestedShape> | undefined
-
-  protected get container(): LoroMovableList {
-    return super.container as LoroMovableList
-  }
-
-  protected absorbValueAtIndex(index: number, value: any): void {
-    // LoroMovableList has set method
-    this.container.set(index, value)
-  }
-
-  move(from: number, to: number): void {
-    this.container.move(from, to)
-    this.commitIfAuto()
-  }
-
-  set(index: number, item: Exclude<Item, Container>) {
-    const result = this.container.set(index, item)
-    this.commitIfAuto()
-    return result
-  }
-}

package/src/typed-refs/struct.ts

@@ -1,201 +0,0 @@
-import type { Container, LoroMap, Value } from "loro-crdt"
-import type {
-  ContainerOrValueShape,
-  ContainerShape,
-  StructContainerShape,
-  ValueShape,
-} from "../shape.js"
-import type { Infer } from "../types.js"
-import { isValueShape } from "../utils/type-guards.js"
-import { TypedRef, type TypedRefParams } from "./base.js"
-import {
-  absorbCachedPlainValues,
-  assignPlainValueToTypedRef,
-  containerConstructor,
-  createContainerTypedRef,
-  hasContainerConstructor,
-  serializeRefToJSON,
-} 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<StructContainerShape<NestedShapes>>) {
-    super(params)
-    this.createLazyProperties()
-  }
-
-  protected get shape(): StructContainerShape<NestedShapes> {
-    return super.shape as StructContainerShape<NestedShapes>
-  }
-
-  protected get container(): LoroMap {
-    return super.container as LoroMap
-  }
-
-  absorbPlainValues() {
-    absorbCachedPlainValues(this.propertyCache, () => this.container)
-  }
-
-  getTypedRefParams<S extends ContainerShape>(
-    key: string,
-    shape: S,
-  ): TypedRefParams<ContainerShape> {
-    const placeholder = (this.placeholder 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]
-
-    return {
-      shape,
-      placeholder,
-      getContainer: () =>
-        this.container.getOrCreateContainer(key, new (LoroContainer as any)()),
-      autoCommit: this._params.autoCommit,
-      batchedMutation: this.batchedMutation,
-      getDoc: this._params.getDoc,
-    }
-  }
-
-  getOrCreateRef<Shape extends ContainerShape | ValueShape>(
-    key: string,
-    shape: Shape,
-  ): any {
-    if (isValueShape(shape)) {
-      // 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.batchedMutation) {
-        const containerValue = this.container.get(key)
-        if (containerValue !== undefined) {
-          return containerValue
-        }
-        // 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")
-        }
-        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 = this.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.placeholder 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, shape))
-      this.propertyCache.set(key, ref)
-    }
-
-    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.getOrCreateRef(key, shape),
-        set: value => {
-          if (isValueShape(shape)) {
-            this.container.set(key, value)
-            this.propertyCache.set(key, value)
-          } else {
-            // 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",
-            )
-          }
-        },
-        enumerable: true,
-      })
-    }
-  }
-
-  toJSON(): Infer<StructContainerShape<NestedShapes>> {
-    return serializeRefToJSON(
-      this as any,
-      Object.keys(this.shape.shapes),
-    ) as Infer<StructContainerShape<NestedShapes>>
-  }
-
-  // TODO(duane): return correct type here
-  get(key: string): any {
-    return this.container.get(key)
-  }
-
-  set(key: string, value: Value): void {
-    this.container.set(key, value)
-    this.commitIfAuto()
-  }
-
-  setContainer<C extends Container>(key: string, container: C): C {
-    const result = this.container.setContainer(key, container)
-    this.commitIfAuto()
-    return result
-  }
-
-  delete(key: string): void {
-    this.container.delete(key)
-    this.commitIfAuto()
-  }
-
-  has(key: string): boolean {
-    // LoroMap doesn't have a has method, so we check if get returns undefined
-    return this.container.get(key) !== undefined
-  }
-
-  keys(): string[] {
-    return this.container.keys()
-  }
-
-  values(): any[] {
-    return this.container.values()
-  }
-
-  get size(): number {
-    return this.container.size
-  }
-}

package/src/typed-refs/text.ts

@@ -1,91 +0,0 @@
-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 {
-    this._materialized = true
-    this.container.insert(index, content)
-    this.commitIfAuto()
-  }
-
-  delete(index: number, len: number): void {
-    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 {
-    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._materialized = true
-    this.container.update(text)
-    this.commitIfAuto()
-  }
-
-  mark(range: { start: number; end: number }, key: string, value: any): void {
-    this._materialized = true
-    this.container.mark(range, key, value)
-    this.commitIfAuto()
-  }
-
-  unmark(range: { start: number; end: number }, key: string): void {
-    this._materialized = true
-    this.container.unmark(range, key)
-    this.commitIfAuto()
-  }
-
-  toDelta(): any[] {
-    return this.container.toDelta()
-  }
-
-  applyDelta(delta: any[]): void {
-    this._materialized = true
-    this.container.applyDelta(delta)
-    this.commitIfAuto()
-  }
-
-  get length(): number {
-    return this.container.length
-  }
-}