mobx-keystone-yjs 1.3.0 → 1.4.0

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

@@ -1,11 +1,32 @@
 import { AnyDataModel, AnyModel, AnyStandardType, ModelClass, TypeToData } from "mobx-keystone";
 import * as Y from "yjs";
+/**
+ * Creates a bidirectional binding between a Y.js data structure and a mobx-keystone model.
+ */
 export declare function bindYjsToMobxKeystone<TType extends AnyStandardType | ModelClass<AnyModel> | ModelClass<AnyDataModel>>({ yjsDoc, yjsObject, mobxKeystoneType, }: {
+    /**
+     * The Y.js document.
+     */
     yjsDoc: Y.Doc;
-    yjsObject: Y.Map<unknown> | Y.Array<unknown>;
+    /**
+     * 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;
 };

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

@@ -1,5 +1,16 @@
 import * as Y from "yjs";
 import { JsonValue, JsonArray, JsonObject, JsonPrimitive } from "../jsonTypes";
-export declare function convertJsonToYjsData(v: JsonValue): JsonPrimitive | JsonObject | Y.Array<unknown> | Y.Map<unknown>;
-export declare function applyJsonArrayYArray(dest: Y.Array<unknown>, source: JsonArray): void;
+/**
+ * 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 declare function convertJsonToYjsData(v: JsonValue): JsonPrimitive | JsonObject | Y.Array<unknown> | Y.Text | Y.Map<unknown>;
+/**
+ * Applies a JSON array to a Y.Array, using the convertJsonToYjsData to convert the values.
+ */
+export declare function applyJsonArrayToYArray(dest: Y.Array<unknown>, source: JsonArray): void;
+/**
+ * Applies a JSON object to a Y.Map, using the convertJsonToYjsData to convert the values.
+ */
 export declare function applyJsonObjectToYMap(dest: Y.Map<unknown>, source: JsonObject): void;

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

@@ -0,0 +1,3 @@
+import * as Y from "yjs";
+import { JsonValue } from "../jsonTypes";
+export declare function convertYjsDataToJson(yjsData: Y.Array<unknown> | Y.Map<unknown> | Y.Text | unknown): JsonValue;

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

@@ -0,0 +1 @@
+export declare function resolveYjsPath(yjsObject: unknown, path: readonly (string | number)[]): unknown;

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

@@ -1,9 +1,35 @@
 import { AnyType } from "mobx-keystone";
 import * as Y from "yjs";
+/**
+ * Context with info on how a mobx-keystone model is bound to a Y.js data structure.
+ */
 export interface YjsBindingContext {
+    /**
+     * The Y.js document.
+     */
     yjsDoc: Y.Doc;
-    yjsObject: Y.Map<unknown> | Y.Array<unknown>;
+    /**
+     * The bound Y.js data structure.
+     */
+    yjsObject: Y.Map<unknown> | Y.Array<unknown> | Y.Text;
+    /**
+     * The mobx-keystone model type.
+     */
     mobxKeystoneType: AnyType;
+    /**
+     * The origin symbol used for transactions.
+     */
     yjsOrigin: symbol;
+    /**
+     * The bound mobx-keystone instance.
+     */
+    boundObject: unknown | undefined;
+    /**
+     * Whether we are currently applying Y.js changes to the mobx-keystone model.
+     */
+    isApplyingYjsChangesToMobxKeystone: boolean;
 }
+/**
+ * Context with info on how a mobx-keystone model is bound to a Y.js data structure.
+ */
 export declare const yjsBindingContext: import("mobx-keystone").Context<YjsBindingContext | undefined>;

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
+export { YjsTextModel, yjsTextModelId } from "./binding/YjsTextModel";
 export { bindYjsToMobxKeystone } from "./binding/bindYjsToMobxKeystone";
-export { applyJsonArrayYArray, applyJsonObjectToYMap, convertJsonToYjsData, } from "./binding/convertJsonToYjsData";
+export { applyJsonArrayToYArray, applyJsonObjectToYMap, convertJsonToYjsData, } from "./binding/convertJsonToYjsData";
 export { yjsBindingContext } from "./binding/yjsBindingContext";
 export type { YjsBindingContext } from "./binding/yjsBindingContext";
 export { MobxKeystoneYjsError } from "./utils/error";

package/dist/types/utils/getOrCreateYjsCollectionAtom.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,87 +1,91 @@
-{
-  "name": "mobx-keystone-yjs",
-  "version": "1.3.0",
-  "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",
-    ".": {
-      "import": "./dist/mobx-keystone-yjs.esm.mjs",
-      "require": "./dist/mobx-keystone-yjs.umd.js",
-      "script": "./dist/mobx-keystone-yjs.umd.js",
-      "default": "./dist/mobx-keystone-yjs.esm.mjs",
-      "types": "./dist/types/index.d.ts"
-    }
-  },
-  "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",
-    "lint": "cd ../.. && yarn eslint \"packages/mobx-keystone-yjs/src/**/*.ts\" \"packages/mobx-keystone-yjs/test/**/*.ts\""
-  },
-  "peerDependencies": {
-    "mobx": "^6.0.0 || ^5.0.0 || ^4.0.0",
-    "mobx-keystone": "^1.8.1",
-    "yjs": "^13.0.0"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.11",
-    "@types/node": "^20.10.6",
-    "babel-jest": "^29.7.0",
-    "jest": "^29.7.0",
-    "mobx": "^6.12.0",
-    "mobx-keystone": "workspace:packages/lib",
-    "rollup-plugin-typescript2": "^0.36.0",
-    "shx": "^0.3.4",
-    "spec.ts": "^1.1.3",
-    "ts-jest": "^29.1.1",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.3.3",
-    "vite": "^5.0.10"
-  },
-  "dependencies": {
-    "tslib": "^2.6.2"
-  },
-  "directories": {
-    "test": "test"
-  }
-}
+{
+  "name": "mobx-keystone-yjs",
+  "version": "1.4.0",
+  "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",
+    ".": {
+      "import": "./dist/mobx-keystone-yjs.esm.mjs",
+      "require": "./dist/mobx-keystone-yjs.umd.js",
+      "script": "./dist/mobx-keystone-yjs.umd.js",
+      "default": "./dist/mobx-keystone-yjs.esm.mjs",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "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",
+    "lint": "cd ../.. && yarn eslint \"packages/mobx-keystone-yjs/src/**/*.ts\" \"packages/mobx-keystone-yjs/test/**/*.ts\""
+  },
+  "peerDependencies": {
+    "mobx": "^6.0.0 || ^5.0.0 || ^4.0.0",
+    "mobx-keystone": "^1.9.0",
+    "yjs": "^13.0.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.23.7",
+    "@babel/plugin-proposal-class-properties": "^7.18.6",
+    "@babel/plugin-proposal-decorators": "^7.23.7",
+    "@babel/preset-env": "^7.23.7",
+    "@babel/preset-typescript": "^7.23.3",
+    "@types/jest": "^29.5.11",
+    "@types/node": "^20.10.6",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
+    "mobx-keystone": "workspace:packages/lib",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "shx": "^0.3.4",
+    "spec.ts": "^1.1.3",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11"
+  },
+  "dependencies": {
+    "tslib": "^2.6.2"
+  },
+  "directories": {
+    "test": "test"
+  }
+}

