@loro-extended/change 0.2.0

package/src/conversion.ts

@@ -0,0 +1,220 @@
+import {
+  type Container,
+  LoroCounter,
+  LoroList,
+  LoroMap,
+  LoroMovableList,
+  LoroText,
+  type Value,
+} from "loro-crdt"
+import type {
+  ArrayValueShape,
+  ContainerOrValueShape,
+  ListContainerShape,
+  MapContainerShape,
+  MovableListContainerShape,
+  ObjectValueShape,
+  RecordContainerShape,
+  RecordValueShape,
+} from "./shape.js"
+import {
+  isContainer,
+  isContainerShape,
+  isObjectValue,
+  isValueShape,
+} from "./utils/type-guards.js"
+
+/**
+ * Converts string input to LoroText container
+ */
+function convertTextInput(value: string): LoroText {
+  const text = new LoroText()
+
+  // TODO(duane): condition can be removed when https://github.com/loro-dev/loro/issues/872 is addressed
+  if (value.length > 0) {
+    text.insert(0, value)
+  }
+
+  return text
+}
+
+/**
+ * Converts number input to LoroCounter container
+ */
+function convertCounterInput(value: number): LoroCounter {
+  const counter = new LoroCounter()
+  counter.increment(value)
+  return counter
+}
+
+/**
+ * Converts array input to LoroList container
+ */
+function convertListInput(
+  value: Value[],
+  shape: ListContainerShape | ArrayValueShape,
+  // parentPath: string[],
+): LoroList | Value[] {
+  if (!isContainerShape(shape)) {
+    return value
+  }
+
+  const list = new LoroList()
+
+  for (const item of value) {
+    const convertedItem = convertInputToNode(item, shape.shape)
+    if (isContainer(convertedItem)) {
+      list.pushContainer(convertedItem)
+    } else {
+      list.push(convertedItem)
+    }
+  }
+
+  return list
+}
+
+/**
+ * Converts array input to LoroMovableList container
+ */
+function convertMovableListInput(
+  value: Value[],
+  shape: MovableListContainerShape | ArrayValueShape,
+  // parentPath: string[],
+): LoroMovableList | Value[] {
+  if (!isContainerShape(shape)) {
+    return value
+  }
+
+  const list = new LoroMovableList()
+
+  for (const item of value) {
+    const convertedItem = convertInputToNode(item, shape.shape)
+    if (isContainer(convertedItem)) {
+      list.pushContainer(convertedItem)
+    } else {
+      list.push(convertedItem)
+    }
+  }
+
+  return list
+}
+
+/**
+ * Converts object input to LoroMap container
+ */
+function convertMapInput(
+  value: { [key: string]: Value },
+  shape: MapContainerShape | ObjectValueShape,
+): LoroMap | { [key: string]: Value } {
+  if (!isContainerShape(shape)) {
+    return value
+  }
+
+  const map = new LoroMap()
+  for (const [k, v] of Object.entries(value)) {
+    const nestedSchema = shape.shapes[k]
+    if (nestedSchema) {
+      const convertedValue = convertInputToNode(v, nestedSchema)
+      if (isContainer(convertedValue)) {
+        map.setContainer(k, convertedValue)
+      } else {
+        map.set(k, convertedValue)
+      }
+    } else {
+      map.set(k, value)
+    }
+  }
+
+  return map
+}
+
+/**
+ * Converts object input to LoroMap container (Record)
+ */
+function convertRecordInput(
+  value: { [key: string]: Value },
+  shape: RecordContainerShape | RecordValueShape,
+): LoroMap | { [key: string]: Value } {
+  if (!isContainerShape(shape)) {
+    return value
+  }
+
+  const map = new LoroMap()
+  for (const [k, v] of Object.entries(value)) {
+    const convertedValue = convertInputToNode(v, shape.shape)
+    if (isContainer(convertedValue)) {
+      map.setContainer(k, convertedValue)
+    } else {
+      map.set(k, convertedValue)
+    }
+  }
+
+  return map
+}
+
+/**
+ * Main conversion function that transforms input values to appropriate CRDT containers
+ * based on schema definitions
+ */
+export function convertInputToNode<Shape extends ContainerOrValueShape>(
+  value: Value,
+  shape: Shape,
+): Container | Value {
+  switch (shape._type) {
+    case "text": {
+      if (typeof value !== "string") {
+        throw new Error("string expected")
+      }
+
+      return convertTextInput(value)
+    }
+    case "counter": {
+      if (typeof value !== "number") {
+        throw new Error("number expected")
+      }
+
+      return convertCounterInput(value)
+    }
+    case "list": {
+      if (!Array.isArray(value)) {
+        throw new Error("array expected")
+      }
+
+      return convertListInput(value, shape)
+    }
+    case "movableList": {
+      if (!Array.isArray(value)) {
+        throw new Error("array expected")
+      }
+
+      return convertMovableListInput(value, shape)
+    }
+    case "map": {
+      if (!isObjectValue(value)) {
+        throw new Error("object expected")
+      }
+
+      return convertMapInput(value, shape)
+    }
+    case "record": {
+      if (!isObjectValue(value)) {
+        throw new Error("object expected")
+      }
+
+      return convertRecordInput(value, shape)
+    }
+    case "value": {
+      if (!isValueShape(shape)) {
+        throw new Error("value expected")
+      }
+
+      return value
+    }
+
+    case "tree":
+      throw new Error("tree type unimplemented")
+
+    default:
+      throw new Error(`unexpected type: ${(shape as Shape)._type}`)
+  }
+}

