mobx-keystone-yjs 1.3.1 → 1.4.0

package/src/binding/applyMobxKeystonePatchToYjsObject.ts

@@ -1,92 +1,96 @@
-import { Patch } from "mobx-keystone"
-import * as Y from "yjs"
-import { failure } from "../utils/error"
-import { convertJsonToYjsData } from "./convertJsonToYjsData"
-
-export function applyMobxKeystonePatchToYjsObject(patch: Patch, yjs: unknown): void {
-  if (patch.path.length > 1) {
-    const [key, ...rest] = patch.path
-
-    if (yjs instanceof Y.Map) {
-      const child = yjs.get(String(key))
-      if (child === undefined) {
-        throw failure(
-          `invalid patch path, key "${key}" not found in Yjs map - patch: ${JSON.stringify(patch)}`
-        )
-      }
-      applyMobxKeystonePatchToYjsObject({ ...patch, path: rest }, child)
-    } else if (yjs instanceof Y.Array) {
-      const child = yjs.get(Number(key))
-      if (child === undefined) {
-        throw failure(
-          `invalid patch path, key "${key}" not found in Yjs array - patch: ${JSON.stringify(
-            patch
-          )}`
-        )
-      }
-      applyMobxKeystonePatchToYjsObject({ ...patch, path: rest }, child)
-    } else {
-      throw failure(
-        `invalid patch path, key "${key}" not found in unknown Yjs object - patch: ${JSON.stringify(
-          patch
-        )}`
-      )
-    }
-  } else if (patch.path.length === 1) {
-    if (yjs instanceof Y.Map) {
-      const key = String(patch.path[0])
-
-      switch (patch.op) {
-        case "add":
-        case "replace": {
-          yjs.set(key, convertJsonToYjsData(patch.value))
-          break
-        }
-        case "remove": {
-          yjs.delete(key)
-          break
-        }
-        default: {
-          throw failure(`invalid patch operation for map`)
-        }
-      }
-    } else if (yjs instanceof Y.Array) {
-      const key = patch.path[0]
-
-      switch (patch.op) {
-        case "replace": {
-          if (key === "length") {
-            if (yjs.length > patch.value) {
-              const toDelete = yjs.length - patch.value
-              yjs.delete(patch.value, toDelete)
-            } else if (yjs.length < patch.value) {
-              const toInsert = patch.value - yjs.length
-              yjs.insert(yjs.length, Array(toInsert).fill(undefined))
-            }
-          } else {
-            yjs.delete(Number(key))
-            yjs.insert(Number(key), [convertJsonToYjsData(patch.value)])
-          }
-          break
-        }
-        case "add": {
-          yjs.insert(Number(key), [convertJsonToYjsData(patch.value)])
-          break
-        }
-        case "remove": {
-          yjs.delete(Number(key))
-          break
-        }
-        default: {
-          throw failure(`invalid patch operation for array`)
-        }
-      }
-    } else {
-      throw failure(
-        `invalid patch path, the Yjs object is of an unkown type, so key "${patch.path[0]}" cannot be found in it`
-      )
-    }
-  } else {
-    throw failure(`invalid patch path, it cannot be empty`)
-  }
-}
+import { Patch } from "mobx-keystone"
+import * as Y from "yjs"
+import { failure } from "../utils/error"
+import { convertJsonToYjsData } from "./convertJsonToYjsData"
+
+export function applyMobxKeystonePatchToYjsObject(patch: Patch, yjs: unknown): void {
+  if (patch.path.length > 1) {
+    const [key, ...rest] = patch.path
+
+    if (yjs instanceof Y.Map) {
+      const child = yjs.get(String(key))
+      if (child === undefined) {
+        throw failure(
+          `invalid patch path, key "${key}" not found in Yjs map - patch: ${JSON.stringify(patch)}`
+        )
+      }
+      applyMobxKeystonePatchToYjsObject({ ...patch, path: rest }, child)
+    } else if (yjs instanceof Y.Array) {
+      const child = yjs.get(Number(key))
+      if (child === undefined) {
+        throw failure(
+          `invalid patch path, key "${key}" not found in Yjs array - patch: ${JSON.stringify(
+            patch
+          )}`
+        )
+      }
+      applyMobxKeystonePatchToYjsObject({ ...patch, path: rest }, child)
+    } else if (yjs instanceof Y.Text) {
+      // changes to deltaList will be handled by the array observe in the YjsTextModel class
+    } else {
+      throw failure(
+        `invalid patch path, key "${key}" not found in unknown Yjs object - patch: ${JSON.stringify(
+          patch
+        )}`
+      )
+    }
+  } else if (patch.path.length === 1) {
+    if (yjs instanceof Y.Map) {
+      const key = String(patch.path[0])
+
+      switch (patch.op) {
+        case "add":
+        case "replace": {
+          yjs.set(key, convertJsonToYjsData(patch.value))
+          break
+        }
+        case "remove": {
+          yjs.delete(key)
+          break
+        }
+        default: {
+          throw failure(`invalid patch operation for map`)
+        }
+      }
+    } else if (yjs instanceof Y.Array) {
+      const key = patch.path[0]
+
+      switch (patch.op) {
+        case "replace": {
+          if (key === "length") {
+            if (yjs.length > patch.value) {
+              const toDelete = yjs.length - patch.value
+              yjs.delete(patch.value, toDelete)
+            } else if (yjs.length < patch.value) {
+              const toInsert = patch.value - yjs.length
+              yjs.insert(yjs.length, Array(toInsert).fill(undefined))
+            }
+          } else {
+            yjs.delete(Number(key))
+            yjs.insert(Number(key), [convertJsonToYjsData(patch.value)])
+          }
+          break
+        }
+        case "add": {
+          yjs.insert(Number(key), [convertJsonToYjsData(patch.value)])
+          break
+        }
+        case "remove": {
+          yjs.delete(Number(key))
+          break
+        }
+        default: {
+          throw failure(`invalid patch operation for array`)
+        }
+      }
+    } else if (yjs instanceof Y.Text) {
+      // initialization of a YjsTextModel, do nothing
+    } else {
+      throw failure(
+        `invalid patch path, the Yjs object is of an unkown type, so key "${patch.path[0]}" cannot be found in it`
+      )
+    }
+  } else {
+    throw failure(`invalid patch path, it cannot be empty`)
+  }
+}

