mobx-keystone-yjs 1.5.5 → 1.6.0

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

@@ -0,0 +1,3 @@
+import { DeepChange } from 'mobx-keystone';
+import * as Y from "yjs";
+export declare function applyMobxChangeToYjsObject(change: DeepChange, yjsObject: Y.Map<any> | Y.Array<any> | Y.Text): void;

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

@@ -0,0 +1,8 @@
+import * as Y from "yjs";
+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 declare function applyYjsEventToMobx(event: Y.YEvent<any>, boundObject: object, reconciliationMap: ReconciliationMap): void;

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

@@ -1,6 +1,17 @@
-import { YjsData } from './convertYjsDataToJson';
 import { PlainArray, PlainObject, PlainValue } from '../plainTypes';
+import { YjsData } from './convertYjsDataToJson';
 import * as Y from "yjs";
+/**
+ * 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";
+}
 /**
  * Converts a plain value to a Y.js data structure.
  * Objects are converted to Y.Maps, arrays to Y.Arrays, primitives are untouched.
@@ -9,9 +20,17 @@ import * as Y from "yjs";
 export declare function convertJsonToYjsData(v: PlainValue): YjsData;
 /**
  * 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 declare const applyJsonArrayToYArray: (dest: Y.Array<any>, source: PlainArray) => void;
+export declare const applyJsonArrayToYArray: (dest: Y.Array<any>, source: PlainArray, options?: ApplyJsonToYjsOptions) => void;
 /**
  * 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 declare const applyJsonObjectToYMap: (dest: Y.Map<any>, source: PlainObject) => void;
+export declare const applyJsonObjectToYMap: (dest: Y.Map<any>, source: PlainObject, options?: ApplyJsonToYjsOptions) => void;

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

@@ -1 +1,14 @@
-export declare function resolveYjsPath(yjsObject: unknown, path: readonly (string | number)[]): unknown;
+import * as Y from "yjs";
+/**
+ * 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 declare function resolveYjsPath(yjsObject: Y.Map<unknown> | Y.Array<unknown> | Y.Text, path: readonly (string | number)[]): unknown;

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

@@ -0,0 +1,24 @@
+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 declare const yjsContainerToSnapshot: 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 declare function setYjsContainerSnapshot(container: Y.Map<any> | Y.Array<any>, snapshot: unknown): void;
+/**
+ * Gets the last synced snapshot for a Y.js container.
+ * Returns undefined if the container has never been synced.
+ */
+export declare function getYjsContainerSnapshot(container: Y.Map<any> | Y.Array<any>): unknown;
+/**
+ * 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 declare function isYjsContainerUpToDate(container: Y.Map<any> | Y.Array<any>, snapshot: unknown): boolean;

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 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';

package/package.json

@@ -1,88 +1,90 @@
-{
-  "name": "mobx-keystone-yjs",
-  "version": "1.5.5",
-  "description": "Yjs bindings for mobx-keystone",
-  "keywords": [
-    "mobx",
-    "mobx-keystone",
-    "yjs",
-    "crdt",
-    "state management"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/xaviergonz/mobx-keystone.git"
-  },
-  "bugs": {
-    "url": "https://github.com/xaviergonz/mobx-keystone/issues"
-  },
-  "homepage": "https://mobx-keystone.js.org",
-  "license": "MIT",
-  "author": "Javier González Garcés",
-  "source": "./src/index.ts",
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "types": "./dist/types/index.d.ts",
-      "script": "./dist/mobx-keystone-yjs.umd.js",
-      "import": "./dist/mobx-keystone-yjs.esm.mjs",
-      "require": "./dist/mobx-keystone-yjs.umd.js",
-      "default": "./dist/mobx-keystone-yjs.esm.mjs"
-    }
-  },
-  "esmodule": "./dist/mobx-keystone-yjs.esm.js",
-  "module": "./dist/mobx-keystone-yjs.esm.js",
-  "jsnext:main": "./dist/mobx-keystone-yjs.esm.js",
-  "react-native": "./dist/mobx-keystone-yjs.umd.js",
-  "umd:main": "./dist/mobx-keystone-yjs.umd.js",
-  "unpkg": "./dist/mobx-keystone-yjs.umd.js",
-  "jsdelivr": "./dist/mobx-keystone-yjs.umd.js",
-  "main": "./dist/mobx-keystone-yjs.umd.js",
-  "types": "./dist/types/index.d.ts",
-  "typings": "./dist/types/index.d.ts",
-  "sideEffects": false,
-  "files": [
-    "src",
-    "dist",
-    "LICENSE",
-    "CHANGELOG.md",
-    "README.md"
-  ],
-  "scripts": {
-    "quick-build": "tsc",
-    "quick-build-tests": "tsc -p test",
-    "copy-root-files": "shx cp ../../LICENSE .",
-    "build": "yarn quick-build && yarn copy-root-files && shx rm -rf dist && vite build && shx cp dist/mobx-keystone-yjs.esm.mjs dist/mobx-keystone-yjs.esm.js",
-    "test": "jest",
-    "test:ci": "yarn test -i",
-    "test:perf": "yarn build && yarn test:perf:run"
-  },
-  "peerDependencies": {
-    "mobx": "^6.0.0 || ^5.0.0 || ^4.0.0",
-    "mobx-keystone": "^1.9.0",
-    "yjs": "^13.0.0"
-  },
-  "devDependencies": {
-    "@babel/core": "^7.28.5",
-    "@babel/plugin-proposal-class-properties": "^7.18.6",
-    "@babel/plugin-proposal-decorators": "^7.28.0",
-    "@babel/preset-env": "^7.28.5",
-    "@babel/preset-typescript": "^7.28.5",
-    "@types/jest": "^30.0.0",
-    "@types/node": "^25.0.3",
-    "babel-jest": "^30.2.0",
-    "jest": "^30.2.0",
-    "mobx-keystone": "workspace:packages/lib",
-    "shx": "^0.4.0",
-    "spec.ts": "^1.1.3",
-    "ts-jest": "^29.4.6",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
-  },
-  "dependencies": {
-    "tslib": "^2.8.1"
-  },
-  "directories": {
-    "test": "test"
-  }
-}
+{
+  "name": "mobx-keystone-yjs",
+  "version": "1.6.0",
+  "description": "Yjs bindings for mobx-keystone",
+  "keywords": [
+    "mobx",
+    "mobx-keystone",
+    "yjs",
+    "crdt",
+    "state",
+    "state-management",
+    "reactive",
+    "collaborative"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xaviergonz/mobx-keystone.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xaviergonz/mobx-keystone/issues"
+  },
+  "homepage": "https://mobx-keystone.js.org",
+  "license": "MIT",
+  "author": "Javier González Garcés",
+  "source": "./src/index.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "script": "./dist/mobx-keystone-yjs.umd.js",
+      "import": "./dist/mobx-keystone-yjs.esm.mjs",
+      "require": "./dist/mobx-keystone-yjs.umd.js",
+      "default": "./dist/mobx-keystone-yjs.esm.mjs"
+    }
+  },
+  "esmodule": "./dist/mobx-keystone-yjs.esm.js",
+  "module": "./dist/mobx-keystone-yjs.esm.js",
+  "jsnext:main": "./dist/mobx-keystone-yjs.esm.js",
+  "react-native": "./dist/mobx-keystone-yjs.umd.js",
+  "umd:main": "./dist/mobx-keystone-yjs.umd.js",
+  "unpkg": "./dist/mobx-keystone-yjs.umd.js",
+  "jsdelivr": "./dist/mobx-keystone-yjs.umd.js",
+  "main": "./dist/mobx-keystone-yjs.umd.js",
+  "types": "./dist/types/index.d.ts",
+  "typings": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "src",
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md",
+    "README.md"
+  ],
+  "scripts": {
+    "quick-build": "tsc",
+    "quick-build-tests": "tsc -p test",
+    "copy-root-files": "shx cp ../../LICENSE .",
+    "build": "yarn quick-build && yarn copy-root-files && shx rm -rf dist && vite build && shx cp dist/mobx-keystone-yjs.esm.mjs dist/mobx-keystone-yjs.esm.js",
+    "test": "jest",
+    "test:ci": "yarn test -i"
+  },
+  "peerDependencies": {
+    "mobx": "^6.0.0 || ^5.0.0 || ^4.0.0",
+    "mobx-keystone": "^1.12.0",
+    "yjs": "^13.0.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.5",
+    "@babel/plugin-proposal-class-properties": "^7.18.6",
+    "@babel/plugin-proposal-decorators": "^7.28.0",
+    "@babel/preset-env": "^7.28.5",
+    "@babel/preset-typescript": "^7.28.5",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
+    "babel-jest": "^30.2.0",
+    "jest": "^30.2.0",
+    "mobx-keystone": "workspace:packages/lib",
+    "shx": "^0.4.0",
+    "spec.ts": "^1.1.3",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "directories": {
+    "test": "test"
+  }
+}

package/src/binding/applyMobxChangeToYjsObject.ts

@@ -0,0 +1,77 @@
+import { DeepChange, DeepChangeType } from "mobx-keystone"
+import * as Y from "yjs"
+import { failure } from "../utils/error"
+import { isYjsValueDeleted } from "../utils/isYjsValueDeleted"
+import { convertJsonToYjsData } from "./convertJsonToYjsData"
+import { resolveYjsPath } from "./resolveYjsPath"
+
+/**
+ * Converts a snapshot value to a Yjs-compatible value.
+ * Note: All values passed here are already snapshots (captured at change time).
+ */
+function convertValue(v: unknown): any {
+  // 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 Y.Array()
+  }
+  // Value is already a snapshot, convert to Yjs data
+  return convertJsonToYjsData(v as any)
+}
+
+export function applyMobxChangeToYjsObject(
+  change: DeepChange,
+  yjsObject: Y.Map<any> | Y.Array<any> | Y.Text
+): void {
+  // Check if the YJS object is deleted
+  if (isYjsValueDeleted(yjsObject)) {
+    throw failure("cannot apply patch to deleted Yjs value")
+  }
+
+  const yjsContainer = resolveYjsPath(yjsObject, change.path)
+
+  if (!yjsContainer) {
+    // Container not found, skip this change
+    return
+  }
+
+  if (yjsContainer instanceof Y.Array) {
+    if (change.type === DeepChangeType.ArraySplice) {
+      // splice
+      yjsContainer.delete(change.index, change.removedValues.length)
+      if (change.addedValues.length > 0) {
+        const valuesToInsert = change.addedValues.map(convertValue)
+        yjsContainer.insert(change.index, valuesToInsert)
+      }
+    } else if (change.type === DeepChangeType.ArrayUpdate) {
+      // update
+      yjsContainer.delete(change.index, 1)
+      yjsContainer.insert(change.index, [convertValue(change.newValue)])
+    } else {
+      throw failure(`unsupported array change type: ${change.type}`)
+    }
+  } else if (yjsContainer instanceof Y.Map) {
+    if (change.type === DeepChangeType.ObjectAdd || change.type === DeepChangeType.ObjectUpdate) {
+      const key = change.key
+      if (change.newValue === undefined) {
+        yjsContainer.delete(key)
+      } else {
+        yjsContainer.set(key, convertValue(change.newValue))
+      }
+    } else if (change.type === DeepChangeType.ObjectRemove) {
+      const key = change.key
+      yjsContainer.delete(key)
+    } else {
+      throw failure(`unsupported object change type: ${change.type}`)
+    }
+  } else if (yjsContainer instanceof Y.Text) {
+    // Y.Text is handled differently - init changes for text are managed by YjsTextModel
+    // Skip init changes for Y.Text containers
+    return
+  } else {
+    throw failure(`unsupported Yjs container type: ${yjsContainer}`)
+  }
+}

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))
+  }
+}