mobx-keystone-loro 1.0.0

package/src/binding/convertLoroDataToJson.ts

@@ -0,0 +1,68 @@
+import { isContainer, LoroMap, LoroMovableList, LoroText } from "loro-crdt"
+import { modelSnapshotOutWithMetadata, toFrozenSnapshot } from "mobx-keystone"
+import type { PlainValue } from "../plainTypes"
+import { failure } from "../utils/error"
+import { type BindableLoroContainer } from "../utils/isBindableLoroContainer"
+import { LoroTextModel } from "./LoroTextModel"
+
+type LoroValue = BindableLoroContainer | PlainValue
+
+/**
+ * Converts Loro data to JSON-compatible format for mobx-keystone snapshots.
+ *
+ * @param value The Loro value to convert
+ * @returns JSON-compatible value
+ */
+export function convertLoroDataToJson(value: LoroValue): PlainValue {
+  if (value === null) {
+    return null
+  }
+
+  if (typeof value !== "object") {
+    if (value === undefined) {
+      throw new Error("undefined values are not supported by Loro")
+    }
+
+    return value as PlainValue
+  }
+
+  if (isContainer(value)) {
+    if (value instanceof LoroMap) {
+      const result: Record<string, PlainValue> = {}
+      for (const [k, v] of value.entries()) {
+        result[k] = convertLoroDataToJson(v as LoroValue)
+      }
+      return result
+    }
+
+    if (value instanceof LoroMovableList) {
+      const result: PlainValue[] = []
+      for (let i = 0; i < value.length; i++) {
+        result.push(convertLoroDataToJson(value.get(i) as LoroValue))
+      }
+      return result
+    }
+
+    if (value instanceof LoroText) {
+      const deltas = value.toDelta()
+      // Return a LoroTextModel-compatible snapshot
+      return modelSnapshotOutWithMetadata(LoroTextModel, {
+        deltaList: toFrozenSnapshot(deltas),
+      }) as unknown as PlainValue
+    }
+
+    throw failure(`unsupported bindable Loro container type`)
+  }
+
+  // Plain object or array
+  if (Array.isArray(value)) {
+    return value.map((item) => convertLoroDataToJson(item as LoroValue))
+  }
+
+  const result: Record<string, PlainValue> = {}
+  for (const [k, v] of Object.entries(value)) {
+    result[k] = convertLoroDataToJson(v as LoroValue)
+  }
+
+  return result
+}

package/src/binding/loroBindingContext.ts

@@ -0,0 +1,46 @@
+import type { LoroDoc } from "loro-crdt"
+import { type AnyType, createContext } from "mobx-keystone"
+import type { BindableLoroContainer } from "../utils/isBindableLoroContainer"
+
+/**
+ * Context for the Loro binding, providing access to the Loro document
+ * and binding state from within mobx-keystone models.
+ */
+export interface LoroBindingContext {
+  /**
+   * The Loro document being bound.
+   */
+  loroDoc: LoroDoc
+
+  /**
+   * The root Loro object being bound.
+   */
+  loroObject: BindableLoroContainer
+
+  /**
+   * The mobx-keystone model type being used.
+   */
+  mobxKeystoneType: AnyType
+
+  /**
+   * String used as origin for Loro transactions to identify changes
+   * coming from mobx-keystone.
+   */
+  loroOrigin: string
+
+  /**
+   * The bound mobx-keystone object (once created).
+   */
+  boundObject: unknown
+
+  /**
+   * Whether changes are currently being applied from Loro to mobx-keystone.
+   * Used to prevent infinite loops.
+   */
+  isApplyingLoroChangesToMobxKeystone: boolean
+}
+
+/**
+ * Context for accessing the Loro binding from within mobx-keystone models.
+ */
+export const loroBindingContext = createContext<LoroBindingContext | undefined>(undefined)

package/src/binding/loroSnapshotTracking.ts

@@ -0,0 +1,36 @@
+import type { LoroMap, LoroMovableList } from "loro-crdt"
+
+type LoroContainer = LoroMap | LoroMovableList
+
+/**
+ * WeakMap that tracks which snapshot each Loro container was last synced from.
+ * This is used during reconciliation to skip containers that are already up-to-date.
+ *
+ * The key is the Loro container (LoroMap or LoroMovableList).
+ * The value is the snapshot (plain object or array) that was last synced to it.
+ */
+export const loroContainerToSnapshot = new WeakMap<LoroContainer, unknown>()
+
+/**
+ * Updates the snapshot tracking for a Loro container.
+ * Call this after syncing a snapshot to a Loro container.
+ */
+export function setLoroContainerSnapshot(container: LoroContainer, snapshot: unknown): void {
+  loroContainerToSnapshot.set(container, snapshot)
+}
+
+/**
+ * Gets the last synced snapshot for a Loro container.
+ * Returns undefined if the container has never been synced.
+ */
+export function getLoroContainerSnapshot(container: LoroContainer): unknown {
+  return loroContainerToSnapshot.get(container)
+}
+
+/**
+ * Checks if a Loro container is up-to-date with the given snapshot.
+ * Uses reference equality to check if the snapshot is the same.
+ */
+export function isLoroContainerUpToDate(container: LoroContainer, snapshot: unknown): boolean {
+  return loroContainerToSnapshot.get(container) === snapshot
+}

