meridian-sdk 0.3.4 → 0.4.0

package/src/crdt/awareness.ts

@@ -0,0 +1,149 @@
+import { Schema as S } from "effect";
+import type { Schema } from "effect";
+import { encode, decode } from "../codec.js";
+import type { WsTransport } from "../transport/websocket.js";
+
+// ---------------------------------------------------------------------------
+// AwarenessEntry
+// ---------------------------------------------------------------------------
+
+/**
+ * A single peer's awareness state on a given channel.
+ *
+ * Unlike presence entries, awareness entries are ephemeral: they are not
+ * persisted and disappear when the sender disconnects or clears their state.
+ */
+export interface AwarenessEntry<T> {
+  /** The sender's client ID (from their token). */
+  clientId: number;
+  /** The decoded payload sent by the peer. */
+  data: T;
+  /** Local timestamp (ms) when this entry was last received. */
+  receivedAt: number;
+}
+
+// ---------------------------------------------------------------------------
+// AwarenessHandle
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle for an ephemeral awareness channel.
+ *
+ * Awareness is a stateless pub/sub channel: updates are fanned out to all
+ * other subscribers in the same namespace in real time, but are **not**
+ * persisted. If a client connects after a peer's last update, it will not
+ * see that peer's state until the peer sends another update.
+ *
+ * Use this for high-frequency, transient UI state like cursor positions,
+ * text selections, or "is typing" indicators — not for durable shared data.
+ *
+ * @example
+ * ```ts
+ * const cursors = client.awareness<{ x: number; y: number }>('cursors');
+ * cursors.update({ x: 100, y: 200 });
+ * cursors.onChange(peers => console.log('peers:', peers));
+ * ```
+ */
+export class AwarenessHandle<T = unknown> {
+  private readonly entries = new Map<number, AwarenessEntry<T>>();
+  private readonly listeners = new Set<
+    (entries: AwarenessEntry<T>[]) => void
+  >();
+
+  constructor(
+    private readonly key: string,
+    private readonly transport: WsTransport,
+    private readonly clientId: number,
+    private readonly schema?: Schema.Schema<T>,
+  ) {}
+
+  /**
+   * Send our local awareness state to all peers (fire-and-forget).
+   *
+   * The server does not acknowledge awareness updates — this is a best-effort
+   * broadcast. Offline updates are **not** queued: they are dropped silently
+   * since awareness data is inherently time-sensitive.
+   */
+  update(data: T): void {
+    const encoded = encode(data);
+    this.transport.send({ AwarenessUpdate: { key: this.key, data: encoded } });
+  }
+
+  /**
+   * Clear our own entry from remote peers (e.g. on tab hide or component unmount).
+   *
+   * Sends a `null` payload, which causes all subscribers to remove our entry.
+   */
+  clear(): void {
+    this.transport.send({
+      AwarenessUpdate: { key: this.key, data: encode(null) },
+    });
+  }
+
+  /**
+   * Apply an incoming `AwarenessBroadcast` from the server.
+   * Called internally by `MeridianClient.handleServerMsg`.
+   *
+   * @internal
+   */
+  applyBroadcast(fromClientId: number, rawData: Uint8Array): void {
+    const decoded = decode(rawData);
+    if (decoded === null || decoded === undefined) {
+      if (this.entries.has(fromClientId)) {
+        this.entries.delete(fromClientId);
+        this.emit();
+      }
+      return;
+    }
+
+    const data = this.schema
+      ? S.decodeUnknownSync(this.schema)(decoded)
+      : (decoded as T);
+
+    const existing = this.entries.get(fromClientId);
+    this.entries.set(fromClientId, {
+      clientId: fromClientId,
+      data,
+      receivedAt: Date.now(),
+    });
+
+    // Only notify if the entry was new or data changed (reference check is
+    // sufficient for the "new entry" case; data change always yields a new obj).
+    if (!existing || existing.data !== data) {
+      this.emit();
+    }
+  }
+
+  /**
+   * Returns the current awareness state for all **other** peers on this channel.
+   *
+   * Self is excluded (own updates are not echoed back by the server).
+   */
+  peers(): AwarenessEntry<T>[] {
+    const result: AwarenessEntry<T>[] = [];
+    for (const entry of this.entries.values()) {
+      if (entry.clientId !== this.clientId) result.push(entry);
+    }
+    return result;
+  }
+
+  /**
+   * Subscribe to peer awareness changes.
+   *
+   * The listener receives the updated `peers()` array whenever a remote peer
+   * sends an update or clears their state. Returns an unsubscribe function.
+   */
+  onChange(
+    listener: (entries: AwarenessEntry<T>[]) => void,
+  ): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private emit(): void {
+    const entries = this.peers();
+    for (const fn of this.listeners) fn(entries);
+  }
+}

