mobx-keystone-yjs 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export { MobxKeystoneYjsError } from "./utils/error";
+export { bindYjsToMobxKeystone } from "./binding/bindYjsToMobxKeystone";

package/dist/types/jsonTypes.d.ts

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

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

@@ -0,0 +1,6 @@
+/**
+ * A mobx-keystone-yjs error.
+ */
+export declare class MobxKeystoneYjsError extends Error {
+    constructor(msg: string);
+}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "mobx-keystone-yjs",
+  "version": "1.0.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.5",
+    "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"
+  }
+}

package/src/binding/applyMobxKeystonePatchToYjsObject.ts

@@ -0,0 +1,92 @@
+import { Patch } from "mobx-keystone"
+import { failure } from "../utils/error"
+import * as Y from "yjs"
+import { toYDataType } from "./toYDataType"
+
+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))
+      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))
+      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 {
+      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, toYDataType(patch.value))
+          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") {
+            if (yjs.length > patch.value) {
+              const toDelete = yjs.length - patch.value
+              yjs.delete(patch.value, 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), [toYDataType(patch.value)])
+          }
+          break
+        }
+        case "add": {
+          yjs.insert(Number(key), [toYDataType(patch.value)])
+          break
+        }
+        case "remove": {
+          yjs.delete(Number(key))
+          break
+        }
+        default: {
+          throw failure(`invalid patch operation for array`)
+        }
+      }
+    } else {
+      throw failure(
+        `invalid patch path, the Yjs object is of an unkown type, so key "${patch.path[0]}" cannot be found in it`
+      )
+    }
+  } else {
+    throw failure(`invalid patch path, it cannot be empty`)
+  }
+}

package/src/binding/bindYjsToMobxKeystone.ts

@@ -0,0 +1,142 @@
+import {
+  AnyDataModel,
+  AnyModel,
+  AnyStandardType,
+  ModelClass,
+  Patch,
+  TypeToData,
+  applyPatches,
+  fromSnapshot,
+  getParentToChildPath,
+  onGlobalPatches,
+  onPatches,
+  onSnapshot,
+} from "mobx-keystone"
+import * as Y from "yjs"
+import { applyMobxKeystonePatchToYjsObject } from "./applyMobxKeystonePatchToYjsObject"
+import { convertYjsEventToPatches } from "./convertYjsEventToPatches"
+
+export function bindYjsToMobxKeystone<
+  TType extends AnyStandardType | ModelClass<AnyModel> | ModelClass<AnyDataModel>,
+>({
+  yjsDoc,
+  yjsObject,
+  mobxKeystoneType,
+}: {
+  yjsDoc: Y.Doc
+  yjsObject: Y.Map<unknown> | Y.Array<unknown>
+  mobxKeystoneType: TType
+}): {
+  boundObject: TypeToData<TType>
+  dispose(): void
+  yjsOrigin: symbol
+} {
+  const yjsJson = yjsObject.toJSON()
+
+  const initializationGlobalPatches: { target: object; patches: Patch[] }[] = []
+
+  const createBoundObject = () => {
+    const disposeOnGlobalPatches = onGlobalPatches((target, patches) => {
+      initializationGlobalPatches.push({ target, patches })
+    })
+
+    try {
+      return fromSnapshot(mobxKeystoneType, yjsJson as any)
+    } finally {
+      disposeOnGlobalPatches()
+    }
+  }
+
+  const boundObject = createBoundObject()
+
+  let applyingMobxKeystoneChanges = 0
+  const yjsOrigin = Symbol("bindYjsToMobxKeystoneTransactionOrigin")
+
+  // bind any changes from yjs to mobx-keystone
+  const observeDeepCb = (events: Y.YEvent<any>[]) => {
+    const patches: Patch[] = []
+    events.forEach((event) => {
+      if (event.transaction.origin !== yjsOrigin) {
+        patches.push(...convertYjsEventToPatches(event))
+      }
+    })
+
+    if (patches.length > 0) {
+      applyingMobxKeystoneChanges++
+      try {
+        applyPatches(boundObject, patches)
+      } finally {
+        applyingMobxKeystoneChanges--
+      }
+    }
+  }
+
+  yjsObject.observeDeep(observeDeepCb)
+
+  // bind any changes from mobx-keystone to yjs
+  let pendingPatches: Patch[] = []
+  const disposeOnPatches = onPatches(boundObject, (patches) => {
+    if (applyingMobxKeystoneChanges > 0) {
+      return
+    }
+
+    pendingPatches.push(...patches)
+  })
+
+  // this is only used so we can transact all patches to the snapshot boundary
+  const disposeOnSnapshot = onSnapshot(boundObject, () => {
+    if (pendingPatches.length === 0) {
+      return
+    }
+
+    const patches = pendingPatches
+    pendingPatches = []
+
+    yjsDoc.transact(() => {
+      patches.forEach((patch) => {
+        applyMobxKeystonePatchToYjsObject(patch, yjsObject)
+      })
+    }, yjsOrigin)
+  })
+
+  // sync initial patches, that might include setting defaults, IDs, etc
+  yjsDoc.transact(() => {
+    // we need to skip initializations until we hit the initialization of the bound object
+    // this is because default objects might be created and initialized before the main object
+    // but we just need to catch when those are actually assigned to the bound object
+    let boundObjectFound = false
+
+    initializationGlobalPatches.forEach(({ target, patches }) => {
+      if (!boundObjectFound) {
+        if (target !== boundObject) {
+          return // skip
+        }
+        boundObjectFound = true
+      }
+
+      const parentToChildPath = getParentToChildPath(boundObject, target)
+      // this is undefined only if target is not a child of boundModel
+      if (parentToChildPath !== undefined) {
+        patches.forEach((patch) => {
+          applyMobxKeystonePatchToYjsObject(
+            {
+              ...patch,
+              path: [...parentToChildPath, ...patch.path],
+            },
+            yjsObject
+          )
+        })
+      }
+    })
+  }, yjsOrigin)
+
+  return {
+    boundObject,
+    dispose: () => {
+      disposeOnPatches()
+      disposeOnSnapshot()
+      yjsObject.unobserveDeep(observeDeepCb)
+    },
+    yjsOrigin,
+  }
+}