package/src/binding/bindYjsToMobxKeystone.ts

@@ -1,157 +1,191 @@
-import {
-  AnyDataModel,
-  AnyModel,
-  AnyStandardType,
-  ModelClass,
-  Patch,
-  TypeToData,
-  applyPatches,
-  fromSnapshot,
-  getParentToChildPath,
-  onGlobalPatches,
-  onPatches,
-  onSnapshot,
-} from "mobx-keystone"
-import * as Y from "yjs"
-import { applyMobxKeystonePatchToYjsObject } from "./applyMobxKeystonePatchToYjsObject"
-import { convertYjsEventToPatches } from "./convertYjsEventToPatches"
-import { YjsBindingContext, yjsBindingContext } from "./yjsBindingContext"
-
-export function bindYjsToMobxKeystone<
-  TType extends AnyStandardType | ModelClass<AnyModel> | ModelClass<AnyDataModel>,
->({
-  yjsDoc,
-  yjsObject,
-  mobxKeystoneType,
-}: {
-  yjsDoc: Y.Doc
-  yjsObject: Y.Map<unknown> | Y.Array<unknown>
-  mobxKeystoneType: TType
-}): {
-  boundObject: TypeToData<TType>
-  dispose(): void
-  yjsOrigin: symbol
-} {
-  const yjsOrigin = Symbol("bindYjsToMobxKeystoneTransactionOrigin")
-
-  const bindingContext: YjsBindingContext = {
-    yjsDoc,
-    yjsObject,
-    mobxKeystoneType,
-    yjsOrigin,
-    boundObject: undefined, // not yet created
-  }
-
-  const yjsJson = yjsObject.toJSON()
-
-  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 any),
-        bindingContext
-      )
-      yjsBindingContext.set(boundObject, { ...bindingContext, boundObject })
-      return boundObject
-    } finally {
-      disposeOnGlobalPatches()
-    }
-  }
-
-  const boundObject = createBoundObject()
-
-  let applyingMobxKeystoneChanges = 0
-
-  // bind any changes from yjs to mobx-keystone
-  const observeDeepCb = (events: Y.YEvent<any>[]) => {
-    const patches: Patch[] = []
-    events.forEach((event) => {
-      if (event.transaction.origin !== yjsOrigin) {
-        patches.push(...convertYjsEventToPatches(event))
-      }
-    })
-
-    if (patches.length > 0) {
-      applyingMobxKeystoneChanges++
-      try {
-        applyPatches(boundObject, patches)
-      } finally {
-        applyingMobxKeystoneChanges--
-      }
-    }
-  }
-
-  yjsObject.observeDeep(observeDeepCb)
-
-  // bind any changes from mobx-keystone to yjs
-  let pendingPatches: Patch[] = []
-  const disposeOnPatches = onPatches(boundObject, (patches) => {
-    if (applyingMobxKeystoneChanges > 0) {
-      return
-    }
-
-    pendingPatches.push(...patches)
-  })
-
-  // this is only used so we can transact all patches to the snapshot boundary
-  const disposeOnSnapshot = onSnapshot(boundObject, () => {
-    if (pendingPatches.length === 0) {
-      return
-    }
-
-    const patches = pendingPatches
-    pendingPatches = []
-
-    yjsDoc.transact(() => {
-      patches.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,
+  ModelClass,
+  Patch,
+  TypeToData,
+  applyPatches,
+  fromSnapshot,
+  getParentToChildPath,
+  onGlobalPatches,
+  onPatches,
+  onSnapshot,
+} from "mobx-keystone"
+import * as Y from "yjs"
+import { getOrCreateYjsCollectionAtom } 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<unknown> | Y.Array<unknown> | 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 any),
+        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) {
+        getOrCreateYjsCollectionAtom(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,
+  }
+}

package/src/binding/convertJsonToYjsData.ts

@@ -1,50 +1,72 @@
-import * as Y from "yjs"
-import { JsonValue, JsonArray, JsonObject, JsonPrimitive } from "../jsonTypes"
-
-function isJsonPrimitive(v: JsonValue): v is JsonPrimitive {
-  const t = typeof v
-  return t === "string" || t === "number" || t === "boolean" || v === null
-}
-
-function isJsonArray(v: JsonValue): v is JsonArray {
-  return Array.isArray(v)
-}
-
-function isJsonObject(v: JsonValue): v is JsonObject {
-  return !isJsonArray(v) && typeof v === "object"
-}
-
-export function convertJsonToYjsData(v: JsonValue) {
-  if (v === undefined || isJsonPrimitive(v)) {
-    return v
-  }
-
-  if (isJsonArray(v)) {
-    const arr = new Y.Array()
-    applyJsonArrayYArray(arr, v)
-    return arr
-  }
-
-  if (isJsonObject(v)) {
-    if (v.$frozen === true) {
-      // frozen value, save as immutable object
-      return v
-    }
-
-    const map = new Y.Map()
-    applyJsonObjectToYMap(map, v)
-    return map
-  }
-
-  throw new Error(`unsupported value type: ${v}`)
-}
-
-export function applyJsonArrayYArray(dest: Y.Array<unknown>, source: JsonArray) {
-  dest.push(source.map(convertJsonToYjsData))
-}
-
-export function applyJsonObjectToYMap(dest: Y.Map<unknown>, source: JsonObject) {
-  Object.entries(source).forEach(([k, v]) => {
-    dest.set(k, convertJsonToYjsData(v))
-  })
-}
+import * as Y from "yjs"
+import { JsonValue, JsonArray, JsonObject, JsonPrimitive } from "../jsonTypes"
+import { YjsTextModel, yjsTextModelId } from "./YjsTextModel"
+import { SnapshotOutOf } from "mobx-keystone"
+
+function isJsonPrimitive(v: JsonValue): v is JsonPrimitive {
+  const t = typeof v
+  return t === "string" || t === "number" || t === "boolean" || v === null
+}
+
+function isJsonArray(v: JsonValue): v is JsonArray {
+  return Array.isArray(v)
+}
+
+function isJsonObject(v: JsonValue): v is JsonObject {
+  return !isJsonArray(v) && typeof v === "object"
+}
+
+/**
+ * Converts a JSON value to a Y.js data structure.
+ * Objects are converted to Y.Maps, arrays to Y.Arrays, primitives are untouched.
+ * Frozen values are a special case and they are kept as immutable plain values.
+ */
+export function convertJsonToYjsData(v: JsonValue) {
+  if (v === undefined || isJsonPrimitive(v)) {
+    return v
+  }
+
+  if (isJsonArray(v)) {
+    const arr = new Y.Array()
+    applyJsonArrayToYArray(arr, v)
+    return arr
+  }
+
+  if (isJsonObject(v)) {
+    if (v.$frozen === true) {
+      // frozen value, save as immutable object
+      return v
+    }
+
+    if (v.$modelType === yjsTextModelId) {
+      const text = new Y.Text()
+      const yjsTextModel = v as SnapshotOutOf<YjsTextModel>
+      yjsTextModel.deltaList.forEach((frozenDeltas) => {
+        text.applyDelta(frozenDeltas.data)
+      })
+      return text
+    }
+
+    const map = new Y.Map()
+    applyJsonObjectToYMap(map, v)
+    return map
+  }
+
+  throw new Error(`unsupported value type: ${v}`)
+}
+
+/**
+ * Applies a JSON array to a Y.Array, using the convertJsonToYjsData to convert the values.
+ */
+export function applyJsonArrayToYArray(dest: Y.Array<unknown>, source: JsonArray) {
+  dest.push(source.map(convertJsonToYjsData))
+}
+
+/**
+ * Applies a JSON object to a Y.Map, using the convertJsonToYjsData to convert the values.
+ */
+export function applyJsonObjectToYMap(dest: Y.Map<unknown>, source: JsonObject) {
+  Object.entries(source).forEach(([k, v]) => {
+    dest.set(k, convertJsonToYjsData(v))
+  })
+}