meridian-sdk 0.2.1 → 0.2.3

package/dist/transport/websocket.js

@@ -1,63 +1,40 @@
-/**
- * WebSocket transport — reconnect FSM + Sync on reconnect.
- *
- * States:
- *   DISCONNECTED → CONNECTING → AUTHENTICATING → CONNECTED → CLOSING
- *
- * On reconnect: re-subscribes to all known CRDTs and sends Sync(localVectorClock)
- * so the server can push missed deltas.
- *
- * Backoff: 100ms → 200ms → 400ms → … → 30s (±20% jitter).
- */
 import { Effect } from "effect";
 import { encodeClientMsg, decodeServerMsg, encodeVectorClock } from "../codec.js";
-// ---------------------------------------------------------------------------
-// WsTransport
-// ---------------------------------------------------------------------------
+import { BACKOFF_INITIAL_MS, BACKOFF_MAX_MS, BACKOFF_MULTIPLIER, JITTER_MULTIPLIER, DEFAULT_TIMEOUT_MS, } from "../constants.js";
 export class WsTransport {
     config;
     maxBackoffMs;
     ws = null;
     state = "DISCONNECTED";
-    backoffMs = 100;
+    backoffMs = BACKOFF_INITIAL_MS;
     reconnectTimer = null;
     closed = false;
-    /** CRDTs to re-subscribe on reconnect: crdt_id → last known VectorClock */
     subscriptions = new Map();
     constructor(config) {
         this.config = config;
-        this.maxBackoffMs = config.maxBackoffMs ?? 30_000;
+        this.maxBackoffMs = config.maxBackoffMs ?? BACKOFF_MAX_MS;
     }
-    // ---- Public API ----
     connect() {
         if (this.closed)
             return;
         this.closed = false;
         this.doConnect();
     }
-    /** Gracefully close — will not reconnect. */
     close() {
         this.closed = true;
         this.clearReconnectTimer();
         this.transitionTo("CLOSING");
         this.ws?.close(1000, "client close");
     }
-    /**
-     * Subscribe to a CRDT's deltas.
-     * If already connected, sends Subscribe immediately.
-     * On reconnect, the subscription is re-sent automatically.
-     */
     subscribe(crdtId, sinceVc = {}) {
         this.subscriptions.set(crdtId, sinceVc);
         if (this.state === "CONNECTED") {
             this.sendSubscribe(crdtId, sinceVc);
         }
     }
-    /** Update the local vector clock for a CRDT (used for reconnect Sync). */
     updateClock(crdtId, vc) {
         this.subscriptions.set(crdtId, vc);
     }
-    /** Send a raw ClientMsg. Throws if not connected. */
     send(msg) {
         if (this.state !== "CONNECTED" || this.ws === null) {
             throw new Error("WsTransport: not connected");
@@ -67,8 +44,7 @@ export class WsTransport {
     get currentState() {
         return this.state;
     }
-    /** Resolves when the transport reaches CONNECTED state (or rejects on timeout). */
-    waitForConnected(timeoutMs = 5_000) {
+    waitForConnected(timeoutMs = DEFAULT_TIMEOUT_MS) {
         if (this.state === "CONNECTED")
             return Promise.resolve();
         return new Promise((resolve, reject) => {
@@ -95,7 +71,6 @@ export class WsTransport {
             };
         });
     }
-    // ---- FSM internals ----
     doConnect() {
         if (this.closed)
             return;
@@ -106,8 +81,8 @@ export class WsTransport {
         this.ws = ws;
         ws.addEventListener("open", () => {
             if (ws !== this.ws)
-                return; // stale socket
-            this.backoffMs = 100; // reset backoff on successful connect
+                return;
+            this.backoffMs = BACKOFF_INITIAL_MS;
             this.transitionTo("CONNECTED");
             this.resubscribeAll();
         });
@@ -127,19 +102,19 @@ export class WsTransport {
             }
         });
         ws.addEventListener("error", () => {
-            // The "close" event fires right after — let that handle reconnect.
+            // HACK: The "close" event fires right after an error — let that handler drive reconnect logic.
         });
     }
     scheduleReconnect() {
         if (this.closed)
             return;
-        const jitter = this.backoffMs * 0.2 * (Math.random() * 2 - 1); // ±20%
+        const jitter = this.backoffMs * JITTER_MULTIPLIER * (Math.random() * 2 - 1);
         const delay = Math.round(this.backoffMs + jitter);
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             this.doConnect();
         }, delay);
-        this.backoffMs = Math.min(this.backoffMs * 2, this.maxBackoffMs);
+        this.backoffMs = Math.min(this.backoffMs * BACKOFF_MULTIPLIER, this.maxBackoffMs);
     }
     clearReconnectTimer() {
         if (this.reconnectTimer !== null) {
@@ -153,7 +128,6 @@ export class WsTransport {
         this.state = next;
         this.config.onStateChange?.(next);
     }
-    /** On reconnect: re-subscribe and send Sync for each known CRDT. */
     resubscribeAll() {
         for (const [crdtId, vc] of this.subscriptions) {
             this.sendSubscribe(crdtId, vc);
@@ -162,9 +136,7 @@ export class WsTransport {
     sendSubscribe(crdtId, vc) {
         if (this.ws === null || this.state !== "CONNECTED")
             return;
-        // First subscribe so the server starts pushing future deltas
         this.ws.send(encodeClientMsg({ Subscribe: { crdt_id: crdtId } }));
-        // Then sync to get missed deltas since our last known VC
         const vcBytes = encodeVectorClock(vc);
         this.ws.send(encodeClientMsg({ Sync: { crdt_id: crdtId, since_vc: vcBytes } }));
     }

package/dist/transport/websocket.js.map

@@ -1 +1 @@
-{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../../src/transport/websocket.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../../src/transport/websocket.ts"],"names":[],"mappings":"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"}

package/dist/utils/to-hex.d.ts

@@ -0,0 +1,2 @@
+export declare const toHex: (value: number) => string;
+//# sourceMappingURL=to-hex.d.ts.map

package/dist/utils/to-hex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-hex.d.ts","sourceRoot":"","sources":["../../src/utils/to-hex.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,KAAG,MAA6C,CAAC"}

package/dist/utils/to-hex.js

@@ -0,0 +1,2 @@
+export const toHex = (value) => value.toString(16).padStart(2, "0");
+//# sourceMappingURL=to-hex.js.map

package/dist/utils/to-hex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-hex.js","sourceRoot":"","sources":["../../src/utils/to-hex.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meridian-sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "TypeScript SDK for Meridian CRDT server",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,15 +15,18 @@
     "build": "tsc",
     "test": "bun test",
     "test:watch": "bun test --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint ./src",
+    "format": "biome format --write ./src"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.7",
     "@types/bun": "latest",
     "typescript": "^5.7.0"
   },
   "dependencies": {
     "effect": "^3.19.0",
-    "msgpackr": "^1.11.0"
+    "@msgpack/msgpack": "^3.0.0"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"

package/src/auth/token.ts

@@ -1,23 +1,9 @@
-/**
- * Token parsing and expiry check (client-side only — no signature verification).
- *
- * Wire format: `base64url_no_pad(msgpack(TokenClaims)) + "." + base64url_no_pad(sig[64B])`
- */
-
-import { unpack } from "msgpackr";
+import { decode } from "@msgpack/msgpack";
 import { Effect, Schema } from "effect";
 import { TokenParseError, TokenExpiredError } from "../errors.js";
 import { TokenClaims } from "../schema.js";
+import { TOKEN_SKEW_MS } from "../constants.js";
 
-// ---------------------------------------------------------------------------
-// Parse
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a Meridian token string and return the decoded claims.
- * Returns Effect<TokenClaims, TokenParseError>.
- * Does NOT verify the ed25519 signature — the server enforces that.
- */
 export const parseToken = (token: string): Effect.Effect<TokenClaims, TokenParseError> =>
   Effect.gen(function* () {
     const dotIndex = token.indexOf(".");
@@ -38,7 +24,7 @@ export const parseToken = (token: string): Effect.Effect<TokenClaims, TokenParse
 
     let raw: unknown;
     try {
-      raw = unpack(bytes);
+      raw = decode(bytes);
     } catch {
       yield* Effect.fail(new TokenParseError({ message: "Invalid token format: msgpack decode failed" }));
       return undefined as never;
@@ -51,39 +37,25 @@ export const parseToken = (token: string): Effect.Effect<TokenClaims, TokenParse
     );
   });
 
-/**
- * Check token expiry. Returns Effect<TokenClaims, TokenExpiredError>.
- * Clock-skew tolerance: ±5s.
- */
 export const checkTokenExpiry = (
   claims: TokenClaims,
   nowMs = Date.now(),
 ): Effect.Effect<TokenClaims, TokenExpiredError> => {
-  const SKEW_MS = 5_000;
-  if (nowMs >= claims.expires_at + SKEW_MS) {
+  if (nowMs >= claims.expires_at + TOKEN_SKEW_MS) {
     return Effect.fail(new TokenExpiredError({ expiredAt: claims.expires_at }));
   }
   return Effect.succeed(claims);
 };
 
-/**
- * Parse and check expiry in one step.
- * Returns Effect<TokenClaims, TokenParseError | TokenExpiredError>.
- */
 export const parseAndValidateToken = (
   token: string,
 ): Effect.Effect<TokenClaims, TokenParseError | TokenExpiredError> =>
   parseToken(token).pipe(Effect.flatMap(checkTokenExpiry));
 
-/** Returns milliseconds until the token expires (negative if already expired). */
 export const tokenTtlMs = (claims: TokenClaims, nowMs = Date.now()): number =>
   claims.expires_at - nowMs;
 
-// ---------------------------------------------------------------------------
-// Base64url (no-padding) decoder — no external dep
-// ---------------------------------------------------------------------------
-
-function base64urlDecode(input: string): Uint8Array {
+const base64urlDecode = (input: string): Uint8Array => {
   const padded = input.replace(/-/g, "+").replace(/_/g, "/");
   const padLen = (4 - (padded.length % 4)) % 4;
   const b64 = padded + "=".repeat(padLen);
@@ -93,4 +65,4 @@ function base64urlDecode(input: string): Uint8Array {
     bytes[i] = binary.charCodeAt(i);
   }
   return bytes;
-}
+};

package/src/client.ts

@@ -1,20 +1,4 @@
-/**
- * MeridianClient — top-level SDK entry point.
- *
- * Use `MeridianClient.create(config)` (returns Effect) to parse the token
- * and validate it before connecting.
- *
- * ```ts
- * const client = await Effect.runPromise(
- *   MeridianClient.create({ url: "ws://localhost:3000", namespace: "room", token })
- * );
- * const counter = client.gcounter("gc:page-views");
- * counter.increment();
- * counter.onChange(v => console.log("views:", v));
- * ```
- */
-
-import { Effect, Schema } from "effect";
+import { Effect, type Schema } from "effect";
 import { WsTransport } from "./transport/websocket.js";
 import { HttpClient } from "./transport/http.js";
 import { GCounterHandle } from "./crdt/gcounter.js";
@@ -33,25 +17,39 @@ import { parseAndValidateToken } from "./auth/token.js";
 import type { ServerMsg, TokenClaims } from "./schema.js";
 import type { TokenParseError, TokenExpiredError } from "./errors.js";
 
-// ---------------------------------------------------------------------------
-// Config
-// ---------------------------------------------------------------------------
-
 export interface MeridianClientConfig {
-  /** Base URL of the Meridian server, e.g. "http://localhost:3000" */
   url: string;
-  /** Namespace to connect to. */
   namespace: string;
-  /** Meridian token for this namespace. */
   token: string;
-  /** If true, open the WebSocket immediately. Default: true */
   autoConnect?: boolean;
 }
 
-// ---------------------------------------------------------------------------
-// MeridianClient
-// ---------------------------------------------------------------------------
-
+/**
+ * The main entry point for the Meridian real-time CRDT SDK.
+ *
+ * Create an instance with the static `MeridianClient.create()` factory, then
+ * use the handle methods to obtain typed CRDT handles that sync automatically
+ * over WebSocket.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from 'effect';
+ * import { MeridianClient } from 'meridian-sdk';
+ *
+ * const client = await Effect.runPromise(
+ *   MeridianClient.create({
+ *     url: 'wss://example.com',
+ *     namespace: 'my-app',
+ *     token: '<JWT>',
+ *   })
+ * );
+ *
+ * const counter = client.gcounter('visitors');
+ * counter.increment();
+ *
+ * client.close();
+ * ```
+ */
 export class MeridianClient {
   readonly namespace: string;
   readonly clientId: number;
@@ -60,8 +58,7 @@ export class MeridianClient {
   private readonly transport: WsTransport;
   readonly http: HttpClient;
 
-  // Handle caches — keyed by crdt_id. Generic params erased at storage level;
-  // factories restore them via typed get+cast on retrieval.
+  // HACK: Generic params are erased at storage level; factories restore them via typed get+cast on retrieval.
   private readonly gcHandles = new Map<string, GCounterHandle>();
   private readonly pnHandles = new Map<string, PNCounterHandle>();
   private readonly orHandles = new Map<string, ORSetHandle<unknown>>();
@@ -91,8 +88,25 @@ export class MeridianClient {
   }
 
   /**
-   * Create a MeridianClient, parsing and validating the token.
-   * Returns Effect<MeridianClient, TokenParseError | TokenExpiredError>.
+   * Creates and validates a new `MeridianClient` from the supplied configuration.
+   *
+   * The JWT `token` is parsed and validated synchronously inside the Effect; the
+   * Effect fails with `TokenParseError` or `TokenExpiredError` if the token is
+   * malformed or expired. The WebSocket connection is opened immediately unless
+   * `autoConnect` is set to `false`.
+   *
+   * @param config - Connection configuration including the server `url`,
+   *   `namespace`, and a signed `token`.
+   *
+   * @example
+   * ```ts
+   * import { Effect } from 'effect';
+   * import { MeridianClient } from 'meridian-sdk';
+   *
+   * const client = await Effect.runPromise(
+   *   MeridianClient.create({ url: 'ws://localhost:8080', namespace: 'demo', token: myToken })
+   * );
+   * ```
    */
   static create(
     config: MeridianClientConfig,
@@ -102,74 +116,160 @@ export class MeridianClient {
     );
   }
 
-  // ---- CRDT factory methods ----
-
+  /**
+   * Returns a handle for a grow-only counter (GCounter) CRDT.
+   *
+   * Handles are cached by `crdtId`; calling this method multiple times with the
+   * same id returns the same handle instance and creates only one subscription.
+   *
+   * @param crdtId - Unique identifier for the CRDT within this namespace.
+   *
+   * @example
+   * ```ts
+   * const counter = client.gcounter('page-views');
+   * counter.increment(5);
+   * console.log(counter.value()); // 5
+   * ```
+   */
   gcounter(crdtId: string): GCounterHandle {
-    let h = this.gcHandles.get(crdtId);
-    if (!h) {
-      h = new GCounterHandle({ ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport });
-      this.gcHandles.set(crdtId, h);
+    let handle = this.gcHandles.get(crdtId);
+    if (!handle) {
+      handle = new GCounterHandle({ ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport });
+      this.gcHandles.set(crdtId, handle);
       this.transport.subscribe(crdtId);
     }
-    return h;
+    return handle;
   }
 
+  /**
+   * Returns a handle for a positive-negative counter (PNCounter) CRDT.
+   *
+   * Handles are cached by `crdtId`; calling this method multiple times with the
+   * same id returns the same handle instance and creates only one subscription.
+   *
+   * @param crdtId - Unique identifier for the CRDT within this namespace.
+   *
+   * @example
+   * ```ts
+   * const score = client.pncounter('game-score');
+   * score.increment(10);
+   * score.decrement(3);
+   * console.log(score.value()); // 7
+   * ```
+   */
   pncounter(crdtId: string): PNCounterHandle {
-    let h = this.pnHandles.get(crdtId);
-    if (!h) {
-      h = new PNCounterHandle({ ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport });
-      this.pnHandles.set(crdtId, h);
+    let handle = this.pnHandles.get(crdtId);
+    if (!handle) {
+      handle = new PNCounterHandle({ ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport });
+      this.pnHandles.set(crdtId, handle);
       this.transport.subscribe(crdtId);
     }
-    return h;
+    return handle;
   }
 
+  /**
+   * Returns a handle for an Observed-Remove Set (OR-Set) CRDT.
+   *
+   * Handles are cached by `crdtId`; calling this method multiple times with the
+   * same id returns the same handle instance and creates only one subscription.
+   *
+   * @param crdtId - Unique identifier for the CRDT within this namespace.
+   * @param schema - Optional Effect schema used to decode elements from the wire format.
+   *
+   * @example
+   * ```ts
+   * import { Schema } from 'effect';
+   *
+   * const tags = client.orset('article-tags', Schema.String);
+   * tags.add('typescript');
+   * tags.remove('typescript');
+   * ```
+   */
   orset<T>(crdtId: string, schema?: Schema.Schema<T>): ORSetHandle<T> {
-    let h = this.orHandles.get(crdtId) as ORSetHandle<T> | undefined;
-    if (!h) {
+    let handle = this.orHandles.get(crdtId) as ORSetHandle<T> | undefined;
+    if (!handle) {
       const base = { ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport };
-      h = schema ? new ORSetHandle<T>({ ...base, schema }) : new ORSetHandle<T>(base);
-      this.orHandles.set(crdtId, h as ORSetHandle<unknown>);
+      handle = schema ? new ORSetHandle<T>({ ...base, schema }) : new ORSetHandle<T>(base);
+      this.orHandles.set(crdtId, handle as ORSetHandle<unknown>);
       this.transport.subscribe(crdtId);
     }
-    return h;
+    return handle;
   }
 
+  /**
+   * Returns a handle for a Last-Write-Wins register (LWW-Register) CRDT.
+   *
+   * Handles are cached by `crdtId`; calling this method multiple times with the
+   * same id returns the same handle instance and creates only one subscription.
+   *
+   * @param crdtId - Unique identifier for the CRDT within this namespace.
+   * @param schema - Optional Effect schema used to decode the value from the wire format.
+   *
+   * @example
+   * ```ts
+   * import { Schema } from 'effect';
+   *
+   * const theme = client.lwwregister('ui-theme', Schema.Literal('light', 'dark'));
+   * theme.set('dark');
+   * console.log(theme.value()); // 'dark'
+   * ```
+   */
   lwwregister<T>(crdtId: string, schema?: Schema.Schema<T>): LwwRegisterHandle<T> {
-    let h = this.lwHandles.get(crdtId) as LwwRegisterHandle<T> | undefined;
-    if (!h) {
+    let handle = this.lwHandles.get(crdtId) as LwwRegisterHandle<T> | undefined;
+    if (!handle) {
       const base = { ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport };
-      h = schema ? new LwwRegisterHandle<T>({ ...base, schema }) : new LwwRegisterHandle<T>(base);
-      this.lwHandles.set(crdtId, h as LwwRegisterHandle<unknown>);
+      handle = schema ? new LwwRegisterHandle<T>({ ...base, schema }) : new LwwRegisterHandle<T>(base);
+      this.lwHandles.set(crdtId, handle as LwwRegisterHandle<unknown>);
       this.transport.subscribe(crdtId);
     }
-    return h;
+    return handle;
   }
 
+  /**
+   * Returns a handle for a presence channel CRDT.
+   *
+   * Handles are cached by `crdtId`; calling this method multiple times with the
+   * same id returns the same handle instance and creates only one subscription.
+   *
+   * @param crdtId - Unique identifier for the presence channel within this namespace.
+   * @param schema - Optional Effect schema used to decode peer data from the wire format.
+   *
+   * @example
+   * ```ts
+   * import { Schema } from 'effect';
+   *
+   * const room = client.presence('room-1', Schema.Struct({ name: Schema.String }));
+   * room.heartbeat({ name: 'Alice' }, 10_000);
+   * console.log(room.online()); // [{ clientId: 1, data: { name: 'Alice' }, expiresAtMs: ... }]
+   * room.leave();
+   * ```
+   */
   presence<T>(crdtId: string, schema?: Schema.Schema<T>): PresenceHandle<T> {
-    let h = this.prHandles.get(crdtId) as PresenceHandle<T> | undefined;
-    if (!h) {
+    let handle = this.prHandles.get(crdtId) as PresenceHandle<T> | undefined;
+    if (!handle) {
       const base = { ns: this.namespace, crdtId, clientId: this.clientId, transport: this.transport };
-      h = schema ? new PresenceHandle<T>({ ...base, schema }) : new PresenceHandle<T>(base);
-      this.prHandles.set(crdtId, h as PresenceHandle<unknown>);
+      handle = schema ? new PresenceHandle<T>({ ...base, schema }) : new PresenceHandle<T>(base);
+      this.prHandles.set(crdtId, handle as PresenceHandle<unknown>);
       this.transport.subscribe(crdtId);
     }
-    return h;
+    return handle;
   }
 
-  // ---- Lifecycle ----
-
-  /** Resolves when the WebSocket is connected and ready. */
   waitForConnected(timeoutMs = 5_000): Promise<void> {
     return this.transport.waitForConnected(timeoutMs);
   }
 
+  /**
+   * Closes the underlying WebSocket connection.
+   *
+   * Call this when the client is no longer needed to free resources. If you are
+   * using `<MeridianProvider>` in React, the provider calls this automatically
+   * on unmount.
+   */
   close(): void {
     this.transport.close();
   }
 
-  // ---- Internal: route ServerMsg.Delta to the right handle ----
-
   private handleServerMsg(msg: ServerMsg): void {
     if (!("Delta" in msg)) return;
     const { crdt_id, delta_bytes } = msg.Delta;