meridian-sdk 0.2.1 → 0.2.3

package/src/codec.ts

@@ -1,57 +1,23 @@
-/**
- * Msgpack codec — wraps msgpackr with Meridian-specific conventions.
- *
- * The server uses rmp-serde with `to_vec_named` (named fields) so enum
- * variants are encoded as `{ "VariantName": { ...fields } }` maps.
- * msgpackr handles this transparently in JS land.
- */
-
-import { pack, unpack } from "msgpackr";
+import { decode as msgpackDecode, encode as msgpackEncode } from "@msgpack/msgpack";
 import { Effect, Schema } from "effect";
 import { CodecError } from "./errors.js";
 import { ServerMsg } from "./schema.js";
 import type { ClientMsg, VectorClock } from "./schema.js";
 
-// ---------------------------------------------------------------------------
-// Low-level encode / decode
-// ---------------------------------------------------------------------------
-
-/** Encode any value to msgpack bytes. */
-export function encode(value: unknown): Uint8Array<ArrayBuffer> {
-  return pack(value) as Uint8Array<ArrayBuffer>;
-}
-
-/** Decode msgpack bytes to a plain JS value (unsafe — no schema validation). */
-export function decode(bytes: Uint8Array): unknown {
-  return unpack(bytes);
-}
+export const encode = (value: unknown): Uint8Array => msgpackEncode(value);
 
-// ---------------------------------------------------------------------------
-// Typed helpers for WebSocket frames
-// ---------------------------------------------------------------------------
+export const decode = (bytes: Uint8Array): unknown => msgpackDecode(bytes);
 
-/**
- * Encode a ClientMsg to a binary WebSocket frame.
- * The msgpack encoding matches rmp-serde's "named" enum format:
- *   `{ Subscribe: { crdt_id: "foo" } }` → msgpack map with one key.
- */
-export function encodeClientMsg(msg: ClientMsg): Uint8Array {
-  return encode(msg);
-}
+export const encodeClientMsg = (msg: ClientMsg): Uint8Array => encode(msg);
 
-/**
- * Decode a binary WebSocket frame into a ServerMsg.
- * Returns Effect<ServerMsg, CodecError>.
- */
-export function decodeServerMsg(bytes: Uint8Array): Effect.Effect<ServerMsg, CodecError> {
+export const decodeServerMsg = (bytes: Uint8Array): Effect.Effect<ServerMsg, CodecError> => {
   let raw: unknown;
   try {
-    raw = unpack(bytes);
+    raw = decode(bytes);
   } catch {
     return Effect.fail(new CodecError({ message: "msgpack decode failed", raw: bytes }));
   }
 
-  // Schema.decodeUnknown accepts `unknown` input — correct for runtime decode boundaries
   return Schema.decodeUnknown(ServerMsg)(raw).pipe(
     Effect.mapError((parseError) =>
       new CodecError({
@@ -60,47 +26,23 @@ export function decodeServerMsg(bytes: Uint8Array): Effect.Effect<ServerMsg, Cod
       }),
     ),
   );
-}
+};
 
-// ---------------------------------------------------------------------------
-// Wire type helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Convert a UUID string ("xxxxxxxx-xxxx-...") to a 16-byte Uint8Array.
- * Rust's `uuid::Uuid` is serialized by rmp-serde as raw bytes (bin type).
- */
-export function uuidToBytes(uuid: string): Uint8Array {
+export const uuidToBytes = (uuid: string): Uint8Array => {
   const hex = uuid.replace(/-/g, "");
   const bytes = new Uint8Array(16);
   for (let i = 0; i < 16; i++) {
     bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
   }
   return bytes;
-}
-
-/**
- * Encode a wall-clock timestamp (ms) as BigInt for msgpack u64 encoding.
- * msgpackr encodes JS `number` as float64 for large values; Rust u64 fields
- * require an integer encoding — BigInt forces msgpackr to use uint64.
- */
-export function wallMsToBigInt(ms: number): bigint {
-  return BigInt(ms);
-}
-
-// ---------------------------------------------------------------------------
-// VectorClock <-> msgpack bytes
-// ---------------------------------------------------------------------------
+};
 
-export function encodeVectorClock(vc: VectorClock): Uint8Array {
-  // Server expects { entries: { "client_id": version, ... } }
-  return encode({ entries: vc });
-}
+export const encodeVectorClock = (vc: VectorClock): Uint8Array => encode({ entries: vc });
 
