mobx-keystone-loro 1.0.0

package/src/binding/applyLoroEventToMobx.ts

@@ -0,0 +1,280 @@
+import type { ContainerID, ListDiff, LoroDoc, LoroEvent, MapDiff } from "loro-crdt"
+import { isContainer, LoroMap, LoroMovableList, LoroText } from "loro-crdt"
+import { remove } from "mobx"
+import {
+  Frozen,
+  fromSnapshot,
+  frozen,
+  getSnapshotModelId,
+  isDataModel,
+  isFrozenSnapshot,
+  isModel,
+  modelIdKey,
+  Path,
+  resolvePath,
+  runUnprotected,
+} from "mobx-keystone"
+import type { PlainValue } from "../plainTypes"
+import { failure } from "../utils/error"
+import { convertLoroDataToJson } from "./convertLoroDataToJson"
+
+// Represents the map of potential objects to reconcile (ID -> Object)
+export type ReconciliationMap = Map<string, object>
+
+/**
+ * Applies a Loro event directly to the MobX model tree using proper mutations
+ * (splice for arrays, property assignment for objects).
+ * This is more efficient than converting to patches first.
+ */
+export function applyLoroEventToMobx(
+  event: LoroEvent,
+  loroDoc: LoroDoc,
+  boundObject: object,
+  rootPath: Path,
+  reconciliationMap: ReconciliationMap,
+  newlyInsertedContainers: Set<ContainerID>
+): void {
+  // Skip events for containers that were just inserted as part of another container
+  // Their content is already included in the parent's convertLoroDataToJson call
+  if (newlyInsertedContainers.has(event.target)) {
+    return
+  }
+
+  // Resolve the path relative to the root
+  const eventPath = loroDoc.getPathToContainer(event.target)
+  if (!eventPath) {
+    return
+  }
+
+  // Strip the root path to get relative path
+  const relativePath = resolveEventPath(eventPath, rootPath)
+  if (relativePath === undefined) {
+    return
+  }
+
+  const { value: target } = resolvePath(boundObject, relativePath)
+
+  if (!target) {
+    throw failure(`cannot resolve path ${JSON.stringify(relativePath)}`)
+  }
+
+  // Wrap in runUnprotected since we're modifying the tree from outside a model action
+  runUnprotected(() => {
+    const diff = event.diff
+    if (diff.type === "map") {
+      applyMapEventToMobx(diff, loroDoc, event.target, target, reconciliationMap)
+    } else if (diff.type === "list") {
+      applyListEventToMobx(
+        diff,
+        loroDoc,
+        event.target,
+        target,
+        reconciliationMap,
+        newlyInsertedContainers
+      )
+    } else if (diff.type === "text") {
+      applyTextEventToMobx(loroDoc, event.target, target)
+    }
+  })
+}
+
+function processDeletedValue(val: unknown, reconciliationMap: ReconciliationMap) {
+  // Handle both Model and DataModel instances
+  if (isModel(val) || isDataModel(val)) {
+    const id = modelIdKey in val ? val[modelIdKey] : undefined
+    if (id) {
+      reconciliationMap.set(id, val)
+    }
+  }
+}
+
+function reviveValue(jsonValue: unknown, reconciliationMap: ReconciliationMap): unknown {
+  // Handle primitives
+  if (jsonValue === null || typeof jsonValue !== "object") {
+    return jsonValue
+  }
+
+  // Handle frozen
+  if (isFrozenSnapshot(jsonValue)) {
+    return frozen(jsonValue.data)
+  }
+
+  // If we have a reconciliation map and the value looks like a model with an ID, check if we have it
+  if (reconciliationMap) {
+    const modelId = getSnapshotModelId(jsonValue)
+    if (modelId) {
+      const existing = reconciliationMap.get(modelId)
+      if (existing) {
+        reconciliationMap.delete(modelId)
+        return existing
+      }
+    }
+  }
+
+  return fromSnapshot(jsonValue)
+}
+
+function applyMapEventToMobx(
+  diff: MapDiff,
+  loroDoc: LoroDoc,
+  containerTarget: ContainerID,
+  target: Record<string, unknown>,
+  reconciliationMap: ReconciliationMap
+): void {
+  const container = loroDoc.getContainerById(containerTarget)
+
+  if (!container || !(container instanceof LoroMap)) {
+    throw failure(`${containerTarget} was not a Loro map`)
+  }
+
+  // Process additions and updates from diff.updated
+  for (const key of Object.keys(diff.updated)) {
+    const loroValue = container.get(key)
+
+    if (loroValue === undefined) {
+      // Key was deleted (Loro returns undefined for deleted keys)
+      if (key in target) {
+        processDeletedValue(target[key], reconciliationMap)
+        // Use MobX's remove to properly delete the key from the observable object
+        if (isModel(target)) {
+          remove(target.$, key)
+        } else {
+          remove(target, key)
+        }
+      }
+    } else {
+      // Key was added or updated
+      if (key in target) {
+        processDeletedValue(target[key], reconciliationMap)
+      }
+      const jsonValue = convertLoroDataToJson(loroValue as PlainValue)
+      target[key] = reviveValue(jsonValue, reconciliationMap)
+    }
+  }
+}
+
+function applyListEventToMobx(
+  diff: ListDiff,
+  loroDoc: LoroDoc,
+  containerTarget: ContainerID,
+  target: unknown[],
+  reconciliationMap: ReconciliationMap,
+  newlyInsertedContainers: Set<ContainerID>
+): void {
+  const container = loroDoc.getContainerById(containerTarget)
+
+  if (!container || !(container instanceof LoroMovableList)) {
+    throw failure(`${containerTarget} was not a Loro movable list`)
+  }
+
+  // Process delta operations in order
+  let currentIndex = 0
+
+  for (const change of diff.diff) {
+    if (change.retain) {
+      currentIndex += change.retain
+    }
+
+    if (change.delete) {
+      // Capture deleted items for reconciliation
+      const deletedItems = target.slice(currentIndex, currentIndex + change.delete)
+      deletedItems.forEach((item) => {
+        processDeletedValue(item, reconciliationMap)
+      })
+
+      // Delete items at current position
+      target.splice(currentIndex, change.delete)
+    }
+
+    if (change.insert) {
+      // Insert items at current position
+      const insertedItems = change.insert
+      const values = insertedItems.map((loroValue) => {
+        // Track container IDs to avoid double-processing their events
+        // When a container with data is inserted, Loro fires events for both
+        // the container insert and the container's content, but the content
+        // is already included in convertLoroDataToJson
+        if (isContainer(loroValue)) {
+          newlyInsertedContainers.add(loroValue.id)
+          // Also recursively track any nested containers
+          collectNestedContainerIds(loroValue, newlyInsertedContainers)
+        }
+        const jsonValue = convertLoroDataToJson(loroValue as PlainValue)
+        return reviveValue(jsonValue, reconciliationMap)
+      })
+
+      target.splice(currentIndex, 0, ...values)
+      currentIndex += values.length
+    }
+  }
+}
+
+function applyTextEventToMobx(
+  loroDoc: LoroDoc,
+  containerTarget: ContainerID,
+  target: { deltaList?: Frozen<unknown[]> }
+): void {
+  const container = loroDoc.getContainerById(containerTarget)
+
+  if (!container || !(container instanceof LoroText)) {
+    throw failure(`${containerTarget} was not a Loro text container`)
+  }
+
+  // LoroTextModel has deltaList as a single Frozen<LoroTextDeltaList>, not an array
+  // Replace it with the current delta from the LoroText
+  if (!("deltaList" in target)) {
+    throw failure("target does not have a deltaList property - expected LoroTextModel")
+  }
+  target.deltaList = frozen(container.toDelta())
+}
+
+/**
+ * Recursively collects all container IDs from a Loro container.
+ * This is used to track containers that have been inserted and should not
+ * have their events processed again (since their content was already included
+ * in the parent's convertLoroDataToJson call).
+ */
+function collectNestedContainerIds(container: unknown, containerIds: Set<ContainerID>): void {
+  if (!isContainer(container)) {
+    return
+  }
+
+  // Add this container's ID
+  containerIds.add(container.id)
+
+  // Handle LoroMap - iterate over values
+  if (container instanceof LoroMap) {
+    for (const key of Object.keys(container.toJSON())) {
+      const value = container.get(key)
+      collectNestedContainerIds(value, containerIds)
+    }
+  }
+
+  // Handle LoroMovableList - iterate over items
+  if (container instanceof LoroMovableList) {
+    for (let i = 0; i < container.length; i++) {
+      collectNestedContainerIds(container.get(i), containerIds)
+    }
+  }
+
+  // LoroText doesn't contain nested containers
+}
+
+/**
+ * Resolves the path from a Loro event to a mobx-keystone path.
+ * The event path is the path from the doc root to the container that emitted the event.
+ * We need to strip the path of our root container to get a path relative to our bound object.
+ */
+function resolveEventPath(eventPath: Path, rootPath: Path): Path | undefined {
+  if (eventPath.length < rootPath.length) {
+    return undefined
+  }
+
+  for (let i = 0; i < rootPath.length; i++) {
+    if (eventPath[i] !== rootPath[i]) {
+      return undefined
+    }
+  }
+
+  return eventPath.slice(rootPath.length) as Path
+}

