mobx-keystone-yjs 1.3.1 → 1.5.0

package/src/binding/bindYjsToMobxKeystone.ts

@@ -1,9 +1,11 @@
+import { action } from "mobx"
 import {
   AnyDataModel,
   AnyModel,
   AnyStandardType,
   ModelClass,
   Patch,
+  SnapshotInOf,
   TypeToData,
   applyPatches,
   fromSnapshot,
@@ -13,10 +15,15 @@ import {
   onSnapshot,
 } from "mobx-keystone"
 import * as Y from "yjs"
+import { getYjsCollectionAtom } from "../utils/getOrCreateYjsCollectionAtom"
 import { applyMobxKeystonePatchToYjsObject } from "./applyMobxKeystonePatchToYjsObject"
+import { YjsData, 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>,
 >({
@@ -24,25 +31,49 @@ export function bindYjsToMobxKeystone<
   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
 } {
   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 = yjsObject.toJSON()
+  const yjsJson = convertYjsDataToJson(yjsObject as YjsData)
 
   const initializationGlobalPatches: { target: object; patches: Patch[] }[] = []
 
@@ -53,7 +84,7 @@ export function bindYjsToMobxKeystone<
 
     try {
       const boundObject = yjsBindingContext.apply(
-        () => fromSnapshot(mobxKeystoneType, yjsJson as any),
+        () => fromSnapshot(mobxKeystoneType, yjsJson as unknown as SnapshotInOf<TypeToData<TType>>),
         bindingContext
       )
       yjsBindingContext.set(boundObject, { ...bindingContext, boundObject })
@@ -65,51 +96,55 @@ export function bindYjsToMobxKeystone<
 
   const boundObject = createBoundObject()
 
-  let applyingMobxKeystoneChanges = 0
-
   // bind any changes from yjs to mobx-keystone
-  const observeDeepCb = (events: Y.YEvent<any>[]) => {
+  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) {
+        getYjsCollectionAtom(event.target)?.reportChanged()
+      }
     })
 
     if (patches.length > 0) {
-      applyingMobxKeystoneChanges++
+      applyingYjsChangesToMobxKeystone++
       try {
         applyPatches(boundObject, patches)
       } finally {
-        applyingMobxKeystoneChanges--
+        applyingYjsChangesToMobxKeystone--
       }
     }
-  }
+  })
 
   yjsObject.observeDeep(observeDeepCb)
 
   // bind any changes from mobx-keystone to yjs
