@marianmeres/ws 0.4.1 → 0.5.0

package/dist/protocol/constants.d.ts

@@ -11,8 +11,13 @@
  *
  * It costs nothing today and it is the only thing that makes a breaking
  * protocol change survivable later.
+ *
+ * Version 2 split the protocol into a required **core** (handshake, messages
+ * in both directions, heartbeat) and an optional **rooms extension**
+ * (subscriptions, publishing, presence, broadcast), so a server that only
+ * needs a data channel implements the core and nothing else.
  */
-export declare const PROTOCOL_VERSION = 1;
+export declare const PROTOCOL_VERSION = 2;
 /** Namespace used when the client does not specify one. */
 export declare const DEFAULT_NAMESPACE = "default";
 /**
@@ -21,34 +26,43 @@ export declare const DEFAULT_NAMESPACE = "default";
  * Note these are *protocol* types and have nothing to do with whatever the
  * application puts inside `payload` — the payload is opaque and is never
  * inspected nor mutated by this library.
+ *
+ * Every server implements the **core** frames. The **rooms extension**
+ * frames are sent only when the application uses rooms (`subscribe()`,
+ * `publish()`, `broadcast()`, presence), so a server that does not support
+ * them never sees one.
  */
 export declare const FRAME: {
     /** Handshake. Always the first frame; carries the auth payload. */
     readonly AUTH: "auth";
-    /** Join one or more rooms, optionally with presence. */
-    readonly SUB: "sub";
-    /** Leave one or more rooms. */
-    readonly UNSUB: "unsub";
-    /** Publish into a room within the connection's own namespace. */
-    readonly PUB: "pub";
-    /** Publish into a room across every namespace. Gated server-side. */
-    readonly BROADCAST: "broadcast";
     /** Liveness probe. Answered with `pong`. */
     readonly PING: "ping";
-    /** Handshake accepted; carries the assigned id, namespace and version. */
+    /** Handshake accepted; carries the protocol version (and, with rooms, identity). */
     readonly HELLO: "hello";
-    /** Positive acknowledgement of a correlated request. */
+    /** Positive acknowledgement of a frame that carried an `id`; may carry a reply. */
     readonly ACK: "ack";
     /** Negative acknowledgement; carries a `WSErrorInfo`. */
     readonly NACK: "nack";
-    /** A message delivered to a subscribed room. */
-    readonly MSG: "msg";
-    /** A membership change in a presence-enabled room. */
-    readonly PRESENCE: "presence";
     /** Reply to `ping`. */
     readonly PONG: "pong";
     /** Uncorrelated error — not tied to any request id. */
     readonly ERROR: "error";
+    /**
+     * A message. Client -> server it is addressed to the server itself;
+     * server -> client it is either a direct message (core) or a room delivery
+     * (rooms extension, recognisable by its `room` field).
+     */
+    readonly MSG: "msg";
+    /** Join one or more rooms, optionally with presence. */
+    readonly SUB: "sub";
+    /** Leave one or more rooms. */
+    readonly UNSUB: "unsub";
+    /** Publish into a room within the connection's own namespace. */
+    readonly PUB: "pub";
+    /** Publish into a room across every namespace. Gated server-side. */
+    readonly BROADCAST: "broadcast";
+    /** A membership change in a presence-enabled room. */
+    readonly PRESENCE: "presence";
 };
 /**
  * WebSocket close codes.
@@ -99,10 +113,15 @@ export declare const ERROR_CODE: {
     readonly BAD_REQUEST: "bad_request";
     /** Frame rate cap exceeded. */
     readonly RATE_LIMITED: "rate_limited";
+    /**
+     * A frame type this server does not implement — typically a rooms frame
+     * sent to a core-only server, or a `msg` to a server with no handler.
+     */
+    readonly UNSUPPORTED: "unsupported";
     /** Unexpected server-side failure. */
     readonly INTERNAL: "internal";
 };
