mobx-keystone-yjs 1.5.4 → 1.6.0

package/src/binding/applyYjsEventToMobx.ts

@@ -0,0 +1,173 @@
+import { remove } from "mobx"
+import {
+  Frozen,
+  fromSnapshot,
+  frozen,
+  getSnapshot,
+  getSnapshotModelId,
+  isFrozenSnapshot,
+  isModel,
+  Path,
+  resolvePath,
+  runUnprotected,
+} from "mobx-keystone"
+import * as Y from "yjs"
+import { failure } from "../utils/error"
+import { convertYjsDataToJson } from "./convertYjsDataToJson"
+
+// Represents the map of potential objects to reconcile (ID -> Object)
+export type ReconciliationMap = Map<string, object>
+
+/**
+ * Applies a Y.js 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 applyYjsEventToMobx(
+  event: Y.YEvent<any>,
+  boundObject: object,
+  reconciliationMap: ReconciliationMap
+): void {
+  const path = event.path as Path
+  const { value: target } = resolvePath(boundObject, path)
+
+  if (!target) {
+    throw failure(`cannot resolve path ${JSON.stringify(path)}`)
+  }
+
+  // Wrap in runUnprotected since we're modifying the tree from outside a model action
+  runUnprotected(() => {
+    if (event instanceof Y.YMapEvent) {
+      applyYMapEventToMobx(event, target, reconciliationMap)
+    } else if (event instanceof Y.YArrayEvent) {
+      applyYArrayEventToMobx(event, target, reconciliationMap)
+    } else if (event instanceof Y.YTextEvent) {
+      applyYTextEventToMobx(event, target)
+    }
+  })
+}
+
+function processDeletedValue(val: unknown, reconciliationMap: ReconciliationMap) {
+  if (val && typeof val === "object" && isModel(val)) {
+    const sn = getSnapshot(val)
+    const id = getSnapshotModelId(sn)
+    if (id) {
+      reconciliationMap.set(id, val)
+    }
+  }
+}
+
+function reviveValue(jsonValue: any, reconciliationMap: ReconciliationMap): any {
+  // 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 && jsonValue && typeof jsonValue === "object") {
+    const modelId = getSnapshotModelId(jsonValue)
+    if (modelId) {
+      const existing = reconciliationMap.get(modelId)
+      if (existing) {
+        reconciliationMap.delete(modelId)
+        return existing
+      }
+    }
+  }
+
+  return fromSnapshot(jsonValue)
+}
+
+function applyYMapEventToMobx(
+  event: Y.YMapEvent<any>,
+  target: Record<string, any>,
+  reconciliationMap: ReconciliationMap
+): void {
+  const source = event.target
+
+  event.changes.keys.forEach((change, key) => {
+    switch (change.action) {
+      case "add":
+      case "update": {
+        const yjsValue = source.get(key)
+        const jsonValue = convertYjsDataToJson(yjsValue)
+
+        // If updating, the old value is overwritten (deleted conceptually)
+        if (change.action === "update") {
+          processDeletedValue(target[key], reconciliationMap)
+        }
+
+        target[key] = reviveValue(jsonValue, reconciliationMap)
+        break
+      }
+
+      case "delete": {
+        processDeletedValue(target[key], reconciliationMap)
+        // Use MobX's remove to properly delete the key from the observable object
+        // This triggers the "remove" interceptor in mobx-keystone's tweaker
+        if (isModel(target)) {
+          remove(target.$, key)
+        } else {
+          remove(target, key)
+        }
+        break
+      }
+
+      default:
+        throw failure(`unsupported Yjs map event action: ${change.action}`)
+    }
+  })
+}
+
+function applyYArrayEventToMobx(
+  event: Y.YArrayEvent<any>,
+  target: any[],
+  reconciliationMap: ReconciliationMap
+): void {
+  // Process delta operations in order
+  let currentIndex = 0
+
+  for (const change of event.changes.delta) {
+    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 = Array.isArray(change.insert) ? change.insert : [change.insert]
+      const values = insertedItems.map((yjsValue) => {
+        const jsonValue = convertYjsDataToJson(yjsValue)
+        return reviveValue(jsonValue, reconciliationMap)
+      })
+
+      target.splice(currentIndex, 0, ...values)
+      currentIndex += values.length
+    }
+  }
+}
+
+function applyYTextEventToMobx(
+  event: Y.YTextEvent,
+  target: { deltaList?: Frozen<unknown[]>[] }
+): void {
+  // YjsTextModel handles text events by appending delta to deltaList
+  if (target?.deltaList) {
+    target.deltaList.push(frozen(event.delta))
+  }
+}

package/src/binding/bindYjsToMobxKeystone.ts

@@ -1,192 +1,300 @@
-import { action } from "mobx"
-import {
-  AnyDataModel,
-  AnyModel,
-  AnyStandardType,
-  ModelClass,
-  Patch,
-  SnapshotInOf,
-  TypeToData,
-  applyPatches,
-  fromSnapshot,
-  getParentToChildPath,
-  onGlobalPatches,
-  onPatches,
-  onSnapshot,
-} from "mobx-keystone"
-import * as Y from "yjs"
-import { getYjsCollectionAtom } from "../utils/getOrCreateYjsCollectionAtom"
-import { applyMobxKeystonePatchToYjsObject } from "./applyMobxKeystonePatchToYjsObject"
-import { convertYjsDataToJson } from "./convertYjsDataToJson"
-import { convertYjsEventToPatches } from "./convertYjsEventToPatches"
-import { YjsBindingContext, yjsBindingContext } from "./yjsBindingContext"
-
-/**
- * Creates a bidirectional binding between a Y.js data structure and a mobx-keystone model.
- */
-export function bindYjsToMobxKeystone<
-  TType extends AnyStandardType | ModelClass<AnyModel> | ModelClass<AnyDataModel>,
->({
-  yjsDoc,
-  yjsObject,
-  mobxKeystoneType,
-}: {
-  /**
-   * The Y.js document.
-   */
-  yjsDoc: Y.Doc
-  /**
-   * The bound Y.js data structure.
-   */
-  yjsObject: Y.Map<any> | Y.Array<any> | Y.Text
-  /**
-   * The mobx-keystone model type.
-   */
-  mobxKeystoneType: TType
-}): {
-  /**
-   * The bound mobx-keystone instance.
-   */
-  boundObject: TypeToData<TType>
-  /**
-   * Disposes the binding.
-   */
-  dispose: () => void
-  /**
-   * The Y.js origin symbol used for binding transactions.
-   */
-  yjsOrigin: symbol
-} {
-  const yjsOrigin = Symbol("bindYjsToMobxKeystoneTransactionOrigin")
-
-  let applyingYjsChangesToMobxKeystone = 0
-
-  const bindingContext: YjsBindingContext = {
-    yjsDoc,
-    yjsObject,
-    mobxKeystoneType,
-    yjsOrigin,
-    boundObject: undefined, // not yet created
-
-    get isApplyingYjsChangesToMobxKeystone() {
-      return applyingYjsChangesToMobxKeystone > 0
-    },
-  }
-
-  const yjsJson = convertYjsDataToJson(yjsObject)
-
-  const initializationGlobalPatches: { target: object; patches: Patch[] }[] = []
-
-  const createBoundObject = () => {
-    const disposeOnGlobalPatches = onGlobalPatches((target, patches) => {
-      initializationGlobalPatches.push({ target, patches })
-    })
-
-    try {
-      const boundObject = yjsBindingContext.apply(
-        () => fromSnapshot(mobxKeystoneType, yjsJson as unknown as SnapshotInOf<TypeToData<TType>>),
-        bindingContext
-      )
-      yjsBindingContext.set(boundObject, { ...bindingContext, boundObject })
-      return boundObject
-    } finally {
-      disposeOnGlobalPatches()
-    }
-  }
-
-  const boundObject = createBoundObject()
-
-  // bind any changes from yjs to mobx-keystone
-  const observeDeepCb = action((events: Y.YEvent<any>[]) => {
-    const patches: Patch[] = []
-    events.forEach((event) => {
-      if (event.transaction.origin !== yjsOrigin) {
-        patches.push(...convertYjsEventToPatches(event))
-      }
-
-      if (event.target instanceof Y.Map || event.target instanceof Y.Array) {
-        getYjsCollectionAtom(event.target)?.reportChanged()
-      }
-    })
-
-    if (patches.length > 0) {
-      applyingYjsChangesToMobxKeystone++
-      try {
-        applyPatches(boundObject, patches)
-      } finally {
-        applyingYjsChangesToMobxKeystone--
-      }
-    }
-  })
-
-  yjsObject.observeDeep(observeDeepCb)
-
-  // bind any changes from mobx-keystone to yjs
-  let pendingArrayOfArrayOfPatches: Patch[][] = []
-  const disposeOnPatches = onPatches(boundObject, (patches) => {
-    if (applyingYjsChangesToMobxKeystone > 0) {
-      return
-    }
-
-    pendingArrayOfArrayOfPatches.push(patches)
-  })
-
-  // this is only used so we can transact all patches to the snapshot boundary
-  const disposeOnSnapshot = onSnapshot(boundObject, () => {
-    if (pendingArrayOfArrayOfPatches.length === 0) {
-      return
-    }
-
-    const arrayOfArrayOfPatches = pendingArrayOfArrayOfPatches
-    pendingArrayOfArrayOfPatches = []
-
-    yjsDoc.transact(() => {
-      arrayOfArrayOfPatches.forEach((arrayOfPatches) => {
-        arrayOfPatches.forEach((patch) => {
-          applyMobxKeystonePatchToYjsObject(patch, yjsObject)
-        })
-      })
-    }, yjsOrigin)
-  })
-
-  // sync initial patches, that might include setting defaults, IDs, etc
-  yjsDoc.transact(() => {
-    // we need to skip initializations until we hit the initialization of the bound object
-    // this is because default objects might be created and initialized before the main object
-    // but we just need to catch when those are actually assigned to the bound object
-    let boundObjectFound = false
-
-    initializationGlobalPatches.forEach(({ target, patches }) => {
-      if (!boundObjectFound) {
-        if (target !== boundObject) {
-          return // skip
-        }
-        boundObjectFound = true
-      }
-
-      const parentToChildPath = getParentToChildPath(boundObject, target)
-      // this is undefined only if target is not a child of boundModel
-      if (parentToChildPath !== undefined) {
-        patches.forEach((patch) => {
-          applyMobxKeystonePatchToYjsObject(
-            {
-              ...patch,
-              path: [...parentToChildPath, ...patch.path],
-            },
-            yjsObject
-          )
-        })
-      }
-    })
-  }, yjsOrigin)
-
-  return {
-    boundObject,
-    dispose: () => {
-      disposeOnPatches()
-      disposeOnSnapshot()
-      yjsObject.unobserveDeep(observeDeepCb)
-    },
-    yjsOrigin,
-  }
-}
+import { action } from "mobx"
+import {
+  AnyDataModel,
+  AnyModel,
+  AnyStandardType,
+  DeepChange,
+  DeepChangeType,
+  fromSnapshot,
+  getParentToChildPath,
+  getSnapshot,
+  isTreeNode,
+  ModelClass,
+  onDeepChange,
+  onGlobalDeepChange,
+  onSnapshot,
+  SnapshotInOf,
+  TypeToData,
+} from "mobx-keystone"
+import * as Y from "yjs"
+import type { PlainArray, PlainObject } from "../plainTypes"
+import { failure } from "../utils/error"
+import { getYjsCollectionAtom } from "../utils/getOrCreateYjsCollectionAtom"
+import { isYjsValueDeleted } from "../utils/isYjsValueDeleted"
+import { applyMobxChangeToYjsObject } from "./applyMobxChangeToYjsObject"
+import { applyYjsEventToMobx, ReconciliationMap } from "./applyYjsEventToMobx"
+import { applyJsonArrayToYArray, applyJsonObjectToYMap } from "./convertJsonToYjsData"
+import { convertYjsDataToJson } from "./convertYjsDataToJson"
+import { YjsBindingContext, yjsBindingContext } from "./yjsBindingContext"
+import { setYjsContainerSnapshot } from "./yjsSnapshotTracking"
+
+/**
+ * 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 Y.js data structure and a mobx-keystone model.
+ */
+export function bindYjsToMobxKeystone<
+  TType extends AnyStandardType | ModelClass<AnyModel> | ModelClass<AnyDataModel>,
+>({
+  yjsDoc,
+  yjsObject,
+  mobxKeystoneType,
+}: {
+  /**
+   * The Y.js document.
+   */
+  yjsDoc: Y.Doc
+  /**
+   * The bound Y.js data structure.
+   */
+  yjsObject: Y.Map<any> | Y.Array<any> | Y.Text
+  /**
+   * The mobx-keystone model type.
+   */
+  mobxKeystoneType: TType
+}): {
+  /**
+   * The bound mobx-keystone instance.
+   */
+  boundObject: TypeToData<TType>
+  /**
+   * Disposes the binding.
+   */
+  dispose: () => void
+  /**
+   * The Y.js origin symbol used for binding transactions.
+   */
+  yjsOrigin: symbol
+} {
+  const yjsOrigin = Symbol("bindYjsToMobxKeystoneTransactionOrigin")
+
+  let applyingYjsChangesToMobxKeystone = 0
+
+  const bindingContext: YjsBindingContext = {
+    yjsDoc,
+    yjsObject,
+    mobxKeystoneType,
+    yjsOrigin,
+    boundObject: undefined, // not yet created
+
+    get isApplyingYjsChangesToMobxKeystone() {
+      return applyingYjsChangesToMobxKeystone > 0
+    },
+  }
+
+  if (isYjsValueDeleted(yjsObject)) {
+    throw failure("cannot apply patch to deleted Yjs value")
+  }
+
+  const yjsJson = convertYjsDataToJson(yjsObject)
+
+  let boundObject: TypeToData<TType>
+
+  // Track if any init changes occur during fromSnapshot
+  // (e.g., defaults being applied, onInit hooks mutating the model)
+  let hasInitChanges = false
+
+  const createBoundObject = () => {
+    // Set up a temporary global listener to detect if any init changes occur during fromSnapshot
+    const disposeGlobalListener = onGlobalDeepChange((_target, change) => {
+      if (change.isInit) {
+        hasInitChanges = true
+      }
+    })
+
+    try {
+      const result = yjsBindingContext.apply(
+        () => fromSnapshot(mobxKeystoneType, yjsJson as unknown as SnapshotInOf<TypeToData<TType>>),
+        bindingContext
+      )
+      yjsBindingContext.set(result, { ...bindingContext, boundObject: result })
+      return result
+    } finally {
+      disposeGlobalListener()
+    }
+  }
+
+  boundObject = createBoundObject()
+
+  // bind any changes from yjs to mobx-keystone
+  const observeDeepCb = action((events: Y.YEvent<any>[]) => {
+    const eventsToApply: Y.YEvent<any>[] = []
+
+    events.forEach((event) => {
+      if (event.transaction.origin !== yjsOrigin) {
+        eventsToApply.push(event)
+      }
+
+      if (event.target instanceof Y.Map || event.target instanceof Y.Array) {
+        getYjsCollectionAtom(event.target)?.reportChanged()
+      }
+    })
+
+    if (eventsToApply.length > 0) {
+      applyingYjsChangesToMobxKeystone++
+      try {
+        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) })
+          }
+        })
+
+        try {
+          eventsToApply.forEach((event) => {
+            applyYjsEventToMobx(event, boundObject, reconciliationMap)
+          })
+        } 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 Yjs event handling are not
+        // captured by the main onDeepChange (it skips changes when applyingYjsChangesToMobxKeystone > 0)
+        if (initChanges.length > 0 && !isYjsValueDeleted(yjsObject)) {
+          yjsDoc.transact(() => {
+            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],
+                }
+                applyMobxChangeToYjsObject(changeWithCorrectPath, yjsObject)
+              }
+            }
+          }, yjsOrigin)
+        }
+
+        // Update snapshot tracking: the Y.js container is now in sync with the current MobX snapshot
+        // This enables the merge optimization to skip unchanged subtrees during reconciliation
+        if (yjsObject instanceof Y.Map || yjsObject instanceof Y.Array) {
+          setYjsContainerSnapshot(yjsObject, getSnapshot(boundObject))
+        }
+      } finally {
+        applyingYjsChangesToMobxKeystone--
+      }
+    }
+  })
+
+  yjsObject.observeDeep(observeDeepCb)
+
+  // bind any changes from mobx-keystone to yjs using deep change observation
+  // This provides proper splice detection for array operations
+  let pendingChanges: DeepChange[] = []
+
+  const disposeOnDeepChange = onDeepChange(boundObject, (change) => {
+    if (applyingYjsChangesToMobxKeystone > 0) {
+      return
+    }
+
+    // Skip init changes - they are handled by the getSnapshot + merge at the end of binding
+    if (change.isInit) {
+      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))
+  })
+
+  // this is only used so we can transact all changes to the snapshot boundary
+  const disposeOnSnapshot = onSnapshot(boundObject, (boundObjectSnapshot) => {
+    if (pendingChanges.length === 0) {
+      return
+    }
+
+    const changesToApply = pendingChanges
+    pendingChanges = []
+
+    // Skip syncing to Yjs if the Yjs object has been deleted/detached
+    if (isYjsValueDeleted(yjsObject)) {
+      return
+    }
+
+    yjsDoc.transact(() => {
+      changesToApply.forEach((change) => {
+        applyMobxChangeToYjsObject(change, yjsObject)
+      })
+    }, yjsOrigin)
+
+    // Update snapshot tracking: the Y.js container is now in sync with the current MobX snapshot
+    if (yjsObject instanceof Y.Map || yjsObject instanceof Y.Array) {
+      setYjsContainerSnapshot(yjsObject, boundObjectSnapshot)
+    }
+  })
+
+  // Sync the init changes to the CRDT.
+  // Init changes include: defaults being applied, onInit hooks mutating the model.
+  // We use getSnapshot + merge because the per-change approach has issues with reference mutation
+  // (values captured in DeepChange can be mutated before we apply them).
+  // The snapshot tracking optimization ensures unchanged subtrees are skipped during merge.
+  const finalSnapshot = getSnapshot(boundObject)
+
+  if (hasInitChanges) {
+    yjsDoc.transact(() => {
+      if (yjsObject instanceof Y.Map) {
+        applyJsonObjectToYMap(yjsObject, finalSnapshot as unknown as PlainObject, {
+          mode: "merge",
+        })
+      } else if (yjsObject instanceof Y.Array) {
+        applyJsonArrayToYArray(yjsObject, finalSnapshot as unknown as PlainArray, {
+          mode: "merge",
+        })
+      }
+    }, yjsOrigin)
+  }
+
+  // Always update snapshot tracking after binding initialization
+  // This ensures the merge optimization can skip unchanged subtrees in future reconciliations
+  if (yjsObject instanceof Y.Map || yjsObject instanceof Y.Array) {
+    setYjsContainerSnapshot(yjsObject, finalSnapshot)
+  }
+
+  const dispose = () => {
+    yjsDoc.off("destroy", dispose)
+    disposeOnDeepChange()
+    disposeOnSnapshot()
+    yjsObject.unobserveDeep(observeDeepCb)
+  }
+
+  yjsDoc.on("destroy", dispose)
+
+  return {
+    boundObject,
+    dispose,
+    yjsOrigin,
+  }
+}