mobx-keystone-yjs 1.5.5 → 1.6.0

package/src/binding/convertJsonToYjsData.ts

@@ -1,73 +1,218 @@
-import * as Y from "yjs"
-import { YjsTextModel, yjsTextModelId } from "./YjsTextModel"
-import { SnapshotOutOf } from "mobx-keystone"
-import { YjsData } from "./convertYjsDataToJson"
-import { PlainArray, PlainObject, PlainPrimitive, PlainValue } from "../plainTypes"
-
-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 !isPlainArray(v) && typeof v === "object" && v !== null
-}
-
-/**
- * Converts a plain 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: PlainValue): YjsData {
-  if (isPlainPrimitive(v)) {
-    return v
-  }
-
-  if (isPlainArray(v)) {
-    const arr = new Y.Array()
-    applyJsonArrayToYArray(arr, v)
-    return arr
-  }
-
-  if (isPlainObject(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 unknown 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 const applyJsonArrayToYArray = (dest: Y.Array<any>, source: PlainArray) => {
-  dest.push(source.map(convertJsonToYjsData))
-}
-
-/**
- * Applies a JSON object to a Y.Map, using the convertJsonToYjsData to convert the values.
- */
-export const applyJsonObjectToYMap = (dest: Y.Map<any>, source: PlainObject) => {
-  Object.entries(source).forEach(([k, v]) => {
-    dest.set(k, convertJsonToYjsData(v))
-  })
-}
+import { frozenKey, modelTypeKey, SnapshotOutOf } from "mobx-keystone"
+import * as Y from "yjs"
+import { PlainArray, PlainObject, PlainPrimitive, PlainValue } from "../plainTypes"
+import { YjsData } from "./convertYjsDataToJson"
+import { YjsTextModel, yjsTextModelId } from "./YjsTextModel"
+import { isYjsContainerUpToDate, setYjsContainerSnapshot } from "./yjsSnapshotTracking"
+
+/**
+ * Options for applying JSON data to Y.js data structures.
+ */
+export interface ApplyJsonToYjsOptions {
+  /**
+   * The mode to use when applying JSON data to Y.js data structures.
+   * - `add`: Creates new Y.js 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)
+}
+
+/**
+ * Converts a plain 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: PlainValue): YjsData {
+  if (isPlainPrimitive(v)) {
+    return v
+  }
+
+  if (isPlainArray(v)) {
+    const arr = new Y.Array()
+    applyJsonArrayToYArray(arr, v)
+    return arr
+  }
+
+  if (isPlainObject(v)) {
+    if (v[frozenKey] === true) {
+      // frozen value, save as immutable object
+      return v
+    }
+
+    if (v[modelTypeKey] === yjsTextModelId) {
+      const text = new Y.Text()
+      const yjsTextModel = v as unknown 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.
+ *
+ * @param dest The destination Y.Array.
+ * @param source The source JSON array.
+ * @param options Options for applying the JSON data.
+ */
+export const applyJsonArrayToYArray = (
+  dest: Y.Array<any>,
+  source: PlainArray,
+  options: ApplyJsonToYjsOptions = {}
+) => {
+  const { mode = "add" } = options
+
+  // In merge mode, check if the container is already up-to-date with this snapshot
+  if (mode === "merge" && isYjsContainerUpToDate(dest, source)) {
+    return
+  }
+
+  const srcLen = source.length
+
+  if (mode === "add") {
+    // Add mode: just push all items to the end
+    for (let i = 0; i < srcLen; i++) {
+      dest.push([convertJsonToYjsData(source[i])])
+    }
+    return
+  }
+
+  // Merge mode: recursively merge values, preserving existing container references
+  const destLen = dest.length
+
+  // Remove extra items from the end
+  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 Y.Map) {
+      applyJsonObjectToYMap(destItem, srcItem, options)
+      continue
+    }
+
+    // If both are arrays, merge recursively
+    if (isPlainArray(srcItem) && destItem instanceof Y.Array) {
+      applyJsonArrayToYArray(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)
+    dest.insert(i, [convertJsonToYjsData(srcItem)])
+  }
+
+  // Add new items at the end
+  for (let i = destLen; i < srcLen; i++) {
+    dest.push([convertJsonToYjsData(source[i])])
+  }
+
+  // Update snapshot tracking after successful merge
+  setYjsContainerSnapshot(dest, source)
+}
+
+/**
+ * Applies a JSON object to a Y.Map, using the convertJsonToYjsData to convert the values.
+ *
+ * @param dest The destination Y.Map.
+ * @param source The source JSON object.
+ * @param options Options for applying the JSON data.
+ */
+export const applyJsonObjectToYMap = (
+  dest: Y.Map<any>,
+  source: PlainObject,
+  options: ApplyJsonToYjsOptions = {}
+) => {
+  const { mode = "add" } = options
+
+  // In merge mode, check if the container is already up-to-date with this snapshot
+  if (mode === "merge" && isYjsContainerUpToDate(dest, source)) {
+    return
+  }
+
+  if (mode === "add") {
+    // Add mode: just set all values
+    for (const k of Object.keys(source)) {
+      const v = source[k]
+      if (v !== undefined) {
+        dest.set(k, convertJsonToYjsData(v))
+      }
+    }
+    return
+  }
+
+  // Merge mode: recursively merge values, preserving existing container references
+
+  // 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 - Y.js maps cannot store undefined
+    if (v === undefined) {
+      continue
+    }
+
+    const existing = dest.get(k)
+
+    // If source is an object and dest has a Y.Map, merge recursively
+    if (isPlainObject(v) && existing instanceof Y.Map) {
+      applyJsonObjectToYMap(existing, v, options)
+      continue
+    }
+
+    // If source is an array and dest has a Y.Array, merge recursively
+    if (isPlainArray(v) && existing instanceof Y.Array) {
+      applyJsonArrayToYArray(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)
+    dest.set(k, convertJsonToYjsData(v))
+  }
+
+  // Update snapshot tracking after successful merge
+  setYjsContainerSnapshot(dest, source)
+}

