mobx-keystone-yjs 1.3.1 → 1.5.0

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

@@ -0,0 +1,39 @@
+import { IAtom } from "mobx";
+import { Frozen } from "mobx-keystone";
+import * as Y from "yjs";
+export declare const yjsTextModelId = "mobx-keystone-yjs/YjsTextModel";
+declare const YjsTextModel_base: import("mobx-keystone")._Model<unknown, {
+    deltaList: import("mobx-keystone").OptionalModelProp<Frozen<unknown[]>[]>;
+}, never, never>;
+/**
+ * A mobx-keystone model that represents a Yjs.Text object.
+ */
+export declare class YjsTextModel extends YjsTextModel_base {
+    /**
+     * Helper function to create a YjsTextModel instance with a simple text.
+     */
+    static withText(text: string): YjsTextModel;
+    /**
+     * The Y.js path from the bound object to the YjsTextModel instance.
+     */
+    private get _yjsObjectPath();
+    /**
+     * The Yjs.Text object present at this mobx-keystone node's path.
+     */
+    private get _yjsObjectAtPath();
+    /**
+     * The Yjs.Text object represented by this mobx-keystone node.
+     */
+    get yjsText(): Y.Text;
+    /**
+     * Atom that gets changed when the associated Y.js text changes.
+     */
+    yjsTextChangedAtom: IAtom;
+    /**
+     * The text value of the Yjs.Text object.
+     * Shortcut for `yjsText.toString()`, but computed.
+     */
+    get text(): string;
+    protected onInit(): () => void;
+}
+export {};

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>;
-    dispose(): void;
+    /**
+     * 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,17 @@
 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;
-export declare function applyJsonObjectToYMap(dest: Y.Map<unknown>, source: JsonObject): void;
+import { YjsData } from "./convertYjsDataToJson";
+import { JsonArrayWithUndefined, JsonObjectWithUndefined, JsonValueWithUndefined } from "jsonTypes";
+/**
+ * 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: JsonValueWithUndefined | undefined): YjsData;
+/**
+ * Applies a JSON array to a Y.Array, using the convertJsonToYjsData to convert the values.
+ */
+export declare function applyJsonArrayToYArray(dest: Y.Array<unknown>, source: JsonArrayWithUndefined): 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: JsonObjectWithUndefined): void;

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

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

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,10 +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;
-    boundObject: unknown | undefined;
+    /**
+     * The bound mobx-keystone instance.
+     */
+    boundObject: unknown;
+    /**
+     * 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/jsonTypes.d.ts

@@ -1,7 +1,7 @@
-export type JsonPrimitive = string | number | boolean | null;
-export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
-export type JsonObject = {
-    [key: string]: JsonValue;
+export type JsonPrimitiveWithUndefined = string | number | boolean | null | undefined;
+export type JsonValueWithUndefined = JsonPrimitiveWithUndefined | JsonObjectWithUndefined | JsonArrayWithUndefined;
+export type JsonObjectWithUndefined = {
+    [key: string]: JsonValueWithUndefined;
 };
-export interface JsonArray extends Array<JsonValue> {
+export interface JsonArrayWithUndefined extends Array<JsonValueWithUndefined> {
 }

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobx-keystone-yjs",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "Yjs bindings for mobx-keystone",
   "keywords": [
     "mobx",
@@ -60,23 +60,27 @@
   },
   "peerDependencies": {
     "mobx": "^6.0.0 || ^5.0.0 || ^4.0.0",
-    "mobx-keystone": "^1.8.1",
+    "mobx-keystone": "^1.9.0",
     "yjs": "^13.0.0"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.11",
-    "@types/node": "^20.10.6",
+    "@babel/core": "^7.24.4",
+    "@babel/plugin-proposal-class-properties": "^7.18.6",
+    "@babel/plugin-proposal-decorators": "^7.24.1",
+    "@babel/preset-env": "^7.24.4",
+    "@babel/preset-typescript": "^7.24.1",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.12.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-jest": "^29.1.2",
     "ts-node": "^10.9.2",
-    "typescript": "^5.3.3",
-    "vite": "^5.0.10"
+    "typescript": "^5.4.4",
+    "vite": "^5.2.8"
   },
   "dependencies": {
     "tslib": "^2.6.2"

package/src/binding/YjsTextModel.ts

@@ -0,0 +1,248 @@
+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?.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()
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    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
+
+        disposeObserveDeltaList = observe(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
+  }
+}

package/src/binding/applyMobxKeystonePatchToYjsObject.ts

@@ -2,13 +2,14 @@ import { Patch } from "mobx-keystone"
 import * as Y from "yjs"
 import { failure } from "../utils/error"
 import { convertJsonToYjsData } from "./convertJsonToYjsData"
+import { JsonValueWithUndefined } from "jsonTypes"
 
 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))
+      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)}`
@@ -16,7 +17,7 @@ export function applyMobxKeystonePatchToYjsObject(patch: Patch, yjs: unknown): v
       }
       applyMobxKeystonePatchToYjsObject({ ...patch, path: rest }, child)
     } else if (yjs instanceof Y.Array) {
-      const child = yjs.get(Number(key))
+      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(
@@ -25,6 +26,8 @@ export function applyMobxKeystonePatchToYjsObject(patch: Patch, yjs: unknown): v
         )
       }
       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(
@@ -39,7 +42,7 @@ export function applyMobxKeystonePatchToYjsObject(patch: Patch, yjs: unknown): v
       switch (patch.op) {
         case "add":
         case "replace": {
-          yjs.set(key, convertJsonToYjsData(patch.value))
+          yjs.set(key, convertJsonToYjsData(patch.value as JsonValueWithUndefined))
           break
         }
         case "remove": {
@@ -56,21 +59,22 @@ export function applyMobxKeystonePatchToYjsObject(patch: Patch, yjs: unknown): v
       switch (patch.op) {
         case "replace": {
           if (key === "length") {
-            if (yjs.length > patch.value) {
-              const toDelete = yjs.length - patch.value
-              yjs.delete(patch.value, toDelete)
+            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(toInsert).fill(undefined))
             }
           } else {
             yjs.delete(Number(key))
-            yjs.insert(Number(key), [convertJsonToYjsData(patch.value)])
+            yjs.insert(Number(key), [convertJsonToYjsData(patch.value as JsonValueWithUndefined)])
           }
           break
         }
         case "add": {
-          yjs.insert(Number(key), [convertJsonToYjsData(patch.value)])
+          yjs.insert(Number(key), [convertJsonToYjsData(patch.value as JsonValueWithUndefined)])
           break
         }
         case "remove": {
@@ -81,9 +85,11 @@ export function applyMobxKeystonePatchToYjsObject(patch: Patch, yjs: unknown): v
           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`
+        `invalid patch path, the Yjs object is of an unkown type, so key "${String(patch.path[0])}" cannot be found in it`
       )
     }
   } else {