package/src/binding/convertYjsEventToPatches.ts

@@ -0,0 +1,85 @@
+import { Patch } from "mobx-keystone"
+import * as Y from "yjs"
+import { JSONArray, JSONObject, JSONValue } 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>
+
+    event.changes.keys.forEach((change, key) => {
+      const path = [...event.path, key]
+
+      switch (change.action) {
+        case "add":
+          patches.push({
+            op: "add",
+            path,
+            value: toPlainValue(source.get(key)),
+          })
+          break
+
+        case "update":
+          patches.push({
+            op: "replace",
+            path,
+            value: toPlainValue(source.get(key)),
+          })
+          break
+
+        case "delete":
+          patches.push({
+            op: "remove",
+            path,
+          })
+          break
+
+        default:
+          throw failure(`unsupported Yjs map event action: ${change.action}`)
+      }
+    })
+  } else if (event instanceof Y.YArrayEvent) {
+    let retain = 0
+    event.changes.delta.forEach((change) => {
+      if (change.retain) {
+        retain += change.retain
+      }
+
+      if (change.delete) {
+        // remove X items at retain position
+        const path = [...event.path, retain]
+        for (let i = 0; i < change.delete; i++) {
+          patches.push({
+            op: "remove",
+            path,
+          })
+        }
+      }
+
+      if (change.insert) {
+        const newValues = Array.isArray(change.insert) ? change.insert : [change.insert]
+        newValues.forEach((v) => {
+          const path = [...event.path, retain]
+          patches.push({
+            op: "add",
+            path,
+            value: toPlainValue(v),
+          })
+          retain++
+        })
+      }
+    })
+  }
+
+  return patches
+}
+
+function toPlainValue(v: Y.Map<any> | Y.Array<any> | JSONValue) {
+  if (v instanceof Y.Map || v instanceof Y.Array) {
+    return v.toJSON() as JSONObject | JSONArray
+  } else {
+    return v
+  }
+}

package/src/binding/toYDataType.ts

@@ -0,0 +1,41 @@
+import * as Y from "yjs"
+import { JSONValue, JSONArray, JSONObject, JSONPrimitive } from "../jsonTypes"
+
+function isJSONPrimitive(v: JSONValue): v is JSONPrimitive {
+  const t = typeof v
+  return t === "string" || t === "number" || t === "boolean" || v === null
+}
+
+function isJSONArray(v: JSONValue): v is JSONArray {
+  return Array.isArray(v)
+}
+
+function isJSONObject(v: JSONValue): v is JSONObject {
+  return !isJSONArray(v) && typeof v === "object"
+}
+
+export function toYDataType(v: JSONValue) {
+  if (isJSONPrimitive(v)) {
+    return v
+  } else if (isJSONArray(v)) {
+    const arr = new Y.Array()
+    applyJsonArray(arr, v)
+    return arr
+  } else if (isJSONObject(v)) {
+    const map = new Y.Map()
+    applyJsonObject(map, v)
+    return map
+  } else {
+    return undefined
+  }
+}
+
+function applyJsonArray(dest: Y.Array<unknown>, source: JSONArray) {
+  dest.push(source.map(toYDataType))
+}
+
+function applyJsonObject(dest: Y.Map<unknown>, source: JSONObject) {
+  Object.entries(source).forEach(([k, v]) => {
+    dest.set(k, toYDataType(v))
+  })
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { MobxKeystoneYjsError } from "./utils/error"
+export { bindYjsToMobxKeystone } from "./binding/bindYjsToMobxKeystone"

package/src/jsonTypes.ts

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

package/src/utils/error.ts

@@ -0,0 +1,18 @@
+/**
+ * A mobx-keystone-yjs error.
+ */
+export class MobxKeystoneYjsError extends Error {
+  constructor(msg: string) {
+    super(msg)
+
+    // Set the prototype explicitly.
+    Object.setPrototypeOf(this, MobxKeystoneYjsError.prototype)
+  }
+}
+
+/**
+ * @internal
+ */
+export function failure(msg: string) {
+  return new MobxKeystoneYjsError(msg)
+}