MeridianClient

Create and manage a Meridian client connection.

Create a client

MeridianClient.create() parses and validates the token before opening the WebSocket. It returns an Effect.

import { Effect } from "effect";
import { MeridianClient } from "meridian-sdk";

const client = await Effect.runPromise(
  MeridianClient.create({
    url: "http://localhost:3000",
    namespace: "my-room",
    token: process.env.MERIDIAN_TOKEN!,
  })
);

Config

Option	Type	Default	Description
url	string	—	Server base URL (http:// or ws://, both work)
namespace	string	—	Namespace to connect to
token	string	—	Meridian token
autoConnect	boolean	true	Open WebSocket immediately

Properties

client.namespace  // string
client.clientId   // number
client.claims     // TokenClaims — full parsed token claims
client.http       // HttpClient — REST API access

CRDT handles

All handles are cached by crdtId — calling the same method twice returns the same instance.

client.gcounter("id")               // GCounterHandle
client.pncounter("id")              // PNCounterHandle
client.orset("id", schema?)         // ORSetHandle<T>
client.lwwregister("id", schema?)   // LwwRegisterHandle<T>
client.presence("id", schema?)      // PresenceHandle<T>

For orset, lwwregister, and presence, passing an Effect Schema enables runtime validation of incoming deltas. Without a schema, T = unknown.

HTTP client

client.http.getCrdt(ns, id)           // → Effect<CrdtGetResponse, HttpError | NetworkError>
client.http.postOp(ns, id, op)        // → Effect<CrdtOpResponse, HttpError | NetworkError>
client.http.syncCrdt(ns, id, sinceVc) // → Effect<CrdtGetResponse, HttpError | NetworkError>
client.http.issueToken(ns, opts)      // → Effect<TokenIssueResponse, HttpError | NetworkError>

Wait for connection

await client.waitForConnected();          // default 5s timeout
await client.waitForConnected(10_000);    // custom timeout in ms

Resolves when the WebSocket reaches CONNECTED state. Useful in tests or when you need to send an operation immediately after creating the client (before the connection handshake completes).

Throws Error: WsTransport: connect timeout if the timeout elapses.

Close

client.close(); // gracefully closes the WebSocket, no reconnect