package/src/draft-nodes/base.ts

@@ -0,0 +1,34 @@
+import type { ContainerShape, DocShape, ShapeToContainer } from "../shape.js"
+import type { InferPlainType } from "../types.js"
+
+export type DraftNodeParams<Shape extends DocShape | ContainerShape> = {
+  shape: Shape
+  emptyState?: InferPlainType<Shape>
+  getContainer: () => ShapeToContainer<Shape>
+}
+
+// Base class for all draft nodes
+export abstract class DraftNode<Shape extends DocShape | ContainerShape> {
+  protected _cachedContainer?: ShapeToContainer<Shape>
+
+  constructor(protected _params: DraftNodeParams<Shape>) {}
+
+  abstract absorbPlainValues(): void
+
+  protected get shape(): Shape {
+    return this._params.shape
+  }
+
+  protected get emptyState(): InferPlainType<Shape> | undefined {
+    return this._params.emptyState
+  }
+
+  protected get container(): ShapeToContainer<Shape> {
+    if (!this._cachedContainer) {
+      const container = this._params.getContainer()
+      this._cachedContainer = container
+      return container
+    }
+    return this._cachedContainer
+  }
+}

package/src/draft-nodes/counter.ts

@@ -0,0 +1,21 @@
+import type { CounterContainerShape } from "../shape.js"
+import { DraftNode } from "./base.js"
+
+// Counter draft node
+export class CounterDraftNode extends DraftNode<CounterContainerShape> {
+  absorbPlainValues() {
+    // no plain values contained within
+  }
+
+  increment(value: number): void {
+    this.container.increment(value)
+  }
+
+  decrement(value: number): void {
+    this.container.decrement(value)
+  }
+
+  get value(): number {
+    return this.container.value
+  }
+}

package/src/draft-nodes/doc.ts