package/src/binding/applyMobxChangeToLoroObject.ts

@@ -0,0 +1,182 @@
+import { LoroMap, LoroMovableList, LoroText } from "loro-crdt"
+import { DeepChange, DeepChangeType } from "mobx-keystone"
+import type { PlainValue } from "../plainTypes"
+import { failure } from "../utils/error"
+import type { BindableLoroContainer } from "../utils/isBindableLoroContainer"
+import {
+  applyDeltaToLoroText,
+  convertJsonToLoroData,
+  extractTextDeltaFromSnapshot,
+} from "./convertJsonToLoroData"
+import { isLoroTextModelSnapshot } from "./LoroTextModel"
+import type { ArrayMoveChange } from "./moveWithinArray"
+import { resolveLoroPath } from "./resolveLoroPath"
+
+/**
+ * Converts a snapshot value to a Loro-compatible value.
+ * Note: All values passed here are already snapshots (captured at change time).
+ */
+function convertValue(v: unknown): unknown {
+  // Handle primitives directly
+  if (v === null || v === undefined || typeof v !== "object") {
+    return v
+  }
+  // Handle plain arrays - used for empty array init
+  if (Array.isArray(v) && v.length === 0) {
+    return new LoroMovableList()
+  }
+  // Handle LoroTextModel snapshot specially - we need to return it as-is
+  // so the caller can handle creating the LoroText container properly
+  if (isLoroTextModelSnapshot(v)) {
+    return v
+  }
+  // Value is already a snapshot, convert to Loro data
+  return convertJsonToLoroData(v as PlainValue)
+}
+
+/**
+ * Inserts a value into a LoroMovableList at the given index.
+ */
+function insertIntoList(list: LoroMovableList, index: number, value: unknown): void {
+  if (value instanceof LoroMap || value instanceof LoroMovableList || value instanceof LoroText) {
+    list.insertContainer(index, value)
+  } else if (isLoroTextModelSnapshot(value)) {
+    const attachedText = list.insertContainer(index, new LoroText())
+    const deltas = extractTextDeltaFromSnapshot((value as any).deltaList)
+    if (deltas.length > 0) {
+      applyDeltaToLoroText(attachedText, deltas)
+    }
+  } else {
+    list.insert(index, value)
+  }
+}
+
+/**
+ * Sets a value in a LoroMap at the given key.
+ */
+function setInMap(map: LoroMap, key: string, value: unknown): void {
+  if (value === undefined) {
+    map.delete(key)
+  } else if (
+    value instanceof LoroMap ||
+    value instanceof LoroMovableList ||
+    value instanceof LoroText
+  ) {
+    map.setContainer(key, value)
+  } else if (isLoroTextModelSnapshot(value)) {
+    const attachedText = map.setContainer(key, new LoroText())
+    const deltas = extractTextDeltaFromSnapshot((value as any).deltaList)
+    if (deltas.length > 0) {
+      applyDeltaToLoroText(attachedText, deltas)
+    }
+  } else {
+    map.set(key, value)
+  }
+}
+
+/**
+ * Applies a MobX DeepChange or an ArrayMoveChange to a Loro object.
+ */
+export function applyMobxChangeToLoroObject(
+  change: DeepChange | ArrayMoveChange,
+  loroObject: BindableLoroContainer
+): void {
+  const loroContainer = resolveLoroPath(loroObject, change.path)
+
+  // If container doesn't exist at this path, throw an error
+  if (!loroContainer) {
+    throw failure(
+      `cannot apply change to missing Loro container at path: ${JSON.stringify(change.path)}`
+    )
+  }
+
+  switch (change.type) {
+    case "ArrayMove": {
+      if (!(loroContainer instanceof LoroMovableList)) {
+        throw failure(`ArrayMove change requires a LoroMovableList container`)
+      }
+      loroContainer.move(change.fromIndex, change.toIndex)
+      break
+    }
+
+    case DeepChangeType.ArraySplice: {
+      if (!(loroContainer instanceof LoroMovableList)) {
+        throw failure(`ArraySplice change requires a LoroMovableList container`)
+      }
+      if (change.removedValues.length > 0) {
+        loroContainer.delete(change.index, change.removedValues.length)
+      }
+      if (change.addedValues.length > 0) {
+        const valuesToInsert = change.addedValues.map(convertValue)
+        for (let i = 0; i < valuesToInsert.length; i++) {
+          insertIntoList(loroContainer, change.index + i, valuesToInsert[i])
+        }
+      }
+      break
+    }
+
+    case DeepChangeType.ArrayUpdate: {
+      if (!(loroContainer instanceof LoroMovableList)) {
+        throw failure(`ArrayUpdate change requires a LoroMovableList container`)
+      }
+      const converted = convertValue(change.newValue)
+      if (
+        converted instanceof LoroMap ||
+        converted instanceof LoroMovableList ||
+        converted instanceof LoroText
+      ) {
+        loroContainer.setContainer(change.index, converted)
+      } else if (isLoroTextModelSnapshot(converted)) {
+        const attachedText = loroContainer.setContainer(change.index, new LoroText())
+        const deltas = extractTextDeltaFromSnapshot((converted as any).deltaList)
+        if (deltas.length > 0) {
+          applyDeltaToLoroText(attachedText, deltas)
+        }
+      } else {
+        loroContainer.set(change.index, converted)
+      }
+      break
+    }
+
+    case DeepChangeType.ObjectAdd:
+    case DeepChangeType.ObjectUpdate: {
+      if (loroContainer instanceof LoroText) {
+        // Handle changes to LoroText properties (mainly deltaList)
+        if (change.key === "deltaList") {
+          // change.newValue is already a snapshot (captured at change time)
+          const deltas = extractTextDeltaFromSnapshot(change.newValue)
+          if (loroContainer.length > 0) {
+            loroContainer.delete(0, loroContainer.length)
+          }
+          if (deltas.length > 0) {
+            applyDeltaToLoroText(loroContainer, deltas)
+          }
+        }
+        // ignore other property changes on LoroText as they're not synced
+      } else if (loroContainer instanceof LoroMap) {
+        const converted = convertValue(change.newValue)
+        setInMap(loroContainer, change.key, converted)
+      } else {
+        throw failure(`ObjectAdd/ObjectUpdate change requires a LoroMap or LoroText container`)
+      }
+      break
+    }
+
+    case DeepChangeType.ObjectRemove: {
+      if (loroContainer instanceof LoroText) {
+        // ignore removes on LoroText properties
+      } else if (loroContainer instanceof LoroMap) {
+        loroContainer.delete(change.key)
+      } else {
+        throw failure(`ObjectRemove change requires a LoroMap or LoroText container`)
+      }
+      break
+    }
+
+    default: {
+      // Exhaustive check - TypeScript will error if we miss a case
+      const _exhaustiveCheck: never = change
+      throw failure(`unsupported change type: ${(_exhaustiveCheck as any).type}`)
+    }
+  }
+}