mobx-keystone-loro 1.0.0

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

@@ -0,0 +1,72 @@
+import { Delta, LoroText } from 'loro-crdt';
+import { SnapshotOutOf } from 'mobx-keystone';
+export declare const loroTextModelId = "mobx-keystone-loro/LoroTextModel";
+/**
+ * Type for the delta stored in the model.
+ * Uses Quill delta format: array of operations with insert, delete, retain.
+ */
+export type LoroTextDeltaList = Delta<string>[];
+declare const LoroTextModel_base: import('mobx-keystone')._Model<unknown, {
+    /**
+     * The current delta representing the rich text content.
+     * Uses Quill delta format.
+     */
+    deltaList: import('mobx-keystone').OptionalModelProp<import('mobx-keystone').Frozen<LoroTextDeltaList>>;
+}, never, never>;
+/**
+ * A mobx-keystone model representing Loro rich text.
+ * This model stores the current delta state (Quill format) and syncs with LoroText.
+ */
+export declare class LoroTextModel extends LoroTextModel_base {
+    /**
+     * Creates a LoroTextModel with initial text content.
+     */
+    static withText(text: string): LoroTextModel;
+    /**
+     * Creates a LoroTextModel with initial delta.
+     */
+    static withDelta(delta: LoroTextDeltaList): LoroTextModel;
+    /**
+     * Atom that gets changed when the associated Loro text changes.
+     */
+    loroTextChangedAtom: import('mobx').IAtom;
+    /**
+     * The LoroText object represented by this mobx-keystone node, if bound.
+     * Returns undefined when the model is not part of a bound object tree.
+     */
+    get loroText(): LoroText | undefined;
+    /**
+     * Gets the plain text content.
+     * This always uses the stored delta, which is kept in sync with Loro.
+     */
+    get text(): string;
+    /**
+     * Gets the current delta (Quill format).
+     */
+    get currentDelta(): LoroTextDeltaList;
+    /**
+     * Converts delta to plain text.
+     */
+    private deltaToText;
+    /**
+     * Sets the delta.
+     */
+    setDelta(delta: LoroTextDeltaList): void;
+    /**
+     * Inserts text at the specified position.
+     */
+    insertText(index: number, text: string): void;
+    /**
+     * Deletes text at the specified range.
+     */
+    deleteText(index: number, length: number): void;
+}
+/**
+ * Type for LoroTextModel for use with tProp.
+ */
+export declare const loroTextModelType: import('mobx-keystone').ModelType<LoroTextModel>;
+/**
+ * Checks if a snapshot is a LoroTextModel snapshot.
+ */
+export declare function isLoroTextModelSnapshot(value: unknown): value is SnapshotOutOf<LoroTextModel>;
+export {};

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

@@ -0,0 +1,9 @@
+import { ContainerID, LoroDoc, LoroEvent } from 'loro-crdt';
+import { Path } from 'mobx-keystone';
+export type ReconciliationMap = Map<string, object>;
+/**
+ * Applies a Loro event directly to the MobX model tree using proper mutations
+ * (splice for arrays, property assignment for objects).
+ * This is more efficient than converting to patches first.
+ */
+export declare function applyLoroEventToMobx(event: LoroEvent, loroDoc: LoroDoc, boundObject: object, rootPath: Path, reconciliationMap: ReconciliationMap, newlyInsertedContainers: Set<ContainerID>): void;

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

@@ -0,0 +1,7 @@
+import { DeepChange } from 'mobx-keystone';
+import { BindableLoroContainer } from '../utils/isBindableLoroContainer';
+import { ArrayMoveChange } from './moveWithinArray';
+/**
+ * Applies a MobX DeepChange or an ArrayMoveChange to a Loro object.
+ */
+export declare function applyMobxChangeToLoroObject(change: DeepChange | ArrayMoveChange, loroObject: BindableLoroContainer): void;

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

@@ -0,0 +1,33 @@
+import { LoroDoc } from 'loro-crdt';
+import { AnyDataModel, AnyModel, AnyStandardType, ModelClass, TypeToData } from 'mobx-keystone';
+import { BindableLoroContainer } from '../utils/isBindableLoroContainer';
+/**
+ * Creates a bidirectional binding between a Loro data structure and a mobx-keystone model.
+ */
+export declare function bindLoroToMobxKeystone<TType extends AnyStandardType | ModelClass<AnyModel> | ModelClass<AnyDataModel>>({ loroDoc, loroObject, mobxKeystoneType, }: {
+    /**
+     * The Loro document.
+     */
+    loroDoc: LoroDoc;
+    /**
+     * The bound Loro data structure.
+     */
+    loroObject: BindableLoroContainer;
+    /**
+     * The mobx-keystone model type.
+     */
+    mobxKeystoneType: TType;
+}): {
+    /**
+     * The bound mobx-keystone instance.
+     */
+    boundObject: TypeToData<TType>;
+    /**
+     * Disposes the binding.
+     */
+    dispose: () => void;
+    /**
+     * The Loro origin string used for binding transactions.
+     */
+    loroOrigin: string;
+};

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