-export function decodeVectorClock(bytes: Uint8Array): Effect.Effect<VectorClock, CodecError> {
+export const decodeVectorClock = (bytes: Uint8Array): Effect.Effect<VectorClock, CodecError> => {
   let raw: unknown;
   try {
-    raw = unpack(bytes);
+    raw = decode(bytes);
   } catch {
     return Effect.fail(new CodecError({ message: "VectorClock msgpack decode failed", raw: bytes }));
   }
@@ -115,4 +57,4 @@ export function decodeVectorClock(bytes: Uint8Array): Effect.Effect<VectorClock,
       new CodecError({ message: `VectorClock schema validation failed: ${e.message}`, raw: bytes }),
     ),
   );
-}
+};

package/src/constants.ts

@@ -0,0 +1,6 @@
+export const BACKOFF_INITIAL_MS = 100;
+export const BACKOFF_MAX_MS = 30_000;
+export const BACKOFF_MULTIPLIER = 2;
+export const JITTER_MULTIPLIER = 0.2;
+export const DEFAULT_TIMEOUT_MS = 5_000;
+export const TOKEN_SKEW_MS = 5_000;

package/src/crdt/gcounter.ts

@@ -1,10 +1,3 @@
-/**
- * GCounter handle — increment-only counter.
- *
- * Local state is kept as a sparse map `{ client_id → count }`.
- * `value()` returns the sum. Deltas are merged on incoming ServerMsg.Delta.
- */
-
 import { encode } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { GCounterDelta } from "../sync/delta.js";
@@ -13,6 +6,12 @@ export interface GCounterState {
   counts: Record<string, number>;
 }
 
