@marianmeres/ws 0.2.0

package/dist/client/rooms.js

@@ -0,0 +1,120 @@
+/**
+ * Refcounted room registry.
+ *
+ * N handlers on one room produce exactly one wire subscription; the `unsub`
+ * frame goes out when the last handler detaches. This is what lets
+ * `subscribe()` hand back a plain unsubscriber that is safe to call from
+ * component teardown without any coordination between call sites.
+ *
+ * @module
+ */
+/** Tracks rooms, their handlers, and their known membership. */
+export class RoomRegistry {
+    #rooms = new Map();
+    /** Rooms currently held, in insertion order. */
+    get rooms() {
+        return [...this.#rooms.keys()];
+    }
+    has(room) {
+        return this.#rooms.has(room);
+    }
+    wantsPresence(room) {
+        const entry = this.#rooms.get(room);
+        return !!entry && entry.presenceHandlers.size > 0;
+    }
+    members(room) {
+        return [...(this.#rooms.get(room)?.members ?? [])];
+    }
+    /**
+     * Attaches handlers, creating the room entry if needed.
+     *
+     * Presence is enabled by *providing a presence handler* rather than by a
+     * separate boolean — one way to express the intent instead of two that can
+     * disagree.
+     */
+    add(room, handler, presenceHandler) {
+        let entry = this.#rooms.get(room);
+        const created = !entry;
+        const hadPresence = !!entry && entry.presenceHandlers.size > 0;
+        if (!entry) {
+            entry = { handlers: new Set(), presenceHandlers: new Set(), members: [] };
+            this.#rooms.set(room, entry);
+        }
+        entry.handlers.add(handler);
+        if (presenceHandler)
+            entry.presenceHandlers.add(presenceHandler);
+        return {
+            created,
+            presenceUpgraded: !created && !hadPresence && !!presenceHandler,
+        };
+    }
+    /**
+     * Detaches handlers.
+     *
+     * @returns `true` when the room became empty and should be unsubscribed.
+     */
+    remove(room, handler, presenceHandler) {
+        const entry = this.#rooms.get(room);
+        if (!entry)
+            return false;
+        entry.handlers.delete(handler);
+        if (presenceHandler)
+            entry.presenceHandlers.delete(presenceHandler);
+        if (entry.handlers.size === 0 && entry.presenceHandlers.size === 0) {
+            this.#rooms.delete(room);
+            return true;
+        }
+        return false;
+    }
+    /** Force-removes a room and every handler attached to it. */
+    removeRoom(room) {
+        return this.#rooms.delete(room);
+    }
+    /**
+     * The full subscription set, for re-subscribing after a reconnect in a
+     * single batched frame rather than one round-trip per room.
+     */
+    subRequests() {
+        return [...this.#rooms.entries()].map(([room, entry]) => ({
+            room,
+            ...(entry.presenceHandlers.size > 0 ? { presence: true } : {}),
+        }));
+    }
+    /**
+     * Delivers to every handler for the room.
+     *
+     * Handlers are snapshotted first, so a handler that unsubscribes (or
+     * subscribes) during delivery cannot corrupt the in-flight iteration.
+     */
+    deliver(room, msg, onError) {
+        const entry = this.#rooms.get(room);
+        if (!entry)
+            return;
+        for (const handler of [...entry.handlers]) {
+            try {
+                handler(msg);
+            }
+            catch (e) {
+                onError(e);
+            }
+        }
+    }
+    /** Updates cached membership, then delivers to presence handlers. */
+    deliverPresence(room, event, onError) {
+        const entry = this.#rooms.get(room);
+        if (!entry)
+            return;
+        entry.members = event.members;
+        for (const handler of [...entry.presenceHandlers]) {
+            try {
+                handler(event);
+            }
+            catch (e) {
+                onError(e);
+            }
+        }
+    }
+    clear() {
+        this.#rooms.clear();
+    }
+}

package/dist/client/ws-client.d.ts

@@ -0,0 +1,351 @@
+/**
+ * The WebSocket client.
+ *
+ * @module
+ */
+import { type Logger } from "@marianmeres/clog";
+import { type Subscriber, type Unsubscriber } from "@marianmeres/pubsub";
+import type { ClientFrame, WSDecoder, WSEncoder, WSMessage, WSPresenceEvent, WSPublishResult } from "../protocol/frames.js";
+import { type MessageHandler, type PresenceHandler } from "./rooms.js";
+/**
+ * Connection lifecycle states.
+ *
+ * A plain union rather than a state-machine dependency — the transition table
+ * below is the whole of the machinery, and it is small enough to read.
+ */
+export type WSConnectionState = "idle" | "connecting" | "authenticating" | "open" | "reconnecting" | "terminated" | "disposed";
+/** Events emitted by {@link WSClient}. */
+export interface WSEvents {
+    /** Socket opened; authentication has not happened yet. */
+    open: void;
+    /** Authenticated and ready. */
+    connected: {
+        clientId: string;
+        namespace: string;
+    };
+    /** Firehose — every message, regardless of room. */
+    message: WSMessage;
+    /** Membership change in a room subscribed with presence enabled. */
+    presence: WSPresenceEvent;
+    /** Socket closed. `willReconnect` reflects the retry classification. */
+    close: {
+        code: number;
+        reason: string;
+        willReconnect: boolean;
+    };
+    /** A retry is scheduled; `delay` is the jittered backoff in ms. */
+    reconnecting: {
+        attempt: number;
+        delay: number;
+    };
+    /** Gave up — the only non-retrying exit. */
+    terminated: {
+        code: number;
+        reason: string;
+    };
+    /** Something failed but the client carries on: decode, a throwing handler, … */
+    error: Error;
+}
+/** Reactive connection state, delivered through the Svelte store contract. */
+export interface WSState {
+    /** Current lifecycle state. */
+    state: WSConnectionState;
+    /** `true` only in the `open` state — authenticated and usable. */
+    connected: boolean;
+    /** `true` while connecting, authenticating or waiting out a backoff. */
+    connecting: boolean;
+    /** Consecutive failed connection attempts; resets to 0 on success. */
+    attempt: number;
+    /** Most recent error, retained until the next successful connect. */
+    lastError: Error | null;
+}
+/** Per-room subscription options. */
+export interface SubscribeOptions {
+    /**
+     * Enables presence tracking for this room.
+     *
+     * Presence is opt-in per room rather than global: a 10k-subscriber
+     * notification room does not want 10k join events every time the fleet
+     * reconnects.
+     */
+    presence?: PresenceHandler;
+}
+/** Configuration for {@link WSClient}. */
+export interface WSClientOptions<TAuth = unknown> {
+    /**
+     * Endpoint. `ws://`/`wss://`, or `http(s)://` (upgraded automatically), or
+     * a path resolved against `location` in the browser. Default `/ws`.
+     */
+    url?: string | URL;
+    /** Isolation boundary. Default `"default"`. */
+    namespace?: string;
+    /** Preferred client id; the server may override it. */
+    clientId?: string;
+    /** Rooms joined automatically on every (re)connect. */
+    rooms?: string[];
+    /**
+     * Produces the auth payload. Called before *every* (re)connect, so
+     * returning a fresh token here is all that token refresh requires.
+     */
+    auth?: () => TAuth | Promise<TAuth>;
+    /**
+     * Let the first `subscribe()`/`publish()` start the connection.
+     * Default `true` — with an outbox and infinite retry, requiring an explicit
+     * `connect()` first is ceremony whose only product is an error for people
+     * who forgot.
+     */
+    autoConnect?: boolean;
+    /** `null` disables logging. */
+    logger?: Logger | null;
+    /** Initial reconnect delay in ms. Default 500. */
+    reconnectDelay?: number;
+    /** Reconnect delay ceiling in ms. Default 30_000. */
+    reconnectDelayMax?: number;
+    /** Close codes after which retrying stops. Default `[4001, 4003]`. */
+    terminalCloseCodes?: number[];
+    /** Ping cadence in ms. `0` disables. Default 25_000. */
+    pingInterval?: number;
+    /**
+     * Liveness deadline in ms — bounds both the pong reply and the initial
+     * auth handshake. Default 10_000.
+     */
+    pongTimeout?: number;
+    /** Bound for the *first* `connect()` await. `0` waits indefinitely. */
+    connectTimeout?: number;
+    /** Per-send deadline covering queue + flight + ack. Default 30_000. */
+    sendTimeout?: number;
+    /** Frames buffered while disconnected. `0` disables buffering. Default 100. */
+    outboxMaxSize?: number;
+    /** Called with frames evicted from a full outbox. */
+    onOutboxDrop?: (frames: ClientFrame[]) => void;
+    /** Custom wire encoder. Must match the server's. */
+    encode?: WSEncoder;
+    /** Custom wire decoder. Must match the server's. */
+    decode?: WSDecoder;
+}
+/**
+ * A reconnecting WebSocket client with namespaces, rooms and presence.
+ *
+ * @example
+ * ```ts
+ * const ws = createWSClient({ url: "/ws", namespace: "org-123" });
+ * const unsub = await ws.subscribe("chat", (msg) => console.log(msg.payload));
+ * await ws.publish("chat", { text: "hi" });
+ * ```
+ */
+export declare class WSClient<TAuth = unknown> {
+    #private;
+    /** Logger. Assignable — set to `null` to silence. */
+    logger: Logger | null;
+    /**
+     * Nothing connects here — the socket opens on the first `connect()`,
+     * `subscribe()` or `publish()`.
+     *
+     * @param options - see {@link WSClientOptions}; every field has a default
+     */
+    constructor(options?: WSClientOptions<TAuth>);
+    /**
+     * Normalizes an endpoint: relative paths resolve against `location`, and
+     * `http(s)` is upgraded to `ws(s)`.
+     *
+     * @param input - absolute url, or a path when running in a browser
+     * @returns the normalized `ws(s)://` url
+     * @throws {WSError} when the input cannot be resolved — outside a browser
+     * there is no `location` to resolve a relative path against
+     */
+    static resolveUrl(input: string | URL): URL;
+    /** `true` only when authenticated and usable — not merely socket-open. */
+    get connected(): boolean;
+    /** Current lifecycle state. See {@link WSConnectionState}. */
+    get connectionState(): WSConnectionState;
+    /** Server-assigned id, available once connected. */
+    get clientId(): string | null;
+    /** Active namespace — the server's assignment wins over the request. */
+    get namespace(): string;
+    /** Resolved endpoint. A copy — mutating it does not affect the client. */
+    get url(): URL;
+    /**
+     * The underlying socket, or `null` while disconnected.
+     *
+     * Escape hatch for inspection. Sending on it directly bypasses the outbox
+     * and the ack correlation, so don't.
+     */
+    get socket(): WebSocket | null;
+    /** Rooms currently subscribed. */
+    get rooms(): string[];
+    /**
+     * Reactive state, Svelte-store compatible: the callback fires immediately
+     * with the current value and again on every change.
+     */
+    get state(): {
+        subscribe: (cb: Subscriber<WSState>) => Unsubscriber;
+    };
+    /**
+     * Debug snapshot: url, state, identity, rooms and outbox counters.
+     *
+     * For logging and troubleshooting — the shape is not part of the stable API.
+     */
+    dump(): Record<string, unknown>;
+    /**
+     * Subscribes to a lifecycle event. See {@link WSEvents}.
+     *
+     * @param event - event name
+     * @param cb - handler; a throw here is caught and reported as `error`
+     * @returns detaches the handler; also `Symbol.dispose`-compatible
+     */
+    on<K extends keyof WSEvents>(event: K, cb: (data: WSEvents[K]) => void): Unsubscriber;
+    /**
+     * Like {@link on}, but detaches after the first emission.
+     *
+     * @param event - event name
+     * @param cb - handler
+     * @returns detaches the handler early, if it has not fired yet
+     */
+    once<K extends keyof WSEvents>(event: K, cb: (data: WSEvents[K]) => void): Unsubscriber;
+    /**
+     * Starts the connection and resolves once it is established.
+     *
+     * Idempotent: concurrent calls share one promise, and it resolves
+     * immediately when already connected.
+     *
+     * Rejects **only** where retrying cannot help:
+     * - {@link WSTerminatedError} — terminal close code (bad credentials, etc.)
+     * - {@link WSConnectTimeoutError} — `connectTimeout` elapsed; note the
+     *   client keeps retrying in the background, so this bounds *your await*,
+     *   not the connection attempt
+     *
+     * Ordinary network failure never rejects; that is what the infinite retry
+     * is for.
+     *
+     * Calling this is optional when `autoConnect` is on — it is a readiness
+     * gate, not a prerequisite.
+     *
+     * @returns resolves once authenticated
+     */
+    connect(): Promise<void>;
+    /**
+     * Stops retrying and closes the socket.
+     *
+     * Resumable: handlers, room subscriptions and buffered sends all survive,
+     * so a later `connect()` picks up exactly where this left off. Use
+     * {@link dispose} for terminal teardown.
+     */
+    disconnect(): void;
+    /**
+     * Terminal teardown: disconnects, then drops every handler, room, timer and
+     * pending promise. The instance is unusable afterwards.
+     */
+    dispose(): void;
+    /**
+     * Subscribes to a room and attaches a handler.
+     *
+     * The handler is attached **synchronously**, before any frame goes out, so
+     * nothing arriving between the request and its acknowledgement is lost.
+     *
+     * Rooms are refcounted: N handlers produce one wire subscription, and the
+     * returned unsubscriber detaches this handler — sending `unsub` only when
+     * it was the last one.
+     *
+     * Resolution: when connected, this awaits the server's acknowledgement, so
+     * a rejected subscription surfaces as a rejection here. When not connected
+     * it resolves as soon as the room is registered — the subscription is then
+     * guaranteed to be established by the re-subscribe step on the next
+     * connect, and a failure there surfaces as an `error` event.
+     *
+     * @param room - room name, scoped to this client's namespace
+     * @param handler - receives every message published to the room
+     * @param options - pass `presence` to enable membership tracking
+     * @returns detaches this handler; also `Symbol.dispose`-compatible, and
+     * idempotent, so calling it twice is harmless
+     * @throws {WSRemoteError} when connected and the server refuses
+     * @throws {WSDisposedError} when the client was disposed
+     *
+     * @example
+     * ```ts
+     * const unsub = await ws.subscribe("chat", (msg) => render(msg.payload), {
+     *     presence: (e) => setMembers(e.members),
+     * });
+     * ```
+     */
+    subscribe<T = unknown>(room: string, handler: MessageHandler<T>, options?: SubscribeOptions): Promise<Unsubscriber>;
+    /**
+     * Removes every handler for a room and unsubscribes it.
+     *
+     * The blunt counterpart to the refcounted unsubscriber returned by
+     * {@link subscribe} — this drops other call sites' handlers too.
+     *
+     * @param room - room name; unknown rooms are a no-op
+     */
+    unsubscribe(room: string): Promise<void>;
+    /**
+     * Whether the room is held locally.
+     *
+     * Reflects local intent, not server state: a room registered while offline
+     * reads `true` before the wire subscription exists.
+     *
+     * @param room - room name
+     */
+    isSubscribed(room: string): boolean;
+    /**
+     * Last known membership of a presence-enabled room.
+     *
+     * @param room - room name
+     * @returns a copy of the members; empty when the room has no presence
+     */
+    members(room: string): string[];
+    /**
+     * Publishes to a room within this client's namespace.
+     *
+     * Resolves with the recipient count once the server acknowledges. While
+     * disconnected the frame is buffered and the promise stays pending until it
+     * flushes — bounded by `sendTimeout`, never indefinitely.
+     *
+     * @param room - target room
+     * @param payload - opaque application data; never inspected or mutated
+     * @param namespace - must equal this client's namespace; the server rejects
+     * anything else, so this is only useful for asserting the expected one
+     * @returns the recipient count reported by the receiving server instance —
+     * best-effort telemetry, not a delivery guarantee
+     * @throws {WSTimeoutError} `sendTimeout` elapsed with no acknowledgement
+     * @throws {WSOutboxDropError} evicted from a full outbox
+     * @throws {WSNotConnectedError} sent while offline with `outboxMaxSize: 0`
+     * @throws {WSRemoteError} the server rejected it with a `nack`
+     */
+    publish<T = unknown>(room: string, payload: T, namespace?: string): Promise<WSPublishResult>;
+    /**
+     * Publishes to a room across **all** namespaces.
+     *
+     * This crosses the isolation boundary, which is why it is its own method
+     * rather than a flag on {@link publish} — the server gates it separately
+     * via `allowBroadcast`, and it denies by default.
+     *
+     * @param room - target room, in every namespace at once
+     * @param payload - opaque application data
+     * @returns the recipient count across all namespaces on the receiving
+     * server instance
+     * @throws {WSRemoteError} with code `forbidden` when `allowBroadcast` denies
+     */
+    broadcast<T = unknown>(room: string, payload: T): Promise<WSPublishResult>;
+}
+/**
+ * Creates a {@link WSClient}.
+ *
+ * Both this and the class are exported, following the `PubSub` /
+ * `createPubSub` precedent in `@marianmeres/pubsub`.
+ *
+ * @param options - see {@link WSClientOptions}
+ * @returns a client that has not connected yet
+ *
+ * @example
+ * ```ts
+ * const ws = createWSClient({
+ *     url: "wss://example.com/ws",
+ *     namespace: "org-123",
+ *     auth: () => session.token, // re-read on every reconnect
+ * });
+ *
+ * await ws.subscribe("chat", (msg) => console.log(msg.from, msg.payload));
+ * await ws.publish("chat", { text: "hello" });
+ * ```
+ */
+export declare function createWSClient<TAuth = unknown>(options?: WSClientOptions<TAuth>): WSClient<TAuth>;