-  let pendingPatches: Patch[] = []
+  let pendingArrayOfArrayOfPatches: Patch[][] = []
   const disposeOnPatches = onPatches(boundObject, (patches) => {
-    if (applyingMobxKeystoneChanges > 0) {
+    if (applyingYjsChangesToMobxKeystone > 0) {
       return
     }
 
-    pendingPatches.push(...patches)
+    pendingArrayOfArrayOfPatches.push(patches)
   })
 
   // this is only used so we can transact all patches to the snapshot boundary
   const disposeOnSnapshot = onSnapshot(boundObject, () => {
-    if (pendingPatches.length === 0) {
+    if (pendingArrayOfArrayOfPatches.length === 0) {
       return
     }
 
-    const patches = pendingPatches
-    pendingPatches = []
+    const arrayOfArrayOfPatches = pendingArrayOfArrayOfPatches
+    pendingArrayOfArrayOfPatches = []
 
     yjsDoc.transact(() => {
-      patches.forEach((patch) => {
-        applyMobxKeystonePatchToYjsObject(patch, yjsObject)
+      arrayOfArrayOfPatches.forEach((arrayOfPatches) => {
+        arrayOfPatches.forEach((patch) => {
+          applyMobxKeystonePatchToYjsObject(patch, yjsObject)
+        })
       })
     }, yjsOrigin)
   })

package/src/binding/convertJsonToYjsData.ts

@@ -1,49 +1,77 @@
 import * as Y from "yjs"
-import { JsonValue, JsonArray, JsonObject, JsonPrimitive } from "../jsonTypes"
+import { YjsTextModel, yjsTextModelId } from "./YjsTextModel"
+import { SnapshotOutOf } from "mobx-keystone"
+import { YjsData } from "./convertYjsDataToJson"
+import {
+  JsonArrayWithUndefined,
+  JsonObjectWithUndefined,
+  JsonPrimitiveWithUndefined,
+  JsonValueWithUndefined,
+} from "jsonTypes"
 
-function isJsonPrimitive(v: JsonValue): v is JsonPrimitive {
+function isJsonPrimitiveWithUndefined(v: JsonValueWithUndefined): v is JsonPrimitiveWithUndefined {
   const t = typeof v
-  return t === "string" || t === "number" || t === "boolean" || v === null
+  return t === "string" || t === "number" || t === "boolean" || v === null || v === undefined
 }
 
-function isJsonArray(v: JsonValue): v is JsonArray {
+function isJsonArrayWithUndefined(v: JsonValueWithUndefined): v is JsonArrayWithUndefined {
   return Array.isArray(v)
 }
 
-function isJsonObject(v: JsonValue): v is JsonObject {
-  return !isJsonArray(v) && typeof v === "object"
+function isJsonObjectWithUndefined(v: JsonValueWithUndefined): v is JsonObjectWithUndefined {
+  return !isJsonArrayWithUndefined(v) && typeof v === "object"
 }
 
-export function convertJsonToYjsData(v: JsonValue) {
-  if (v === undefined || isJsonPrimitive(v)) {
+/**
+ * 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: JsonValueWithUndefined | undefined): YjsData {
+  if (v === undefined || isJsonPrimitiveWithUndefined(v)) {
     return v
   }
 
-  if (isJsonArray(v)) {
+  if (isJsonArrayWithUndefined(v)) {
     const arr = new Y.Array()
-    applyJsonArrayYArray(arr, v)
-    return arr
+    applyJsonArrayToYArray(arr, v)
+    return arr as YjsData
   }
 
-  if (isJsonObject(v)) {
+  if (isJsonObjectWithUndefined(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
+    return map as YjsData
   }
 
   throw new Error(`unsupported value type: ${v}`)
 }
 
-export function applyJsonArrayYArray(dest: Y.Array<unknown>, source: JsonArray) {
+/**
+ * Applies a JSON array to a Y.Array, using the convertJsonToYjsData to convert the values.
+ */
+export function applyJsonArrayToYArray(dest: Y.Array<unknown>, source: JsonArrayWithUndefined) {
   dest.push(source.map(convertJsonToYjsData))
 }
 
-export function applyJsonObjectToYMap(dest: Y.Map<unknown>, source: JsonObject) {
+/**
+ * Applies a JSON object to a Y.Map, using the convertJsonToYjsData to convert the values.
+ */
+export function applyJsonObjectToYMap(dest: Y.Map<unknown>, source: JsonObjectWithUndefined) {
   Object.entries(source).forEach(([k, v]) => {
     dest.set(k, convertJsonToYjsData(v))
   })

package/src/binding/convertYjsDataToJson.ts

@@ -0,0 +1,31 @@
+import { modelSnapshotOutWithMetadata } from "mobx-keystone"
+import * as Y from "yjs"
+import { JsonObjectWithUndefined, JsonValueWithUndefined } from "../jsonTypes"
+import { YjsTextModel } from "./YjsTextModel"
+
+export type YjsData = Y.Array<YjsData> | Y.Map<YjsData> | Y.Text | JsonValueWithUndefined
+
+export function convertYjsDataToJson(yjsData: YjsData): JsonValueWithUndefined {
+  if (yjsData instanceof Y.Array) {
+    return yjsData.map((v) => convertYjsDataToJson(v))
+  }
+
+  if (yjsData instanceof Y.Map) {
+    const obj: JsonObjectWithUndefined = {}
+    yjsData.forEach((v, k) => {
+      obj[k] = convertYjsDataToJson(v)
+    })
+    return obj
+  }
+
+  if (yjsData instanceof Y.Text) {
+    const deltas = yjsData.toDelta() as unknown[]
+
+    return modelSnapshotOutWithMetadata(YjsTextModel, {
+      deltaList: deltas.length > 0 ? [{ $frozen: true, data: deltas }] : [],
+    }) as unknown as JsonValueWithUndefined
+  }
+
+  // assume it's a primitive
+  return yjsData
+}

package/src/binding/convertYjsEventToPatches.ts

@@ -1,13 +1,17 @@
 import { Patch } from "mobx-keystone"
 import * as Y from "yjs"
-import { JsonArray, JsonObject, JsonValue } from "../jsonTypes"
+import {
+  JsonArrayWithUndefined,
+  JsonObjectWithUndefined,
+  JsonValueWithUndefined,
+} from "../jsonTypes"
 import { failure } from "../utils/error"
 
 export function convertYjsEventToPatches(event: Y.YEvent<any>): Patch[] {
   const patches: Patch[] = []
 
   if (event instanceof Y.YMapEvent) {
-    const source = event.target as Y.Map<any>
+    const source = event.target
 
     event.changes.keys.forEach((change, key) => {
       const path = [...event.path, key]
@@ -71,14 +75,21 @@ export function convertYjsEventToPatches(event: Y.YEvent<any>): Patch[] {
         })
       }
     })
+  } else if (event instanceof Y.YTextEvent) {
+    const path = [...event.path, "deltaList", -1 /* last item */]
+    patches.push({
+      op: "add",
+      path,
+      value: { $frozen: true, data: event.delta },
+    })
   }
 
   return patches
 }
 
-function toPlainValue(v: Y.Map<any> | Y.Array<any> | JsonValue) {
+function toPlainValue(v: Y.Map<any> | Y.Array<any> | JsonValueWithUndefined) {
   if (v instanceof Y.Map || v instanceof Y.Array) {
-    return v.toJSON() as JsonObject | JsonArray
+    return v.toJSON() as JsonObjectWithUndefined | JsonArrayWithUndefined
   } else {
     return v
   }

package/src/binding/resolveYjsPath.ts

@@ -0,0 +1,27 @@
+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
+}

package/src/binding/yjsBindingContext.ts

@@ -1,12 +1,42 @@
 import { AnyType, createContext } 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 const yjsBindingContext = createContext<YjsBindingContext | undefined>(undefined)

package/src/index.ts

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

package/src/jsonTypes.ts

@@ -1,4 +1,9 @@
-export type JsonPrimitive = string | number | boolean | null
-export type JsonValue = JsonPrimitive | JsonObject | JsonArray
-export type JsonObject = { [key: string]: JsonValue }
-export interface JsonArray extends Array<JsonValue> {}
+export type JsonPrimitiveWithUndefined = string | number | boolean | null | undefined
+export type JsonValueWithUndefined =
+  | JsonPrimitiveWithUndefined
+  | JsonObjectWithUndefined
+  | JsonArrayWithUndefined
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type JsonObjectWithUndefined = { [key: string]: JsonValueWithUndefined }
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface JsonArrayWithUndefined extends Array<JsonValueWithUndefined> {}

package/src/utils/getOrCreateYjsCollectionAtom.ts

@@ -0,0 +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
+}