meridian-sdk 1.2.1 → 1.3.0

package/src/validation/index.ts

@@ -0,0 +1,137 @@
+/**
+ * Runtime validation for CRDT string values.
+ *
+ * Values stored in TreeCRDT and RGA are always strings on the wire. This
+ * layer lets you attach a validator to a handle so that ops are checked
+ * before being sent. Invalid values throw a `CrdtValidationError`.
+ *
+ * The validator interface is intentionally minimal — plug in Zod, Valibot,
+ * ArkType, or a plain function without any SDK dependency on those libraries.
+ *
+ * @example Using Zod:
+ * ```ts
+ * import { z } from "zod";
+ * import { zodValidator } from "meridian-sdk";
+ *
+ * const schema = z.object({ title: z.string(), done: z.boolean() });
+ * const tree = client.tree("tasks", { validator: zodValidator(schema) });
+ *
+ * // Validated — value is parsed JSON then checked against schema
+ * tree.addNode(null, "a0", JSON.stringify({ title: "Task 1", done: false }));
+ *
+ * // Throws CrdtValidationError
+ * tree.addNode(null, "a0", JSON.stringify({ title: 42 }));
+ * ```
+ *
+ * @example Using a plain function:
+ * ```ts
+ * import { fnValidator } from "meridian-sdk";
+ *
+ * const tree = client.tree("tasks", {
+ *   validator: fnValidator((v) => typeof v === "string" && v.length > 0),
+ * });
+ * ```
+ */
+
+/** Thrown when a CRDT value fails validation before being sent. */
+export class CrdtValidationError extends Error {
+  override readonly name = "CrdtValidationError";
+  constructor(
+    /** The raw string value that failed. */
+    public readonly value: string,
+    /** Human-readable reason from the validator. */
+    public readonly reason: string,
+  ) {
+    super(`CrdtValidationError: ${reason} (value: ${JSON.stringify(value)})`);
+  }
+}
+
+/**
+ * A validator that can be attached to a CRDT handle.
+ *
+ * `validate` receives the raw string value as stored on the wire. It should
+ * throw or return `{ ok: false, error: string }` for invalid values, and
+ * return `{ ok: true }` or `undefined` for valid ones.
+ */
+export interface CrdtValidator {
+  /**
+   * Validate `value`. Throw, or return `{ ok: false, error }` to reject.
+   * Return `{ ok: true }` or `undefined` to accept.
+   */
+  validate(value: string): { ok: false; error: string } | { ok: true } | undefined | void;
+}
+
+/**
+ * Run a validator against a value. Throws `CrdtValidationError` on failure.
+ * No-ops if `validator` is undefined.
+ */
+export function runValidator(validator: CrdtValidator | undefined, value: string): void {
+  if (validator === undefined) return;
+  let result: ReturnType<CrdtValidator["validate"]>;
+  try {
+    result = validator.validate(value);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new CrdtValidationError(value, reason);
+  }
+  if (result !== undefined && result !== null && !result.ok) {
+    throw new CrdtValidationError(value, result.error);
+  }
+}
+
+/**
+ * Creates a `CrdtValidator` from any Zod schema (or any object with a
+ * `safeParse` method returning `{ success, error }`).
+ *
+ * The string value is JSON-parsed before being passed to the schema.
+ * If JSON parsing fails, the raw string is passed as-is.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * const validator = zodValidator(z.object({ title: z.string() }));
+ * ```
+ */
+export function zodValidator(schema: {
+  safeParse(value: unknown): { success: true } | { success: false; error: { message: string } };
+}): CrdtValidator {
+  return {
+    validate(raw: string) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        parsed = raw;
+      }
+      const result = schema.safeParse(parsed);
+      if (!result.success) {
+        return { ok: false, error: result.error.message };
+      }
+      return { ok: true };
+    },
+  };
+}
+
+/**
+ * Creates a `CrdtValidator` from a plain predicate function.
+ *
+ * The function receives the raw string value. Return `true` to accept,
+ * `false` or a string (used as the error message) to reject.
+ *
+ * @example
+ * ```ts
+ * const validator = fnValidator((v) => v.length > 0 || "Value must not be empty");
+ * ```
+ */
+export function fnValidator(
+  fn: (value: string) => boolean | string,
+): CrdtValidator {
+  return {
+    validate(raw: string) {
+      const result = fn(raw);
+      if (result === true) return { ok: true };
+      if (result === false) return { ok: false, error: "Validation failed" };
+      return { ok: false, error: result };
+    },
+  };
+}

package/test/conflict.test.ts