@@ -0,0 +1,81 @@
+import type { LoroDoc } from "loro-crdt"
+import type { InferPlainType } from "../index.js"
+import type { ContainerShape, DocShape } from "../shape.js"
+import { DraftNode, type DraftNodeParams } from "./base.js"
+import { createContainerDraftNode } from "./utils.js"
+
+const containerGetter = {
+  counter: "getCounter",
+  list: "getList",
+  map: "getMap",
+  movableList: "getMovableList",
+  record: "getMap",
+  text: "getText",
+  tree: "getTree",
+} as const
+
+// Draft Document class -- the actual object passed to the change `mutation` function
+export class DraftDoc<Shape extends DocShape> extends DraftNode<Shape> {
+  private doc: LoroDoc
+  private propertyCache = new Map<string, DraftNode<ContainerShape>>()
+  private requiredEmptyState!: InferPlainType<Shape>
+
+  constructor(
+    _params: Omit<DraftNodeParams<Shape>, "getContainer"> & { doc: LoroDoc },
+  ) {
+    super({
+      ..._params,
+      getContainer: () => {
+        throw new Error("can't get container on DraftDoc")
+      },
+    })
+    if (!_params.emptyState) throw new Error("emptyState required")
+    this.doc = _params.doc
+    this.requiredEmptyState = _params.emptyState
+    this.createLazyProperties()
+  }
+
+  getDraftNodeParams<S extends ContainerShape>(
+    key: string,
+    shape: S,
+  ): DraftNodeParams<ContainerShape> {
+    const getter = this.doc[containerGetter[shape._type]].bind(this.doc)
+
+    return {
+      shape,
+      emptyState: this.requiredEmptyState[key],
+      getContainer: () => getter(key),
+    }
+  }
+
+  getOrCreateDraftNode(
+    key: string,
+    shape: ContainerShape,
+  ): DraftNode<ContainerShape> {
+    let node = this.propertyCache.get(key)
+
+    if (!node) {
+      node = createContainerDraftNode(this.getDraftNodeParams(key, shape))
+      this.propertyCache.set(key, node)
+    }
+
+    return node
+  }
+
+  private createLazyProperties(): void {
+    for (const key in this.shape.shapes) {
+      const shape = this.shape.shapes[key]
+      Object.defineProperty(this, key, {
+        get: () => this.getOrCreateDraftNode(key, shape),
+      })
+    }
+  }
+
+  absorbPlainValues(): void {
+    // By iterating over the propertyCache, we achieve a small optimization
+    // by only absorbing values that have been 'touched' in some way
+    for (const [, node] of this.propertyCache.entries()) {
+      node.absorbPlainValues()
+    }
+  }
+}

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

