@marianmeres/ws 0.3.0 → 0.5.0

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

@@ -1,6 +1,13 @@
 /**
  * The WebSocket client.
  *
+ * Two ways to use it, freely mixed on one connection:
+ *
+ * - **Messages** (core): `send()` to the server, `on("message")` to receive.
+ *   Needs nothing from the server beyond the core protocol.
+ * - **Rooms** (extension): `subscribe()` / `publish()` / `broadcast()` and
+ *   presence, for servers that relay between clients.
+ *
  * @module
  */
 import { type Logger } from "@marianmeres/clog";
@@ -18,16 +25,26 @@ export type WSConnectionState = "idle" | "connecting" | "authenticating" | "open
 export interface WSEvents {
     /** Socket opened; authentication has not happened yet. */
     open: void;
-    /** Authenticated and ready. */
+    /**
+     * Authenticated and ready. `clientId` is `null` when the server assigned
+     * none — identity belongs to the rooms extension, and a core-only server
+     * may skip it.
+     */
     connected: {
-        clientId: string;
+        clientId: string | null;
         namespace: string;
     };
-    /** Firehose — every message, regardless of room. */
+    /**
+     * Every inbound message: direct messages from the server, and — with
+     * rooms — every room delivery regardless of room. `room` tells them apart.
+     */
     message: WSMessage;
     /** Membership change in a room subscribed with presence enabled. */
     presence: WSPresenceEvent;
-    /** Socket closed. `willReconnect` reflects the retry classification. */
+    /**
+     * Socket closed. `willReconnect` reflects the retry classification, and is
+     * `false` for the `4900` a local `disconnect()` emits.
+     */
     close: {
         code: number;
         reason: string;
@@ -59,6 +76,16 @@ export interface WSState {
     /** Most recent error, retained until the next successful connect. */
     lastError: Error | null;
 }
+/** Options for {@link WSClient.send}. */
+export interface WSSendOptions {
+    /**
+     * Wait for the server's acknowledgement and resolve with its reply.
+     *
+     * Default `false`: resolve as soon as the frame is written to the socket,
+     * with no confirmation that the server ever received it.
+     */
+    ack?: boolean;
+}
 /** Per-room subscription options. */
 export interface SubscribeOptions {
     /**
@@ -77,11 +104,14 @@ export interface WSClientOptions<TAuth = unknown> {
      * a path resolved against `location` in the browser. Default `/ws`.
      */
     url?: string | URL;
-    /** Isolation boundary. Default `"default"`. */
+    /**
+     * Isolation boundary for rooms. Default `"default"`. Sent to the server only
+     * when set here — a server without rooms has no use for it.
+     */
     namespace?: string;
-    /** Preferred client id; the server may override it. */
+    /** Preferred client id; the server may override or ignore it. */
     clientId?: string;
-    /** Rooms joined automatically on every (re)connect. */
+    /** Rooms joined automatically on every (re)connect (rooms extension). */
     rooms?: string[];
     /**
      * Produces the auth payload. Called before *every* (re)connect, so
@@ -89,7 +119,7 @@ export interface WSClientOptions<TAuth = unknown> {
      */
     auth?: () => TAuth | Promise<TAuth>;
     /**
-     * Let the first `subscribe()`/`publish()` start the connection.
+     * Let the first `send()`/`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.
@@ -124,9 +154,18 @@ export interface WSClientOptions<TAuth = unknown> {
     decode?: WSDecoder;
 }
 /**
- * A reconnecting WebSocket client with namespaces, rooms and presence.
+ * A reconnecting WebSocket client: plain messages to and from the server, and
+ * optionally namespaces, rooms and presence on top.
  *
- * @example
+ * @example Messages — the server is the peer
+ * ```ts
+ * const ws = createWSClient({ url: "/ws", auth: () => session.token });
+ * ws.on("message", (msg) => console.log(msg.payload));
+ * await ws.send({ op: "typing" }); // fire-and-forget
+ * const doc = await ws.send({ op: "load", id: 42 }, { ack: true }); // reply
+ * ```
+ *
+ * @example Rooms — the server relays between clients
  * ```ts
  * const ws = createWSClient({ url: "/ws", namespace: "org-123" });
  * const unsub = await ws.subscribe("chat", (msg) => console.log(msg.payload));
@@ -139,7 +178,7 @@ export declare class WSClient<TAuth = unknown> {
     logger: Logger | null;
     /**
      * Nothing connects here — the socket opens on the first `connect()`,
-     * `subscribe()` or `publish()`.
+     * `send()`, `subscribe()` or `publish()`.
      *
      * @param options - see {@link WSClientOptions}; every field has a default
      */
@@ -158,9 +197,15 @@ export declare class WSClient<TAuth = unknown> {
     get connected(): boolean;
     /** Current lifecycle state. See {@link WSConnectionState}. */
     get connectionState(): WSConnectionState;
-    /** Server-assigned id, available once connected. */
+    /**
+     * Server-assigned id, available once connected. Stays `null` when the
+     * server assigns none (a core-only server may not).
+     */
     get clientId(): string | null;
-    /** Active namespace — the server's assignment wins over the request. */
+    /**
+     * Active namespace — the server's assignment wins over the request. Falls
+     * back to the requested one when the server assigns none.
+     */
     get namespace(): string;
     /** Resolved endpoint. A copy — mutating it does not affect the client. */
     get url(): URL;
@@ -229,6 +274,10 @@ export declare class WSClient<TAuth = unknown> {
      * 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.
+     *
+     * Emits `close` with {@link CLOSE.CLIENT_GONE} and `willReconnect: false`
+     * when there was a socket to close; nothing when already idle, reconnecting
+     * or terminated.
      */
     disconnect(): void;
     /**
@@ -257,7 +306,8 @@ export declare class WSClient<TAuth = unknown> {
      * @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 {WSRemoteError} when connected and the server refuses — with code
+     * `unsupported` when it does not implement rooms at all
      * @throws {WSDisposedError} when the client was disposed
      *
      * @example
@@ -293,6 +343,73 @@ export declare class WSClient<TAuth = unknown> {
      * @returns a copy of the members; empty when the room has no presence
      */
     members(room: string): string[];
+    /**
+     * Sends a message to the server — the room-free way to talk to it, and all
+     * a core-only server has to understand.
+     *
+     * Fire-and-forget: resolves as soon as the frame is written to the socket.
+     * While disconnected it is buffered and resolves when flushed after the
+     * next connect — bounded by `sendTimeout`, never indefinitely. There is no
+     * delivery confirmation: a frame written into a connection that turns out
+     * to be dead is lost, exactly as with a plain `WebSocket`. Pass
+     * `{ ack: true }` when that matters.
+     *
+     * Safe to call without awaiting: the returned promise is marked handled,
+     * so a failure nobody awaits is not an unhandled rejection. Await it to
+     * learn about one.
+     *
+     * @param payload - opaque application data; never inspected or mutated
+     * @param options - see {@link WSSendOptions}
+     * @returns resolves once the frame is written to the socket
+     * @throws {WSTimeoutError} still buffered when `sendTimeout` elapsed
+     * @throws {WSOutboxDropError} evicted from a full outbox
+     * @throws {WSNotConnectedError} sent while offline with `outboxMaxSize: 0`
+     * @throws {WSTerminatedError} sent after a terminal close
+     *
+     * @example
+     * ```ts
+     * ws.send({ op: "cursor", x: 10, y: 20 });
+     * ```
+     */
+    send<T = unknown>(payload: T, options?: WSSendOptions & {
+        ack?: false;
+    }): Promise<void>;
+    /**
+     * Sends a message to the server and waits for its acknowledgement.
+     *
+     * Resolves with the reply the server put in the ack — which makes this a
+     * request/response call — or with `undefined` when it sent a bare ack.
+     * Buffered while disconnected like any other send, and one `sendTimeout`
+     * spans queue, flight and ack.
+     *
+     * @param payload - opaque application data; never inspected or mutated
+     * @param options - `{ ack: true }`
+     * @returns the server's reply, `undefined` when there was none
+     * @throws {WSRemoteError} the server rejected it with a `nack` — code
+     * `unsupported` when it accepts no messages at all
+     * @throws {WSTimeoutError} `sendTimeout` elapsed with no acknowledgement
+     * @throws {WSConnectionLostError} the socket closed before the ack arrived;
+     * the message was not resent
+     * @throws {WSOutboxDropError} evicted from a full outbox
+     * @throws {WSNotConnectedError} sent while offline with `outboxMaxSize: 0`
+     * @throws {WSTerminatedError} sent after a terminal close
+     *
+     * @example
+     * ```ts
+     * const doc = await ws.send<Doc>({ op: "load", id: 42 }, { ack: true });
+     * ```
+     */
+    send<R = unknown, T = unknown>(payload: T, options: WSSendOptions & {
+        ack: true;
+    }): Promise<R>;
+    /**
+     * Either of the above, decided at runtime by `options.ack`.
+     *
+     * @param payload - opaque application data; never inspected or mutated
+     * @param options - see {@link WSSendOptions}
+     * @returns `undefined` without an ack, the server's reply with one
+     */
+    send<T = unknown>(payload: T, options?: WSSendOptions): Promise<unknown>;
     /**
      * Publishes to a room within this client's namespace.
      *
@@ -309,6 +426,8 @@ export declare class WSClient<TAuth = unknown> {
      * @throws {WSTimeoutError} `sendTimeout` elapsed with no acknowledgement
      * @throws {WSOutboxDropError} evicted from a full outbox
      * @throws {WSNotConnectedError} sent while offline with `outboxMaxSize: 0`
+     * @throws {WSTerminatedError} sent after a terminal close, which only an
+     * explicit `connect()` recovers from — rejected at once, not buffered
      * @throws {WSRemoteError} the server rejected it with a `nack`
      */
     publish<T = unknown>(room: string, payload: T, namespace?: string): Promise<WSPublishResult>;
@@ -336,14 +455,21 @@ export declare class WSClient<TAuth = unknown> {
  * @param options - see {@link WSClientOptions}
  * @returns a client that has not connected yet
  *
- * @example
+ * @example Messages
  * ```ts
  * const ws = createWSClient({
  *     url: "wss://example.com/ws",
- *     namespace: "org-123",
  *     auth: () => session.token, // re-read on every reconnect
  * });
  *
+ * ws.on("message", (msg) => console.log(msg.payload));
+ * const reply = await ws.send({ op: "ping" }, { ack: true });
+ * ```
+ *
+ * @example Rooms
+ * ```ts
+ * const ws = createWSClient({ url: "wss://example.com/ws", namespace: "org-123" });
+ *
  * await ws.subscribe("chat", (msg) => console.log(msg.from, msg.payload));
  * await ws.publish("chat", { text: "hello" });
  * ```