meridian-sdk 0.2.0 → 0.2.2

package/src/crdt/presence.ts

@@ -1,16 +1,5 @@
-/**
- * Presence handle — TTL-aware presence tracking.
- *
- * `heartbeat(data, ttlMs)` upserts the local client's entry.
- * `leave()` creates an explicit tombstone (ttl = 0).
- * Background GC on the server prunes expired entries every 5s.
- *
- * Pass a `schema` to get runtime validation of incoming delta data:
- *   client.presence("id", Schema.Struct({ cursor: Schema.Tuple(Schema.Number, 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 { PresenceDelta, PresenceEntryDelta } from "../sync/delta.js";
 
@@ -20,6 +9,13 @@ export interface PresenceEntry<T> {
   expiresAtMs: number;
 }
 
+/**
+ * Low-level handle for a presence channel CRDT.
+ *
+ * Obtained via `MeridianClient.presence()`. Prefer the `usePresence` React hook
+ * for component-level usage (it manages heartbeat timers and cleanup automatically);
+ * use this handle directly in non-React environments.
+ */
 export class PresenceHandle<T> {
   private readonly entries = new Map<string, PresenceEntry<T>>();
   private readonly crdtId: string;
@@ -41,9 +37,10 @@ export class PresenceHandle<T> {
     this.schema = opts.schema ?? null;
   }
 
-  // ---- Read ----
-
-  /** Returns all live entries (expired entries are filtered out). */
+  /**
+   * Returns all currently online entries — those whose TTL has not yet elapsed
+   * as of the call time.
+   */
   online(): PresenceEntry<T>[] {
     const now = Date.now();
     const live: PresenceEntry<T>[] = [];
@@ -53,17 +50,30 @@ export class PresenceHandle<T> {
     return live;
   }
 
+  /**
+   * Registers a listener that is called whenever the online entries change.
+   *
+   * @returns An unsubscribe function — call it to stop receiving updates.
+   */
   onChange(listener: (entries: PresenceEntry<T>[]) => void): () => void {
     this.listeners.add(listener);
     return () => { this.listeners.delete(listener); };
   }
 
-  // ---- Write ----
-
-  /** Send a presence heartbeat. Call every `ttlMs / 2` to stay alive. Default ttl: 30s. */
+  /**
+   * Broadcasts a heartbeat that marks the current client as online for `ttlMs`
+   * milliseconds (default `30 000`).
+   *
+   * Call this periodically (at least once per `ttlMs`) to remain visible to
+   * other clients. The `usePresence` hook manages this automatically when
+   * `opts.data` is provided.
+   *
+   * @param data - Arbitrary payload broadcast to other clients.
+   * @param ttlMs - Time-to-live in milliseconds before the entry is considered stale.
+   */
   heartbeat(data: T, ttlMs: number = 30_000): void {
     const wallMs = Date.now();
-    const hlc = { wall_ms: wallMsToBigInt(wallMs), logical: 0, node_id: this.clientId };
+    const hlc = { wall_ms: wallMs, logical: 0, node_id: this.clientId };
 
     this.entries.set(String(this.clientId), {
       clientId: this.clientId,
@@ -82,10 +92,15 @@ export class PresenceHandle<T> {
     });
   }
 
-  /** Explicitly leave — entry expires immediately for all peers. */
+  /**
+   * Marks the current client as offline and broadcasts a leave operation.
+   *
+   * After calling this, the client's entry is removed from the `online()` list
+   * on all peers. The `usePresence` hook calls this automatically on unmount.
+   */
   leave(): void {
     const wallMs = Date.now();
-    const hlc = { wall_ms: wallMsToBigInt(wallMs), logical: 0, node_id: this.clientId };
+    const hlc = { wall_ms: wallMs, logical: 0, node_id: this.clientId };
 
     this.entries.delete(String(this.clientId));
     this.emit();
@@ -98,8 +113,6 @@ export class PresenceHandle<T> {
     });
   }
 
-  // ---- Delta application ----
-
   applyDelta(delta: PresenceDelta): void {
     let changed = false;
     for (const [clientIdStr, entry] of Object.entries(delta.changes)) {
@@ -115,8 +128,6 @@ export class PresenceHandle<T> {
     if (changed) this.emit();
   }
 
-  // ---- Internal ----
-
   private decode(raw: unknown): T {
     if (this.schema !== null) {
       return Schema.decodeUnknownSync(this.schema)(raw);
@@ -157,6 +168,6 @@ export class PresenceHandle<T> {
 
   private emit(): void {
     const live = this.online();
-    for (const l of this.listeners) l(live);
+    for (const listener of this.listeners) listener(live);
   }
 }

package/src/errors.ts

@@ -1,24 +1,11 @@
-/**
- * Typed errors for the Meridian SDK — all extend Data.TaggedError so they
- * can be matched with Effect.catchTag / Effect.catchAll.
- */
-
 import { Data } from "effect";
 import type { ErrorResponse } from "./schema.js";
 
-// ---------------------------------------------------------------------------
-// Codec
-// ---------------------------------------------------------------------------
-
 export class CodecError extends Data.TaggedError("CodecError")<{
   readonly message: string;
   readonly raw: Uint8Array;
 }> {}
 
-// ---------------------------------------------------------------------------
-// Auth / Token
-// ---------------------------------------------------------------------------
-
 export class TokenParseError extends Data.TaggedError("TokenParseError")<{
   readonly message: string;
 }> {}
@@ -27,10 +14,6 @@ export class TokenExpiredError extends Data.TaggedError("TokenExpiredError")<{
   readonly expiredAt: number;
 }> {}
 
-// ---------------------------------------------------------------------------
-// HTTP
-// ---------------------------------------------------------------------------
-
 export class HttpError extends Data.TaggedError("HttpError")<{
   readonly status: number;
   readonly body: ErrorResponse;
@@ -41,10 +24,6 @@ export class NetworkError extends Data.TaggedError("NetworkError")<{
   readonly cause?: unknown;
 }> {}
 
-// ---------------------------------------------------------------------------
-// WebSocket / Transport
-// ---------------------------------------------------------------------------
-
 export class TransportError extends Data.TaggedError("TransportError")<{
   readonly message: string;
   readonly cause?: unknown;

package/src/schema.ts

@@ -7,34 +7,20 @@
 
 import { Schema } from "effect";
 
-// ---------------------------------------------------------------------------
-// Shared primitives
-// ---------------------------------------------------------------------------
-
-/**
- * Unix timestamp in milliseconds.
- * msgpackr decodes Rust u64 as BigInt — accept both for compatibility.
- */
+/** Unix timestamp in milliseconds. Rust u64 decodes as bigint when > Number.MAX_SAFE_INTEGER — normalise to number. */
 export const TimestampMs = Schema.Union(Schema.Number, Schema.BigIntFromSelf.pipe(Schema.transform(
   Schema.Number,
   { decode: (n) => Number(n), encode: (n) => BigInt(n) },
 )));
 export type TimestampMs = number;
 
-/**
- * client_id / author — Rust u64, decoded by msgpackr as BigInt or number.
- * Accept both and normalise to number.
- */
+/** client_id / author — Rust u64, may decode as bigint for large values. Normalise to number. */
 export const ClientId = Schema.Union(Schema.Number, Schema.BigIntFromSelf.pipe(Schema.transform(
   Schema.Number,
   { decode: (n) => Number(n), encode: (n) => BigInt(n) },
 )));
 export type ClientId = number;
 
-// ---------------------------------------------------------------------------
-// Auth / Token claims
-// ---------------------------------------------------------------------------
-
 export const Permissions = Schema.Struct({
   read: Schema.Array(Schema.String),
   write: Schema.Array(Schema.String),
@@ -50,18 +36,10 @@ export const TokenClaims = Schema.Struct({
 });
 export type TokenClaims = typeof TokenClaims.Type;
 
-// ---------------------------------------------------------------------------
-// Vector clock
-// ---------------------------------------------------------------------------
-
 /** BTreeMap<client_id, version> — matches server VectorClock.entries */
 export const VectorClock = Schema.Record({ key: Schema.String, value: Schema.Number });
 export type VectorClock = typeof VectorClock.Type;
 
-// ---------------------------------------------------------------------------
-// Client → Server WebSocket messages
-// ---------------------------------------------------------------------------
-
 export const ClientMsg = Schema.Union(
   Schema.Struct({ Subscribe: Schema.Struct({ crdt_id: Schema.String }) }),
   Schema.Struct({
@@ -73,22 +51,11 @@ export const ClientMsg = Schema.Union(
 );
 export type ClientMsg = typeof ClientMsg.Type;
 
-// ---------------------------------------------------------------------------
-// Server → Client WebSocket messages
-// ---------------------------------------------------------------------------
-
 export const ServerMsg = Schema.Union(
   Schema.Struct({
     Delta: Schema.Struct({
       crdt_id: Schema.String,
-      // msgpackr may decode bin as Uint8Array or number[] depending on context — normalise to Uint8Array
-      delta_bytes: Schema.Union(
-        Schema.Uint8ArrayFromSelf,
-        Schema.Array(Schema.Number).pipe(Schema.transform(Schema.Uint8ArrayFromSelf, {
-          decode: (arr) => new Uint8Array(arr),
-          encode: (u8) => Array.from(u8),
-        })),
-      ),
+      delta_bytes: Schema.Uint8ArrayFromSelf,
     }),
   }),
   Schema.Struct({ Ack: Schema.Struct({ seq: Schema.Number }) }),
@@ -98,10 +65,6 @@ export const ServerMsg = Schema.Union(
 );
 export type ServerMsg = typeof ServerMsg.Type;
 
-// ---------------------------------------------------------------------------
-// CRDT value types (returned by GET /v1/namespaces/:ns/crdts/:id)
-// ---------------------------------------------------------------------------
-
 export const GCounterValue = Schema.Struct({
   value: Schema.Number,
   counts: Schema.Record({ key: Schema.String, value: Schema.Number }),
@@ -136,10 +99,6 @@ export const PresenceValue = Schema.Struct({
 });
 export type PresenceValue = typeof PresenceValue.Type;
 
-// ---------------------------------------------------------------------------
-// HTTP response envelopes
-// ---------------------------------------------------------------------------
-
 /** GET /v1/namespaces/:ns/crdts/:id — server returns the raw JSON value directly. */
 export const CrdtGetResponse = Schema.Unknown;
 export type CrdtGetResponse = unknown;

package/src/sync/clock.ts

@@ -1,25 +1,10 @@
-/**
- * Client-side VectorClock.
- *
- * Tracks the latest version seen per client_id. Used to request
- * delta-since on reconnect (Sync message).
- *
- * Persisted to localStorage (browser) or a JSON file (Node/Bun) via
- * the optional `ClockStorage` adapter injected at construction.
- */
-
 import type { VectorClock } from "../schema.js";
 
-// ---------------------------------------------------------------------------
-// ClockStorage adapter
-// ---------------------------------------------------------------------------
-
 export interface ClockStorage {
   load(key: string): VectorClock | null;
   save(key: string, vc: VectorClock): void;
 }
 
-/** In-memory only — useful for tests and SSR. */
 export const memoryStorage: ClockStorage = (() => {
   const store = new Map<string, VectorClock>();
   return {
@@ -28,39 +13,26 @@ export const memoryStorage: ClockStorage = (() => {
   };
 })();
 
-/** localStorage-backed storage (browser). Falls back to memory if unavailable. */
-export function localStorageAdapter(prefix = "meridian:"): ClockStorage {
-  return {
-    load(key) {
-      try {
-        const raw = localStorage.getItem(`${prefix}${key}`);
-        if (raw === null) return null;
-        return JSON.parse(raw) as VectorClock;
-      } catch {
-        return null;
-      }
-    },
-    save(key, vc) {
-      try {
-        localStorage.setItem(`${prefix}${key}`, JSON.stringify(vc));
-      } catch {
-        // quota exceeded — ignore
-      }
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// VectorClockTracker
-// ---------------------------------------------------------------------------
+export const localStorageAdapter = (prefix = "meridian:"): ClockStorage => ({
+  load(key) {
+    try {
+      const raw = localStorage.getItem(`${prefix}${key}`);
+      if (raw === null) return null;
+      return JSON.parse(raw) as VectorClock;
+    } catch {
+      return null;
+    }
+  },
+  save(key, vc) {
+    try {
+      localStorage.setItem(`${prefix}${key}`, JSON.stringify(vc));
+    } catch {
+    }
+  },
+});
 
-/**
- * Mutable wrapper around VectorClock that tracks seen versions and
- * optionally persists them across page reloads.
- */
 export class VectorClockTracker {
-  // Mutable internal copy — VectorClock (Schema type) is readonly, so we
-  // keep a plain mutable Record internally and expose snapshots.
+  // HACK: VectorClock (Schema type) is readonly, so we keep a plain mutable Record internally and expose snapshots.
   private readonly clock: Record<string, number>;
   private readonly storage: ClockStorage | null;
   private readonly storageKey: string;
@@ -78,7 +50,6 @@ export class VectorClockTracker {
     this.clock = { ...(opts.initial ?? {}), ...(persisted ?? {}) };
   }
 
-  /** Observe a version from a peer. Updates clock if newer. */
   observe(clientId: string, version: number): void {
     const current = this.clock[clientId] ?? 0;
     if (version > current) {
@@ -87,7 +58,6 @@ export class VectorClockTracker {
     }
   }
 
-  /** Merge an entire remote VectorClock (take max per entry). */
   merge(remote: VectorClock): void {
     let changed = false;
     for (const [id, ver] of Object.entries(remote)) {
@@ -102,12 +72,10 @@ export class VectorClockTracker {
     }
   }
 
-  /** Returns an immutable snapshot suitable for the Sync message. */
   snapshot(): VectorClock {
     return { ...this.clock };
   }
 
-  /** Reset to empty (e.g. when the namespace is cleared). */
   reset(): void {
     for (const key of Object.keys(this.clock)) {
       delete this.clock[key];

package/src/sync/delta.ts

@@ -1,40 +1,21 @@
-/**
- * Delta application helpers.
- *
- * The server sends deltas as opaque msgpack bytes inside `ServerMsg.Delta`.
- * Each CRDT type decodes its own delta format matching Rust serde output.
- *
- * Field names mirror the Rust structs exactly (rmp-serde named encoding).
- */
+import { decode } from "@msgpack/msgpack";
 
-import { unpack } from "msgpackr";
-
-// ---------------------------------------------------------------------------
-// GCounter delta
-// ---------------------------------------------------------------------------
-
-/** GCounterDelta { counters: BTreeMap<u64, u64> } */
 export interface GCounterDelta {
   counters: Record<string, number>;
 }
 
-export function decodeGCounterDelta(bytes: Uint8Array): GCounterDelta {
-  const raw = unpack(bytes) as { counters?: Record<string, number> };
+export const decodeGCounterDelta = (bytes: Uint8Array): GCounterDelta => {
+  const raw = decode(bytes) as { counters?: Record<string, number> };
   return { counters: raw.counters ?? {} };
-}
+};
 
-// ---------------------------------------------------------------------------
-// PNCounter delta
-// ---------------------------------------------------------------------------
-
-/** PNCounterDelta { pos: Option<GCounterDelta>, neg: Option<GCounterDelta> } */
 export interface PNCounterDelta {
   pos: GCounterDelta | null;
   neg: GCounterDelta | null;
 }
 
-export function decodePNCounterDelta(bytes: Uint8Array): PNCounterDelta {
-  const raw = unpack(bytes) as {
+export const decodePNCounterDelta = (bytes: Uint8Array): PNCounterDelta => {
+  const raw = decode(bytes) as {
     pos?: { counters?: Record<string, number> } | null;
     neg?: { counters?: Record<string, number> } | null;
   };
@@ -42,57 +23,39 @@ export function decodePNCounterDelta(bytes: Uint8Array): PNCounterDelta {
     pos: raw.pos ? { counters: raw.pos.counters ?? {} } : null,
     neg: raw.neg ? { counters: raw.neg.counters ?? {} } : null,
   };
-}
-
-// ---------------------------------------------------------------------------
-// ORSet delta
-// ---------------------------------------------------------------------------
+};
 
-/**
- * ORSetDelta { adds: HashMap<String, HashSet<Uuid>>, removes: HashMap<String, HashSet<Uuid>> }
- * Uuid bytes are decoded by msgpackr as Uint8Array or number[].
- */
 export interface ORSetDelta {
   adds: Record<string, Uint8Array[]>;
   removes: Record<string, Uint8Array[]>;
 }
 
-export function decodeORSetDelta(bytes: Uint8Array): ORSetDelta {
-  const raw = unpack(bytes) as {
+export const decodeORSetDelta = (bytes: Uint8Array): ORSetDelta => {
+  const raw = decode(bytes) as {
     adds?: Record<string, unknown[]>;
     removes?: Record<string, unknown[]>;
   };
-  const toBytes = (v: unknown): Uint8Array =>
-    v instanceof Uint8Array ? v : new Uint8Array(v as number[]);
-  const decodeMap = (m?: Record<string, unknown[]>) =>
-    Object.fromEntries(Object.entries(m ?? {}).map(([k, tags]) => [k, tags.map(toBytes)]));
+  const toBytes = (value: unknown): Uint8Array =>
+    value instanceof Uint8Array ? value : new Uint8Array(value as number[]);
+  const decodeMap = (map?: Record<string, unknown[]>) =>
+    Object.fromEntries(Object.entries(map ?? {}).map(([key, tags]) => [key, tags.map(toBytes)]));
   return { adds: decodeMap(raw.adds), removes: decodeMap(raw.removes) };
-}
-
-// ---------------------------------------------------------------------------
-// LWW Register delta
-// ---------------------------------------------------------------------------
+};
 
-/** LwwEntry { value, hlc: HybridLogicalClock, author: u64 } */
 export interface LwwEntry {
   value: unknown;
   hlc: { wall_ms: number | bigint; logical: number; node_id: number | bigint };
   author: number | bigint;
 }
 
-/** LwwDelta { entry: Option<LwwEntry> } */
 export interface LwwDelta {
   entry: LwwEntry | null;
 }
 
-export function decodeLwwDelta(bytes: Uint8Array): LwwDelta {
-  const raw = unpack(bytes) as { entry?: LwwEntry | null };
+export const decodeLwwDelta = (bytes: Uint8Array): LwwDelta => {
+  const raw = decode(bytes) as { entry?: LwwEntry | null };
   return { entry: raw.entry ?? null };
-}
-
-// ---------------------------------------------------------------------------
-// Presence delta
-// ---------------------------------------------------------------------------
+};
 
 export interface PresenceEntryDelta {
   data: unknown;
@@ -100,12 +63,11 @@ export interface PresenceEntryDelta {
   ttl_ms: number | bigint;
 }
 
-/** PresenceDelta — changes per client_id */
 export interface PresenceDelta {
   changes: Record<string, PresenceEntryDelta | null>;
 }
 
-export function decodePresenceDelta(bytes: Uint8Array): PresenceDelta {
-  const raw = unpack(bytes) as { changes?: Record<string, PresenceEntryDelta | null> };
+export const decodePresenceDelta = (bytes: Uint8Array): PresenceDelta => {
+  const raw = decode(bytes) as { changes?: Record<string, PresenceEntryDelta | null> };
   return { changes: raw.changes ?? {} };
-}
+};

package/src/transport/http.ts

@@ -1,10 +1,3 @@
-/**
- * HTTP transport — REST API client for Meridian.
- *
- * All methods return Effect<T, HttpError | NetworkError> so callers
- * can handle network failures and server errors as typed values.
- */
-
 import { encode, decode } from "../codec.js";
 import { Effect, Schema } from "effect";
 import { HttpError, NetworkError } from "../errors.js";
@@ -13,27 +6,16 @@ import {
   CrdtOpResponse,
   TokenIssueResponse,
   ErrorResponse,
-  VectorClock,
+  type VectorClock,
 } from "../schema.js";
 import type { Permissions } from "../schema.js";
 
-// ---------------------------------------------------------------------------
-// Config
-// ---------------------------------------------------------------------------
-
 export interface HttpClientConfig {
-  /** Base URL of the Meridian server, e.g. "http://localhost:3000" */
   baseUrl: string;
-  /** Bearer token. Can be updated after construction (e.g. after refresh). */
   token: string;
-  /** Request timeout in ms. Default: 10_000 */
   timeoutMs?: number;
 }
 
-// ---------------------------------------------------------------------------
-// HttpClient
-// ---------------------------------------------------------------------------
-
 export class HttpClient {
   private readonly baseUrl: string;
   private readonly timeoutMs: number;
@@ -45,19 +27,14 @@ export class HttpClient {
     this.timeoutMs = config.timeoutMs ?? 10_000;
   }
 
-  // ---- CRDT REST ----
-
-  /** GET /v1/namespaces/:ns/crdts/:id */
   getCrdt(ns: string, id: string): Effect.Effect<CrdtGetResponse, HttpError | NetworkError> {
     return this.request(CrdtGetResponse, "GET", `/v1/namespaces/${ns}/crdts/${id}`);
   }
 
-  /** POST /v1/namespaces/:ns/crdts/:id/ops */
   postOp(ns: string, id: string, op: unknown): Effect.Effect<CrdtOpResponse, HttpError | NetworkError> {
     return this.request(CrdtOpResponse, "POST", `/v1/namespaces/${ns}/crdts/${id}/ops`, op);
   }
 
-  /** GET /v1/namespaces/:ns/crdts/:id/sync?since=<base64url(msgpack(vc))> */
   syncCrdt(
     ns: string,
     id: string,
@@ -71,7 +48,6 @@ export class HttpClient {
     return this.request(CrdtGetResponse, "GET", path);
   }
 
-  /** POST /v1/namespaces/:ns/tokens  (admin-only) */
   issueToken(
     ns: string,
     opts: { client_id: number; ttl_ms: number; permissions: Permissions },
@@ -79,8 +55,6 @@ export class HttpClient {
     return this.request(TokenIssueResponse, "POST", `/v1/namespaces/${ns}/tokens`, opts);
   }
 
-  // ---- Internal ----
-
   private request<A, I>(
     responseSchema: Schema.Schema<A, I>,
     method: string,
@@ -140,14 +114,10 @@ export class HttpClient {
   }
 }
 
-// ---------------------------------------------------------------------------
-// base64url (no-padding) encoder
-// ---------------------------------------------------------------------------
-
-function base64urlEncode(bytes: Uint8Array): string {
+const base64urlEncode = (bytes: Uint8Array): string => {
   let binary = "";
   for (const b of bytes) {
     binary += String.fromCharCode(b);
   }
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
-}
+};