-/** Presence event kinds. */
+/** Presence event kinds (rooms extension). */
 export declare const PRESENCE: {
     /** Full membership snapshot, sent on every (re)subscribe. */
     readonly SYNC: "sync";

package/dist/protocol/constants.js

@@ -11,8 +11,13 @@
  *
  * It costs nothing today and it is the only thing that makes a breaking
  * protocol change survivable later.
+ *
+ * Version 2 split the protocol into a required **core** (handshake, messages
+ * in both directions, heartbeat) and an optional **rooms extension**
+ * (subscriptions, publishing, presence, broadcast), so a server that only
+ * needs a data channel implements the core and nothing else.
  */
-export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = 2;
 /** Namespace used when the client does not specify one. */
 export const DEFAULT_NAMESPACE = "default";
 /**
@@ -21,36 +26,48 @@ export const DEFAULT_NAMESPACE = "default";
  * Note these are *protocol* types and have nothing to do with whatever the
  * application puts inside `payload` — the payload is opaque and is never
  * inspected nor mutated by this library.
+ *
+ * Every server implements the **core** frames. The **rooms extension**
+ * frames are sent only when the application uses rooms (`subscribe()`,
+ * `publish()`, `broadcast()`, presence), so a server that does not support
+ * them never sees one.
  */
 export const FRAME = {
-    // client -> server
+    // core, client -> server
     /** Handshake. Always the first frame; carries the auth payload. */
     AUTH: "auth",
-    /** Join one or more rooms, optionally with presence. */
-    SUB: "sub",
-    /** Leave one or more rooms. */
-    UNSUB: "unsub",
-    /** Publish into a room within the connection's own namespace. */
-    PUB: "pub",
-    /** Publish into a room across every namespace. Gated server-side. */
-    BROADCAST: "broadcast",
     /** Liveness probe. Answered with `pong`. */
     PING: "ping",
-    // server -> client
-    /** Handshake accepted; carries the assigned id, namespace and version. */
+    // core, server -> client
+    /** Handshake accepted; carries the protocol version (and, with rooms, identity). */
     HELLO: "hello",
-    /** Positive acknowledgement of a correlated request. */
+    /** Positive acknowledgement of a frame that carried an `id`; may carry a reply. */
     ACK: "ack",
     /** Negative acknowledgement; carries a `WSErrorInfo`. */
     NACK: "nack",
-    /** A message delivered to a subscribed room. */
-    MSG: "msg",
-    /** A membership change in a presence-enabled room. */
-    PRESENCE: "presence",
     /** Reply to `ping`. */
     PONG: "pong",
     /** Uncorrelated error — not tied to any request id. */
     ERROR: "error",
+    // core, both directions
+    /**
+     * A message. Client -> server it is addressed to the server itself;
+     * server -> client it is either a direct message (core) or a room delivery
+     * (rooms extension, recognisable by its `room` field).
+     */
+    MSG: "msg",
+    // rooms extension, client -> server
+    /** Join one or more rooms, optionally with presence. */
+    SUB: "sub",
+    /** Leave one or more rooms. */
+    UNSUB: "unsub",
+    /** Publish into a room within the connection's own namespace. */
+    PUB: "pub",
+    /** Publish into a room across every namespace. Gated server-side. */
+    BROADCAST: "broadcast",
+    // rooms extension, server -> client
+    /** A membership change in a presence-enabled room. */
+    PRESENCE: "presence",
 };
 /**
  * WebSocket close codes.
@@ -104,10 +121,15 @@ export const ERROR_CODE = {
     BAD_REQUEST: "bad_request",
     /** Frame rate cap exceeded. */
     RATE_LIMITED: "rate_limited",
+    /**
+     * A frame type this server does not implement — typically a rooms frame
+     * sent to a core-only server, or a `msg` to a server with no handler.
+     */
+    UNSUPPORTED: "unsupported",
     /** Unexpected server-side failure. */
     INTERNAL: "internal",
 };