package/src/binding/YjsTextModel.ts

@@ -0,0 +1,249 @@
+import { IAtom, computed, createAtom, observe, reaction } from "mobx"
+import {
+  Frozen,
+  Model,
+  frozen,
+  getParentToChildPath,
+  model,
+  onSnapshot,
+  tProp,
+  types,
+} from "mobx-keystone"
+import * as Y from "yjs"
+import { failure } from "../utils/error"
+import { YjsBindingContext, yjsBindingContext } from "./yjsBindingContext"
+import { resolveYjsPath } from "./resolveYjsPath"
+
+// Delta[][], since each single change is a Delta[]
+// we use frozen so that we can reuse each delta change
+const deltaListType = types.array(types.frozen(types.unchecked<unknown[]>()))
+
+export const yjsTextModelId = "mobx-keystone-yjs/YjsTextModel"
+
+/**
+ * A mobx-keystone model that represents a Yjs.Text object.
+ */
+@model(yjsTextModelId)
+export class YjsTextModel extends Model({
+  deltaList: tProp(deltaListType, () => []),
+}) {
+  /**
+   * Helper function to create a YjsTextModel instance with a simple text.
+   */
+  static withText(text: string): YjsTextModel {
+    return new DecoratedYjsTextModel({
+      deltaList: [
+        frozen([
+          {
+            insert: text,
+          },
+        ]),
+      ],
+    })
+  }
+
+  /**
+   * The Y.js path from the bound object to the YjsTextModel instance.
+   */
+  @computed
+  private get _yjsObjectPath() {
+    const ctx = yjsBindingContext.get(this)
+    if (!ctx || ctx.boundObject == null) {
+      throw failure(
+        "the YjsTextModel instance must be part of a bound object before it can be accessed"
+      )
+    }
+
+    const path = getParentToChildPath(ctx.boundObject, this)
+    if (!path) {
+      throw failure("a path from the bound object to the YjsTextModel instance is not available")
+    }
+
+    return path
+  }
+
+  /**
+   * The Yjs.Text object present at this mobx-keystone node's path.
+   */
+  @computed
+  private get _yjsObjectAtPath(): unknown {
+    const path = this._yjsObjectPath
+
+    const ctx = yjsBindingContext.get(this)!
+
+    return resolveYjsPath(ctx.yjsObject, path)
+  }
+
+  /**
+   * The Yjs.Text object represented by this mobx-keystone node.
+   */
+  @computed
+  get yjsText(): Y.Text {
+    const yjsObject = this._yjsObjectAtPath
+
+    if (!(yjsObject instanceof Y.Text)) {
+      throw failure(`Y.Text was expected at path ${JSON.stringify(this._yjsObjectPath)}`)
+    }
+
+    return yjsObject
+  }
+
+  /**
+   * Atom that gets changed when the associated Y.js text changes.
+   */
+  yjsTextChangedAtom = createAtom("yjsTextChangedAtom")
+
+  /**
+   * The text value of the Yjs.Text object.
+   * Shortcut for `yjsText.toString()`, but computed.
+   */
+  @computed
+  get text(): string {
+    this.yjsTextChangedAtom.reportObserved()
+    return this.yjsText.toString()
+  }
+
+  protected onInit() {
+    const shouldReplicateToYjs = (ctx: YjsBindingContext | undefined): ctx is YjsBindingContext => {
+      return !!ctx && !!ctx.boundObject && !ctx.isApplyingYjsChangesToMobxKeystone
+    }
+
+    let reapplyDeltasToYjsText = false
+    const newDeltas: Frozen<unknown[]>[] = []
+
+    let disposeObserveDeltaList: (() => void) | undefined
+
+    const disposeReactionToDeltaListRefChange = reaction(
+      () => this.$.deltaList,
+      (deltaList) => {
+        disposeObserveDeltaList?.()
+        disposeObserveDeltaList = undefined
+
+        if (deltaList) {
+          disposeObserveDeltaList = observe(this.$.deltaList, (change) => {
+            if (reapplyDeltasToYjsText) {
+              // already gonna replace them all
+              return
+            }
+            if (!shouldReplicateToYjs(yjsBindingContext.get(this))) {
+              // yjs text is already up to date with these changes
+              return
+            }
+
+            if (
+              change.type === "splice" &&
+              change.removedCount === 0 &&
+              change.addedCount > 0 &&
+              change.index === this.deltaList.length
+            ) {
+              // optimization, just adding new ones to the end
+              newDeltas.push(...change.added)
+            } else {
+              // any other change, we need to reapply all deltas
+              reapplyDeltasToYjsText = true
+            }
+          })
+        }
+      },
+      { fireImmediately: true }
+    )
+
+    const disposeOnSnapshot = onSnapshot(this, () => {
+      try {
+        if (reapplyDeltasToYjsText) {
+          const ctx = yjsBindingContext.get(this)
+
+          if (shouldReplicateToYjs(ctx)) {
+            const { yjsText } = this
+
+            ctx.yjsDoc.transact(() => {
+              // didn't find a better way than this to reapply all deltas
+              // without having to re-create the Y.Text object
+              if (yjsText.length > 0) {
+                yjsText.delete(0, yjsText.length)
+              }
+
+              this.deltaList.forEach((frozenDeltas) => {
+                yjsText.applyDelta(frozenDeltas.data)
+              })
+            }, ctx.yjsOrigin)
+          }
+        } else if (newDeltas.length > 0) {
+          const ctx = yjsBindingContext.get(this)
+
+          if (shouldReplicateToYjs(ctx)) {
+            const { yjsText } = this
+
+            ctx.yjsDoc.transact(() => {
+              newDeltas.forEach((frozenDeltas) => {
+                yjsText.applyDelta(frozenDeltas.data)
+              })
+            }, ctx.yjsOrigin)
+          }
+        }
+      } finally {
+        reapplyDeltasToYjsText = false
+        newDeltas.length = 0
+      }
+    })
+
+    const diposeYjsTextChangedAtom = hookYjsTextChangedAtom(
+      () => this.yjsText,
+      this.yjsTextChangedAtom
+    )
+
+    return () => {
+      disposeOnSnapshot()
+      disposeReactionToDeltaListRefChange()
+      disposeObserveDeltaList?.()
+      disposeObserveDeltaList = undefined
+
+      diposeYjsTextChangedAtom()
+    }
+  }
+}
+
+// we use this trick just to avoid a babel bug that causes classes used inside classes not to be overriden
+// by the decorator
+const DecoratedYjsTextModel = YjsTextModel
+
+function hookYjsTextChangedAtom(getYjsText: () => Y.Text, textChangedAtom: IAtom) {
+  let disposeObserveYjsText: (() => void) | undefined
+
+  const observeFn = () => {
+    textChangedAtom.reportChanged()
+  }
+
+  const disposeReactionToYTextChange = reaction(
+    () => {
+      try {
+        return getYjsText()
+      } catch {
+        return undefined
+      }
+    },
+    (yjsText) => {
+      disposeObserveYjsText?.()
+      disposeObserveYjsText = undefined
+
+      if (yjsText) {
+        yjsText.observe(observeFn)
+
+        disposeObserveYjsText = () => {
+          yjsText.unobserve(observeFn)
+        }
+      }
+
+      textChangedAtom.reportChanged()
+    },
+    {
+      fireImmediately: true,
+    }
+  )
+
+  return () => {
+    disposeReactionToYTextChange()
+    disposeObserveYjsText?.()
+    disposeObserveYjsText = undefined
+  }
+}