@znight/websocket 0.0.0-stage → 0.6.0

package/dist/server-CI_Bh9o1.d.mts

@@ -0,0 +1,331 @@
+import { a as TransportSocket, n as SendStatus, r as SocketEvents } from "./transport-xnJqvB93.mjs";
+import { HttpContext } from "@znight/http";
+/** The token bucket of `@Gateway({ rateLimit })` (RFC 0003 §8.6), one per connection. */
+declare class TokenBucket {
+  #private;
+  /** `messages` per `intervalMs`, refilled continuously; full at first. */
+  constructor(messages: number, intervalMs: number, now?: number);
+  /** Takes one token: `false` when the bucket is empty. */
+  take(now?: number): boolean;
+}
+/** Event names: `^[A-Za-z][\w.:/-]{0,127}$`; names starting with `$` are reserved. */
+declare const EVENT_NAME: RegExp;
+/** A message id: a string of at most 64 characters or a safe integer, chosen by the client. */
+type MessageId = string | number;
+/** A decoded inbound message. */
+interface InboundMessage {
+  readonly event: string;
+  readonly data: unknown;
+  /** Present when the client expects exactly one reply. */
+  readonly id: MessageId | undefined;
+}
+/** A frame that could not be decoded: answered with `$error` (or a reply when the id was readable). */
+interface InboundFailure {
+  readonly error: string;
+  readonly message: string;
+  readonly id: MessageId | undefined;
+}
+/** The wire error of a reply or of an `$error` event. */
+interface WireError {
+  readonly code: string;
+  readonly message: string;
+  readonly details?: unknown;
+}
+/** Whether `value` is a valid message id. */
+declare function isMessageId(value: unknown): value is MessageId;
+/**
+ * Decodes an inbound frame of an `events` gateway with the JSON codec: a binary frame is
+ * `UNSUPPORTED_FRAME`, anything but a JSON object with a string `event` is `BAD_FRAME`. Unknown
+ * fields are ignored.
+ */
+declare function decodeFrame(frame: string | Uint8Array): InboundMessage | InboundFailure;
+/** Whether a decoded frame is a failure. */
+declare function isFailure(decoded: InboundMessage | InboundFailure): decoded is InboundFailure;
+/** A success reply: `{ id, data }`, `data` omitted when `undefined`. */
+declare function encodeReply(id: MessageId, data: unknown): string;
+/** A failure reply: `{ id, error }`. */
+declare function encodeErrorReply(id: MessageId, error: WireError): string;
+/** A server event: `{ event, data }`. */
+declare function encodeEvent(event: string, data: unknown): string;
+/** The failure of a message without id: `{ event: '$error', data: { event, code, message, details? } }`. */
+declare function encodeErrorEvent(event: string | undefined, error: WireError): string;
+/** An outbound frame of an `events` gateway, before encoding. */
+type OutboundMessage = {
+  readonly kind: "event";
+  readonly event: string;
+  readonly data: unknown;
+} | {
+  readonly kind: "reply";
+  readonly id: MessageId;
+  readonly data: unknown;
+} | {
+  readonly kind: "error";
+  readonly id: MessageId | undefined;
+  readonly event: string | undefined;
+  readonly error: WireError;
+};
+/**
+ * The codec of `events` gateways (`WebSocketPlugin` option `codec`): how frames are decoded into
+ * `{ event, data, id }` and how outbound messages are encoded. The default is {@link jsonCodec};
+ * a custom codec may carry MessagePack over binary frames, for instance.
+ */
+interface WsCodec {
+  /** Decodes an inbound frame; a failure is answered with its code (`BAD_FRAME`...). */
+  decode(frame: string | Uint8Array, binary: boolean): InboundMessage | InboundFailure;
+  /** Encodes an outbound message: a string is a text frame, bytes a binary frame. */
+  encode(message: OutboundMessage): string | Uint8Array;
+}
+/** The default codec: UTF-8 JSON text frames (RFC 0003 §5.3); binary frames are `UNSUPPORTED_FRAME`. */
+declare const jsonCodec: WsCodec;
+/** What a room holds: a connection, seen through the operations rooms need. */
+interface ChannelMember {
+  readonly id: string;
+  /** The rooms of the member, kept in sync by the channel. */
+  readonly roomSet: Set<string>;
+  /** Sends an already encoded frame (`string`: text, `Uint8Array`: binary). */
+  sendFrame(frame: string | Uint8Array): unknown;
+  close(code?: number, reason?: string): void;
+}
+/** A target of `except()`: a member or its id. */
+type MemberRef<M extends ChannelMember = ChannelMember> = M | string;
+/** A selection of members of a gateway (RFC 0003 §5.4). */
+interface Broadcast<E extends object = Record<string, unknown>, M extends ChannelMember = ChannelMember> {
+  to(room: string | readonly string[]): Broadcast<E, M>;
+  except(target: MemberRef<M> | readonly MemberRef<M>[]): Broadcast<E, M>;
+  exceptRoom(room: string | readonly string[]): Broadcast<E, M>;
+  emit<K extends keyof E & string>(event: K, data: E[K]): void;
+  send(frame: string | Uint8Array): void;
+  join(room: string): void;
+  leave(room: string): void;
+  close(code?: number, reason?: string): void;
+}
+interface Selection {
+  /** `undefined`: every member of the gateway. */
+  readonly rooms: readonly string[] | undefined;
+  readonly except: ReadonlySet<string>;
+  readonly exceptRooms: readonly string[];
+}
+/** The members and rooms of one gateway. */
+declare class RoomRegistry<M extends ChannelMember = ChannelMember> {
+  #private;
+  /** Encodes the events of broadcasts (once per broadcast). */
+  readonly codec: WsCodec;
+  constructor(codec?: WsCodec);
+  /** Open members. */
+  get size(): number;
+  add(member: M): void;
+  /** Removes the member and leaves its rooms. */
+  remove(member: M): void;
+  get(id: string): M | undefined;
+  members(): IterableIterator<M>;
+  join(member: M, room: string): void;
+  leave(member: M, room: string): void;
+  /** The members of `room` (a read-only view). */
+  room(room: string): ReadonlySet<M>;
+  /** Room → size. */
+  rooms(): ReadonlyMap<string, number>;
+  /** A broadcast over every member, or over the members of `rooms`. */
+  select<E extends object>(rooms?: string | readonly string[], except?: readonly string[]): Broadcast<E, M>;
+  /** @internal The members a selection designates, each once. */
+  resolve(selection: Selection): M[];
+}
+/** Who closed a connection. */
+type WsCloseInitiator = "client" | "server" | "shutdown" | "heartbeat" | "backpressure" | "error";
+/** How a connection closed. */
+interface WsCloseInfo {
+  readonly code: number;
+  readonly reason: string;
+  readonly initiator: WsCloseInitiator;
+}
+/** The result of a send: written, buffered by the transport, or dropped. */
+type WsSendResult = SendStatus;
+/** `conn.drained()` rejects with it once the connection is closed. */
+declare class WsClosedError extends Error {
+  constructor(message?: string);
+}
+/** A WebSocket connection, as handlers and services see it. */
+interface WsConnection<TData extends object = Record<string, unknown>, E extends object = Record<string, unknown>> {
+  readonly id: string;
+  /** Path pattern of the gateway, prefix included (`/api/chat`). */
+  readonly gateway: string;
+  /** The request id of the handshake. */
+  readonly requestId: string;
+  /** The handshake, detached from its socket. */
+  readonly handshake: HttpContext;
+  readonly params: Readonly<Record<string, string>>;
+  /** The negotiated subprotocol, `''` when none. */
+  readonly protocol: string;
+  /** Per-connection state, an empty object at first. */
+  readonly data: TData;
+  readonly rooms: ReadonlySet<string>;
+  readonly readyState: "open" | "closing" | "closed";
+  readonly bufferedAmount: number;
+  /** Aborted when the connection starts closing. */
+  readonly signal: AbortSignal;
+  /** How the connection closed: set once the socket closed, before `@OnDisconnect`. */
+  readonly closeInfo: WsCloseInfo | undefined;
+  emit<K extends keyof E & string>(event: K, data: E[K]): WsSendResult;
+  send(frame: string | Uint8Array): WsSendResult;
+  join(room: string | readonly string[]): void;
+  leave(room: string): void;
+  /** The other members of `room`. */
+  to(room: string | readonly string[]): Broadcast<E>;
+  /** Resolves once the outbound buffer is below `limit / 4`; rejects with {@link WsClosedError} once closed. */
+  drained(): Promise<void>;
+  close(code?: number, reason?: string): void;
+  terminate(): void;
+}
+/** Limits of one connection, resolved from the gateway and the plugin options. */
+interface ConnectionLimits {
+  readonly maxPayload: number;
+  readonly maxPendingMessages: number;
+  readonly concurrency: number;
+  readonly backpressureLimit: number;
+  readonly onBackpressure: "close" | "drop";
+  readonly closeTimeoutMs: number;
+  readonly rateLimit?: {
+    readonly bucket: TokenBucket;
+    readonly onLimit: "reject" | "close";
+  };
+}
+/** What the plugin does with a connection (the gateway semantics). */
+interface ConnectionDriver {
+  /** Runs `@OnConnect`; a rejection closes the connection with the code it returns. */
+  connect(conn: WsConnectionImpl): Promise<void>;
+  /** Handles one inbound message (decode, guards, handler, reply). Never rejects. */
+  dispatch(conn: WsConnectionImpl, frame: string | Uint8Array, binary: boolean): Promise<void>;
+  /** A message refused by the rate limit with `onLimit: 'reject'`. */
+  rateLimited(conn: WsConnectionImpl, frame: string | Uint8Array, binary: boolean): void;
+  /** The close code of an `@OnConnect` failure. */
+  connectFailure(error: unknown): {
+    readonly code: number;
+    readonly reason: string;
+  };
+  /** Runs `@OnDisconnect` (errors handled by the driver). */
+  disconnect(conn: WsConnectionImpl): Promise<void>;
+  /** Once fully closed (rooms left): hooks, stats, scope release. */
+  closed(conn: WsConnectionImpl, info: WsCloseInfo): void;
+}
+/** Totals of the plugin (`WebSocketPlugin.stats()`), updated by the connections. */
+interface WsStats {
+  /** Open connections. */
+  readonly connections: number;
+  readonly opened: number;
+  readonly closed: number;
+  readonly messagesIn: number;
+  readonly messagesOut: number;
+  readonly bytesIn: number;
+  readonly bytesOut: number;
+  /** Outbound frames dropped by a `drop` backpressure policy or refused by the transport. */
+  readonly dropped: number;
+  /** Connections closed with `1013` (slow consumer). */
+  readonly slowConsumerCloses: number;
+}
+/** The mutable counters behind {@link WsStats} (internal). */
+declare class StatsCounter {
+  opened: number;
+  closed: number;
+  messagesIn: number;
+  messagesOut: number;
+  bytesIn: number;
+  bytesOut: number;
+  dropped: number;
+  slowConsumerCloses: number;
+  /** A frozen snapshot, with the number of open connections. */
+  snapshot(connections: number): WsStats;
+}
+/** What a connection is created with. */
+interface ConnectionInit {
+  readonly id: string;
+  readonly gateway: string;
+  readonly handshake: HttpContext;
+  readonly protocol: string;
+  readonly limits: ConnectionLimits;
+  readonly rooms: RoomRegistry<WsConnectionImpl>;
+  readonly driver: ConnectionDriver;
+  /** Counters shared by the connections of a plugin. */
+  readonly stats?: StatsCounter;
+}
+/** The implementation of {@link WsConnection} (internal to the package). */
+declare class WsConnectionImpl implements WsConnection, ChannelMember {
+  #private;
+  readonly id: string;
+  readonly gateway: string;
+  readonly handshake: HttpContext;
+  readonly protocol: string;
+  readonly data: Record<string, unknown>;
+  readonly roomSet: Set<string>;
+  constructor(init: ConnectionInit);
+  get requestId(): string;
+  get params(): Readonly<Record<string, string>>;
+  get rooms(): ReadonlySet<string>;
+  get readyState(): "open" | "closing" | "closed";
+  get bufferedAmount(): number;
+  get signal(): AbortSignal;
+  get closeInfo(): WsCloseInfo | undefined;
+  /** Resolves once the connection is fully closed. */
+  get finished(): Promise<WsCloseInfo>;
+  /** The socket events to give to the transport. */
+  socketEvents(): SocketEvents;
+  /** Binds the accepted socket, joins the gateway and runs `@OnConnect` as the first task. */
+  start(socket: TransportSocket): void;
+  emit(event: string, data: unknown): WsSendResult;
+  send(frame: string | Uint8Array): WsSendResult;
+  /** Sends an encoded frame through the backpressure policy. */
+  sendFrame(frame: string | Uint8Array): WsSendResult;
+  join(room: string | readonly string[]): void;
+  leave(room: string): void;
+  to(room: string | readonly string[]): Broadcast;
+  drained(): Promise<void>;
+  close(code?: number, reason?: string): void;
+  /** Closes with an initiator (shutdown, heartbeat...). */
+  closeWith(code: number, reason: string, initiator: WsCloseInitiator): void;
+  terminate(): void;
+  /** Terminates without close frame (heartbeat timeout, shutdown deadline...): local code `1006`. */
+  terminateWith(initiator: WsCloseInitiator): void;
+  /**
+   * One heartbeat tick (RFC 0003 §8.7): a connection not seen alive since the previous tick is
+   * terminated, the others are marked and pinged.
+   */
+  heartbeat(): void;
+}
+/** A gateway class or its declared path (`'/chat'`, without the HTTP prefix). */
+type GatewayRef = (abstract new (...args: never[]) => object) | string;
+/** The connections and rooms of one gateway (this process). */
+interface GatewayChannel<E extends object = Record<string, unknown>> {
+  /** The gateway path, prefix included. */
+  readonly path: string;
+  readonly size: number;
+  connection(id: string): WsConnection | undefined;
+  connections(): IterableIterator<WsConnection>;
+  members(room: string): ReadonlySet<WsConnection>;
+  rooms(): ReadonlyMap<string, number>;
+  to(room: string | readonly string[]): Broadcast<E>;
+  except(target: MemberRef<WsConnectionImpl> | readonly MemberRef<WsConnectionImpl>[]): Broadcast<E>;
+  emit<K extends keyof E & string>(event: K, data: E[K]): void;
+  send(frame: string | Uint8Array): void;
+}
+/** One served gateway, as registered by the plugin. */
+interface ServedGateway {
+  /** The gateway class. */
+  readonly type: abstract new (...args: never[]) => object;
+  /** The declared path, without the prefix. */
+  readonly declaredPath: string;
+  /** The path, prefix included. */
+  readonly path: string;
+  readonly rooms: RoomRegistry<WsConnectionImpl>;
+}
+/** The gateways of the application: injectable singleton provided by `WebSocketPlugin`. */
+declare class WsServer {
+  #private;
+  /** @internal Called by the plugin at bootstrap. */
+  register(gateway: ServedGateway): void;
+  /** @internal Called by the plugin when it serves a new application. */
+  reset(): void;
+  /** Open connections of every gateway of this process. */
+  get connections(): number;
+  /** A lazy handle on a gateway: its class or its declared path. */
+  of<E extends object = Record<string, unknown>>(gateway: GatewayRef): GatewayChannel<E>;
+}
+export { TokenBucket as A, encodeErrorEvent as C, isFailure as D, encodeReply as E, isMessageId as O, decodeFrame as S, encodeEvent as T, InboundMessage as _, WsCloseInfo as a, WireError as b, WsConnection as c, Broadcast as d, ChannelMember as f, InboundFailure as g, EVENT_NAME as h, WsServer as i, jsonCodec as k, WsSendResult as l, RoomRegistry as m, GatewayRef as n, WsCloseInitiator as o, MemberRef as p, ServedGateway as r, WsClosedError as s, GatewayChannel as t, WsStats as u, MessageId as v, encodeErrorReply as w, WsCodec as x, OutboundMessage as y };
+//# sourceMappingURL=server-CI_Bh9o1.d.mts.map