@@ -0,0 +1,242 @@
+/**
+ * Unit tests for TreeHandle conflict visualization.
+ *
+ * Conflict events are detected by comparing the local optimistic state
+ * (nodeMetaMap) against the incoming server delta. Transport is stubbed.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { TreeHandle } from "../src/crdt/tree.js";
+import type { WsTransport } from "../src/transport/websocket.js";
+import type { ConflictEvent } from "../src/conflict/types.js";
+import type { TreeDelta } from "../src/sync/delta.js";
+
+function stubTransport(): WsTransport & { sent: unknown[] } {
+  const sent: unknown[] = [];
+  return {
+    sent,
+    connect: () => {},
+    close: () => {},
+    send: (msg) => { sent.push(msg); },
+    onStateChange: () => () => {},
+    onMessage: () => () => {},
+    pendingCount: () => 0,
+  } as unknown as WsTransport & { sent: unknown[] };
+}
+
+function makeTree(clientId = 1): TreeHandle {
+  return new TreeHandle({
+    crdtId: "tree-1",
+    clientId,
+    transport: stubTransport(),
+  });
+}
+
+/** Helper: build a flat TreeDelta (no children) */
+function flatDelta(nodes: Array<{ id: string; value: string; position: string; parentId?: string }>): TreeDelta {
+  return {
+    roots: nodes
+      .filter((n) => n.parentId === undefined)
+      .map((root) => ({
+        id: root.id,
+        value: root.value,
+        position: root.position,
+        children: nodes
+          .filter((n) => n.parentId === root.id)
+          .map((child) => ({
+            id: child.id,
+            value: child.value,
+            position: child.position,
+            children: [],
+          })),
+      })),
+  };
+}
+
+describe("conflict visualization — move_reordered", () => {
+  it("fires when server places node at different position than local optimistic", () => {
+    const tree = makeTree();
+    const events: ConflictEvent[] = [];
+    tree.onConflict((e) => events.push(e));
+
+    // Local client adds node at position "a0"
+    const nodeId = tree.addNode(null, "a0", "Node");
+
+    // Server responds with the node at "b0" (concurrent move won)
+    tree.applyDelta(flatDelta([{ id: nodeId, value: "Node", position: "b0" }]));
+
+    expect(events).toHaveLength(1);
+    expect(events[0]!.kind).toBe("move_reordered");
+    if (events[0]!.kind === "move_reordered") {
+      expect(events[0]!.nodeId).toBe(nodeId);
+      expect(events[0]!.localPosition).toBe("a0");
+      expect(events[0]!.serverPosition).toBe("b0");
+    }
+  });
+
+  it("fires when server places node under different parent", () => {
+    const tree = makeTree();
+    const events: ConflictEvent[] = [];
+    tree.onConflict((e) => events.push(e));
+
+    const parentA = tree.addNode(null, "a0", "ParentA");
+    const parentB = tree.addNode(null, "b0", "ParentB");
+    const child = tree.addNode(parentA, "a0", "Child");
+
+    // Locally: child is under parentA. Server says it moved to parentB.
+    tree.applyDelta(
+      flatDelta([
+        { id: parentA, value: "ParentA", position: "a0" },
+        { id: parentB, value: "ParentB", position: "b0" },
+        { id: child, value: "Child", position: "a0", parentId: parentB },
+      ])
+    );
+
+    const moveEvents = events.filter((e) => e.kind === "move_reordered");
+    expect(moveEvents.length).toBeGreaterThanOrEqual(1);
+    const childEvent = moveEvents.find((e) => e.kind === "move_reordered" && e.nodeId === child);
+    expect(childEvent).toBeDefined();
+    if (childEvent?.kind === "move_reordered") {
+      expect(childEvent.localParentId).toBe(parentA);
+      expect(childEvent.serverParentId).toBe(parentB);
+    }
+  });
+
+  it("does not fire when server confirms local state", () => {
+    const tree = makeTree();
+    const events: ConflictEvent[] = [];
+    tree.onConflict((e) => events.push(e));
+
+    const nodeId = tree.addNode(null, "a0", "Node");
+
+    // Server agrees with local
+    tree.applyDelta(flatDelta([{ id: nodeId, value: "Node", position: "a0" }]));
+
+    expect(events).toHaveLength(0);
+  });
+});
+
+describe("conflict visualization — lww_overwrite", () => {
+  it("fires when server value differs from local value", () => {
+    const tree = makeTree();
+    const events: ConflictEvent[] = [];
+    tree.onConflict((e) => events.push(e));
+
+    const nodeId = tree.addNode(null, "a0", "LocalValue");
+
+    // Server resolves LWW in favor of a concurrent update
+    tree.applyDelta(flatDelta([{ id: nodeId, value: "RemoteWinner", position: "a0" }]));
+
+    const lwwEvents = events.filter((e) => e.kind === "lww_overwrite");
+    expect(lwwEvents).toHaveLength(1);
+    if (lwwEvents[0]!.kind === "lww_overwrite") {
+      expect(lwwEvents[0]!.discardedValue).toBe("LocalValue");
+      expect(lwwEvents[0]!.winnerValue).toBe("RemoteWinner");
+    }
+  });
+
+  it("does not fire when value matches local", () => {
+    const tree = makeTree();
+    const events: ConflictEvent[] = [];
+    tree.onConflict((e) => events.push(e));
+
+    const nodeId = tree.addNode(null, "a0", "Same");
+    tree.applyDelta(flatDelta([{ id: nodeId, value: "Same", position: "a0" }]));
+
+    expect(events.filter((e) => e.kind === "lww_overwrite")).toHaveLength(0);
+  });
+});
+
+describe("conflict visualization — move_discarded", () => {
+  it("fires when delta contains a discarded_move from server", () => {
+    const tree = makeTree();
+    const events: ConflictEvent[] = [];
+    tree.onConflict((e) => events.push(e));
+
+    const nodeId = tree.addNode(null, "a0", "Root");
+    const childId = tree.addNode(nodeId, "a0", "Child");
+
+    // Simulate server returning a delta with a discarded cycle move.
+    // The server rejected: move nodeId under childId (would be a cycle).
+    // Both nodeId parts: wall_ms:logical:node_id
+    const [wall, logical, nodeIdNum] = nodeId.split(":").map(Number) as [number, number, number];
+    const [cwall, clogical, cNodeIdNum] = childId.split(":").map(Number) as [number, number, number];
+
+    tree.applyDelta({
+      roots: [
+        {
+          id: nodeId,
+          value: "Root",
+          position: "a0",
+          children: [{ id: childId, value: "Child", position: "a0", children: [] }],
+        },
+      ],
+      discarded_moves: [
+        {
+          node_id: { wall_ms: wall, logical, node_id: nodeIdNum },
+          attempted_parent_id: { wall_ms: cwall, logical: clogical, node_id: cNodeIdNum },
+          attempted_position: "a0",
+          actual_parent_id: null,
+          actual_position: "a0",
+        },
+      ],
+    });
+
+    const discarded = events.filter((e) => e.kind === "move_discarded");
+    expect(discarded).toHaveLength(1);
+    if (discarded[0]!.kind === "move_discarded") {
+      expect(discarded[0]!.nodeId).toBe(nodeId);
+      expect(discarded[0]!.attemptedParentId).toBe(childId);
+      expect(discarded[0]!.attemptedPosition).toBe("a0");
+      expect(discarded[0]!.actualParentId).toBeNull();
+    }
+  });
+
+  it("does not fire when discarded_moves is empty", () => {
+    const tree = makeTree();
+    const events: ConflictEvent[] = [];
+    tree.onConflict((e) => events.push(e));
+
+    const nodeId = tree.addNode(null, "a0", "Root");
+    tree.applyDelta({
+      roots: [{ id: nodeId, value: "Root", position: "a0", children: [] }],
+      discarded_moves: [],
+    });
+
+    expect(events.filter((e) => e.kind === "move_discarded")).toHaveLength(0);
+  });
+});
+
+describe("conflict visualization — conflictLog()", () => {
+  it("accumulates events in chronological order", () => {
+    const tree = makeTree();
+    const n1 = tree.addNode(null, "a0", "V1");
+    const n2 = tree.addNode(null, "b0", "V2");
+
+    tree.applyDelta(flatDelta([
+      { id: n1, value: "X", position: "a0" }, // lww_overwrite
+      { id: n2, value: "V2", position: "c0" }, // move_reordered
+    ]));
+
+    const log = tree.conflictLog();
+    expect(log.length).toBeGreaterThanOrEqual(2);
+    expect(log.map((e) => e.kind)).toContain("lww_overwrite");
+    expect(log.map((e) => e.kind)).toContain("move_reordered");
+  });
+
+  it("onConflict unsubscribe works", () => {
+    const tree = makeTree();
+    const events: ConflictEvent[] = [];
+    const unsub = tree.onConflict((e) => events.push(e));
+
+    const nodeId = tree.addNode(null, "a0", "A");
+    unsub();
+
+    tree.applyDelta(flatDelta([{ id: nodeId, value: "B", position: "z9" }]));
+
+    // Listener was removed — no events delivered
+    expect(events).toHaveLength(0);
+    // But log still captures it
+    expect(tree.conflictLog().length).toBeGreaterThan(0);
+  });
+});