@@ -0,0 +1,51 @@
+import { Delta, LoroMap, LoroMovableList, LoroText } from 'loro-crdt';
+import { PlainArray, PlainObject, PlainValue } from '../plainTypes';
+import { BindableLoroContainer } from '../utils/isBindableLoroContainer';
+type LoroValue = BindableLoroContainer | PlainValue;
+/**
+ * Options for applying JSON data to Loro data structures.
+ */
+export interface ApplyJsonToLoroOptions {
+    /**
+     * The mode to use when applying JSON data to Loro data structures.
+     * - `add`: Creates new Loro containers for objects/arrays (default, backwards compatible)
+     * - `merge`: Recursively merges values, preserving existing container references where possible
+     */
+    mode?: "add" | "merge";
+}
+/**
+ * Extracts delta array from a LoroTextModel snapshot's delta field.
+ * The delta field is a frozen Delta<string>[] (array of delta operations).
+ */
+export declare function extractTextDeltaFromSnapshot(delta: unknown): Delta<string>[];
+/**
+ * Applies delta operations to a LoroText using insert/mark APIs.
+ * This works on both attached and detached containers.
+ *
+ * Strategy: Insert all text first, then apply marks. This avoids mark inheritance
+ * issues when inserting at the boundary of a marked region.
+ */
+export declare function applyDeltaToLoroText(text: LoroText, deltas: Delta<string>[]): void;
+/**
+ * Converts a plain value to a Loro data structure.
+ * Objects are converted to LoroMaps, arrays to LoroMovableLists, primitives are untouched.
+ * Frozen values are a special case and they are kept as immutable plain values.
+ */
+export declare function convertJsonToLoroData(v: PlainValue): LoroValue;
+/**
+ * Applies a JSON array to a LoroMovableList, using convertJsonToLoroData to convert the values.
+ *
+ * @param dest The destination LoroMovableList.
+ * @param source The source JSON array.
+ * @param options Options for applying the JSON data.
+ */
+export declare const applyJsonArrayToLoroMovableList: (dest: LoroMovableList, source: PlainArray, options?: ApplyJsonToLoroOptions) => void;
+/**
+ * Applies a JSON object to a LoroMap, using convertJsonToLoroData to convert the values.
+ *
+ * @param dest The destination LoroMap.
+ * @param source The source JSON object.
+ * @param options Options for applying the JSON data.
+ */
+export declare const applyJsonObjectToLoroMap: (dest: LoroMap, source: PlainObject, options?: ApplyJsonToLoroOptions) => void;
+export {};

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

@@ -0,0 +1,11 @@
+import { PlainValue } from '../plainTypes';
+import { BindableLoroContainer } from '../utils/isBindableLoroContainer';
+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 declare function convertLoroDataToJson(value: LoroValue): PlainValue;
+export {};

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