-/** Presence event kinds. */
+/** Presence event kinds (rooms extension). */
 export const PRESENCE = {
     /** Full membership snapshot, sent on every (re)subscribe. */
     SYNC: "sync",

package/dist/protocol/errors.d.ts

@@ -58,7 +58,12 @@ export declare class WSConnectTimeoutError extends WSError {
      */
     constructor(ms: number);
 }
-/** `sendTimeout` elapsed while queued, in flight, or awaiting an ack. */
+/**
+ * `sendTimeout` elapsed while queued, in flight, or awaiting an ack.
+ *
+ * A send that awaits no ack — `send()` without `{ ack: true }` — can only hit
+ * this while still queued, i.e. when no connection came up in time.
+ */
 export declare class WSTimeoutError extends WSError {
     /**
      * Reports the deadline that was exceeded.
@@ -80,7 +85,12 @@ export declare class WSOutboxDropError extends WSError {
 export declare class WSConnectionLostError extends WSError {
     constructor();
 }
-/** The server rejected the operation with a `nack`. */
+/**
+ * The server rejected the operation with a `nack`.
+ *
+ * Also the way a server-side `onMessage` hook rejects a message on purpose:
+ * throw one, and its `code` and `message` travel back in the `nack` unchanged.
+ */
 export declare class WSRemoteError extends WSError {
     /** Machine-readable code from the server — see `ERROR_CODE`. */
     readonly code: string;

package/dist/protocol/errors.js

@@ -64,7 +64,12 @@ export class WSConnectTimeoutError extends WSError {
         super(`Not connected within ${ms}ms (still retrying in background)`);
     }
 }
-/** `sendTimeout` elapsed while queued, in flight, or awaiting an ack. */
+/**
+ * `sendTimeout` elapsed while queued, in flight, or awaiting an ack.
+ *
+ * A send that awaits no ack — `send()` without `{ ack: true }` — can only hit
+ * this while still queued, i.e. when no connection came up in time.
+ */
 export class WSTimeoutError extends WSError {
     /**
      * Reports the deadline that was exceeded.
@@ -72,7 +77,7 @@ export class WSTimeoutError extends WSError {
      * @param ms - the elapsed `sendTimeout`
      */
     constructor(ms) {
-        super(`No acknowledgement within ${ms}ms`);
+        super(`Send not completed within ${ms}ms`);
     }
 }
 /** The frame was evicted from a full outbox before it could be sent. */
@@ -92,7 +97,12 @@ export class WSConnectionLostError extends WSError {
         super("The connection closed before the server acknowledged the frame; it was not resent");
     }
 }
-/** The server rejected the operation with a `nack`. */
+/**
+ * The server rejected the operation with a `nack`.
+ *
+ * Also the way a server-side `onMessage` hook rejects a message on purpose:
+ * throw one, and its `code` and `message` travel back in the `nack` unchanged.
+ */
 export class WSRemoteError extends WSError {
     /** Machine-readable code from the server — see `ERROR_CODE`. */
     code;

package/dist/protocol/frames.d.ts

@@ -7,6 +7,11 @@
  * application. Your payload may contain its own `type` field and nothing will
  * collide.
  *
+ * The frames come in two layers. The **core** — `auth`/`hello`, `msg` in both
+ * directions, `ack`/`nack`, `ping`/`pong`, `error` — is all a server must
+ * implement. The **rooms extension** — `sub`, `unsub`, `pub`, `broadcast`,
+ * `presence`, and the routing fields on a delivered `msg` — is opt-in.
+ *
  * @module
  */
 import type { FRAME, PRESENCE } from "./constants.js";
@@ -18,23 +23,45 @@ export interface WSErrorInfo {
     message: string;
 }
 /**
- * A message as delivered to application code.
+ * A message as delivered to application code — the `message` event fires
+ * with one for every inbound `msg` frame.
  *
  * A `msg` frame minus its `type` field *is* a `WSMessage` — there is no
  * translation layer and no divergence between wire names and API names.
+ *
+ * Only `payload` is guaranteed. A direct message from the server (core) has
+ * nothing else; a message delivered through a room (rooms extension) carries
+ * every routing field — see {@link WSRoomMessage}. `room` tells them apart.
  */
 export interface WSMessage<T = unknown> {
+    /** Opaque application payload. */
+    payload: T;
+    /** Room the message was published to. Absent on a direct message. */
+    room?: string;
+    /** Namespace the message belongs to. Absent on a direct message. */
+    namespace?: string;
+    /**
+     * Originating client id, `null` when injected server-side. Absent on a
+     * direct message, which always comes from the server.
+     */
+    from?: string | null;
+    /** Server-assigned epoch milliseconds. Absent on a direct message. */
+    timestamp?: number;
+}
+/**
+ * A message delivered through a room (rooms extension). This is what room
+ * handlers receive: every routing field is present.
+ */
+export interface WSRoomMessage<T = unknown> extends WSMessage<T> {
     /** Room the message was published to. */
     room: string;
-    /** Namespace the message belongs to. */
+    /** Namespace the message belongs to — always the receiver's own. */
     namespace: string;
     /**
      * Originating client id, or `null` when the message was injected
      * server-side (via the service API or the HTTP routes).
      */
     from: string | null;
-    /** Opaque application payload. */
-    payload: T;
     /** Server-assigned epoch milliseconds. */
     timestamp: number;
 }
@@ -42,7 +69,7 @@ export interface WSMessage<T = unknown> {
 export type PresenceEventType = (typeof PRESENCE)[keyof typeof PRESENCE];
 /**
  * A membership change in a room the client subscribed to with presence
- * enabled.
+ * enabled (rooms extension).
  *
  * `sync` carries the full snapshot and is emitted on every (re)subscribe —
  * crucially including after a reconnect, when membership may have changed
@@ -62,7 +89,7 @@ export interface WSPresenceEvent {
     /** Server-assigned epoch milliseconds. */
     timestamp: number;
 }
-/** A single room subscription request. */
+/** A single room subscription request (rooms extension). */
 export interface SubRequest {
     /** Room name to join. */
     room: string;
@@ -72,12 +99,24 @@ export interface SubRequest {
 /** Frames sent by the client. */
 export type ClientFrame = {
     type: typeof FRAME.AUTH;
-    id: string;
+    /**
+     * Not sent since protocol 2 and never acknowledged. Kept optional so a
+     * server keeps accepting a protocol-1 client that still sends it.
+     */
+    id?: string;
     protocol: number;
     payload: unknown;
     /** Preferred client id — the server may override it. */
     clientId?: string;
+    /** Requested namespace — sent only when the application chose one. */
     namespace?: string;
+} | {
+    type: typeof FRAME.MSG;
+    /** Present only when the sender awaits an `ack`/`nack`. */
+    id?: string;
+    payload: unknown;
+} | {
+    type: typeof FRAME.PING;
 } | {
     type: typeof FRAME.SUB;
     id: string;
@@ -97,36 +136,39 @@ export type ClientFrame = {
     id: string;
     room: string;
     payload: unknown;
-} | {
-    type: typeof FRAME.PING;
 };
 /** Frames sent by the server. */
 export type ServerFrame = {
     type: typeof FRAME.HELLO;
-    clientId: string;
-    namespace: string;
     protocol: number;
+    /** Assigned client id. Optional in the core; always sent with rooms. */
+    clientId?: string;
+    /** Assigned namespace. Optional in the core; always sent with rooms. */
+    namespace?: string;
 } | {
     type: typeof FRAME.ACK;
     id: string;
+    /** Delivery count, on `pub`/`broadcast` acks only. */
     recipients?: number;
+    /** The server's reply, on `msg` acks only. Any JSON value. */
+    payload?: unknown;
 } | {
     type: typeof FRAME.NACK;
     id: string;
     error: WSErrorInfo;
 } | ({
     type: typeof FRAME.MSG;
-} & WSMessage) | ({
-    type: typeof FRAME.PRESENCE;
-} & WSPresenceEvent) | {
+} & WSMessage) | {
     type: typeof FRAME.PONG;
 } | {
     type: typeof FRAME.ERROR;
     error: WSErrorInfo;
-};
+} | ({
+    type: typeof FRAME.PRESENCE;
+} & WSPresenceEvent);
 /** Any frame, in either direction. */
 export type WSFrame = ClientFrame | ServerFrame;
-/** Result of a successful `publish()` / `broadcast()`. */
+/** Result of a successful `publish()` / `broadcast()` (rooms extension). */
 export interface WSPublishResult {
     /**
      * Sockets the message was handed to **on the receiving server instance**.

package/dist/protocol/frames.js

@@ -7,6 +7,11 @@
  * application. Your payload may contain its own `type` field and nothing will
  * collide.
  *
+ * The frames come in two layers. The **core** — `auth`/`hello`, `msg` in both
+ * directions, `ack`/`nack`, `ping`/`pong`, `error` — is all a server must
+ * implement. The **rooms extension** — `sub`, `unsub`, `pub`, `broadcast`,
+ * `presence`, and the routing fields on a delivered `msg` — is opt-in.
+ *
  * @module
  */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/ws",
-	"version": "0.4.1",
+	"version": "0.5.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",