@@ -0,0 +1,326 @@
+import type { Container, LoroList, LoroMovableList } from "loro-crdt"
+import { convertInputToNode } from "../conversion.js"
+import type {
+  ContainerOrValueShape,
+  ContainerShape,
+  ListContainerShape,
+  MovableListContainerShape,
+} from "../shape.js"
+import { isContainer, isValueShape } from "../utils/type-guards.js"
+import { DraftNode, type DraftNodeParams } from "./base.js"
+import { createContainerDraftNode } from "./utils.js"
+
+// Shared logic for list operations
+export abstract class ListDraftNodeBase<
+  NestedShape extends ContainerOrValueShape,
+  Item = NestedShape["_plain"],
+  DraftItem = NestedShape["_draft"],
+> extends DraftNode<any> {
+  // Cache for items returned by array methods to track mutations
+  private itemCache = new Map<number, any>()
+
+  protected get container(): LoroList | LoroMovableList {
+    return super.container as LoroList | LoroMovableList
+  }
+
+  protected get shape():
+    | ListContainerShape<NestedShape>
+    | MovableListContainerShape<NestedShape> {
+    return super.shape as
+      | ListContainerShape<NestedShape>
+      | MovableListContainerShape<NestedShape>
+  }
+
+  absorbPlainValues() {
+    // Critical function: absorb mutated plain values back into Loro containers
+    // This is called at the end of change() to persist mutations made to plain objects
+    for (const [index, cachedItem] of this.itemCache.entries()) {
+      if (cachedItem) {
+        if (isValueShape(this.shape.shape)) {
+          // For value shapes, delegate to subclass-specific absorption logic
+          this.absorbValueAtIndex(index, cachedItem)
+        } else {
+          // For container shapes, the item should be a draft node that handles its own absorption
+          if (
+            cachedItem &&
+            typeof cachedItem === "object" &&
+            "absorbPlainValues" in cachedItem
+          ) {
+            ;(cachedItem as any).absorbPlainValues()
+          }
+        }
+      }
+    }
+
+    // Clear the cache after absorbing values
+    this.itemCache.clear()
+  }
+
+  // Abstract method to be implemented by subclasses
+  // Each subclass knows how to handle its specific container type
+  protected abstract absorbValueAtIndex(index: number, value: any): void
+
+  protected insertWithConversion(index: number, item: Item): void {
+    const convertedItem = convertInputToNode(item as any, this.shape.shape)
+    if (isContainer(convertedItem)) {
+      this.container.insertContainer(index, convertedItem)
+    } else {
+      this.container.insert(index, convertedItem)
+    }
+  }
+
+  protected pushWithConversion(item: Item): void {
+    const convertedItem = convertInputToNode(item as any, this.shape.shape)
+    if (isContainer(convertedItem)) {
+      this.container.pushContainer(convertedItem)
+    } else {
+      this.container.push(convertedItem)
+    }
+  }
+
+  getDraftNodeParams(
+    index: number,
+    shape: ContainerShape,
+  ): DraftNodeParams<ContainerShape> {
+    return {
+      shape,
+      emptyState: undefined, // List items don't have empty state
+      getContainer: () => {
+        const containerItem = this.container.get(index)
+        if (!containerItem || !isContainer(containerItem)) {
+          throw new Error(`No container found at index ${index}`)
+        }
+        return containerItem
+      },
+    }
+  }
+
+  // Get item for predicate functions - always returns plain Item for filtering logic
+  protected getPredicateItem(index: number): Item {
+    // CRITICAL FIX: For predicates to work correctly with mutations,
+    // we need to check if there's a cached (mutated) version first
+    const cachedItem = this.itemCache.get(index)
+    if (cachedItem && isValueShape(this.shape.shape)) {
+      // For value shapes, if we have a cached item, use it so predicates see mutations
+      return cachedItem as Item
+    }
+
+    const containerItem = this.container.get(index)
+    if (containerItem === undefined) {
+      return undefined as Item
+    }
+
+    if (isValueShape(this.shape.shape)) {
+      // For value shapes, return the plain value directly
+      return containerItem as Item
+    } else {
+      // For container shapes, we need to return the plain object representation
+      // This allows predicates to access nested properties like article.metadata.author
+      if (isContainer(containerItem)) {
+        // Convert container to plain object for predicate logic
+        // Handle different container types that may not have toJSON method
+        if (
+          typeof containerItem === "object" &&
+          containerItem !== null &&
+          "toJSON" in containerItem
+        ) {
+          return (containerItem as any).toJSON() as Item
+        } else if (
+          typeof containerItem === "object" &&
+          containerItem !== null &&
+          "getShallowValue" in containerItem
+        ) {
+          // For containers like LoroCounter that don't have toJSON but have getShallowValue
+          return (containerItem as any).getShallowValue() as Item
+        } else {
+          // Fallback for other container types
+          return containerItem as Item
+        }
+      }
+      return containerItem as Item
+    }
+  }
+
+  // Get item for return values - returns DraftItem that can be mutated
+  protected getDraftItem(index: number): DraftItem {
+    // Check if we already have a cached item for this index
+    let cachedItem = this.itemCache.get(index)
+    if (cachedItem) {
+      return cachedItem
+    }
+
+    // Get the raw container item
+    const containerItem = this.container.get(index)
+    if (containerItem === undefined) {
+      return undefined as DraftItem
+    }
+
+    if (isValueShape(this.shape.shape)) {
+      // For value shapes, we need to ensure mutations persist
+      // The key insight: we must return the SAME object for the same index
+      // so that mutations to filtered/found items persist back to the cache
+      if (typeof containerItem === "object" && containerItem !== null) {
+        // Create a deep copy for objects so mutations can be tracked
+        // IMPORTANT: Only create the copy once, then always return the same cached object
+        cachedItem = JSON.parse(JSON.stringify(containerItem))
+      } else {
+        // For primitives, just use the value directly
+        cachedItem = containerItem
+      }
+      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),
+      )
+      this.itemCache.set(index, cachedItem)
+      return cachedItem as DraftItem
+    }
+  }
+
+  // Array-like methods for better developer experience
+  // DUAL INTERFACE: Predicates get Item (plain data), return values are DraftItem (mutable)
+
+  find(
+    predicate: (item: Item, index: number) => boolean,
+  ): DraftItem | undefined {
+    for (let i = 0; i < this.length; i++) {
+      const predicateItem = this.getPredicateItem(i)
+      if (predicate(predicateItem, i)) {
+        return this.getDraftItem(i) // Return mutable draft item
+      }
+    }
+    return undefined
+  }
+
+  findIndex(predicate: (item: Item, index: number) => boolean): number {
+    for (let i = 0; i < this.length; i++) {
+      const predicateItem = this.getPredicateItem(i)
+      if (predicate(predicateItem, i)) {
+        return i
+      }
+    }
+    return -1
+  }
+
+  map<ReturnType>(
+    callback: (item: Item, index: number) => ReturnType,
+  ): ReturnType[] {
+    const result: ReturnType[] = []
+    for (let i = 0; i < this.length; i++) {
+      const predicateItem = this.getPredicateItem(i)
+      result.push(callback(predicateItem, i))
+    }
+    return result
+  }
+
+  filter(predicate: (item: Item, index: number) => boolean): DraftItem[] {
+    const result: DraftItem[] = []
+    for (let i = 0; i < this.length; i++) {
+      const predicateItem = this.getPredicateItem(i)
+      if (predicate(predicateItem, i)) {
+        result.push(this.getDraftItem(i)) // Return mutable draft items
+      }
+    }
+    return result
+  }
+
+  forEach(callback: (item: Item, index: number) => void): void {
+    for (let i = 0; i < this.length; i++) {
+      const predicateItem = this.getPredicateItem(i)
+      callback(predicateItem, i)
+    }
+  }
+
+  some(predicate: (item: Item, index: number) => boolean): boolean {
+    for (let i = 0; i < this.length; i++) {
+      const predicateItem = this.getPredicateItem(i)
+      if (predicate(predicateItem, i)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  every(predicate: (item: Item, index: number) => boolean): boolean {
+    for (let i = 0; i < this.length; i++) {
+      const predicateItem = this.getPredicateItem(i)
+      if (!predicate(predicateItem, i)) {
+        return false
+      }
+    }
+    return true
+  }
+
+  insert(index: number, item: Item): void {
+    // Update cache indices before performing the insert operation
+    this.updateCacheForInsert(index)
+    this.insertWithConversion(index, item)
+  }
+
+  delete(index: number, len: number): void {
+    // Update cache indices before performing the delete operation
+    this.updateCacheForDelete(index, len)
+    this.container.delete(index, len)
+  }
+
+  push(item: Item): void {
+    this.pushWithConversion(item)
+  }
+
+  pushContainer(container: Container): Container {
+    return this.container.pushContainer(container)
+  }
+
+  insertContainer(index: number, container: Container): Container {
+    return this.container.insertContainer(index, container)
+  }
+
+  get(index: number): DraftItem {
+    return this.getDraftItem(index)
+  }
+
+  toArray(): Item[] {
+    return this.container.toArray() as Item[]
+  }
+
+  get length(): number {
+    return this.container.length
+  }
+
+  // Update cache indices when items are deleted
+  private updateCacheForDelete(deleteIndex: number, deleteLen: number): void {
+    const newCache = new Map<number, any>()
+
+    for (const [cachedIndex, cachedItem] of this.itemCache.entries()) {
+      if (cachedIndex < deleteIndex) {
+        // Items before the deletion point keep their indices
+        newCache.set(cachedIndex, cachedItem)
+      } else if (cachedIndex >= deleteIndex + deleteLen) {
+        // Items after the deletion range shift down by deleteLen
+        newCache.set(cachedIndex - deleteLen, cachedItem)
+      }
+      // Items within the deletion range are removed from cache
+    }
+
+    this.itemCache = newCache
+  }
+
+  // Update cache indices when items are inserted
+  private updateCacheForInsert(insertIndex: number): void {
+    const newCache = new Map<number, any>()
+
+    for (const [cachedIndex, cachedItem] of this.itemCache.entries()) {
+      if (cachedIndex < insertIndex) {
+        // Items before the insertion point keep their indices
+        newCache.set(cachedIndex, cachedItem)
+      } else {
+        // Items at or after the insertion point shift up by 1
+        newCache.set(cachedIndex + 1, cachedItem)
+      }
+    }
+
+    this.itemCache = newCache
+  }
+}

package/src/draft-nodes/list.ts

@@ -0,0 +1,18 @@
+import type { LoroList } from "loro-crdt"
+import type { ContainerOrValueShape } from "../shape.js"
+import { ListDraftNodeBase } from "./list-base.js"
+
+// List draft node
+export class ListDraftNode<
+  NestedShape extends ContainerOrValueShape,
+> extends ListDraftNodeBase<NestedShape> {
+  protected get container(): LoroList {
+    return super.container as LoroList
+  }
+
+  protected absorbValueAtIndex(index: number, value: any): void {
+    // LoroList doesn't have set method, need to delete and insert
+    this.container.delete(index, 1)
+    this.container.insert(index, value)
+  }
+}