package/src/binding/resolveYjsPath.ts

@@ -1,27 +1,51 @@
-import * as Y from "yjs"
-import { failure } from "../utils/error"
-import { getOrCreateYjsCollectionAtom } from "../utils/getOrCreateYjsCollectionAtom"
-
-export function resolveYjsPath(yjsObject: unknown, path: readonly (string | number)[]): unknown {
-  let currentYjsObject: unknown = yjsObject
-
-  path.forEach((pathPart, i) => {
-    if (currentYjsObject instanceof Y.Map) {
-      getOrCreateYjsCollectionAtom(currentYjsObject).reportObserved()
-      const key = String(pathPart)
-      currentYjsObject = currentYjsObject.get(key)
-    } else if (currentYjsObject instanceof Y.Array) {
-      getOrCreateYjsCollectionAtom(currentYjsObject).reportObserved()
-      const key = Number(pathPart)
-      currentYjsObject = currentYjsObject.get(key)
-    } else {
-      throw failure(
-        `Y.Map or Y.Array was expected at path ${JSON.stringify(
-          path.slice(0, i)
-        )} in order to resolve path ${JSON.stringify(path)}, but got ${currentYjsObject} instead`
-      )
-    }
-  })
-
-  return currentYjsObject
-}
+import * as Y from "yjs"
+import { failure } from "../utils/error"
+import { getOrCreateYjsCollectionAtom } from "../utils/getOrCreateYjsCollectionAtom"
+
+/**
+ * Resolves a path within a Yjs object structure.
+ * Returns the Yjs container at the specified path.
+ *
+ * When a Y.Text is encountered during path resolution (either at the start
+ * or mid-path), it is returned immediately since Y.Text doesn't support
+ * nested path traversal.
+ *
+ * @param yjsObject The root Yjs object
+ * @param path Array of keys/indices to traverse
+ * @returns The Yjs container at the path, or Y.Text if encountered during traversal
+ */
+export function resolveYjsPath(
+  yjsObject: Y.Map<unknown> | Y.Array<unknown> | Y.Text,
+  path: readonly (string | number)[]
+): unknown {
+  let currentYjsObject: unknown = yjsObject
+
+  let i = -1
+  for (const pathPart of path) {
+    i++
+    // If we encounter a Y.Text during path resolution, return it immediately.
+    // Y.Text objects don't support nested path traversal, and their updates
+    // are handled separately by YjsTextModel's own synchronization mechanism.
+    if (currentYjsObject instanceof Y.Text) {
+      return currentYjsObject
+    }
+
+    if (currentYjsObject instanceof Y.Map) {
+      getOrCreateYjsCollectionAtom(currentYjsObject).reportObserved()
+      const key = String(pathPart)
+      currentYjsObject = currentYjsObject.get(key)
+    } else if (currentYjsObject instanceof Y.Array) {
+      getOrCreateYjsCollectionAtom(currentYjsObject).reportObserved()
+      const key = Number(pathPart)
+      currentYjsObject = currentYjsObject.get(key)
+    } else {
+      throw failure(
+        `Y.Map or Y.Array was expected at path ${JSON.stringify(
+          path.slice(0, i)
+        )} in order to resolve path ${JSON.stringify(path)}, but got ${currentYjsObject} instead`
+      )
+    }
+  }
+
+  return currentYjsObject
+}