package/src/binding/moveWithinArray.ts

@@ -0,0 +1,112 @@
+import { DeepChange } from "mobx-keystone"
+
+/**
+ * Synthetic change type for array moves.
+ */
+export interface ArrayMoveChange {
+  type: "ArrayMove"
+  path: readonly (string | number)[]
+  fromIndex: number
+  toIndex: number
+}
+
+/**
+ * Tracks the currently active move operation.
+ * When set, the next two splice operations on this array are intercepted.
+ */
+let activeMoveContext:
+  | {
+      array: unknown[]
+      fromIndex: number
+      toIndex: number
+      path: readonly (string | number)[] | undefined // Captured from first splice
+      receivedFirstSplice: boolean
+    }
+  | undefined
+
+/**
+ * Moves an item within an array from one index to another.
+ *
+ * When used on a mobx-keystone array bound to a Loro movable list,
+ * this translates to a native Loro move operation for optimal CRDT merging.
+ *
+ * For unbound arrays, performs a standard splice-based move.
+ *
+ * @param array The array to move within
+ * @param fromIndex The index of the item to move
+ * @param toIndex The target index to move the item to
+ */
+export function moveWithinArray<T>(array: T[], fromIndex: number, toIndex: number): void {
+  // Validate indices
+  if (fromIndex < 0 || fromIndex >= array.length) {
+    throw new Error(`fromIndex ${fromIndex} is out of bounds (array length: ${array.length})`)
+  }
+  if (toIndex < 0 || toIndex > array.length) {
+    throw new Error(`toIndex ${toIndex} is out of bounds (array length: ${array.length})`)
+  }
+  if (fromIndex === toIndex) {
+    return // No-op
+  }
+
+  // Set up the move context before mutations
+  activeMoveContext = {
+    array,
+    fromIndex,
+    toIndex,
+    path: undefined,
+    receivedFirstSplice: false,
+  }
+
+  try {
+    // Perform the actual splice operations
+    // This will trigger onDeepChange for each splice
+    const [item] = array.splice(fromIndex, 1)
+    const adjustedTarget = toIndex > fromIndex ? toIndex - 1 : toIndex
+    array.splice(adjustedTarget, 0, item)
+  } finally {
+    activeMoveContext = undefined
+  }
+}
+
+/**
+ * Check if a change is part of an active move operation and process it.
+ * This is called for ArraySplice changes on the target array.
+ *
+ * @param change The deep change (must be ArraySplice type)
+ * @returns The ArrayMoveChange if the move is complete (second splice),
+ *          undefined if intercepted but not complete (first splice)
+ */
+export function processChangeForMove(change: DeepChange): ArrayMoveChange | undefined {
+  // We know we're in a move context and this is an ArraySplice on the target array
+  const ctx = activeMoveContext!
+
+  if (!ctx.receivedFirstSplice) {
+    // First splice - capture the path and mark as received
+    ctx.path = change.path
+    ctx.receivedFirstSplice = true
+    return undefined
+  }
+
+  // Second splice - the move is complete.
+  // Note: We adjust toIndex here for Loro's move() semantics, which expects
+  // the target position after removal. This is intentionally separate from
+  // the adjustment on line 64, which is for the splice operation on the MobX array.
+  // Both adjustments are needed because:
+  // - Line 64: splice() inserts at a position in the already-shortened array
+  // - Here: Loro's move(from, to) also expects `to` as the position after removal
+  const adjustedToIndex = ctx.toIndex > ctx.fromIndex ? ctx.toIndex - 1 : ctx.toIndex
+
+  return {
+    type: "ArrayMove",
+    path: ctx.path!,
+    fromIndex: ctx.fromIndex,
+    toIndex: adjustedToIndex,
+  }
+}
+
+/**
+ * Check if we're currently in a move context for a specific array.
+ */
+export function isInMoveContextForArray(array: unknown[]): boolean {
+  return activeMoveContext !== undefined && activeMoveContext.array === array
+}