@@ -0,0 +1,39 @@
+import { LoroDoc } from 'loro-crdt';
+import { AnyType } from 'mobx-keystone';
+import { 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 declare const loroBindingContext: import('mobx-keystone').Context<LoroBindingContext | undefined>;

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

@@ -0,0 +1,26 @@
+import { 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 declare const loroContainerToSnapshot: WeakMap<LoroContainer, unknown>;
+/**
+ * Updates the snapshot tracking for a Loro container.
+ * Call this after syncing a snapshot to a Loro container.
+ */
+export declare function setLoroContainerSnapshot(container: LoroContainer, snapshot: unknown): void;
+/**
+ * Gets the last synced snapshot for a Loro container.
+ * Returns undefined if the container has never been synced.
+ */
+export declare function getLoroContainerSnapshot(container: LoroContainer): unknown;
+/**
+ * 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 declare function isLoroContainerUpToDate(container: LoroContainer, snapshot: unknown): boolean;
+export {};

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

@@ -0,0 +1,36 @@
+import { DeepChange } from 'mobx-keystone';
+/**
+ * Synthetic change type for array moves.
+ */
+export interface ArrayMoveChange {
+    type: "ArrayMove";
+    path: readonly (string | number)[];
+    fromIndex: number;
+    toIndex: number;
+}
+/**
+ * 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 declare function moveWithinArray<T>(array: T[], fromIndex: number, toIndex: number): void;
+/**
+ * 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 declare function processChangeForMove(change: DeepChange): ArrayMoveChange | undefined;
+/**
+ * Check if we're currently in a move context for a specific array.
+ */
+export declare function isInMoveContextForArray(array: unknown[]): boolean;

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

@@ -0,0 +1,11 @@
+import { Path } from 'mobx-keystone';
+import { 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 declare function resolveLoroPath(loroObject: BindableLoroContainer, path: Path): unknown;

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+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/dist/types/plainTypes.d.ts

@@ -0,0 +1,6 @@
+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/dist/types/utils/error.d.ts

@@ -0,0 +1,4 @@
+export declare class MobxKeystoneLoroError extends Error {
+    constructor(msg: string);
+}
+export declare function failure(message: string): never;

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

@@ -0,0 +1,7 @@
+import { IAtom } from 'mobx';
+import { BindableLoroContainer } from './isBindableLoroContainer';
+/**
+ * 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 declare function getOrCreateLoroCollectionAtom(collection: BindableLoroContainer): IAtom;

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

@@ -0,0 +1,9 @@
+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 declare function isBindableLoroContainer(value: unknown): value is BindableLoroContainer;

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "mobx-keystone-loro",
+  "version": "1.0.0",
+  "description": "Loro CRDT bindings for mobx-keystone",
+  "keywords": [
+    "mobx",
+    "mobx-keystone",
+    "loro",
+    "loro-crdt",
+    "crdt",
+    "state",
+    "state-management",
+    "reactive",
+    "collaborative"
+  ],
+  "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",
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "script": "./dist/mobx-keystone-loro.umd.js",
+      "import": "./dist/mobx-keystone-loro.esm.mjs",
+      "require": "./dist/mobx-keystone-loro.umd.js",
+      "default": "./dist/mobx-keystone-loro.esm.mjs"
+    }
+  },
+  "esmodule": "./dist/mobx-keystone-loro.esm.js",
+  "module": "./dist/mobx-keystone-loro.esm.js",
+  "jsnext:main": "./dist/mobx-keystone-loro.esm.js",
+  "react-native": "./dist/mobx-keystone-loro.umd.js",
+  "umd:main": "./dist/mobx-keystone-loro.umd.js",
+  "unpkg": "./dist/mobx-keystone-loro.umd.js",
+  "jsdelivr": "./dist/mobx-keystone-loro.umd.js",
+  "main": "./dist/mobx-keystone-loro.umd.js",
+  "types": "./dist/types/index.d.ts",
+  "typings": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "src",
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE",
+    "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-loro.esm.mjs dist/mobx-keystone-loro.esm.js",
+    "test": "jest",
+    "test:ci": "jest --ci"
+  },
+  "peerDependencies": {
+    "loro-crdt": "^1.10.3",
+    "mobx": "^6.0.0 || ^5.0.0 || ^4.0.0",
+    "mobx-keystone": "^1.12.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.28.5",
+    "@babel/plugin-proposal-class-properties": "^7.18.6",
+    "@babel/plugin-proposal-decorators": "^7.28.0",
+    "@babel/preset-env": "^7.28.5",
+    "@babel/preset-typescript": "^7.28.5",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
+    "babel-jest": "^30.2.0",
+    "jest": "^30.2.0",
+    "mobx-keystone": "workspace:packages/lib",
+    "shx": "^0.4.0",
+    "spec.ts": "^1.1.3",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "nanoid": "^3.3.11",
+    "tslib": "^2.8.1"
+  },
+  "directories": {
+    "test": "test"
+  }
+}

package/src/binding/LoroTextModel.ts

@@ -0,0 +1,211 @@
+import { type Delta, LoroText } from "loro-crdt"
+import { computed, createAtom } from "mobx"
+import {
+  frozen,
+  getParentToChildPath,
+  getSnapshotModelType,
+  Model,
+  model,
+  modelAction,
+  type SnapshotOutOf,
+  tProp,
+  types,
+} from "mobx-keystone"
+import { getOrCreateLoroCollectionAtom } from "../utils/getOrCreateLoroCollectionAtom"
+import { loroBindingContext } from "./loroBindingContext"
+import { resolveLoroPath } from "./resolveLoroPath"
+
+export const loroTextModelId = "mobx-keystone-loro/LoroTextModel"
+
+/**
+ * Type for the delta stored in the model.
+ * Uses Quill delta format: array of operations with insert, delete, retain.
+ */
+export type LoroTextDeltaList = Delta<string>[]
+
+/**
+ * A mobx-keystone model representing Loro rich text.
+ * This model stores the current delta state (Quill format) and syncs with LoroText.
+ */
+@model(loroTextModelId)
+export class LoroTextModel extends Model({
+  /**
+   * The current delta representing the rich text content.
+   * Uses Quill delta format.
+   */
+  deltaList: tProp(types.frozen(types.unchecked<LoroTextDeltaList>()), () => frozen([])),
+}) {
+  /**
+   * Creates a LoroTextModel with initial text content.
+   */
+  static withText(text: string): LoroTextModel {
+    return new LoroTextModel({
+      deltaList: frozen([{ insert: text }]),
+    })
+  }
+
+  /**
+   * Creates a LoroTextModel with initial delta.
+   */
+  static withDelta(delta: LoroTextDeltaList): LoroTextModel {
+    return new LoroTextModel({
+      deltaList: frozen(delta),
+    })
+  }
+
+  /**
+   * Atom that gets changed when the associated Loro text changes.
+   */
+  loroTextChangedAtom = createAtom("loroTextChangedAtom")
+
+  /**
+   * The LoroText object represented by this mobx-keystone node, if bound.
+   * Returns undefined when the model is not part of a bound object tree.
+   */
+  @computed
+  get loroText(): LoroText | undefined {
+    // Check if we have a binding context first - return undefined if not bound
+    const ctx = loroBindingContext.get(this)
+    if (ctx?.boundObject == null) {
+      return undefined
+    }
+
+    try {
+      const path = getParentToChildPath(ctx.boundObject, this)
+      if (!path) {
+        return undefined
+      }
+
+      // If this model IS the bound object, the loroObject is the LoroText
+      if (path.length === 0) {
+        const loroObject = ctx.loroObject
+        if (loroObject instanceof LoroText) {
+          getOrCreateLoroCollectionAtom(loroObject).reportObserved()
+          return loroObject
+        }
+        return undefined
+      }
+
+      // Otherwise resolve the path
+      const loroObject = resolveLoroPath(ctx.loroObject, path)
+
+      if (loroObject instanceof LoroText) {
+        getOrCreateLoroCollectionAtom(loroObject).reportObserved()
+        return loroObject
+      }
+    } catch {
+      // Path resolution failed - return undefined
+    }
+
+    return undefined
+  }
+
+  /**
+   * Gets the plain text content.
+   * This always uses the stored delta, which is kept in sync with Loro.
+   */
+  @computed
+  get text(): string {
+    this.loroTextChangedAtom.reportObserved()
+
+    // Always compute from delta - it's the source of truth for this model
+    // The delta is kept in sync with Loro via patches
+    return this.deltaToText(this.deltaList.data)
+  }
+
+  /**
+   * Gets the current delta (Quill format).
+   */
+  @computed
+  get currentDelta(): LoroTextDeltaList {
+    this.loroTextChangedAtom.reportObserved()
+
+    // Try to get from bound LoroText first
+    const loroText = this.loroText
+    if (loroText) {
+      try {
+        return loroText.toDelta()
+      } catch {
+        // fall back to stored delta
+      }
+    }
+
+    return this.deltaList.data
+  }
+
+  /**
+   * Converts delta to plain text.
+   */
+  private deltaToText(delta: LoroTextDeltaList): string {
+    let result = ""
+    for (const op of delta) {
+      if ("insert" in op && typeof op.insert === "string") {
+        result += op.insert
+      }
+    }
+    return result
+  }
+
+  /**
+   * Sets the delta.
+   */
+  @modelAction
+  setDelta(delta: LoroTextDeltaList): void {
+    this.deltaList = frozen(delta)
+  }
+
+  /**
+   * Inserts text at the specified position.
+   */
+  @modelAction
+  insertText(index: number, text: string): void {
+    const loroText = this.loroText
+    if (loroText) {
+      loroText.insert(index, text)
+      // The binding will handle syncing back
+    } else {
+      // Fallback: modify delta directly
+      const currentText = this.text
+      const newText = currentText.slice(0, index) + text + currentText.slice(index)
+      this.deltaList = frozen([{ insert: newText }])
+    }
+  }
+
+  /**
+   * Deletes text at the specified range.
+   */
+  @modelAction
+  deleteText(index: number, length: number): void {
+    const loroText = this.loroText
+    if (loroText) {
+      loroText.delete(index, length)
+      // The binding will handle syncing back
+    } else {
+      // Fallback: modify delta directly
+      const currentText = this.text
+      const newText = currentText.slice(0, index) + currentText.slice(index + length)
+      this.deltaList = frozen([{ insert: newText }])
+    }
+  }
+
+  /**
+   * Internal action to update delta from Loro sync.
+   * @internal
+   */
+  @modelAction
+  _updateDeltaFromLoro(delta: LoroTextDeltaList): void {
+    this.deltaList = frozen(delta)
+  }
+}
+
+/**
+ * Type for LoroTextModel for use with tProp.
+ */
+export const loroTextModelType = types.model(LoroTextModel)
+
+/**
+ * Checks if a snapshot is a LoroTextModel snapshot.
+ */
+export function isLoroTextModelSnapshot(value: unknown): value is SnapshotOutOf<LoroTextModel> {
+  return getSnapshotModelType(value) === loroTextModelId
+}