package/src/binding/yjsSnapshotTracking.ts

@@ -0,0 +1,40 @@
+import * as Y from "yjs"
+
+/**
+ * WeakMap that tracks which snapshot each Y.js container was last synced from.
+ * This is used during reconciliation to skip containers that are already up-to-date.
+ *
+ * The key is the Y.js container (Y.Map or Y.Array).
+ * The value is the snapshot (plain object or array) that was last synced to it.
+ */
+export const yjsContainerToSnapshot = new WeakMap<Y.Map<any> | Y.Array<any>, unknown>()
+
+/**
+ * Updates the snapshot tracking for a Y.js container.
+ * Call this after syncing a snapshot to a Y.js container.
+ */
+export function setYjsContainerSnapshot(
+  container: Y.Map<any> | Y.Array<any>,
+  snapshot: unknown
+): void {
+  yjsContainerToSnapshot.set(container, snapshot)
+}
+
+/**
+ * Gets the last synced snapshot for a Y.js container.
+ * Returns undefined if the container has never been synced.
+ */
+export function getYjsContainerSnapshot(container: Y.Map<any> | Y.Array<any>): unknown {
+  return yjsContainerToSnapshot.get(container)
+}
+
+/**
+ * Checks if a Y.js container is up-to-date with the given snapshot.
+ * Uses reference equality to check if the snapshot is the same.
+ */
+export function isYjsContainerUpToDate(
+  container: Y.Map<any> | Y.Array<any>,
+  snapshot: unknown
+): boolean {
+  return yjsContainerToSnapshot.get(container) === snapshot
+}

package/src/index.ts

@@ -1,10 +1,11 @@
-export { bindYjsToMobxKeystone } from "./binding/bindYjsToMobxKeystone"
-export {
-  applyJsonArrayToYArray,
-  applyJsonObjectToYMap,
-  convertJsonToYjsData,
-} from "./binding/convertJsonToYjsData"
-export { YjsTextModel, yjsTextModelId } from "./binding/YjsTextModel"
-export type { YjsBindingContext } from "./binding/yjsBindingContext"
-export { yjsBindingContext } from "./binding/yjsBindingContext"
-export { MobxKeystoneYjsError } from "./utils/error"
+export { bindYjsToMobxKeystone } from "./binding/bindYjsToMobxKeystone"
+export type { ApplyJsonToYjsOptions } from "./binding/convertJsonToYjsData"
+export {
+  applyJsonArrayToYArray,
+  applyJsonObjectToYMap,
+  convertJsonToYjsData,
+} from "./binding/convertJsonToYjsData"
+export { YjsTextModel, yjsTextModelId } from "./binding/YjsTextModel"
+export type { YjsBindingContext } from "./binding/yjsBindingContext"
+export { yjsBindingContext } from "./binding/yjsBindingContext"
+export { MobxKeystoneYjsError } from "./utils/error"

package/src/utils/getOrCreateYjsCollectionAtom.ts

