mobx-keystone-loro 1.0.0

package/src/binding/bindLoroToMobxKeystone.ts

@@ -0,0 +1,353 @@
+import {
+  type ContainerID,
+  type LoroDoc,
+  type LoroEventBatch,
+  LoroMap,
+  LoroMovableList,
+  LoroText,
+} from "loro-crdt"
+import { action } from "mobx"
+import {
+  AnyDataModel,
+  AnyModel,
+  AnyStandardType,
+  DeepChange,
+  DeepChangeType,
+  fromSnapshot,
+  getParentToChildPath,
+  getSnapshot,
+  isTreeNode,
+  ModelClass,
+  onDeepChange,
+  onGlobalDeepChange,
+  onSnapshot,
+  resolvePath,
+  SnapshotOutOf,
+  TypeToData,
+} from "mobx-keystone"
+import { nanoid } from "nanoid"
+import type { PlainArray, PlainObject } from "../plainTypes"
+import { getOrCreateLoroCollectionAtom } from "../utils/getOrCreateLoroCollectionAtom"
+import type { BindableLoroContainer } from "../utils/isBindableLoroContainer"
+
+import { applyLoroEventToMobx, ReconciliationMap } from "./applyLoroEventToMobx"
+import { applyMobxChangeToLoroObject } from "./applyMobxChangeToLoroObject"
+import {
+  applyDeltaToLoroText,
+  applyJsonArrayToLoroMovableList,
+  applyJsonObjectToLoroMap,
+  extractTextDeltaFromSnapshot,
+} from "./convertJsonToLoroData"
+import { convertLoroDataToJson } from "./convertLoroDataToJson"
+import { loroTextModelId } from "./LoroTextModel"
+import { type LoroBindingContext, loroBindingContext } from "./loroBindingContext"
+import { setLoroContainerSnapshot } from "./loroSnapshotTracking"
+import {
+  type ArrayMoveChange,
+  isInMoveContextForArray,
+  processChangeForMove,
+} from "./moveWithinArray"
+
+/**
+ * Captures snapshots of tree nodes in a DeepChange.
+ * This ensures values are captured at change time, not at apply time,
+ * preventing issues when values are mutated after being added to a collection.
+ */
+function captureChangeSnapshots(change: DeepChange): DeepChange {
+  if (change.type === DeepChangeType.ArraySplice && change.addedValues.length > 0) {
+    const snapshots = change.addedValues.map((v) => (isTreeNode(v) ? getSnapshot(v) : v))
+    return { ...change, addedValues: snapshots }
+  } else if (change.type === DeepChangeType.ArrayUpdate) {
+    const snapshot = isTreeNode(change.newValue) ? getSnapshot(change.newValue) : change.newValue
+    return { ...change, newValue: snapshot }
+  } else if (
+    change.type === DeepChangeType.ObjectAdd ||
+    change.type === DeepChangeType.ObjectUpdate
+  ) {
+    const snapshot = isTreeNode(change.newValue) ? getSnapshot(change.newValue) : change.newValue
+    return { ...change, newValue: snapshot }
+  }
+  return change
+}
+
+/**
+ * Creates a bidirectional binding between a Loro data structure and a mobx-keystone model.
+ */
+export function bindLoroToMobxKeystone<
+  TType extends AnyStandardType | ModelClass<AnyModel> | ModelClass<AnyDataModel>,
+>({
+  loroDoc,
+  loroObject,
+  mobxKeystoneType,
+}: {
+  /**
+   * The Loro document.
+   */
+  loroDoc: LoroDoc
+  /**
+   * The bound Loro data structure.
+   */
+  loroObject: BindableLoroContainer
+  /**
+   * The mobx-keystone model type.
+   */
+  mobxKeystoneType: TType
+}): {
+  /**
+   * The bound mobx-keystone instance.
+   */
+  boundObject: TypeToData<TType>
+  /**
+   * Disposes the binding.
+   */
+  dispose: () => void
+  /**
+   * The Loro origin string used for binding transactions.
+   */
+  loroOrigin: string
+} {
+  const loroOrigin = `bindLoroToMobxKeystoneTransactionOrigin-${nanoid()}`
+
+  let applyingLoroChangesToMobxKeystone = 0
+
+  const bindingContext: LoroBindingContext = {
+    loroDoc,
+    loroObject,
+    mobxKeystoneType,
+    loroOrigin,
+    boundObject: undefined, // not yet created
+
+    get isApplyingLoroChangesToMobxKeystone() {
+      return applyingLoroChangesToMobxKeystone > 0
+    },
+  }
+
+  const loroJson = convertLoroDataToJson(loroObject) as SnapshotOutOf<TypeToData<TType>>
+
+  let boundObject: TypeToData<TType>
+
+  // Track if any init changes occurred during fromSnapshot
+  // If they did, we need to sync the model snapshot to the CRDT
+  let hasInitChanges = false
+
+  const createBoundObject = () => {
+    // Set up a temporary global listener to detect init changes during fromSnapshot
+    const disposeGlobalListener = onGlobalDeepChange((_target, change) => {
+      if (change.isInit) {
+        hasInitChanges = true
+      }
+    })
+
+    try {
+      const result = loroBindingContext.apply(
+        () => fromSnapshot(mobxKeystoneType, loroJson),
+        bindingContext
+      )
+      loroBindingContext.set(result, { ...bindingContext, boundObject: result })
+      return result
+    } finally {
+      disposeGlobalListener()
+    }
+  }
+
+  boundObject = createBoundObject()
+
+  // Get the path to the root Loro object for path resolution
+  const rootLoroPath = loroDoc.getPathToContainer(loroObject.id) ?? []
+
+  // bind any changes from Loro to mobx-keystone
+  const loroSubscribeCb = action((eventBatch: LoroEventBatch) => {
+    // Skip changes that originated from this binding
+    if (eventBatch.origin === loroOrigin) {
+      return
+    }
+
+    // Track newly inserted containers to avoid double-processing their events
+    const newlyInsertedContainers = new Set<ContainerID>()
+
+    // Create a map to store reconciliation data for this batch
+    const reconciliationMap: ReconciliationMap = new Map()
+
+    // Collect init changes that occur during event application
+    // (e.g., fromSnapshot calls that trigger onInit hooks)
+    // We store both target and change so we can compute the correct path later
+    // Snapshots are captured immediately to preserve values at init time
+    const initChanges: { target: object; change: DeepChange }[] = []
+    const disposeGlobalListener = onGlobalDeepChange((target, change) => {
+      if (change.isInit) {
+        initChanges.push({ target, change: captureChangeSnapshots(change) })
+      }
+    })
+
+    applyingLoroChangesToMobxKeystone++
+    try {
+      try {
+        for (const event of eventBatch.events) {
+          applyLoroEventToMobx(
+            event,
+            loroDoc,
+            boundObject,
+            rootLoroPath,
+            reconciliationMap,
+            newlyInsertedContainers
+          )
+        }
+      } finally {
+        disposeGlobalListener()
+      }
+
+      // Sync back any init-time mutations from fromSnapshot calls
+      // (e.g., onInit hooks that modify the model)
+      // This is needed because init changes during Loro event handling are not
+      // captured by the main onDeepChange (it skips changes when applyingLoroChangesToMobxKeystone > 0)
+      if (initChanges.length > 0) {
+        loroDoc.setNextCommitOrigin(loroOrigin)
+
+        for (const { target, change } of initChanges) {
+          // Compute the path from boundObject to the target
+          const pathToTarget = getParentToChildPath(boundObject, target)
+          if (pathToTarget !== undefined) {
+            // Create a new change with the correct path from the root
+            const changeWithCorrectPath: DeepChange = {
+              ...change,
+              path: [...pathToTarget, ...change.path],
+            }
+            applyMobxChangeToLoroObject(changeWithCorrectPath, loroObject)
+          }
+        }
+
+        loroDoc.commit()
+      }
+
+      // Update snapshot tracking: the Loro container is now in sync with the current MobX snapshot
+      // This enables the merge optimization to skip unchanged subtrees during reconciliation
+      if (loroObject instanceof LoroMap || loroObject instanceof LoroMovableList) {
+        setLoroContainerSnapshot(loroObject, getSnapshot(boundObject))
+      }
+    } finally {
+      applyingLoroChangesToMobxKeystone--
+    }
+  })
+  const loroUnsubscribe = loroDoc.subscribe(loroSubscribeCb)
+
+  // bind any changes from mobx-keystone to Loro
+  // Collect changes during an action and apply them after the action completes
+  let pendingChanges: (DeepChange | ArrayMoveChange)[] = []
+
+  const disposeOnDeepChange = onDeepChange(boundObject, (change) => {
+    // Skip if we're currently applying Loro changes to MobX
+    if (bindingContext.isApplyingLoroChangesToMobxKeystone) {
+      return
+    }
+
+    // Skip init changes - they are handled by the getSnapshot + merge at the end of binding
+    if (change.isInit) {
+      return
+    }
+
+    // Check if this is part of a moveWithinArray operation
+    if (change.type === DeepChangeType.ArraySplice) {
+      const resolved = resolvePath(boundObject, change.path)
+      if (resolved.resolved && isInMoveContextForArray(resolved.value as unknown[])) {
+        const moveResult = processChangeForMove(change)
+
+        if (moveResult === undefined) {
+          // Intercepted but move not complete - skip this change
+          return
+        }
+
+        // Move complete - add the move change instead
+        pendingChanges.push(moveResult)
+        return
+      }
+    }
+
+    // Capture snapshots now before the values can be mutated within the same transaction.
+    // This is necessary because changes are collected and applied after the action completes,
+    // by which time the original values may have been modified.
+    // Example: `obj.items = [a, b]; obj.items.splice(0, 1)` - without early capture,
+    // the ObjectUpdate for `items` would get the post-splice array state.
+    pendingChanges.push(captureChangeSnapshots(change))
+  })
+
+  // Apply collected changes when snapshot changes (i.e., after action completes)
+  // Also notify that the loro container atoms have been updated
+  const disposeOnSnapshot = onSnapshot(boundObject, () => {
+    if (pendingChanges.length === 0) {
+      return
+    }
+
+    const changesToApply = pendingChanges
+    pendingChanges = []
+
+    // Skip if we're currently applying Loro changes to MobX
+    if (bindingContext.isApplyingLoroChangesToMobxKeystone) {
+      return
+    }
+
+    loroDoc.setNextCommitOrigin(loroOrigin)
+
+    // Apply all changes directly to Loro
+    for (const change of changesToApply) {
+      applyMobxChangeToLoroObject(change, loroObject)
+    }
+
+    loroDoc.commit()
+
+    // Update snapshot tracking: the Loro container is now in sync with the current MobX snapshot
+    if (loroObject instanceof LoroMap || loroObject instanceof LoroMovableList) {
+      setLoroContainerSnapshot(loroObject, getSnapshot(boundObject))
+    }
+
+    // Notify MobX that the Loro container has been updated
+    getOrCreateLoroCollectionAtom(loroObject).reportChanged()
+  })
+
+  // Sync the model snapshot to the CRDT if any init changes occurred.
+  // Init changes include: defaults being applied, onInit hooks mutating the model.
+  // This is an optimization: if no init changes occurred, we skip the sync entirely.
+  const finalSnapshot = getSnapshot(boundObject)
+
+  if (hasInitChanges) {
+    loroDoc.setNextCommitOrigin(loroOrigin)
+
+    if (loroObject instanceof LoroMap) {
+      applyJsonObjectToLoroMap(loroObject, finalSnapshot as PlainObject, { mode: "merge" })
+    } else if (loroObject instanceof LoroMovableList) {
+      applyJsonArrayToLoroMovableList(loroObject, finalSnapshot as PlainArray, { mode: "merge" })
+    } else if (loroObject instanceof LoroText) {
+      // For LoroText, we need to handle LoroTextModel snapshot
+      const snapshot = finalSnapshot as Record<string, unknown>
+      if (snapshot.$modelType === loroTextModelId) {
+        // Clear existing content and apply deltas
+        if (loroObject.length > 0) {
+          loroObject.delete(0, loroObject.length)
+        }
+        const deltas = extractTextDeltaFromSnapshot(snapshot.deltaList)
+        if (deltas.length > 0) {
+          applyDeltaToLoroText(loroObject, deltas)
+        }
+      }
+    }
+
+    loroDoc.commit()
+  }
+
+  // Always update snapshot tracking after binding initialization
+  // This ensures the merge optimization can skip unchanged subtrees in future reconciliations
+  if (loroObject instanceof LoroMap || loroObject instanceof LoroMovableList) {
+    setLoroContainerSnapshot(loroObject, finalSnapshot)
+  }
+
+  const dispose = () => {
+    loroUnsubscribe()
+    disposeOnDeepChange()
+    disposeOnSnapshot()
+  }
+
+  return {
+    boundObject,
+    dispose,
+    loroOrigin,
+  }
+}