package/test/fractional.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from "bun:test";
+import { fi, between, before, after, start, end, spread } from "../src/utils/fractional.js";
+
+describe("fractional indexing — between()", () => {
+  it("returns a string strictly between two positions", () => {
+    const mid = between("a0", "z9");
+    expect(mid > "a0").toBe(true);
+    expect(mid < "z9").toBe(true);
+  });
+
+  it("works for adjacent single-char positions", () => {
+    const mid = between("a0", "b0");
+    expect(mid > "a0").toBe(true);
+    expect(mid < "b0").toBe(true);
+  });
+
+  it("handles equal-length strings", () => {
+    const mid = between("a0", "a2");
+    expect(mid > "a0").toBe(true);
+    expect(mid < "a2").toBe(true);
+  });
+
+  it("handles different-length strings", () => {
+    const mid = between("a", "b0");
+    expect(mid > "a").toBe(true);
+    expect(mid < "b0").toBe(true);
+  });
+
+  it("subdivides when gap is minimal", () => {
+    // "a0" and "a1" are adjacent — between should append a char
+    const mid = between("a0", "a1");
+    expect(mid > "a0").toBe(true);
+    expect(mid < "a1").toBe(true);
+  });
+
+  it("throws when a >= b", () => {
+    expect(() => between("b0", "a0")).toThrow();
+    expect(() => between("a0", "a0")).toThrow();
+  });
+
+  it("can be called recursively to produce ordered sequence", () => {
+    const p1 = between("a0", "z9");
+    const p2 = between(p1, "z9");
+    const p3 = between(p1, p2);
+    expect("a0" < p1).toBe(true);
+    expect(p1 < p2).toBe(true);
+    expect(p1 < p3).toBe(true);
+    expect(p3 < p2).toBe(true);
+    expect(p2 < "z9").toBe(true);
+  });
+});
+
+describe("fractional indexing — before() / after()", () => {
+  it("before returns a string less than the input", () => {
+    const p = before("a0");
+    expect(p < "a0").toBe(true);
+  });
+
+  it("after returns a string greater than the input", () => {
+    const p = after("z9");
+    expect(p > "z9").toBe(true);
+  });
+
+  it("before/after round-trips are monotone", () => {
+    const base = "m4";
+    const b = before(base);
+    const a = after(base);
+    expect(b < base).toBe(true);
+    expect(a > base).toBe(true);
+    expect(b < a).toBe(true);
+  });
+});
+
+describe("fractional indexing — start() / end()", () => {
+  it("start < end", () => {
+    expect(start() < end()).toBe(true);
+  });
+
+  it("between(start, end) is valid", () => {
+    const mid = between(start(), end());
+    expect(mid > start()).toBe(true);
+    expect(mid < end()).toBe(true);
+  });
+});
+
+describe("fractional indexing — spread()", () => {
+  it("returns n positions in ascending order", () => {
+    const positions = spread("a0", "z9", 4);
+    expect(positions).toHaveLength(4);
+    for (let i = 1; i < positions.length; i++) {
+      expect(positions[i]! > positions[i - 1]!).toBe(true);
+    }
+  });
+
+  it("all positions are within bounds", () => {
+    const positions = spread("a0", "z9", 5);
+    for (const p of positions) {
+      expect(p > "a0").toBe(true);
+      expect(p < "z9").toBe(true);
+    }
+  });
+
+  it("returns empty array for n=0", () => {
+    expect(spread("a0", "z9", 0)).toEqual([]);
+  });
+
+  it("returns single midpoint for n=1", () => {
+    const [p] = spread("a0", "z9", 1);
+    expect(p! > "a0").toBe(true);
+    expect(p! < "z9").toBe(true);
+  });
+});
+
+describe("fractional indexing — fi namespace", () => {
+  it("fi object exposes all helpers", () => {
+    expect(typeof fi.between).toBe("function");
+    expect(typeof fi.before).toBe("function");
+    expect(typeof fi.after).toBe("function");
+    expect(typeof fi.start).toBe("function");
+    expect(typeof fi.end).toBe("function");
+    expect(typeof fi.spread).toBe("function");
+  });
+
+  it("fi.between matches named export", () => {
+    expect(fi.between("a0", "z9")).toBe(between("a0", "z9"));
+  });
+});