@@ -1,27 +1,27 @@
-import { IAtom, createAtom } from "mobx"
-import * as Y from "yjs"
-
-const yjsCollectionAtoms = new WeakMap<Y.Map<unknown> | Y.Array<unknown>, IAtom>()
-
-/**
- * @internal
- */
-export const getYjsCollectionAtom = (
-  yjsCollection: Y.Map<unknown> | Y.Array<unknown>
-): IAtom | undefined => {
-  return yjsCollectionAtoms.get(yjsCollection)
-}
-
-/**
- * @internal
- */
-export const getOrCreateYjsCollectionAtom = (
-  yjsCollection: Y.Map<unknown> | Y.Array<unknown>
-): IAtom => {
-  let atom = yjsCollectionAtoms.get(yjsCollection)
-  if (!atom) {
-    atom = createAtom(`yjsCollectionAtom`)
-    yjsCollectionAtoms.set(yjsCollection, atom)
-  }
-  return atom
-}
+import { createAtom, IAtom } from "mobx"
+import * as Y from "yjs"
+
+const yjsCollectionAtoms = new WeakMap<Y.Map<unknown> | Y.Array<unknown>, IAtom>()
+
+/**
+ * @internal
+ */
+export const getYjsCollectionAtom = (
+  yjsCollection: Y.Map<unknown> | Y.Array<unknown>
+): IAtom | undefined => {
+  return yjsCollectionAtoms.get(yjsCollection)
+}
+
+/**
+ * @internal
+ */
+export const getOrCreateYjsCollectionAtom = (
+  yjsCollection: Y.Map<unknown> | Y.Array<unknown>
+): IAtom => {
+  let atom = yjsCollectionAtoms.get(yjsCollection)
+  if (!atom) {
+    atom = createAtom(`yjsCollectionAtom`)
+    yjsCollectionAtoms.set(yjsCollection, atom)
+  }
+  return atom
+}

package/dist/types/binding/applyMobxKeystonePatchToYjsObject.d.ts

@@ -1,2 +0,0 @@
-import { Patch } from 'mobx-keystone';
-export declare function applyMobxKeystonePatchToYjsObject(patch: Patch, yjs: unknown): void;

package/dist/types/binding/convertYjsEventToPatches.d.ts

@@ -1,3 +0,0 @@
-import { Patch } from 'mobx-keystone';
-import * as Y from "yjs";
-export declare function convertYjsEventToPatches(event: Y.YEvent<any>): Patch[];

package/src/binding/applyMobxKeystonePatchToYjsObject.ts

@@ -1,103 +0,0 @@
-import { Patch } from "mobx-keystone"
-import * as Y from "yjs"
-import { PlainValue } from "../plainTypes"
-import { failure } from "../utils/error"
-import { isYjsValueDeleted } from "../utils/isYjsValueDeleted"
-import { convertJsonToYjsData } from "./convertJsonToYjsData"
-
-export function applyMobxKeystonePatchToYjsObject(patch: Patch, yjs: unknown): void {
-  if (isYjsValueDeleted(yjs)) {
-    throw failure("cannot apply patch to deleted Yjs value")
-  }
-
-  if (patch.path.length > 1) {
-    const [key, ...rest] = patch.path
-
-    if (yjs instanceof Y.Map) {
-      const child = yjs.get(String(key)) as unknown
-      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)) as unknown
-      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 as PlainValue))
-          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") {
-            const newLength = patch.value as number
-            if (yjs.length > newLength) {
-              const toDelete = yjs.length - newLength
-              yjs.delete(newLength, toDelete)
-            } else if (yjs.length < patch.value) {
-              const toInsert = patch.value - yjs.length
-              yjs.insert(yjs.length, Array.from({ length: toInsert }).fill(undefined))
-            }
-          } else {
-            yjs.delete(Number(key))
-            yjs.insert(Number(key), [convertJsonToYjsData(patch.value as PlainValue)])
-          }
-          break
-        }
-        case "add": {
-          yjs.insert(Number(key), [convertJsonToYjsData(patch.value as PlainValue)])
-          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 "${String(patch.path[0])}" cannot be found in it`
-      )
-    }
-  } else {
-    throw failure(`invalid patch path, it cannot be empty`)
-  }
-}