package/src/binding/convertJsonToLoroData.ts

@@ -0,0 +1,315 @@
+import type { Delta } from "loro-crdt"
+import { LoroMap, LoroMovableList, LoroText } from "loro-crdt"
+import { frozenKey, isFrozenSnapshot } from "mobx-keystone"
+import type { PlainArray, PlainObject, PlainPrimitive, PlainValue } from "../plainTypes"
+import {
+  type BindableLoroContainer,
+  isBindableLoroContainer,
+} from "../utils/isBindableLoroContainer"
+import { isLoroTextModelSnapshot } from "./LoroTextModel"
+import { isLoroContainerUpToDate, setLoroContainerSnapshot } from "./loroSnapshotTracking"
+
+type LoroValue = BindableLoroContainer | PlainValue
+
+/**
+ * Options for applying JSON data to Loro data structures.
+ */
+export interface ApplyJsonToLoroOptions {
+  /**
+   * The mode to use when applying JSON data to Loro data structures.
+   * - `add`: Creates new Loro containers for objects/arrays (default, backwards compatible)
+   * - `merge`: Recursively merges values, preserving existing container references where possible
+   */
+  mode?: "add" | "merge"
+}
+
+function isPlainPrimitive(v: PlainValue): v is PlainPrimitive {
+  const t = typeof v
+  return t === "string" || t === "number" || t === "boolean" || v === null || v === undefined
+}
+
+function isPlainArray(v: PlainValue): v is PlainArray {
+  return Array.isArray(v)
+}
+
+function isPlainObject(v: PlainValue): v is PlainObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v)
+}
+
+/**
+ * Extracts delta array from a LoroTextModel snapshot's delta field.
+ * The delta field is a frozen Delta<string>[] (array of delta operations).
+ */
+export function extractTextDeltaFromSnapshot(delta: unknown): Delta<string>[] {
+  // The delta field is frozen, so we need to extract it
+  if (isFrozenSnapshot<Delta<string>[]>(delta)) {
+    const data = delta.data
+    if (Array.isArray(data)) {
+      return data
+    }
+  }
+
+  // Handle plain delta array (not wrapped in frozen)
+  if (Array.isArray(delta)) {
+    return delta as Delta<string>[]
+  }
+
+  return []
+}
+
+/**
+ * Applies delta operations to a LoroText using insert/mark APIs.
+ * This works on both attached and detached containers.
+ *
+ * Strategy: Insert all text first, then apply marks. This avoids mark inheritance
+ * issues when inserting at the boundary of a marked region.
+ */
+export function applyDeltaToLoroText(text: LoroText, deltas: Delta<string>[]): void {
+  // Phase 1: Insert all text content
+  let position = 0
+  const markOperations: Array<{
+    start: number
+    end: number
+    attributes: Record<string, unknown>
+  }> = []
+
+  for (const delta of deltas) {
+    if (delta.insert !== undefined) {
+      const content = delta.insert
+      text.insert(position, content)
+
+      // Collect mark operations to apply later
+      if (delta.attributes && Object.keys(delta.attributes).length > 0) {
+        markOperations.push({
+          start: position,
+          end: position + content.length,
+          attributes: delta.attributes,
+        })
+      }
+
+      position += content.length
+    } else if (delta.retain) {
+      position += delta.retain
+    } else if (delta.delete) {
+      text.delete(position, delta.delete)
+    }
+  }
+
+  // Phase 2: Apply all marks after text is inserted
+  for (const op of markOperations) {
+    for (const [key, value] of Object.entries(op.attributes)) {
+      text.mark({ start: op.start, end: op.end }, key, value)
+    }
+  }
+}
+
+/**
+ * Converts a plain value to a Loro data structure.
+ * Objects are converted to LoroMaps, arrays to LoroMovableLists, primitives are untouched.
+ * Frozen values are a special case and they are kept as immutable plain values.
+ */
+export function convertJsonToLoroData(v: PlainValue): LoroValue {
+  if (isPlainPrimitive(v)) {
+    return v
+  }
+
+  if (isPlainArray(v)) {
+    const list = new LoroMovableList()
+    applyJsonArrayToLoroMovableList(list, v)
+    return list
+  }
+
+  if (isPlainObject(v)) {
+    if (v[frozenKey] === true) {
+      // frozen value with explicit $frozen marker (shouldn't reach here after above check)
+      return v
+    }
+
+    if (isLoroTextModelSnapshot(v)) {
+      const text = new LoroText()
+      // Extract delta from the snapshot and apply using insert/mark APIs
+      // (applyDelta doesn't work on detached containers, but insert/mark do)
+      const deltas = extractTextDeltaFromSnapshot(v.deltaList)
+      if (deltas.length > 0) {
+        applyDeltaToLoroText(text, deltas)
+      }
+      return text
+    }
+
+    const map = new LoroMap()
+    applyJsonObjectToLoroMap(map, v)
+    return map
+  }
+
+  throw new Error(`unsupported value type: ${v}`)
+}
+
+/**
+ * Applies a JSON array to a LoroMovableList, using convertJsonToLoroData to convert the values.
+ *
+ * @param dest The destination LoroMovableList.
+ * @param source The source JSON array.
+ * @param options Options for applying the JSON data.
+ */
+export const applyJsonArrayToLoroMovableList = (
+  dest: LoroMovableList,
+  source: PlainArray,
+  options: ApplyJsonToLoroOptions = {}
+) => {
+  const { mode = "add" } = options
+
+  if (mode === "add") {
+    // Add mode: just push all items to the end
+    for (const item of source) {
+      const converted = convertJsonToLoroData(item)
+      if (isBindableLoroContainer(converted)) {
+        dest.pushContainer(converted)
+      } else {
+        dest.push(converted)
+      }
+    }
+    return
+  }
+
+  // Merge mode: recursively merge values, preserving existing container references
+  // In merge mode, check if the container is already up-to-date with this snapshot
+  if (isLoroContainerUpToDate(dest, source)) {
+    return
+  }
+
+  // Remove extra items from the end
+  const destLen = dest.length
+  const srcLen = source.length
+  if (destLen > srcLen) {
+    dest.delete(srcLen, destLen - srcLen)
+  }
+
+  // Update existing items
+  const minLen = Math.min(destLen, srcLen)
+  for (let i = 0; i < minLen; i++) {
+    const srcItem = source[i]
+    const destItem = dest.get(i)
+
+    // If both are objects, merge recursively
+    if (isPlainObject(srcItem) && destItem instanceof LoroMap) {
+      applyJsonObjectToLoroMap(destItem, srcItem, options)
+      continue
+    }
+
+    // If both are arrays, merge recursively
+    if (isPlainArray(srcItem) && destItem instanceof LoroMovableList) {
+      applyJsonArrayToLoroMovableList(destItem, srcItem, options)
+      continue
+    }
+
+    // Skip if primitive value is unchanged (optimization)
+    if (isPlainPrimitive(srcItem) && destItem === srcItem) {
+      continue
+    }
+
+    // Otherwise, replace the item
+    dest.delete(i, 1)
+    const converted = convertJsonToLoroData(srcItem)
+    if (isBindableLoroContainer(converted)) {
+      dest.insertContainer(i, converted)
+    } else {
+      dest.insert(i, converted)
+    }
+  }
+
+  // Add new items at the end
+  for (let i = destLen; i < srcLen; i++) {
+    const converted = convertJsonToLoroData(source[i])
+    if (isBindableLoroContainer(converted)) {
+      dest.pushContainer(converted)
+    } else {
+      dest.push(converted)
+    }
+  }
+
+  // Update snapshot tracking after successful merge
+  setLoroContainerSnapshot(dest, source)
+}
+
+/**
+ * Applies a JSON object to a LoroMap, using convertJsonToLoroData to convert the values.
+ *
+ * @param dest The destination LoroMap.
+ * @param source The source JSON object.
+ * @param options Options for applying the JSON data.
+ */
+export const applyJsonObjectToLoroMap = (
+  dest: LoroMap,
+  source: PlainObject,
+  options: ApplyJsonToLoroOptions = {}
+) => {
+  const { mode = "add" } = options
+
+  if (mode === "add") {
+    // Add mode: just set all values
+    for (const k of Object.keys(source)) {
+      const v = source[k]
+      if (v !== undefined) {
+        const converted = convertJsonToLoroData(v)
+        if (isBindableLoroContainer(converted)) {
+          dest.setContainer(k, converted)
+        } else {
+          dest.set(k, converted)
+        }
+      }
+    }
+    return
+  }
+
+  // Merge mode: recursively merge values, preserving existing container references
+  // In merge mode, check if the container is already up-to-date with this snapshot
+  if (isLoroContainerUpToDate(dest, source)) {
+    return
+  }
+
+  // Delete keys that are not present in source (or have undefined value)
+  const sourceKeysWithValues = new Set(Object.keys(source).filter((k) => source[k] !== undefined))
+  for (const key of dest.keys()) {
+    if (!sourceKeysWithValues.has(key)) {
+      dest.delete(key)
+    }
+  }
+
+  for (const k of Object.keys(source)) {
+    const v = source[k]
+    // Skip undefined values - Loro maps cannot store undefined
+    if (v === undefined) {
+      continue
+    }
+
+    const existing = dest.get(k)
+
+    // If source is an object and dest has a LoroMap, merge recursively
+    if (isPlainObject(v) && existing instanceof LoroMap) {
+      applyJsonObjectToLoroMap(existing, v, options)
+      continue
+    }
+
+    // If source is an array and dest has a LoroMovableList, merge recursively
+    if (isPlainArray(v) && existing instanceof LoroMovableList) {
+      applyJsonArrayToLoroMovableList(existing, v, options)
+      continue
+    }
+
+    // Skip if primitive value is unchanged (optimization)
+    if (isPlainPrimitive(v) && existing === v) {
+      continue
+    }
+
+    // Otherwise, convert and set the value (this creates new containers if needed)
+    const converted = convertJsonToLoroData(v)
+    if (isBindableLoroContainer(converted)) {
+      dest.setContainer(k, converted)
+    } else {
+      dest.set(k, converted)
+    }
+  }
+
+  // Update snapshot tracking after successful merge
+  setLoroContainerSnapshot(dest, source)
+}