package/src/binding/resolveLoroPath.ts

@@ -0,0 +1,37 @@
+import { LoroMap, LoroMovableList } from "loro-crdt"
+import type { Path } from "mobx-keystone"
+import { failure } from "../utils/error"
+import { getOrCreateLoroCollectionAtom } from "../utils/getOrCreateLoroCollectionAtom"
+import type { BindableLoroContainer } from "../utils/isBindableLoroContainer"
+
+/**
+ * Resolves a path within a Loro object structure.
+ * Returns the Loro container at the specified path.
+ *
+ * @param loroObject The root Loro object
+ * @param path Array of keys/indices to traverse
+ * @returns The Loro container at the path
+ */
+export function resolveLoroPath(loroObject: BindableLoroContainer, path: Path): unknown {
+  let currentLoroObject: unknown = loroObject
+
+  path.forEach((pathPart, i) => {
+    if (currentLoroObject instanceof LoroMap) {
+      getOrCreateLoroCollectionAtom(currentLoroObject).reportObserved()
+      const key = String(pathPart)
+      currentLoroObject = currentLoroObject.get(key)
+    } else if (currentLoroObject instanceof LoroMovableList) {
+      getOrCreateLoroCollectionAtom(currentLoroObject).reportObserved()
+      const key = Number(pathPart)
+      currentLoroObject = currentLoroObject.get(key)
+    } else {
+      throw failure(
+        `LoroMap or LoroMovableList was expected at path ${JSON.stringify(
+          path.slice(0, i)
+        )} in order to resolve path ${JSON.stringify(path)}, but got ${currentLoroObject} instead`
+      )
+    }
+  })
+
+  return currentLoroObject
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { bindLoroToMobxKeystone } from "./binding/bindLoroToMobxKeystone"
+export type { ApplyJsonToLoroOptions } from "./binding/convertJsonToLoroData"
+export {
+  applyJsonArrayToLoroMovableList,
+  applyJsonObjectToLoroMap,
+  convertJsonToLoroData,
+} from "./binding/convertJsonToLoroData"
+export {
+  isLoroTextModelSnapshot,
+  LoroTextModel,
+  loroTextModelType,
+} from "./binding/LoroTextModel"
+export type { LoroBindingContext } from "./binding/loroBindingContext"
+export { loroBindingContext } from "./binding/loroBindingContext"
+export { moveWithinArray } from "./binding/moveWithinArray"
+export { MobxKeystoneLoroError } from "./utils/error"

package/src/plainTypes.ts

@@ -0,0 +1,7 @@
+export type PlainPrimitive = string | number | boolean | null | undefined
+
+export type PlainValue = PlainPrimitive | PlainObject | PlainArray
+
+export type PlainObject = { [key: string]: PlainValue }
+
+export type PlainArray = PlainValue[]

package/src/utils/error.ts

@@ -0,0 +1,12 @@
+export class MobxKeystoneLoroError extends Error {
+  constructor(msg: string) {
+    super(msg)
+
+    // Set the prototype explicitly for better instanceof support
+    Object.setPrototypeOf(this, MobxKeystoneLoroError.prototype)
+  }
+}
+
+export function failure(message: string): never {
+  throw new MobxKeystoneLoroError(message)
+}

package/src/utils/getOrCreateLoroCollectionAtom.ts

@@ -0,0 +1,17 @@
+import { createAtom, type IAtom } from "mobx"
+import type { BindableLoroContainer } from "./isBindableLoroContainer"
+
+const atomMap = new WeakMap<BindableLoroContainer, IAtom>()
+
+/**
+ * Gets or creates a MobX atom for a Loro collection.
+ * This is used to track reactivity for computed properties that read from Loro containers.
+ */
+export function getOrCreateLoroCollectionAtom(collection: BindableLoroContainer): IAtom {
+  let atom = atomMap.get(collection)
+  if (!atom) {
+    atom = createAtom(`loroCollectionAtom`)
+    atomMap.set(collection, atom)
+  }
+  return atom
+}

package/src/utils/isBindableLoroContainer.ts

@@ -0,0 +1,13 @@
+import { LoroMap, LoroMovableList, LoroText } from "loro-crdt"
+
+/**
+ * A bindable Loro container (Map, MovableList, or Text).
+ */
+export type BindableLoroContainer = LoroMap | LoroMovableList | LoroText
+
+/**
+ * Checks if a value is a bindable Loro container.
+ */
+export function isBindableLoroContainer(value: unknown): value is BindableLoroContainer {
+  return value instanceof LoroMap || value instanceof LoroMovableList || value instanceof LoroText
+}