+/**
+ * Low-level handle for a grow-only counter (GCounter) CRDT.
+ *
+ * Obtained via `MeridianClient.gcounter()`. Prefer the `useGCounter` React hook
+ * for component-level usage; use this handle directly in non-React environments.
+ */
 export class GCounterHandle {
   private state: GCounterState;
   private readonly clientId: number;
@@ -20,7 +19,6 @@ export class GCounterHandle {
   private readonly ns: string;
   private readonly transport: WsTransport;
 
-  /** Emits on every state change. */
   private readonly listeners = new Set<(value: number) => void>();
 
   constructor(opts: {
@@ -37,34 +35,38 @@ export class GCounterHandle {
     this.state = opts.initial ?? { counts: {} };
   }
 
-  // ---- Read ----
-
+  /** Returns the current counter value (sum of all client contributions). */
   value(): number {
     return Object.values(this.state.counts).reduce((a, b) => a + b, 0);
   }
 
+  /** Returns the raw per-client contribution map, keyed by client id string. */
   counts(): Readonly<Record<string, number>> {
     return this.state.counts;
   }
 
-  /** Subscribe to value changes. Returns an unsubscribe function. */
+  /**
+   * Registers a listener that is called whenever the counter value changes.
+   *
+   * @returns An unsubscribe function — call it to stop receiving updates.
+   */
   onChange(listener: (value: number) => void): () => void {
     this.listeners.add(listener);
     return () => { this.listeners.delete(listener); };
   }
 
-  // ---- Write ----
-
-  /** Increment by `amount` (must be > 0). */
+  /**
+   * Increments the counter by `amount` (default `1`) and broadcasts the delta.
+   *
+   * @throws {RangeError} If `amount` is not greater than zero.
+   */
   increment(amount: number = 1): void {
     if (amount <= 0) throw new RangeError("GCounter: increment amount must be > 0");
 
-    // Optimistic local update
     const key = String(this.clientId);
     this.state.counts[key] = (this.state.counts[key] ?? 0) + amount;
     this.emit();
 
-    // Send Op to server
     const op = encode({
       GCounter: {
         client_id: this.clientId,
@@ -76,8 +78,6 @@ export class GCounterHandle {
     });
   }
 
-  // ---- Delta application (called by MeridianClient on incoming Delta) ----
-
   applyDelta(delta: GCounterDelta): void {
     let changed = false;
     for (const [id, count] of Object.entries(delta.counters)) {
@@ -90,8 +90,6 @@ export class GCounterHandle {
     if (changed) this.emit();
   }
 
-  // ---- Internal ----
-
   private emit(): void {
     const v = this.value();
     for (const listener of this.listeners) {

package/src/crdt/lwwregister.ts

@@ -1,19 +1,14 @@
-/**
- * LWW Register handle — Last-Write-Wins single-value cell.
- *
- * The winning write is determined by HLC (highest wall_ms wins),
- * tie-broken by author (higher client_id wins). The client sends its
- * local wall clock as HLC wall_ms; the server enforces ±30s drift limit.
- *
- * Pass a `schema` to get runtime validation of incoming deltas:
- *   client.lwwregister("id", Schema.Struct({ x: Schema.Number }))
- */
-
 import { Schema } from "effect";
-import { encode, wallMsToBigInt } from "../codec.js";
+import { encode } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { LwwDelta, LwwEntry } from "../sync/delta.js";
 
+/**
+ * Low-level handle for a Last-Write-Wins register (LWW-Register) CRDT.
+ *
+ * Obtained via `MeridianClient.lwwregister()`. Prefer the `useLwwRegister` React
+ * hook for component-level usage; use this handle directly in non-React environments.
+ */
 export class LwwRegisterHandle<T> {
   private entry: LwwEntry | null = null;
   private readonly crdtId: string;
@@ -37,26 +32,39 @@ export class LwwRegisterHandle<T> {
     this.entry = opts.initial ?? null;
   }
 
-  // ---- Read ----
-
+  /** Returns the current register value, or `null` if no value has been written yet. */
   value(): T | null {
     if (this.entry === null) return null;
     return this.decode(this.entry.value);
   }
 
-  /** Metadata: when was the last write and by whom. */
+  /**
+   * Returns metadata about the winning entry, or `null` if the register is empty.
+   *
+   * `updatedAtMs` is the wall-clock timestamp of the write; `author` is the
+   * numeric client id of the writer.
+   */
   meta(): { updatedAtMs: number; author: number } | null {
     if (this.entry === null) return null;
     return { updatedAtMs: Number(this.entry.hlc.wall_ms), author: Number(this.entry.author) };
   }
 
+  /**
+   * Registers a listener that is called whenever the register value changes.
+   *
+   * @returns An unsubscribe function — call it to stop receiving updates.
+   */
   onChange(listener: (value: T | null) => void): () => void {
     this.listeners.add(listener);
     return () => { this.listeners.delete(listener); };
   }
 
-  // ---- Write ----
-
+  /**
+   * Writes `value` to the register and broadcasts the operation.
+   *
+   * 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 {
     const wallMs = Date.now();
     const hlc = { wall_ms: wallMs, logical: 0, node_id: this.clientId };
@@ -67,19 +75,14 @@ export class LwwRegisterHandle<T> {
       this.emit();
     }
 
-    // wall_ms must be BigInt — msgpackr encodes large JS numbers as float64,
-    // but Rust expects u64 integer encoding
-    const wireHlc = { wall_ms: wallMsToBigInt(wallMs), logical: 0, node_id: this.clientId };
     this.transport.send({
       Op: {
         crdt_id: this.crdtId,
-        op_bytes: encode({ LwwRegister: { value, hlc: wireHlc, author: this.clientId } }),
+        op_bytes: encode({ LwwRegister: { value, hlc: { wall_ms: wallMs, logical: 0, node_id: this.clientId }, author: this.clientId } }),
       },
     });
   }
 
-  // ---- Delta application ----
-
   applyDelta(delta: LwwDelta): void {
     if (delta.entry === null) return;
     if (this.entryWins(delta.entry, this.entry)) {
@@ -88,13 +91,11 @@ export class LwwRegisterHandle<T> {
     }
   }
 
-  // ---- Internal ----
-
   private decode(raw: unknown): T {
     if (this.schema !== null) {
       return Schema.decodeUnknownSync(this.schema)(raw);
     }
-    // No schema provided — T defaults to unknown, cast is the caller's responsibility
+    // HACK: No schema provided — T defaults to unknown, cast is the caller's responsibility.
     return raw as T;
   }
 

package/src/crdt/orset.ts

@@ -1,22 +1,16 @@
-/**
- * ORSet handle — add-wins observed-remove set.
- *
- * Each element has a set of add-tags (UUIDs). Remove only removes tags
- * known at remove time — a concurrent add with a new tag survives.
- *
- * Elements are serialized as JSON for the wire (serde_json::Value).
- *
- * Pass a `schema` to get runtime validation of elements deserialized from deltas:
- *   client.orset("id", Schema.Struct({ id: Schema.String }))
- */
-
 import { Schema } from "effect";
 import { encode, uuidToBytes } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { ORSetDelta } from "../sync/delta.js";
+import { toHex } from "../utils/to-hex.js";
 
+/**
+ * Low-level handle for an Observed-Remove Set (OR-Set) CRDT.
+ *
+ * Obtained via `MeridianClient.orset()`. Prefer the `useORSet` React hook for
+ * component-level usage; use this handle directly in non-React environments.
+ */
 export class ORSetHandle<T> {
-  /** element (JSON-stringified) → Set of live add-tags */
   private readonly tags = new Map<string, Set<string>>();
   private readonly crdtId: string;
   private readonly clientId: number;
@@ -37,36 +31,44 @@ export class ORSetHandle<T> {
     this.schema = opts.schema ?? null;
   }
 
-  // ---- Read ----
-
-  /** Returns all live elements (add-wins). */
+  /** Returns the current set elements as an array, decoded via the optional schema. */
   elements(): T[] {
     return Array.from(this.tags.keys())
       .filter(k => (this.tags.get(k)?.size ?? 0) > 0)
       .map(k => this.decode(JSON.parse(k)));
   }
 
+  /** Returns `true` if the set currently contains `element`. */
   has(element: T): boolean {
     const key = JSON.stringify(element);
     return (this.tags.get(key)?.size ?? 0) > 0;
   }
 
+  /**
+   * Registers a listener that is called whenever the set contents change.
+   *
+   * @returns An unsubscribe function — call it to stop receiving updates.
+   */
   onChange(listener: (elements: T[]) => void): () => void {
     this.listeners.add(listener);
     return () => { this.listeners.delete(listener); };
   }
 
-  // ---- Write ----
-
+  /**
+   * Adds `element` to the set and broadcasts the operation.
+   *
+   * Each call generates a unique tag so concurrent adds of the same value
+   * are treated as distinct entries.
+   */
   add(element: T): void {
     const tag = crypto.randomUUID();
     const key = JSON.stringify(element);
 
     if (!this.tags.has(key)) this.tags.set(key, new Set());
-    this.tags.get(key)!.add(tag);
+    const tagSet = this.tags.get(key) as Set<string>;
+    tagSet.add(tag);
     this.emit();
 
-    // Rust Uuid is serialized as 16-byte bin — encode tag as bytes
     this.transport.send({
       Op: {
         crdt_id: this.crdtId,
@@ -75,6 +77,12 @@ export class ORSetHandle<T> {
     });
   }
 
+  /**
+   * Removes `element` from the set and broadcasts the operation.
+   *
+   * 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 {
     const key = JSON.stringify(element);
     const currentTags = Array.from(this.tags.get(key) ?? []);
@@ -83,7 +91,6 @@ export class ORSetHandle<T> {
     this.tags.delete(key);
     this.emit();
 
-    // Rust expects known_tags as a set of 16-byte UUIDs
     this.transport.send({
       Op: {
         crdt_id: this.crdtId,
@@ -92,16 +99,14 @@ export class ORSetHandle<T> {
     });
   }
 
-  // ---- Delta application ----
-
   applyDelta(delta: ORSetDelta): void {
     let changed = false;
 
     for (const [elem, addedTags] of Object.entries(delta.adds)) {
       if (!this.tags.has(elem)) this.tags.set(elem, new Set());
-      const set = this.tags.get(elem)!;
+      const set = this.tags.get(elem) as Set<string>;
       for (const tag of addedTags) {
-        const tagStr = Array.from(tag).map(b => b.toString(16).padStart(2, "0")).join("");
+        const tagStr = Array.from(tag).map(toHex).join("");
         if (!set.has(tagStr)) { set.add(tagStr); changed = true; }
       }
     }
@@ -110,7 +115,7 @@ export class ORSetHandle<T> {
       const set = this.tags.get(elem);
       if (!set) continue;
       for (const tag of removedTags) {
-        const tagStr = Array.from(tag).map(b => b.toString(16).padStart(2, "0")).join("");
+        const tagStr = Array.from(tag).map(toHex).join("");
         if (set.has(tagStr)) { set.delete(tagStr); changed = true; }
       }
       if (set.size === 0) this.tags.delete(elem);
@@ -119,8 +124,6 @@ export class ORSetHandle<T> {
     if (changed) this.emit();
   }
 
-  // ---- Internal ----
-
   private decode(raw: unknown): T {
     if (this.schema !== null) {
       return Schema.decodeUnknownSync(this.schema)(raw);
@@ -130,6 +133,6 @@ export class ORSetHandle<T> {
 
   private emit(): void {
     const elems = this.elements();
-    for (const l of this.listeners) l(elems);
+    for (const listener of this.listeners) listener(elems);
   }
 }

package/src/crdt/pncounter.ts

@@ -1,17 +1,18 @@
-/**
- * PNCounter handle — increment and decrement counter.
- * value = sum(increments) - sum(decrements). Can be negative.
- */
-
 import { encode } from "../codec.js";
 import type { WsTransport } from "../transport/websocket.js";
 import type { PNCounterDelta } from "../sync/delta.js";
 
 export interface PNCounterState {
-  p: Record<string, number>; // positive GCounter
-  n: Record<string, number>; // negative GCounter
+  p: Record<string, number>;
+  n: Record<string, number>;
 }
 
+/**
+ * Low-level handle for a positive-negative counter (PNCounter) CRDT.
+ *
+ * Obtained via `MeridianClient.pncounter()`. Prefer the `usePNCounter` React hook
+ * for component-level usage; use this handle directly in non-React environments.
+ */
 export class PNCounterHandle {
   private state: PNCounterState;
   private readonly clientId: number;
@@ -32,21 +33,28 @@ export class PNCounterHandle {
     this.state = opts.initial ?? { p: {}, n: {} };
   }
 
-  // ---- Read ----
-
+  /** Returns the current net counter value (sum of increments minus sum of decrements). */
   value(): number {
     const pos = Object.values(this.state.p).reduce((a, b) => a + b, 0);
     const neg = Object.values(this.state.n).reduce((a, b) => a + b, 0);
     return pos - neg;
   }
 
+  /**
+   * Registers a listener that is called whenever the counter value changes.
+   *
+   * @returns An unsubscribe function — call it to stop receiving updates.
+   */
   onChange(listener: (value: number) => void): () => void {
     this.listeners.add(listener);
     return () => { this.listeners.delete(listener); };
   }
 
-  // ---- Write ----
-
+  /**
+   * Increments the counter by `amount` (default `1`) and broadcasts the delta.
+   *
+   * @throws {RangeError} If `amount` is not greater than zero.
+   */
   increment(amount: number = 1): void {
     if (amount <= 0) throw new RangeError("PNCounter: increment amount must be > 0");
     const key = String(this.clientId);
@@ -55,6 +63,11 @@ export class PNCounterHandle {
     this.sendOp({ Increment: { client_id: this.clientId, amount } });
   }
 
+  /**
+   * Decrements the counter by `amount` (default `1`) and broadcasts the delta.
+   *
+   * @throws {RangeError} If `amount` is not greater than zero.
+   */
   decrement(amount: number = 1): void {
     if (amount <= 0) throw new RangeError("PNCounter: decrement amount must be > 0");
     const key = String(this.clientId);
@@ -63,23 +76,19 @@ export class PNCounterHandle {
     this.sendOp({ Decrement: { client_id: this.clientId, amount } });
   }
 
-  // ---- Delta application ----
-
   applyDelta(delta: PNCounterDelta): void {
     let changed = false;
     for (const [id, count] of Object.entries(delta.pos?.counters ?? {})) {
-      const cur = this.state.p[id] ?? 0;
-      if (count > cur) { this.state.p[id] = count; changed = true; }
+      const currentCount = this.state.p[id] ?? 0;
+      if (count > currentCount) { this.state.p[id] = count; changed = true; }
     }
     for (const [id, count] of Object.entries(delta.neg?.counters ?? {})) {
-      const cur = this.state.n[id] ?? 0;
-      if (count > cur) { this.state.n[id] = count; changed = true; }
+      const currentCount = this.state.n[id] ?? 0;
+      if (count > currentCount) { this.state.n[id] = count; changed = true; }
     }
     if (changed) this.emit();
   }
 
-  // ---- Internal ----
-
   private sendOp(op: unknown): void {
     this.transport.send({
       Op: { crdt_id: this.crdtId, op_bytes: encode({ PNCounter: op }) },
@@ -87,7 +96,7 @@ export class PNCounterHandle {
   }
 
   private emit(): void {
-    const v = this.value();
-    for (const l of this.listeners) l(v);
+    const currentValue = this.value();
+    for (const listener of this.listeners) listener(currentValue);
   }
 }