@strata-sync/mobx 0.1.0

package/AGENTS.md

@@ -0,0 +1,23 @@
+# @strata-sync/mobx
+
+MobX reactivity adapter for the sync system.
+
+## Commands
+
+- `npm run build` — compile TypeScript (`tsc`)
+- `npm run dev` — watch mode (`tsc --watch`)
+- `npm run test` — run tests (`vitest`)
+- `npm run lint` — lint with Biome
+- `npm run check-types` — type check without emitting
+
+## Gotchas
+
+- `mobx` ^6.0.0 is a peer dependency — the consuming app must install it
+- This package implements the reactivity adapter interface defined in `@strata-sync/core` — changes to the interface require updates here
+- MobX observable properties are set up during model hydration — accessing properties before hydration will not trigger reactions
+
+## Conventions
+
+- Implement the `ReactivityAdapter` interface from sync-core — do not create a custom interface
+- Use MobX `makeObservable` / `makeAutoObservable` patterns, not legacy decorators
+- Computed values should derive from observable model properties only

package/README.md

@@ -0,0 +1,42 @@
+# @strata-sync/mobx
+
+MobX reactivity adapter for the Strata Sync.
+
+## Overview
+
+sync-mobx implements the reactivity adapter interface defined in `@strata-sync/core` using MobX observables:
+
+- **Observable model instances** — model properties become MobX observables
+- **Computed values** — derived state from observable model properties
+- **Reaction-based updates** — automatic re-rendering when synced data changes
+
+## Installation
+
+```bash
+npm install @strata-sync/mobx
+```
+
+Peer dependency: `mobx` ^6.0.0
+
+## Usage
+
+Register the MobX adapter when initializing the sync client:
+
+```typescript
+import { createMobxAdapter } from "@strata-sync/mobx";
+
+const adapter = createMobxAdapter();
+
+// Pass to SyncClient configuration
+const client = new SyncClient({
+  reactivityAdapter: adapter,
+});
+```
+
+The adapter makes model instances observable, so MobX `observer()` components and `autorun` / `reaction` will automatically track and respond to sync updates.
+
+## How It Works
+
+1. When models are hydrated from sync deltas, the adapter wraps properties with MobX observables
+2. React components wrapped with `observer()` automatically re-render when observed properties change
+3. Computed values can derive state from multiple observable model properties

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@strata-sync/mobx",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "biome lint .",
+    "check-types": "tsc --noEmit",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@strata-sync/core": "*",
+    "mobx": "^6.13.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.12",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "mobx": "^6.0.0"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,212 @@
+import type {
+  DisposeFn,
+  ObservableArray,
+  ObservableBox,
+  ObservableMap,
+  ObservableOptions,
+  ReactionOptions,
+  ReactivityAdapter,
+} from "@strata-sync/core";
+import {
+  computed,
+  makeObservable,
+  observable,
+  reaction,
+  runInAction,
+} from "mobx";
+
+class MobXBox<T> implements ObservableBox<T> {
+  value: T;
+
+  constructor(initialValue: T) {
+    this.value = initialValue;
+    makeObservable(this, {
+      value: observable,
+    });
+  }
+
+  get(): T {
+    return this.value;
+  }
+
+  set(value: T): void {
+    runInAction(() => {
+      this.value = value;
+    });
+  }
+}
+
+class MobXMap<K, V> implements ObservableMap<K, V> {
+  private readonly map: Map<K, V>;
+
+  constructor(entries?: Iterable<[K, V]>) {
+    this.map = observable.map<K, V>(entries ? new Map(entries) : undefined);
+  }
+
+  get(key: K): V | undefined {
+    return this.map.get(key);
+  }
+
+  set(key: K, value: V): void {
+    runInAction(() => {
+      this.map.set(key, value);
+    });
+  }
+
+  has(key: K): boolean {
+    return this.map.has(key);
+  }
+
+  delete(key: K): boolean {
+    return runInAction(() => this.map.delete(key));
+  }
+
+  clear(): void {
+    runInAction(() => {
+      this.map.clear();
+    });
+  }
+
+  keys(): IterableIterator<K> {
+    return this.map.keys();
+  }
+
+  values(): IterableIterator<V> {
+    return this.map.values();
+  }
+
+  entries(): IterableIterator<[K, V]> {
+    return this.map.entries();
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  forEach(callback: (value: V, key: K) => void): void {
+    this.map.forEach(callback);
+  }
+}
+
+class MobXArray<T> implements ObservableArray<T> {
+  private readonly array: T[];
+
+  constructor(items?: T[]) {
+    this.array = observable.array<T>(items ?? []);
+  }
+
+  get(index: number): T | undefined {
+    return this.array[index];
+  }
+
+  toArray(): T[] {
+    return [...this.array];
+  }
+
+  push(...items: T[]): number {
+    return runInAction(() => this.array.push(...items));
+  }
+
+  pop(): T | undefined {
+    return runInAction(() => this.array.pop());
+  }
+
+  remove(predicate: (item: T) => boolean): T[] {
+    return runInAction(() => {
+      const removed: T[] = [];
+      for (let i = this.array.length - 1; i >= 0; i--) {
+        const item = this.array[i];
+        if (item !== undefined && predicate(item)) {
+          removed.push(item);
+          this.array.splice(i, 1);
+        }
+      }
+      return removed;
+    });
+  }
+
+  replace(items: T[]): void {
+    runInAction(() => {
+      this.array.length = 0;
+      this.array.push(...items);
+    });
+  }
+
+  clear(): void {
+    runInAction(() => {
+      this.array.length = 0;
+    });
+  }
+
+  find(predicate: (item: T) => boolean): T | undefined {
+    return this.array.find(predicate);
+  }
+
+  filter(predicate: (item: T) => boolean): T[] {
+    return this.array.filter(predicate);
+  }
+
+  map<U>(mapper: (item: T) => U): U[] {
+    return this.array.map(mapper);
+  }
+
+  get length(): number {
+    return this.array.length;
+  }
+
+  [Symbol.iterator](): Iterator<T> {
+    return this.array[Symbol.iterator]();
+  }
+}
+
+export const mobxReactivityAdapter: ReactivityAdapter = {
+  createBox<T>(
+    initialValue: T,
+    _options?: ObservableOptions
+  ): ObservableBox<T> {
+    return new MobXBox(initialValue);
+  },
+
+  createMap<K, V>(
+    entries?: Iterable<[K, V]>,
+    _options?: ObservableOptions
+  ): ObservableMap<K, V> {
+    return new MobXMap(entries);
+  },
+
+  createArray<T>(
+    items?: T[],
+    _options?: ObservableOptions
+  ): ObservableArray<T> {
+    return new MobXArray(items);
+  },
+
+  makeObservable<T extends object>(target: T, _options?: ObservableOptions): T {
+    return observable(target);
+  },
+
+  batch(fn) {
+    runInAction(fn);
+  },
+
+  runInAction<T>(fn: () => T): T {
+    return runInAction(fn);
+  },
+
+  reaction<T>(
+    expression: () => T,
+    effect: (value: T) => void,
+    options?: ReactionOptions
+  ): DisposeFn {
+    return reaction(expression, effect, options);
+  },
+
+  computed<T>(getter: () => T, _options?: ObservableOptions): { get(): T } {
+    const c = computed(getter);
+    return { get: () => c.get() };
+  },
+};
+
+export function createMobXReactivity(): ReactivityAdapter {
+  return mobxReactivityAdapter;
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+export type { Hydrated, LazyReference } from "@strata-sync/core";
+// biome-ignore lint/performance/noBarrelFile: package entry point
+export {
+  BackReference,
+  CachedPromise,
+  ClientModel,
+  Collection,
+  EphemeralProperty,
+  LazyCollection,
+  ManyToOne,
+  Model,
+  makeObservableProperty,
+  makeReferenceModelProperty,
+  OneToMany,
+  Property,
+  Reference,
+  ReferenceArray,
+  ReferenceCollection,
+  resolvePromise,
+} from "@strata-sync/core";
+export { createMobXReactivity, mobxReactivityAdapter } from "./adapter";

package/tests/adapter.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "vitest";
+import { createMobXReactivity, mobxReactivityAdapter } from "../src/index";
+
+describe("mobx reactivity adapter", () => {
+  it("returns the shared adapter instance", () => {
+    expect(createMobXReactivity()).toBe(mobxReactivityAdapter);
+  });
+
+  it("creates observable boxes that notify reactions", () => {
+    const adapter = createMobXReactivity();
+    const box = adapter.createBox(1);
+    const values: number[] = [];
+
+    const dispose = adapter.reaction(
+      () => box.get(),
+      (value) => values.push(value),
+      { fireImmediately: true }
+    );
+
+    box.set(2);
+    box.set(3);
+
+    expect(values).toEqual([1, 2, 3]);
+    dispose();
+  });
+
+  it("batches updates with action", () => {
+    const adapter = createMobXReactivity();
+    const box = adapter.createBox(0);
+    const values: number[] = [];
+
+    const dispose = adapter.reaction(
+      () => box.get(),
+      (value) => values.push(value)
+    );
+
+    adapter.batch(() => {
+      box.set(1);
+      box.set(2);
+    });
+
+    expect(values).toEqual([2]);
+    dispose();
+  });
+
+  it("creates observable maps that react to key changes", () => {
+    const adapter = createMobXReactivity();
+    const map = adapter.createMap([["a", 1]]);
+    const values: Array<number | undefined> = [];
+
+    const dispose = adapter.reaction(
+      () => map.get("a"),
+      (value) => values.push(value),
+      { fireImmediately: true }
+    );
+
+    map.set("a", 2);
+
+    expect(values).toEqual([1, 2]);
+    dispose();
+  });
+
+  it("creates observable arrays that track length changes", () => {
+    const adapter = createMobXReactivity();
+    const array = adapter.createArray([1, 2, 3]);
+    const lengths: number[] = [];
+
+    const dispose = adapter.reaction(
+      () => array.length,
+      (value) => lengths.push(value),
+      { fireImmediately: true }
+    );
+
+    array.push(4);
+    array.remove((value) => value % 2 === 0);
+
+    expect(array.toArray()).toEqual([1, 3]);
+    expect(lengths).toEqual([3, 4, 2]);
+    dispose();
+  });
+
+  it("supports computed values derived from observables", () => {
+    const adapter = createMobXReactivity();
+    const box = adapter.createBox(2);
+    const doubled = adapter.computed(() => box.get() * 2);
+    const values: number[] = [];
+
+    const dispose = adapter.reaction(
+      () => doubled.get(),
+      (value) => values.push(value),
+      { fireImmediately: true }
+    );
+
+    box.set(3);
+
+    expect(values).toEqual([4, 6]);
+    dispose();
+  });
+
+  it("makes objects observable", () => {
+    const adapter = createMobXReactivity();
+    const target = { count: 0 };
+    const observableTarget = adapter.makeObservable(target);
+    const values: number[] = [];
+
+    const dispose = adapter.reaction(
+      () => observableTarget.count,
+      (value) => values.push(value),
+      { fireImmediately: true }
+    );
+
+    adapter.runInAction(() => {
+      observableTarget.count = 1;
+    });
+
+    expect(values).toEqual([0, 1]);
+    dispose();
+  });
+});

package/tests/observability.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import {
+  makeObservableProperty,
+  makeReferenceModelProperty,
+} from "../src/index";
+
+interface PropertyChange {
+  name: string;
+  oldValue: unknown;
+  newValue: unknown;
+}
+
+class TestModel {
+  _mobx: Record<string, { get(): unknown; set(value: unknown): void }> = {};
+  __data: Record<string, unknown> = { title: "Initial" };
+  declare title: string | undefined;
+  changes: PropertyChange[] = [];
+
+  propertyChanged(name: string, oldValue: unknown, newValue: unknown): void {
+    this.changes.push({ name, oldValue, newValue });
+  }
+}
+
+makeObservableProperty(TestModel.prototype, "title");
+
+describe("makeObservableProperty", () => {
+  it("proxies through MobX boxes and tracks changes", () => {
+    const model = new TestModel();
+
+    expect(model.title).toBe("Initial");
+
+    model.title = "Updated";
+
+    expect(model.__data.title).toBe("Updated");
+    expect(model._mobx.title?.get()).toBe("Updated");
+    expect(model.changes).toEqual([
+      { name: "title", oldValue: "Initial", newValue: "Updated" },
+    ]);
+
+    model.title = "Again";
+
+    expect(model.changes).toEqual([
+      { name: "title", oldValue: "Initial", newValue: "Updated" },
+      { name: "title", oldValue: "Updated", newValue: "Again" },
+    ]);
+  });
+
+  it("falls back to __data when no MobX storage is present", () => {
+    const model = {
+      __data: { status: "open" },
+      changes: [] as PropertyChange[],
+      propertyChanged(name: string, oldValue: unknown, newValue: unknown) {
+        this.changes.push({ name, oldValue, newValue });
+      },
+    } as {
+      __data: Record<string, unknown>;
+      status?: string;
+      changes: PropertyChange[];
+      propertyChanged: (
+        name: string,
+        oldValue: unknown,
+        newValue: unknown
+      ) => void;
+    };
+
+    makeObservableProperty(model, "status");
+
+    expect(model.status).toBe("open");
+
+    model.status = "closed";
+
+    expect(model.__data.status).toBe("closed");
+    expect((model as { _mobx?: unknown })._mobx).toBeUndefined();
+    expect(model.changes).toEqual([
+      { name: "status", oldValue: "open", newValue: "closed" },
+    ]);
+  });
+});
+
+describe("makeReferenceModelProperty", () => {
+  it("gets and sets reference ids via the store", () => {
+    const store = {
+      get: (modelName: string, id: string) => ({ modelName, id }),
+    };
+
+    const model = {
+      store,
+      userId: "user-1" as string | null,
+      user: null as { id?: string } | null,
+    };
+
+    makeReferenceModelProperty(model, "user", "userId", "User");
+
+    expect(model.user).toEqual({ modelName: "User", id: "user-1" });
+
+    model.user = { id: "user-2" };
+
+    expect(model.userId).toBe("user-2");
+
+    model.user = null;
+
+    expect(model.userId).toBeNull();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "useDefineForClassFields": true,
+    "experimentalDecorators": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}