package/dist/server-D40_bC88.mjs

@@ -0,0 +1,72 @@
+// src/server.ts
+/** The gateways of the application: injectable singleton provided by `WebSocketPlugin`. */
+var WsServer = class {
+	#byType = /* @__PURE__ */ new Map();
+	#byPath = /* @__PURE__ */ new Map();
+	/** @internal Called by the plugin at bootstrap. */
+	register(gateway) {
+		this.#byType.set(gateway.type, gateway);
+		this.#byPath.set(gateway.declaredPath, gateway);
+	}
+	/** @internal Called by the plugin when it serves a new application. */
+	reset() {
+		this.#byType.clear();
+		this.#byPath.clear();
+	}
+	/** Open connections of every gateway of this process. */
+	get connections() {
+		let total = 0;
+		for (const gateway of this.#byType.values()) total += gateway.rooms.size;
+		return total;
+	}
+	/** A lazy handle on a gateway: its class or its declared path. */
+	of(gateway) {
+		return new Channel(() => {
+			const served = typeof gateway === "string" ? this.#byPath.get(gateway) : this.#byType.get(gateway);
+			if (served === void 0) {
+				const name = typeof gateway === "string" ? `"${gateway}"` : gateway.name;
+				throw new TypeError(`WsServer.of(${name}): no gateway is served for it (or WebSocketPlugin is not bootstrapped)`);
+			}
+			return served;
+		});
+	}
+};
+var Channel = class {
+	#resolve;
+	constructor(resolve) {
+		this.#resolve = resolve;
+	}
+	get path() {
+		return this.#resolve().path;
+	}
+	get size() {
+		return this.#resolve().rooms.size;
+	}
+	connection(id) {
+		return this.#resolve().rooms.get(id);
+	}
+	connections() {
+		return this.#resolve().rooms.members();
+	}
+	members(room) {
+		return this.#resolve().rooms.room(room);
+	}
+	rooms() {
+		return this.#resolve().rooms.rooms();
+	}
+	to(room) {
+		return this.#resolve().rooms.select(room);
+	}
+	except(target) {
+		return this.#resolve().rooms.select().except(target);
+	}
+	emit(event, data) {
+		this.#resolve().rooms.select().emit(event, data);
+	}
+	send(frame) {
+		this.#resolve().rooms.select().send(frame);
+	}
+};
+export { WsServer as t };
+
+//# sourceMappingURL=server-D40_bC88.mjs.map

package/dist/server-D40_bC88.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-D40_bC88.mjs","names":[],"sources":["../src/server.ts"],"sourcesContent":["/**\n * `WsServer` and `GatewayChannel` (RFC 0003 §5.4): the injectable view of the gateways, their\n * connections and rooms. `of()` is lazy: it never throws, a handle of an unknown gateway throws a\n * `TypeError` when used.\n */\nimport type { WsConnection, WsConnectionImpl } from './connection.ts'\nimport type { Broadcast, MemberRef, RoomRegistry } from './rooms.ts'\n\n/** A gateway class or its declared path (`'/chat'`, without the HTTP prefix). */\nexport type GatewayRef = (abstract new (...args: never[]) => object) | string\n\n/** The connections and rooms of one gateway (this process). */\nexport interface GatewayChannel<E extends object = Record<string, unknown>> {\n  /** The gateway path, prefix included. */\n  readonly path: string\n  readonly size: number\n  connection(id: string): WsConnection | undefined\n  connections(): IterableIterator<WsConnection>\n  members(room: string): ReadonlySet<WsConnection>\n  rooms(): ReadonlyMap<string, number>\n  to(room: string | readonly string[]): Broadcast<E>\n  except(target: MemberRef<WsConnectionImpl> | readonly MemberRef<WsConnectionImpl>[]): Broadcast<E>\n  emit<K extends keyof E & string>(event: K, data: E[K]): void\n  send(frame: string | Uint8Array): void\n}\n\n/** One served gateway, as registered by the plugin. */\nexport interface ServedGateway {\n  /** The gateway class. */\n  readonly type: abstract new (\n    ...args: never[]\n  ) => object\n  /** The declared path, without the prefix. */\n  readonly declaredPath: string\n  /** The path, prefix included. */\n  readonly path: string\n  readonly rooms: RoomRegistry<WsConnectionImpl>\n}\n\n/** The gateways of the application: injectable singleton provided by `WebSocketPlugin`. */\nexport class WsServer {\n  readonly #byType = new Map<unknown, ServedGateway>()\n  readonly #byPath = new Map<string, ServedGateway>()\n\n  /** @internal Called by the plugin at bootstrap. */\n  register(gateway: ServedGateway): void {\n    this.#byType.set(gateway.type, gateway)\n    this.#byPath.set(gateway.declaredPath, gateway)\n  }\n\n  /** @internal Called by the plugin when it serves a new application. */\n  reset(): void {\n    this.#byType.clear()\n    this.#byPath.clear()\n  }\n\n  /** Open connections of every gateway of this process. */\n  get connections(): number {\n    let total = 0\n    for (const gateway of this.#byType.values()) total += gateway.rooms.size\n    return total\n  }\n\n  /** A lazy handle on a gateway: its class or its declared path. */\n  of<E extends object = Record<string, unknown>>(gateway: GatewayRef): GatewayChannel<E> {\n    return new Channel<E>(() => {\n      const served = typeof gateway === 'string' ? this.#byPath.get(gateway) : this.#byType.get(gateway)\n      if (served === undefined) {\n        const name = typeof gateway === 'string' ? `\"${gateway}\"` : gateway.name\n        throw new TypeError(\n          `WsServer.of(${name}): no gateway is served for it (or WebSocketPlugin is not bootstrapped)`,\n        )\n      }\n      return served\n    })\n  }\n}\n\nclass Channel<E extends object> implements GatewayChannel<E> {\n  readonly #resolve: () => ServedGateway\n\n  constructor(resolve: () => ServedGateway) {\n    this.#resolve = resolve\n  }\n\n  get path(): string {\n    return this.#resolve().path\n  }\n\n  get size(): number {\n    return this.#resolve().rooms.size\n  }\n\n  connection(id: string): WsConnection | undefined {\n    return this.#resolve().rooms.get(id)\n  }\n\n  connections(): IterableIterator<WsConnection> {\n    return this.#resolve().rooms.members()\n  }\n\n  members(room: string): ReadonlySet<WsConnection> {\n    return this.#resolve().rooms.room(room)\n  }\n\n  rooms(): ReadonlyMap<string, number> {\n    return this.#resolve().rooms.rooms()\n  }\n\n  to(room: string | readonly string[]): Broadcast<E> {\n    return this.#resolve().rooms.select<E>(room)\n  }\n\n  except(target: MemberRef<WsConnectionImpl> | readonly MemberRef<WsConnectionImpl>[]): Broadcast<E> {\n    return this.#resolve().rooms.select<E>().except(target)\n  }\n\n  emit<K extends keyof E & string>(event: K, data: E[K]): void {\n    this.#resolve().rooms.select<E>().emit(event, data)\n  }\n\n  send(frame: string | Uint8Array): void {\n    this.#resolve().rooms.select<E>().send(frame)\n  }\n}\n"],"mappings":";;AAwCA,IAAa,WAAb,MAAsB;CACpB,0BAAmB,IAAI,IAA4B;CACnD,0BAAmB,IAAI,IAA2B;;CAGlD,SAAS,SAA8B;EACrC,KAAK,QAAQ,IAAI,QAAQ,MAAM,OAAO;EACtC,KAAK,QAAQ,IAAI,QAAQ,cAAc,OAAO;CAChD;;CAGA,QAAc;EACZ,KAAK,QAAQ,MAAM;EACnB,KAAK,QAAQ,MAAM;CACrB;;CAGA,IAAI,cAAsB;EACxB,IAAI,QAAQ;EACZ,KAAK,MAAM,WAAW,KAAK,QAAQ,OAAO,GAAG,SAAS,QAAQ,MAAM;EACpE,OAAO;CACT;;CAGA,GAA+C,SAAwC;EACrF,OAAO,IAAI,cAAiB;GAC1B,MAAM,SAAS,OAAO,YAAY,WAAW,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO;GACjG,IAAI,WAAW,KAAA,GAAW;IACxB,MAAM,OAAO,OAAO,YAAY,WAAW,IAAI,QAAQ,KAAK,QAAQ;IACpE,MAAM,IAAI,UACR,eAAe,KAAK,wEACtB;GACF;GACA,OAAO;EACT,CAAC;CACH;AACF;AAEA,IAAM,UAAN,MAA6D;CAC3D;CAEA,YAAY,SAA8B;EACxC,KAAK,WAAW;CAClB;CAEA,IAAI,OAAe;EACjB,OAAO,KAAK,SAAS,CAAC,CAAC;CACzB;CAEA,IAAI,OAAe;EACjB,OAAO,KAAK,SAAS,CAAC,CAAC,MAAM;CAC/B;CAEA,WAAW,IAAsC;EAC/C,OAAO,KAAK,SAAS,CAAC,CAAC,MAAM,IAAI,EAAE;CACrC;CAEA,cAA8C;EAC5C,OAAO,KAAK,SAAS,CAAC,CAAC,MAAM,QAAQ;CACvC;CAEA,QAAQ,MAAyC;EAC/C,OAAO,KAAK,SAAS,CAAC,CAAC,MAAM,KAAK,IAAI;CACxC;CAEA,QAAqC;EACnC,OAAO,KAAK,SAAS,CAAC,CAAC,MAAM,MAAM;CACrC;CAEA,GAAG,MAAgD;EACjD,OAAO,KAAK,SAAS,CAAC,CAAC,MAAM,OAAU,IAAI;CAC7C;CAEA,OAAO,QAA4F;EACjG,OAAO,KAAK,SAAS,CAAC,CAAC,MAAM,OAAU,CAAC,CAAC,OAAO,MAAM;CACxD;CAEA,KAAiC,OAAU,MAAkB;EAC3D,KAAK,SAAS,CAAC,CAAC,MAAM,OAAU,CAAC,CAAC,KAAK,OAAO,IAAI;CACpD;CAEA,KAAK,OAAkC;EACrC,KAAK,SAAS,CAAC,CAAC,MAAM,OAAU,CAAC,CAAC,KAAK,KAAK;CAC9C;AACF"}

package/dist/testing.d.mts

@@ -0,0 +1,60 @@
+import { c as WsConnection, i as WsServer } from "./server-CI_Bh9o1.mjs";
+import { HttpContext } from "@znight/http";
+/** One recorded broadcast (or a `close`, `join` or `leave` of a selection). */
+export interface RecordedBroadcast {
+  /** The gateway path, or the class name when no path was given for it. */
+  readonly gateway: string;
+  /** Selected rooms, `[]` for every connection of the gateway. */
+  readonly rooms: readonly string[];
+  /** Excluded connection ids. */
+  readonly except: readonly string[];
+  /** Excluded rooms (omitted when none). */
+  readonly exceptRooms?: readonly string[];
+  /** The emitted event, `undefined` for `send()` and the selection operations. */
+  readonly event?: string;
+  readonly data?: unknown;
+  /** A raw frame (`send()`). */
+  readonly frame?: string | Uint8Array;
+  /** `join`, `leave` or `close` of the selection. */
+  readonly action?: "join" | "leave" | "close";
+  readonly room?: string;
+}
+/** Options of {@link createTestConnection}. */
+export interface TestConnectionOptions<TData extends object> {
+  readonly id?: string;
+  /** Gateway path. Default: `'/'`. */
+  readonly gateway?: string;
+  readonly data?: TData;
+  readonly rooms?: readonly string[];
+  readonly params?: Readonly<Record<string, string>>;
+  readonly protocol?: string;
+  readonly requestId?: string;
+  /** The handshake context. Default: a minimal object with `params`, `query`, `headers` and `state`. */
+  readonly handshake?: Partial<HttpContext>;
+}
+/** A fake connection: a `WsConnection` with the record of what it was sent. */
+export interface TestConnection<TData extends object = Record<string, unknown>, E extends object = Record<string, unknown>> extends WsConnection<TData, E> {
+  /** Events emitted to this connection only (`conn.emit`), in order. */
+  readonly emitted: {
+    readonly event: string;
+    readonly data: unknown;
+  }[];
+  /** Raw frames sent to this connection (`conn.send`). */
+  readonly sent: (string | Uint8Array)[];
+  /** Broadcasts made through `conn.to()` (the connection itself is in `except`). */
+  readonly broadcasts: RecordedBroadcast[];
+}
+/** A fake server: a `WsServer` recording broadcasts. */
+export interface TestServer extends WsServer {
+  readonly broadcasts: RecordedBroadcast[];
+}
+/** Creates a fake connection for unit tests. */
+export declare function createTestConnection<TData extends object = Record<string, unknown>, E extends object = Record<string, unknown>>(options?: TestConnectionOptions<TData>): TestConnection<TData, E>;
+/** Options of {@link createTestServer}. */
+export interface TestServerOptions {
+  /** Paths of gateway classes, for the `gateway` of recorded broadcasts (`[[ChatGateway, '/chat']]`). */
+  readonly paths?: readonly (readonly [abstract new (...args: never[]) => object, string])[];
+}
+/** Creates a fake `WsServer` recording broadcasts (no connection, every room empty). */
+export declare function createTestServer(options?: TestServerOptions): TestServer;
+//# sourceMappingURL=testing.d.mts.map

package/dist/testing.mjs

@@ -0,0 +1,189 @@
+import { t as WsServer } from "./server-D40_bC88.mjs";
+// src/testing/index.ts
+/** A selection recording what is done with it. */
+var RecordingBroadcast = class RecordingBroadcast {
+	#gateway;
+	#rooms;
+	#except;
+	#exceptRooms;
+	#record;
+	constructor(gateway, rooms, except, exceptRooms, record) {
+		this.#gateway = gateway;
+		this.#rooms = rooms;
+		this.#except = except;
+		this.#exceptRooms = exceptRooms;
+		this.#record = record;
+	}
+	to(room) {
+		return new RecordingBroadcast(this.#gateway, [...this.#rooms, ...list(room)], this.#except, this.#exceptRooms, this.#record);
+	}
+	except(target) {
+		const ids = (Array.isArray(target) ? target : [target]).map((ref) => typeof ref === "string" ? ref : ref.id);
+		return new RecordingBroadcast(this.#gateway, this.#rooms, [...this.#except, ...ids], this.#exceptRooms, this.#record);
+	}
+	exceptRoom(room) {
+		return new RecordingBroadcast(this.#gateway, this.#rooms, this.#except, [...this.#exceptRooms, ...list(room)], this.#record);
+	}
+	emit(event, data) {
+		this.#record({
+			...this.#base(),
+			event,
+			data
+		});
+	}
+	send(frame) {
+		this.#record({
+			...this.#base(),
+			frame
+		});
+	}
+	join(room) {
+		this.#record({
+			...this.#base(),
+			action: "join",
+			room
+		});
+	}
+	leave(room) {
+		this.#record({
+			...this.#base(),
+			action: "leave",
+			room
+		});
+	}
+	close() {
+		this.#record({
+			...this.#base(),
+			action: "close"
+		});
+	}
+	#base() {
+		return {
+			gateway: this.#gateway,
+			rooms: [...this.#rooms],
+			except: [...this.#except],
+			...this.#exceptRooms.length === 0 ? {} : { exceptRooms: [...this.#exceptRooms] }
+		};
+	}
+};
+function list(value) {
+	return typeof value === "string" ? [value] : value;
+}
+/** Creates a fake connection for unit tests. */
+function createTestConnection(options = {}) {
+	const id = options.id ?? crypto.randomUUID();
+	const gateway = options.gateway ?? "/";
+	const rooms = new Set(options.rooms ?? []);
+	const abort = new AbortController();
+	const params = options.params ?? {};
+	const handshake = {
+		params,
+		query: {},
+		headers: {},
+		state: /* @__PURE__ */ new Map(),
+		requestId: options.requestId ?? "test-request",
+		...options.handshake
+	};
+	let state = "open";
+	let closeInfo;
+	const emitted = [];
+	const sent = [];
+	const broadcasts = [];
+	const result = () => state === "open" ? "sent" : "dropped";
+	return {
+		id,
+		gateway,
+		requestId: options.requestId ?? "test-request",
+		handshake,
+		params,
+		protocol: options.protocol ?? "",
+		data: options.data ?? {},
+		rooms,
+		get readyState() {
+			return state;
+		},
+		bufferedAmount: 0,
+		signal: abort.signal,
+		get closeInfo() {
+			return closeInfo;
+		},
+		emitted,
+		sent,
+		broadcasts,
+		emit(event, data) {
+			if (state === "open") emitted.push({
+				event,
+				data
+			});
+			return result();
+		},
+		send(frame) {
+			if (state === "open") sent.push(frame);
+			return result();
+		},
+		join(room) {
+			for (const name of list(room)) rooms.add(name);
+		},
+		leave(room) {
+			rooms.delete(room);
+		},
+		to(room) {
+			return new RecordingBroadcast(gateway, list(room), [id], [], (entry) => broadcasts.push(entry));
+		},
+		drained() {
+			return state === "open" ? Promise.resolve() : Promise.reject(/* @__PURE__ */ new Error("The WebSocket connection is closed"));
+		},
+		close(code = 1e3, reason = "") {
+			if (state !== "open") return;
+			state = "closed";
+			closeInfo = {
+				code,
+				reason,
+				initiator: "server"
+			};
+			abort.abort();
+		},
+		terminate() {
+			if (state !== "open") return;
+			state = "closed";
+			closeInfo = {
+				code: 1006,
+				reason: "",
+				initiator: "server"
+			};
+			abort.abort();
+		}
+	};
+}
+/** Creates a fake `WsServer` recording broadcasts (no connection, every room empty). */
+function createTestServer(options = {}) {
+	const paths = new Map(options.paths ?? []);
+	const broadcasts = [];
+	const record = (entry) => broadcasts.push(entry);
+	class FakeServer extends WsServer {
+		broadcasts = broadcasts;
+		get connections() {
+			return 0;
+		}
+		of(gateway) {
+			const path = typeof gateway === "string" ? gateway : paths.get(gateway) ?? gateway.name;
+			const all = () => new RecordingBroadcast(path, [], [], [], record);
+			return {
+				path,
+				size: 0,
+				connection: () => void 0,
+				connections: () => [][Symbol.iterator](),
+				members: () => /* @__PURE__ */ new Set(),
+				rooms: () => /* @__PURE__ */ new Map(),
+				to: (room) => all().to(room),
+				except: (target) => all().except(target),
+				emit: (event, data) => all().emit(event, data),
+				send: (frame) => all().send(frame)
+			};
+		}
+	}
+	return new FakeServer();
+}
+export { createTestConnection, createTestServer };
+
+//# sourceMappingURL=testing.mjs.map