meridian-sdk 0.1.0

package/test/crdt.test.ts

@@ -0,0 +1,290 @@
+/**
+ * Unit tests for CRDT handles (no server required).
+ *
+ * We stub the WsTransport so sends are captured but not actually sent.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { GCounterHandle } from "../src/crdt/gcounter.js";
+import { PNCounterHandle } from "../src/crdt/pncounter.js";
+import { ORSetHandle } from "../src/crdt/orset.js";
+import { LwwRegisterHandle } from "../src/crdt/lwwregister.js";
+import { PresenceHandle } from "../src/crdt/presence.js";
+import type { WsTransport } from "../src/transport/websocket.js";
+
+// ---------------------------------------------------------------------------
+// Stub transport — captures sends, never actually connects
+// ---------------------------------------------------------------------------
+
+function stubTransport(): WsTransport & { sent: unknown[] } {
+  const sent: unknown[] = [];
+  return {
+    sent,
+    connect: () => {},
+    close: () => {},
+    subscribe: () => {},
+    updateClock: () => {},
+    send: (msg: unknown) => { sent.push(msg); },
+    get currentState() { return "CONNECTED" as const; },
+  } as unknown as WsTransport & { sent: unknown[] };
+}
+
+const BASE_OPTS = { ns: "test", clientId: 1 };
+
+// ---------------------------------------------------------------------------
+// GCounter
+// ---------------------------------------------------------------------------
+
+describe("GCounterHandle", () => {
+  it("starts at 0", () => {
+    const t = stubTransport();
+    const h = new GCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    expect(h.value()).toBe(0);
+  });
+
+  it("increment updates value optimistically", () => {
+    const t = stubTransport();
+    const h = new GCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    h.increment(5);
+    expect(h.value()).toBe(5);
+    expect(t.sent).toHaveLength(1);
+  });
+
+  it("increment fires onChange", () => {
+    const t = stubTransport();
+    const h = new GCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    const values: number[] = [];
+    h.onChange(v => values.push(v));
+    h.increment(3);
+    h.increment(2);
+    expect(values).toEqual([3, 5]);
+  });
+
+  it("applyDelta merges remote counts (max-merge)", () => {
+    const t = stubTransport();
+    const h = new GCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    h.increment(10); // client 1 = 10
+    h.applyDelta({ increments: { "2": 20 } });
+    expect(h.value()).toBe(30);
+  });
+
+  it("applyDelta ignores stale counts (no regression)", () => {
+    const t = stubTransport();
+    const h = new GCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    h.increment(10);
+    h.applyDelta({ increments: { "1": 5 } }); // 5 < 10 — stale
+    expect(h.value()).toBe(10);
+  });
+
+  it("unsubscribe stops onChange notifications", () => {
+    const t = stubTransport();
+    const h = new GCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    const values: number[] = [];
+    const unsub = h.onChange(v => values.push(v));
+    h.increment(1);
+    unsub();
+    h.increment(1);
+    expect(values).toEqual([1]); // only the first increment
+  });
+
+  it("increment rejects non-positive amount", () => {
+    const t = stubTransport();
+    const h = new GCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    expect(() => h.increment(0)).toThrow(RangeError);
+    expect(() => h.increment(-1)).toThrow(RangeError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// PNCounter
+// ---------------------------------------------------------------------------
+
+describe("PNCounterHandle", () => {
+  it("starts at 0", () => {
+    const t = stubTransport();
+    const h = new PNCounterHandle({ ...BASE_OPTS, crdtId: "pn", transport: t });
+    expect(h.value()).toBe(0);
+  });
+
+  it("increment and decrement", () => {
+    const t = stubTransport();
+    const h = new PNCounterHandle({ ...BASE_OPTS, crdtId: "pn", transport: t });
+    h.increment(10);
+    h.decrement(3);
+    expect(h.value()).toBe(7);
+  });
+
+  it("can go negative", () => {
+    const t = stubTransport();
+    const h = new PNCounterHandle({ ...BASE_OPTS, crdtId: "pn", transport: t });
+    h.decrement(5);
+    expect(h.value()).toBe(-5);
+  });
+
+  it("applyDelta merges both GCounters", () => {
+    const t = stubTransport();
+    const h = new PNCounterHandle({ ...BASE_OPTS, crdtId: "pn", transport: t });
+    h.applyDelta({ p: { increments: { "2": 100 } }, n: { increments: { "2": 40 } } });
+    expect(h.value()).toBe(60);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ORSet
+// ---------------------------------------------------------------------------
+
+describe("ORSetHandle", () => {
+  it("empty by default", () => {
+    const t = stubTransport();
+    const h = new ORSetHandle({ ...BASE_OPTS, crdtId: "s", transport: t });
+    expect(h.elements()).toEqual([]);
+  });
+
+  it("add makes element visible", () => {
+    const t = stubTransport();
+    const h = new ORSetHandle<string>({ ...BASE_OPTS, crdtId: "s", transport: t });
+    h.add("alice");
+    expect(h.has("alice")).toBe(true);
+  });
+
+  it("remove makes element invisible", () => {
+    const t = stubTransport();
+    const h = new ORSetHandle<string>({ ...BASE_OPTS, crdtId: "s", transport: t });
+    h.add("alice");
+    h.remove("alice");
+    expect(h.has("alice")).toBe(false);
+  });
+
+  it("add-wins: concurrent add+remove → element survives via applyDelta", () => {
+    const t = stubTransport();
+    const h = new ORSetHandle<string>({ ...BASE_OPTS, crdtId: "s", transport: t });
+    // Remote adds "alice" with tag "t1", local remove only removes "t2" (different tag)
+    h.applyDelta({ added: { '"alice"': ["t1"] }, removed: {} });
+    h.applyDelta({ added: {}, removed: { '"alice"': ["t2"] } }); // unknown tag — no effect
+    expect(h.has("alice")).toBe(true);
+  });
+
+  it("fires onChange on add and remove", () => {
+    const t = stubTransport();
+    const h = new ORSetHandle<string>({ ...BASE_OPTS, crdtId: "s", transport: t });
+    const snapshots: string[][] = [];
+    h.onChange(elems => snapshots.push([...elems].sort()));
+    h.add("a");
+    h.add("b");
+    h.remove("a");
+    expect(snapshots).toEqual([["a"], ["a", "b"], ["b"]]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// LWW Register
+// ---------------------------------------------------------------------------
+
+describe("LwwRegisterHandle", () => {
+  it("starts null", () => {
+    const t = stubTransport();
+    const h = new LwwRegisterHandle({ ...BASE_OPTS, crdtId: "r", transport: t });
+    expect(h.value()).toBeNull();
+  });
+
+  it("set updates value", () => {
+    const t = stubTransport();
+    const h = new LwwRegisterHandle<string>({ ...BASE_OPTS, crdtId: "r", transport: t });
+    h.set("hello");
+    expect(h.value()).toBe("hello");
+  });
+
+  it("applyDelta with higher HLC wins", () => {
+    const t = stubTransport();
+    const h = new LwwRegisterHandle<string>({ ...BASE_OPTS, crdtId: "r", transport: t });
+    h.set("first");
+    const localMeta = h.meta()!;
+    h.applyDelta({
+      entry: {
+        value: "second",
+        hlc: { wall_ms: localMeta.updatedAtMs + 1000, logical: 0, node_id: 2 },
+        author: 2,
+      },
+    });
+    expect(h.value()).toBe("second");
+  });
+
+  it("applyDelta with lower HLC is rejected", () => {
+    const t = stubTransport();
+    const h = new LwwRegisterHandle<string>({ ...BASE_OPTS, crdtId: "r", transport: t });
+    // Set local value with current time
+    h.set("current");
+    h.applyDelta({
+      entry: {
+        value: "old",
+        hlc: { wall_ms: 1, logical: 0, node_id: 99 }, // epoch — always loses
+        author: 99,
+      },
+    });
+    expect(h.value()).toBe("current");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Presence
+// ---------------------------------------------------------------------------
+
+describe("PresenceHandle", () => {
+  it("empty by default", () => {
+    const t = stubTransport();
+    const h = new PresenceHandle({ ...BASE_OPTS, crdtId: "p", transport: t });
+    expect(h.online()).toEqual([]);
+  });
+
+  it("heartbeat adds self to online list", () => {
+    const t = stubTransport();
+    const h = new PresenceHandle<{ name: string }>({ ...BASE_OPTS, crdtId: "p", transport: t });
+    h.heartbeat({ name: "alice" }, 30_000);
+    expect(h.online()).toHaveLength(1);
+    expect(h.online()[0]?.data).toEqual({ name: "alice" });
+  });
+
+  it("leave removes self from online list", () => {
+    const t = stubTransport();
+    const h = new PresenceHandle<{ name: string }>({ ...BASE_OPTS, crdtId: "p", transport: t });
+    h.heartbeat({ name: "alice" }, 30_000);
+    h.leave();
+    expect(h.online()).toHaveLength(0);
+  });
+
+  it("applyDelta adds remote entries", () => {
+    const t = stubTransport();
+    const h = new PresenceHandle<{ name: string }>({ ...BASE_OPTS, crdtId: "p", transport: t });
+    const now = Date.now();
+    h.applyDelta({
+      changes: {
+        "2": { data: { name: "bob" }, hlc: { wall_ms: now, logical: 0, node_id: 2 }, ttl_ms: 30_000 },
+      },
+    });
+    expect(h.online()).toHaveLength(1);
+    expect(h.online()[0]?.data).toEqual({ name: "bob" });
+  });
+
+  it("applyDelta null removes entry", () => {
+    const t = stubTransport();
+    const h = new PresenceHandle<{ name: string }>({ ...BASE_OPTS, crdtId: "p", transport: t });
+    const now = Date.now();
+    h.applyDelta({
+      changes: {
+        "2": { data: { name: "bob" }, hlc: { wall_ms: now, logical: 0, node_id: 2 }, ttl_ms: 30_000 },
+      },
+    });
+    h.applyDelta({ changes: { "2": null } });
+    expect(h.online()).toHaveLength(0);
+  });
+
+  it("fires onChange on heartbeat and leave", () => {
+    const t = stubTransport();
+    const h = new PresenceHandle<string>({ ...BASE_OPTS, crdtId: "p", transport: t });
+    const counts: number[] = [];
+    h.onChange(entries => counts.push(entries.length));
+    h.heartbeat("alice", 30_000);
+    h.leave();
+    expect(counts).toEqual([1, 0]);
+  });
+});

package/test/sync.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Unit tests for sync utilities: VectorClockTracker, codec, token parsing.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { Effect } from "effect";
+import { VectorClockTracker } from "../src/sync/clock.js";
+import { encode, decode, encodeClientMsg, decodeServerMsg } from "../src/codec.js";
+import { parseToken, checkTokenExpiry } from "../src/auth/token.js";
+import { CodecError, TokenParseError, TokenExpiredError } from "../src/errors.js";
+import { pack } from "msgpackr";
+
+// ---------------------------------------------------------------------------
+// VectorClockTracker
+// ---------------------------------------------------------------------------
+
+describe("VectorClockTracker", () => {
+  function freshStorage() {
+    const store = new Map<string, Record<string, number>>();
+    return {
+      load: (key: string) => store.get(key) ?? null,
+      save: (key: string, vc: Record<string, number>) => { store.set(key, { ...vc }); },
+    };
+  }
+
+  function tracker(initial: Record<string, number> = {}) {
+    return new VectorClockTracker({ namespace: "ns", crdtId: "c", storage: freshStorage(), initial });
+  }
+
+  it("starts empty", () => {
+    expect(tracker().snapshot()).toEqual({});
+  });
+
+  it("observe updates clock", () => {
+    const t = tracker();
+    t.observe("1", 5);
+    expect(t.snapshot()["1"]).toBe(5);
+  });
+
+  it("observe ignores older versions", () => {
+    const t = tracker({ "1": 10 });
+    t.observe("1", 3);
+    expect(t.snapshot()["1"]).toBe(10);
+  });
+
+  it("merge takes max per key", () => {
+    const t = tracker({ "1": 5, "2": 10 });
+    t.merge({ "1": 3, "2": 20, "3": 1 });
+    const snap = t.snapshot();
+    expect(snap["1"]).toBe(5);
+    expect(snap["2"]).toBe(20);
+    expect(snap["3"]).toBe(1);
+  });
+
+  it("reset clears all entries", () => {
+    const t = tracker({ "1": 10 });
+    t.reset();
+    expect(t.snapshot()).toEqual({});
+  });
+
+  it("persists to storage on observe", () => {
+    const storage = freshStorage();
+    const t1 = new VectorClockTracker({ namespace: "ns", crdtId: "x", storage });
+    t1.observe("42", 7);
+    const t2 = new VectorClockTracker({ namespace: "ns", crdtId: "x", storage });
+    expect(t2.snapshot()["42"]).toBe(7);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Codec
+// ---------------------------------------------------------------------------
+
+describe("codec", () => {
+  it("encode/decode roundtrip for plain objects", () => {
+    const obj = { foo: "bar", n: 42 };
+    expect(decode(encode(obj))).toEqual(obj);
+  });
+
+  it("encodeClientMsg produces bytes", () => {
+    const bytes = encodeClientMsg({ Subscribe: { crdt_id: "foo" } });
+    expect(bytes).toBeInstanceOf(Uint8Array);
+    expect(bytes.length).toBeGreaterThan(0);
+  });
+
+  it("decodeServerMsg succeeds on valid Ack", async () => {
+    const msg = { Ack: { seq: 99 } };
+    const bytes = new Uint8Array(encode(msg));
+    const result = await Effect.runPromise(decodeServerMsg(bytes));
+    expect(result).toEqual(msg);
+  });
+
+  it("decodeServerMsg fails with CodecError on unknown variant", async () => {
+    const bad = new Uint8Array(encode({ Unknown: {} }));
+    const err = await Effect.runPromise(
+      decodeServerMsg(bad).pipe(Effect.flip),
+    );
+    expect(err).toBeInstanceOf(CodecError);
+  });
+
+  it("decodeServerMsg fails with CodecError on non-object", async () => {
+    const bad = new Uint8Array(encode("not-an-object"));
+    const err = await Effect.runPromise(
+      decodeServerMsg(bad).pipe(Effect.flip),
+    );
+    expect(err).toBeInstanceOf(CodecError);
+  });
+
+  it("decodeServerMsg succeeds on multi-key map (Schema matches first valid variant)", async () => {
+    // Effect Schema union picks first matching variant — Ack wins here.
+    // The server never sends multi-key maps; this tests Schema's lenient-but-safe behaviour.
+    const bytes = new Uint8Array(
+      encode({ Ack: { seq: 1 }, Delta: { crdt_id: "x", delta_bytes: new Uint8Array() } }),
+    );
+    const result = await Effect.runPromise(decodeServerMsg(bytes));
+    // Schema picks whichever variant matches first — just assert it decoded without error
+    expect("Ack" in result || "Delta" in result).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Token parsing
+// ---------------------------------------------------------------------------
+
+describe("parseToken", () => {
+  function makeToken(claims: object): string {
+    const payload = pack(claims);
+    const b64 = btoa(String.fromCharCode(...payload))
+      .replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+    return `${b64}.fakesig`;
+  }
+
+  it("parses valid claims", async () => {
+    const token = makeToken({
+      namespace: "my-room",
+      client_id: 42,
+      expires_at: Date.now() + 3_600_000,
+      permissions: { read: true, write: true, admin: false },
+    });
+    const claims = await Effect.runPromise(parseToken(token));
+    expect(claims.namespace).toBe("my-room");
+    expect(claims.client_id).toBe(42);
+  });
+
+  it("fails with TokenParseError on missing dot", async () => {
+    const err = await Effect.runPromise(parseToken("nodothere").pipe(Effect.flip));
+    expect(err).toBeInstanceOf(TokenParseError);
+  });
+
+  it("fails with TokenParseError on bad base64", async () => {
+    const err = await Effect.runPromise(parseToken("!!!.sig").pipe(Effect.flip));
+    expect(err).toBeInstanceOf(TokenParseError);
+  });
+
+  it("checkTokenExpiry succeeds for future expiry", async () => {
+    const token = makeToken({
+      namespace: "ns",
+      client_id: 1,
+      expires_at: Date.now() + 3_600_000,
+      permissions: { read: true, write: false, admin: false },
+    });
+    const claims = await Effect.runPromise(parseToken(token));
+    const result = await Effect.runPromise(checkTokenExpiry(claims));
+    expect(result.client_id).toBe(1);
+  });
+
+  it("checkTokenExpiry fails with TokenExpiredError for past expiry", async () => {
+    const token = makeToken({
+      namespace: "ns",
+      client_id: 1,
+      expires_at: 1,
+      permissions: { read: true, write: false, admin: false },
+    });
+    const claims = await Effect.runPromise(parseToken(token));
+    const err = await Effect.runPromise(checkTokenExpiry(claims).pipe(Effect.flip));
+    expect(err).toBeInstanceOf(TokenExpiredError);
+  });
+});

package/test/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "types": ["bun-types"]
+  },
+  "include": ["../**/*"]
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}