package/src/crdt/crdtmap.ts

@@ -57,7 +57,7 @@ export class CRDTMapHandle {
   }
 
   /** Increment a GCounter key by `amount` (default `1`). */
-  incrementCounter(key: string, amount: number = 1): void {
+  incrementCounter(key: string, amount: number = 1, ttlMs?: number): void {
     if (amount <= 0) throw new RangeError("CRDTMap.incrementCounter: amount must be > 0");
     const op = encode({
       CRDTMap: {
@@ -66,11 +66,11 @@ export class CRDTMapHandle {
         op: { GCounter: { client_id: this.clientId, amount } },
       },
     });
-    this.transport.send({ Op: { crdt_id: this.crdtId, op_bytes: op } });
+    this.transport.send({ Op: { crdt_id: this.crdtId, op_bytes: op, ...(ttlMs !== undefined && { ttl_ms: ttlMs }) } });
   }
 
   /** Increment a PNCounter key by `amount` (default `1`). */
-  incrementPNCounter(key: string, amount: number = 1): void {
+  incrementPNCounter(key: string, amount: number = 1, ttlMs?: number): void {
     if (amount <= 0) throw new RangeError("CRDTMap.incrementPNCounter: amount must be > 0");
     const op = encode({
       CRDTMap: {
@@ -79,11 +79,11 @@ export class CRDTMapHandle {
         op: { PNCounter: { Increment: { client_id: this.clientId, amount } } },
       },
     });
-    this.transport.send({ Op: { crdt_id: this.crdtId, op_bytes: op } });
+    this.transport.send({ Op: { crdt_id: this.crdtId, op_bytes: op, ...(ttlMs !== undefined && { ttl_ms: ttlMs }) } });
   }
 
   /** Decrement a PNCounter key by `amount` (default `1`). */
-  decrementPNCounter(key: string, amount: number = 1): void {
+  decrementPNCounter(key: string, amount: number = 1, ttlMs?: number): void {
     if (amount <= 0) throw new RangeError("CRDTMap.decrementPNCounter: amount must be > 0");
     const op = encode({
       CRDTMap: {
@@ -92,7 +92,7 @@ export class CRDTMapHandle {
         op: { PNCounter: { Decrement: { client_id: this.clientId, amount } } },
       },
     });
-    this.transport.send({ Op: { crdt_id: this.crdtId, op_bytes: op } });
+    this.transport.send({ Op: { crdt_id: this.crdtId, op_bytes: op, ...(ttlMs !== undefined && { ttl_ms: ttlMs }) } });
   }
 
   /** Add an element to an ORSet key. `tag` must be a 16-byte UUID as Uint8Array. */
@@ -120,7 +120,7 @@ export class CRDTMapHandle {
   }
 
   /** Write a value to an LWW-Register key. */
-  lwwSet(key: string, value: unknown): void {
+  lwwSet(key: string, value: unknown, ttlMs?: number): void {
     const wallMs = Date.now();
     const op = encode({
       CRDTMap: {
@@ -135,7 +135,7 @@ export class CRDTMapHandle {
         },
       },
     });
-    this.transport.send({ Op: { crdt_id: this.crdtId, op_bytes: op } });
+    this.transport.send({ Op: { crdt_id: this.crdtId, op_bytes: op, ...(ttlMs !== undefined && { ttl_ms: ttlMs }) } });
   }
 
   applyDelta(delta: CRDTMapDelta): void {

package/src/crdt/gcounter.ts

@@ -60,7 +60,7 @@ export class GCounterHandle {
    *
    * @throws {RangeError} If `amount` is not greater than zero.
    */
-  increment(amount: number = 1): void {
+  increment(amount: number = 1, ttlMs?: number): void {
     if (amount <= 0) throw new RangeError("GCounter: increment amount must be > 0");
 
     const key = String(this.clientId);
@@ -74,7 +74,7 @@ export class GCounterHandle {
       },
     });
     this.transport.send({
-      Op: { crdt_id: this.crdtId, op_bytes: op },
+      Op: { crdt_id: this.crdtId, op_bytes: op, ...(ttlMs !== undefined && { ttl_ms: ttlMs }) },
     });
   }
 

package/src/crdt/lwwregister.ts

@@ -65,7 +65,7 @@ export class LwwRegisterHandle<T> {
    * The write is stamped with the current wall-clock time. If a concurrent
    * write from another client has a later timestamp it will win over this one.
    */
-  set(value: T): void {
+  set(value: T, ttlMs?: number): void {
     const wallMs = Date.now();
     const hlc = { wall_ms: wallMs, logical: 0, node_id: this.clientId };
 
@@ -79,6 +79,7 @@ export class LwwRegisterHandle<T> {
       Op: {
         crdt_id: this.crdtId,
         op_bytes: encode({ LwwRegister: { value, hlc: { wall_ms: wallMs, logical: 0, node_id: this.clientId }, author: this.clientId } }),
+        ...(ttlMs !== undefined && { ttl_ms: ttlMs }),
       },
     });
   }

package/src/crdt/orset.ts

@@ -60,7 +60,7 @@ export class ORSetHandle<T> {
    * Each call generates a unique tag so concurrent adds of the same value
    * are treated as distinct entries.
    */
-  add(element: T): void {
+  add(element: T, ttlMs?: number): void {
     const tag = crypto.randomUUID();
     const key = JSON.stringify(element);
 
@@ -73,6 +73,7 @@ export class ORSetHandle<T> {
       Op: {
         crdt_id: this.crdtId,
         op_bytes: encode({ ORSet: { Add: { element, tag: uuidToBytes(tag) } } }),
+        ...(ttlMs !== undefined && { ttl_ms: ttlMs }),
       },
     });
   }
@@ -83,7 +84,7 @@ export class ORSetHandle<T> {
    * Only the tags observed locally at the time of this call are removed;
    * concurrently added copies on other clients are left intact.
    */
-  remove(element: T): void {
+  remove(element: T, ttlMs?: number): void {
     const key = JSON.stringify(element);
     const currentTags = Array.from(this.tags.get(key) ?? []);
     if (currentTags.length === 0) return;
@@ -95,6 +96,7 @@ export class ORSetHandle<T> {
       Op: {
         crdt_id: this.crdtId,
         op_bytes: encode({ ORSet: { Remove: { element, known_tags: currentTags.map(uuidToBytes) } } }),
+        ...(ttlMs !== undefined && { ttl_ms: ttlMs }),
       },
     });
   }

package/src/crdt/pncounter.ts

@@ -55,12 +55,12 @@ export class PNCounterHandle {
    *
    * @throws {RangeError} If `amount` is not greater than zero.
    */
-  increment(amount: number = 1): void {
+  increment(amount: number = 1, ttlMs?: number): void {
     if (amount <= 0) throw new RangeError("PNCounter: increment amount must be > 0");
     const key = String(this.clientId);
     this.state.p[key] = (this.state.p[key] ?? 0) + amount;
     this.emit();
-    this.sendOp({ Increment: { client_id: this.clientId, amount } });
+    this.sendOp({ Increment: { client_id: this.clientId, amount } }, ttlMs);
   }
 
   /**
@@ -68,12 +68,12 @@ export class PNCounterHandle {
    *
    * @throws {RangeError} If `amount` is not greater than zero.
    */
-  decrement(amount: number = 1): void {
+  decrement(amount: number = 1, ttlMs?: number): void {
     if (amount <= 0) throw new RangeError("PNCounter: decrement amount must be > 0");
     const key = String(this.clientId);
     this.state.n[key] = (this.state.n[key] ?? 0) + amount;
     this.emit();
-    this.sendOp({ Decrement: { client_id: this.clientId, amount } });
+    this.sendOp({ Decrement: { client_id: this.clientId, amount } }, ttlMs);
   }
 
   applyDelta(delta: PNCounterDelta): void {
@@ -89,9 +89,9 @@ export class PNCounterHandle {
     if (changed) this.emit();
   }
 
-  private sendOp(op: unknown): void {
+  private sendOp(op: unknown, ttlMs?: number): void {
     this.transport.send({
-      Op: { crdt_id: this.crdtId, op_bytes: encode({ PNCounter: op }) },
+      Op: { crdt_id: this.crdtId, op_bytes: encode({ PNCounter: op }), ...(ttlMs !== undefined && { ttl_ms: ttlMs }) },
     });
   }
 

package/src/index.ts

@@ -23,6 +23,8 @@ export { PresenceHandle } from "./crdt/presence.js";
 export type { PresenceEntry } from "./crdt/presence.js";
 export { CRDTMapHandle } from "./crdt/crdtmap.js";
 export type { CrdtMapValue } from "./crdt/crdtmap.js";
+export { AwarenessHandle } from "./crdt/awareness.js";
+export type { AwarenessEntry } from "./crdt/awareness.js";
 
 // Transport
 export { HttpClient } from "./transport/http.js";

package/src/schema.ts

@@ -43,11 +43,21 @@ export type VectorClock = typeof VectorClock.Type;
 export const ClientMsg = Schema.Union(
   Schema.Struct({ Subscribe: Schema.Struct({ crdt_id: Schema.String }) }),
   Schema.Struct({
-    Op: Schema.Struct({ crdt_id: Schema.String, op_bytes: Schema.Uint8ArrayFromSelf }),
+    Op: Schema.Struct({
+      crdt_id: Schema.String,
+      op_bytes: Schema.Uint8ArrayFromSelf,
+      ttl_ms: Schema.optional(Schema.Number),
+    }),
   }),
   Schema.Struct({
     Sync: Schema.Struct({ crdt_id: Schema.String, since_vc: Schema.Uint8ArrayFromSelf }),
   }),
+  Schema.Struct({
+    AwarenessUpdate: Schema.Struct({
+      key: Schema.String,
+      data: Schema.Uint8ArrayFromSelf,
+    }),
+  }),
 );
 export type ClientMsg = typeof ClientMsg.Type;
 
@@ -62,6 +72,13 @@ export const ServerMsg = Schema.Union(
   Schema.Struct({
     Error: Schema.Struct({ code: Schema.Number, message: Schema.String }),
   }),
+  Schema.Struct({
+    AwarenessBroadcast: Schema.Struct({
+      client_id: ClientId,
+      key: Schema.String,
+      data: Schema.Uint8ArrayFromSelf,
+    }),
+  }),
 );
 export type ServerMsg = typeof ServerMsg.Type;
 

package/src/transport/websocket.ts

@@ -57,6 +57,11 @@ export class WsTransport {
   }
 
   reopen(): void {
+    // Disown the current ws before creating a new one so its close event
+    // fires with ws !== this.ws and does not trigger scheduleReconnect.
+    const old = this.ws;
+    this.ws = null;
+    old?.close(1000, "reopen");
     this.closed = false;
     this.doConnect();
   }
@@ -209,8 +214,10 @@ export class WsTransport {
   private flushPendingOps(): void {
     const ops = this.pendingOps.splice(0);
     for (let i = 0; i < ops.length; i++) {
+      const op = ops[i];
+      if (op === undefined) continue;
       try {
-        this.ws!.send(encodeClientMsg(ops[i]!));
+        this.ws?.send(encodeClientMsg(op));
       } catch {
         // WebSocket closed between open and flush — re-queue remaining ops.
         this.pendingOps.unshift(...ops.slice(i));

package/test/crdt.test.ts

@@ -10,6 +10,7 @@ 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 { CRDTMapHandle } from "../src/crdt/crdtmap.js";
 import type { WsTransport } from "../src/transport/websocket.js";
 
 // ---------------------------------------------------------------------------
@@ -290,3 +291,73 @@ describe("PresenceHandle", () => {
     expect(counts).toEqual([1, 0]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// TTL — ttl_ms forwarded in Op message
+// ---------------------------------------------------------------------------
+
+describe("ttl_ms forwarding", () => {
+  it("GCounter.increment includes ttl_ms when provided", () => {
+    const t = stubTransport();
+    const h = new GCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    h.increment(1, 5_000);
+    expect((t.sent[0] as { Op: { ttl_ms?: number } }).Op.ttl_ms).toBe(5_000);
+  });
+
+  it("GCounter.increment omits ttl_ms when not provided", () => {
+    const t = stubTransport();
+    const h = new GCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    h.increment(1);
+    expect((t.sent[0] as { Op: { ttl_ms?: number } }).Op.ttl_ms).toBeUndefined();
+  });
+
+  it("PNCounter.increment includes ttl_ms", () => {
+    const t = stubTransport();
+    const h = new PNCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    h.increment(1, 10_000);
+    expect((t.sent[0] as { Op: { ttl_ms?: number } }).Op.ttl_ms).toBe(10_000);
+  });
+
+  it("PNCounter.decrement includes ttl_ms", () => {
+    const t = stubTransport();
+    const h = new PNCounterHandle({ ...BASE_OPTS, crdtId: "c", transport: t });
+    h.decrement(1, 10_000);
+    expect((t.sent[0] as { Op: { ttl_ms?: number } }).Op.ttl_ms).toBe(10_000);
+  });
+
+  it("ORSet.add includes ttl_ms", () => {
+    const t = stubTransport();
+    const h = new ORSetHandle({ ...BASE_OPTS, crdtId: "s", transport: t });
+    h.add("x", 3_000);
+    expect((t.sent[0] as { Op: { ttl_ms?: number } }).Op.ttl_ms).toBe(3_000);
+  });
+
+  it("ORSet.remove includes ttl_ms", () => {
+    const t = stubTransport();
+    const h = new ORSetHandle({ ...BASE_OPTS, crdtId: "s", transport: t });
+    h.add("x");
+    h.remove("x", 3_000);
+    expect((t.sent[1] as { Op: { ttl_ms?: number } }).Op.ttl_ms).toBe(3_000);
+  });
+
+  it("LwwRegister.set includes ttl_ms", () => {
+    const t = stubTransport();
+    const h = new LwwRegisterHandle({ ...BASE_OPTS, crdtId: "r", transport: t });
+    h.set("hello", 60_000);
+    expect((t.sent[0] as { Op: { ttl_ms?: number } }).Op.ttl_ms).toBe(60_000);
+  });
+
+  it("CRDTMap.lwwSet includes ttl_ms", () => {
+    const t = stubTransport();
+    const h = new CRDTMapHandle({ ...BASE_OPTS, crdtId: "m", transport: t });
+    h.lwwSet("key", "val", 7_000);
+    expect((t.sent[0] as { Op: { ttl_ms?: number } }).Op.ttl_ms).toBe(7_000);
+  });
+
+  it("CRDTMap.incrementCounter includes ttl_ms", () => {
+    const t = stubTransport();
+    const h = new CRDTMapHandle({ ...BASE_OPTS, crdtId: "m", transport: t });
+    h.incrementCounter("views", 1, 7_000);
+    expect((t.sent[0] as { Op: { ttl_ms?: number } }).Op.ttl_ms).toBe(7_000);
+  });
+});