@hedystia/ws 2.3.1

package/dist/server.d.mts

@@ -0,0 +1,119 @@
+import { ServerWebSocket, UpgradeOptions, UpgradeRequest, WSData, WSMessage, WebSocketHandlers, WebSocketServerOptions } from "./types.mjs";
+
+//#region src/server.d.ts
+/**
+ * Runtime-agnostic WebSocket server.
+ *
+ * @remarks
+ * Internally backed by the [`ws`](https://github.com/websockets/ws) package
+ * which runs on Bun, Node.js and Deno (via `npm:` specifiers). The class
+ * does **not** create or own an HTTP server — callers feed it raw upgrade
+ * tuples coming from any HTTP runtime they prefer.
+ *
+ * It implements topic-based pub/sub on top of the per-connection
+ * `subscribe` / `unsubscribe` / `publish` API expected by Hedystia,
+ * matching the shape of `Bun.ServerWebSocket`.
+ *
+ * @typeParam Data - Shape of the user-attached `data` field
+ *
+ * @example
+ * ```ts
+ * import { createServer } from "node:http";
+ * import { WebSocketServer } from "@hedystia/ws/server";
+ *
+ * const wss = new WebSocketServer({
+ *   open: (ws) => ws.send("welcome"),
+ *   message: (ws, msg) => ws.publish("room", msg),
+ * });
+ *
+ * const http = createServer((_req, res) => res.end("ok"));
+ * http.on("upgrade", (req, socket, head) => {
+ *   wss.upgrade({ rawRequest: req, socket, head }, { data: { user: "anon" } });
+ * });
+ * http.listen(3000);
+ * ```
+ */
+declare class WebSocketServer<Data extends WSData = WSData> {
+  private readonly handlers;
+  private readonly wss;
+  private readonly topics;
+  private readonly socketTopics;
+  private readonly allSockets;
+  /**
+   * Build a new WebSocket server.
+   *
+   * @param handlers - Lifecycle handlers ({@link WebSocketHandlers})
+   * @param options - Optional behavioural overrides ({@link WebSocketServerOptions})
+   *
+   * @example
+   * ```ts
+   * const wss = new WebSocketServer(
+   *   { message: (ws, msg) => ws.send(msg) },
+   *   { maxPayload: 1024 * 1024 },
+   * );
+   * ```
+   */
+  constructor(handlers: WebSocketHandlers<Data>, options?: WebSocketServerOptions);
+  /**
+   * Upgrade a raw HTTP upgrade tuple to a WebSocket connection.
+   *
+   * @remarks
+   * The returned promise resolves to the connected {@link ServerWebSocket}
+   * once the handshake completes; rejection means the handshake failed.
+   *
+   * @param req - Upgrade tuple emitted by `node:http`'s `'upgrade'` event
+   * @param options - Optional initial `data` for the new connection
+   * @returns Promise that resolves with the established socket wrapper
+   *
+   * @throws {Error} When the underlying handshake throws synchronously
+   *
+   * @example
+   * ```ts
+   * http.on("upgrade", async (req, socket, head) => {
+   *   try {
+   *     await wss.upgrade({ rawRequest: req, socket, head });
+   *   } catch (err) {
+   *     console.error("Upgrade failed", err);
+   *     socket.destroy();
+   *   }
+   * });
+   * ```
+   */
+  upgrade(req: UpgradeRequest, options?: UpgradeOptions<Data>): Promise<ServerWebSocket<Data>>;
+  /**
+   * Publish a message to all sockets currently subscribed to `topic`.
+   *
+   * @param topic - Topic name
+   * @param message - Payload to broadcast
+   * @param _compress - Reserved for future use; ignored under the `ws` adapter
+   * @returns Number of sockets that received the message.
+   *
+   * @example
+   * ```ts
+   * wss.publish("room", JSON.stringify({ kind: "ping" }));
+   * ```
+   */
+  publish(topic: string, message: WSMessage, _compress?: boolean): number;
+  /**
+   * Close the server and optionally terminate all live sockets.
+   *
+   * @param closeActiveConnections - When `true`, calls `socket.terminate()`
+   *  on every live connection before shutting down.
+   */
+  close(closeActiveConnections?: boolean): void;
+  /**
+   * Attach the per-socket lifecycle listeners (`message`, `close`, `error`).
+   *
+   * @internal
+   */
+  private bind;
+  /**
+   * Build the {@link ServerWebSocket} wrapper exposed to user handlers.
+   *
+   * @internal
+   */
+  private wrap;
+}
+//#endregion
+export { type ServerWebSocket, type UpgradeOptions, type UpgradeRequest, type WSData, type WSMessage, type WebSocketHandlers, WebSocketServer, type WebSocketServerOptions };
+//# sourceMappingURL=server.d.mts.map

package/dist/server.mjs

@@ -0,0 +1,236 @@
+import { WebSocketServer as WebSocketServer$1 } from "ws";
+//#region src/server.ts
+/**
+* Runtime-agnostic WebSocket server.
+*
+* @remarks
+* Internally backed by the [`ws`](https://github.com/websockets/ws) package
+* which runs on Bun, Node.js and Deno (via `npm:` specifiers). The class
+* does **not** create or own an HTTP server — callers feed it raw upgrade
+* tuples coming from any HTTP runtime they prefer.
+*
+* It implements topic-based pub/sub on top of the per-connection
+* `subscribe` / `unsubscribe` / `publish` API expected by Hedystia,
+* matching the shape of `Bun.ServerWebSocket`.
+*
+* @typeParam Data - Shape of the user-attached `data` field
+*
+* @example
+* ```ts
+* import { createServer } from "node:http";
+* import { WebSocketServer } from "@hedystia/ws/server";
+*
+* const wss = new WebSocketServer({
+*   open: (ws) => ws.send("welcome"),
+*   message: (ws, msg) => ws.publish("room", msg),
+* });
+*
+* const http = createServer((_req, res) => res.end("ok"));
+* http.on("upgrade", (req, socket, head) => {
+*   wss.upgrade({ rawRequest: req, socket, head }, { data: { user: "anon" } });
+* });
+* http.listen(3000);
+* ```
+*/
+var WebSocketServer = class {
+	handlers;
+	wss;
+	topics = /* @__PURE__ */ new Map();
+	socketTopics = /* @__PURE__ */ new WeakMap();
+	allSockets = /* @__PURE__ */ new Set();
+	/**
+	* Build a new WebSocket server.
+	*
+	* @param handlers - Lifecycle handlers ({@link WebSocketHandlers})
+	* @param options - Optional behavioural overrides ({@link WebSocketServerOptions})
+	*
+	* @example
+	* ```ts
+	* const wss = new WebSocketServer(
+	*   { message: (ws, msg) => ws.send(msg) },
+	*   { maxPayload: 1024 * 1024 },
+	* );
+	* ```
+	*/
+	constructor(handlers, options = {}) {
+		this.handlers = handlers;
+		this.wss = new WebSocketServer$1({
+			noServer: true,
+			maxPayload: options.maxPayload,
+			perMessageDeflate: options.perMessageDeflate ?? false
+		});
+	}
+	/**
+	* Upgrade a raw HTTP upgrade tuple to a WebSocket connection.
+	*
+	* @remarks
+	* The returned promise resolves to the connected {@link ServerWebSocket}
+	* once the handshake completes; rejection means the handshake failed.
+	*
+	* @param req - Upgrade tuple emitted by `node:http`'s `'upgrade'` event
+	* @param options - Optional initial `data` for the new connection
+	* @returns Promise that resolves with the established socket wrapper
+	*
+	* @throws {Error} When the underlying handshake throws synchronously
+	*
+	* @example
+	* ```ts
+	* http.on("upgrade", async (req, socket, head) => {
+	*   try {
+	*     await wss.upgrade({ rawRequest: req, socket, head });
+	*   } catch (err) {
+	*     console.error("Upgrade failed", err);
+	*     socket.destroy();
+	*   }
+	* });
+	* ```
+	*/
+	upgrade(req, options) {
+		return new Promise((resolve, reject) => {
+			try {
+				this.wss.handleUpgrade(req.rawRequest, req.socket, req.head, (socket) => {
+					const data = options?.data ?? {};
+					const wrapped = this.wrap(socket, data, req.rawRequest);
+					this.bind(socket, wrapped);
+					resolve(wrapped);
+				});
+			} catch (err) {
+				reject(err);
+			}
+		});
+	}
+	/**
+	* Publish a message to all sockets currently subscribed to `topic`.
+	*
+	* @param topic - Topic name
+	* @param message - Payload to broadcast
+	* @param _compress - Reserved for future use; ignored under the `ws` adapter
+	* @returns Number of sockets that received the message.
+	*
+	* @example
+	* ```ts
+	* wss.publish("room", JSON.stringify({ kind: "ping" }));
+	* ```
+	*/
+	publish(topic, message, _compress) {
+		const set = this.topics.get(topic);
+		if (!set || set.size === 0) return 0;
+		const payload = toSendable(message);
+		let count = 0;
+		for (const socket of set) if (socket.readyState === 1) {
+			socket.send(payload);
+			count++;
+		}
+		return count;
+	}
+	/**
+	* Close the server and optionally terminate all live sockets.
+	*
+	* @param closeActiveConnections - When `true`, calls `socket.terminate()`
+	*  on every live connection before shutting down.
+	*/
+	close(closeActiveConnections = false) {
+		if (closeActiveConnections) {
+			for (const socket of this.allSockets) try {
+				socket.terminate();
+			} catch {}
+			this.allSockets.clear();
+		}
+		this.wss.close();
+	}
+	/**
+	* Attach the per-socket lifecycle listeners (`message`, `close`, `error`).
+	*
+	* @internal
+	*/
+	bind(socket, wrapped) {
+		this.allSockets.add(socket);
+		if (this.handlers.open) Promise.resolve(this.handlers.open(wrapped)).catch((err) => console.error("[ws] open handler error:", err));
+		socket.on("message", (raw, isBinary) => {
+			const message = isBinary ? raw instanceof ArrayBuffer ? new Uint8Array(raw) : Array.isArray(raw) ? Buffer.concat(raw) : raw : raw.toString();
+			Promise.resolve(this.handlers.message(wrapped, message)).catch((err) => console.error("[ws] message handler error:", err));
+		});
+		socket.on("close", (code, reason) => {
+			const owned = this.socketTopics.get(socket);
+			if (owned) {
+				for (const topic of owned) this.topics.get(topic)?.delete(socket);
+				this.socketTopics.delete(socket);
+			}
+			this.allSockets.delete(socket);
+			if (this.handlers.close) Promise.resolve(this.handlers.close(wrapped, code, reason?.toString() ?? "")).catch((err) => console.error("[ws] close handler error:", err));
+		});
+		socket.on("error", (err) => {
+			if (this.handlers.error) Promise.resolve(this.handlers.error(wrapped, err)).catch((e) => console.error("[ws] error handler error:", e));
+		});
+	}
+	/**
+	* Build the {@link ServerWebSocket} wrapper exposed to user handlers.
+	*
+	* @internal
+	*/
+	wrap(socket, data, rawReq) {
+		const remoteAddress = rawReq?.socket?.remoteAddress || rawReq?.headers?.["x-forwarded-for"] || "";
+		const subscribe = (topic) => {
+			let set = this.topics.get(topic);
+			if (!set) {
+				set = /* @__PURE__ */ new Set();
+				this.topics.set(topic, set);
+			}
+			set.add(socket);
+			let owned = this.socketTopics.get(socket);
+			if (!owned) {
+				owned = /* @__PURE__ */ new Set();
+				this.socketTopics.set(socket, owned);
+			}
+			owned.add(topic);
+		};
+		const unsubscribe = (topic) => {
+			this.topics.get(topic)?.delete(socket);
+			this.socketTopics.get(socket)?.delete(topic);
+		};
+		const publishToPeers = (topic, message) => {
+			const set = this.topics.get(topic);
+			if (!set) return;
+			const payload = toSendable(message);
+			for (const peer of set) if (peer !== socket && peer.readyState === 1) peer.send(payload);
+		};
+		const wrapper = {
+			data,
+			get readyState() {
+				return socket.readyState;
+			},
+			remoteAddress,
+			send: (message, _compress) => {
+				const payload = toSendable(message);
+				socket.send(payload);
+				return typeof payload === "string" ? Buffer.byteLength(payload) : payload.byteLength;
+			},
+			close: (code, reason) => {
+				socket.close(code, reason);
+			},
+			subscribe,
+			unsubscribe,
+			publish: publishToPeers,
+			isSubscribed: (topic) => !!this.socketTopics.get(socket)?.has(topic),
+			cork: (cb) => cb(wrapper)
+		};
+		return wrapper;
+	}
+};
+/**
+* Coerce a {@link WSMessage} into something the `ws` package can transmit.
+*
+* @param message - User-supplied payload
+* @returns A `string`, `Buffer` or `Uint8Array` ready to be sent
+*
+* @internal
+*/
+function toSendable(message) {
+	if (typeof message === "string") return message;
+	if (message instanceof ArrayBuffer) return Buffer.from(message);
+	return message;
+}
+//#endregion
+export { WebSocketServer };
+
+//# sourceMappingURL=server.mjs.map

package/dist/server.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.mjs","names":["WSServer"],"sources":["../src/server.ts"],"sourcesContent":["import { type WebSocket as NodeWebSocket, WebSocketServer as WSServer } from \"ws\";\n\nimport type {\n  ServerWebSocket,\n  UpgradeOptions,\n  UpgradeRequest,\n  WebSocketHandlers,\n  WebSocketServerOptions,\n  WSData,\n  WSMessage,\n} from \"./types\";\n\nexport type {\n  ServerWebSocket,\n  UpgradeOptions,\n  UpgradeRequest,\n  WebSocketHandlers,\n  WebSocketServerOptions,\n  WSData,\n  WSMessage,\n} from \"./types\";\n\n/**\n * Runtime-agnostic WebSocket server.\n *\n * @remarks\n * Internally backed by the [`ws`](https://github.com/websockets/ws) package\n * which runs on Bun, Node.js and Deno (via `npm:` specifiers). The class\n * does **not** create or own an HTTP server — callers feed it raw upgrade\n * tuples coming from any HTTP runtime they prefer.\n *\n * It implements topic-based pub/sub on top of the per-connection\n * `subscribe` / `unsubscribe` / `publish` API expected by Hedystia,\n * matching the shape of `Bun.ServerWebSocket`.\n *\n * @typeParam Data - Shape of the user-attached `data` field\n *\n * @example\n * ```ts\n * import { createServer } from \"node:http\";\n * import { WebSocketServer } from \"@hedystia/ws/server\";\n *\n * const wss = new WebSocketServer({\n *   open: (ws) => ws.send(\"welcome\"),\n *   message: (ws, msg) => ws.publish(\"room\", msg),\n * });\n *\n * const http = createServer((_req, res) => res.end(\"ok\"));\n * http.on(\"upgrade\", (req, socket, head) => {\n *   wss.upgrade({ rawRequest: req, socket, head }, { data: { user: \"anon\" } });\n * });\n * http.listen(3000);\n * ```\n */\nexport class WebSocketServer<Data extends WSData = WSData> {\n  private readonly handlers: WebSocketHandlers<Data>;\n  private readonly wss: WSServer;\n  private readonly topics = new Map<string, Set<NodeWebSocket>>();\n  private readonly socketTopics = new WeakMap<NodeWebSocket, Set<string>>();\n  private readonly allSockets = new Set<NodeWebSocket>();\n\n  /**\n   * Build a new WebSocket server.\n   *\n   * @param handlers - Lifecycle handlers ({@link WebSocketHandlers})\n   * @param options - Optional behavioural overrides ({@link WebSocketServerOptions})\n   *\n   * @example\n   * ```ts\n   * const wss = new WebSocketServer(\n   *   { message: (ws, msg) => ws.send(msg) },\n   *   { maxPayload: 1024 * 1024 },\n   * );\n   * ```\n   */\n  constructor(handlers: WebSocketHandlers<Data>, options: WebSocketServerOptions = {}) {\n    this.handlers = handlers;\n    this.wss = new WSServer({\n      noServer: true,\n      maxPayload: options.maxPayload,\n      perMessageDeflate: (options.perMessageDeflate ?? false) as any,\n    });\n  }\n\n  /**\n   * Upgrade a raw HTTP upgrade tuple to a WebSocket connection.\n   *\n   * @remarks\n   * The returned promise resolves to the connected {@link ServerWebSocket}\n   * once the handshake completes; rejection means the handshake failed.\n   *\n   * @param req - Upgrade tuple emitted by `node:http`'s `'upgrade'` event\n   * @param options - Optional initial `data` for the new connection\n   * @returns Promise that resolves with the established socket wrapper\n   *\n   * @throws {Error} When the underlying handshake throws synchronously\n   *\n   * @example\n   * ```ts\n   * http.on(\"upgrade\", async (req, socket, head) => {\n   *   try {\n   *     await wss.upgrade({ rawRequest: req, socket, head });\n   *   } catch (err) {\n   *     console.error(\"Upgrade failed\", err);\n   *     socket.destroy();\n   *   }\n   * });\n   * ```\n   */\n  upgrade(req: UpgradeRequest, options?: UpgradeOptions<Data>): Promise<ServerWebSocket<Data>> {\n    return new Promise((resolve, reject) => {\n      try {\n        this.wss.handleUpgrade(req.rawRequest, req.socket, req.head as Buffer, (socket) => {\n          const data = (options?.data ?? ({} as Data)) as Data;\n          const wrapped = this.wrap(socket, data, req.rawRequest);\n          this.bind(socket, wrapped);\n          resolve(wrapped);\n        });\n      } catch (err) {\n        reject(err);\n      }\n    });\n  }\n\n  /**\n   * Publish a message to all sockets currently subscribed to `topic`.\n   *\n   * @param topic - Topic name\n   * @param message - Payload to broadcast\n   * @param _compress - Reserved for future use; ignored under the `ws` adapter\n   * @returns Number of sockets that received the message.\n   *\n   * @example\n   * ```ts\n   * wss.publish(\"room\", JSON.stringify({ kind: \"ping\" }));\n   * ```\n   */\n  publish(topic: string, message: WSMessage, _compress?: boolean): number {\n    const set = this.topics.get(topic);\n    if (!set || set.size === 0) {\n      return 0;\n    }\n    const payload = toSendable(message);\n    let count = 0;\n    for (const socket of set) {\n      if (socket.readyState === 1) {\n        socket.send(payload);\n        count++;\n      }\n    }\n    return count;\n  }\n\n  /**\n   * Close the server and optionally terminate all live sockets.\n   *\n   * @param closeActiveConnections - When `true`, calls `socket.terminate()`\n   *  on every live connection before shutting down.\n   */\n  close(closeActiveConnections = false): void {\n    if (closeActiveConnections) {\n      for (const socket of this.allSockets) {\n        try {\n          socket.terminate();\n        } catch {\n          /* ignore */\n        }\n      }\n      this.allSockets.clear();\n    }\n    this.wss.close();\n  }\n\n  /**\n   * Attach the per-socket lifecycle listeners (`message`, `close`, `error`).\n   *\n   * @internal\n   */\n  private bind(socket: NodeWebSocket, wrapped: ServerWebSocket<Data>): void {\n    this.allSockets.add(socket);\n\n    if (this.handlers.open) {\n      Promise.resolve(this.handlers.open(wrapped)).catch((err) =>\n        console.error(\"[ws] open handler error:\", err),\n      );\n    }\n\n    socket.on(\"message\", (raw, isBinary) => {\n      const message: WSMessage = isBinary\n        ? raw instanceof ArrayBuffer\n          ? new Uint8Array(raw)\n          : Array.isArray(raw)\n            ? Buffer.concat(raw)\n            : (raw as Buffer)\n        : raw.toString();\n      Promise.resolve(this.handlers.message(wrapped, message)).catch((err) =>\n        console.error(\"[ws] message handler error:\", err),\n      );\n    });\n\n    socket.on(\"close\", (code, reason) => {\n      const owned = this.socketTopics.get(socket);\n      if (owned) {\n        for (const topic of owned) {\n          this.topics.get(topic)?.delete(socket);\n        }\n        this.socketTopics.delete(socket);\n      }\n      this.allSockets.delete(socket);\n      if (this.handlers.close) {\n        Promise.resolve(this.handlers.close(wrapped, code, reason?.toString() ?? \"\")).catch((err) =>\n          console.error(\"[ws] close handler error:\", err),\n        );\n      }\n    });\n\n    socket.on(\"error\", (err) => {\n      if (this.handlers.error) {\n        Promise.resolve(this.handlers.error(wrapped, err)).catch((e) =>\n          console.error(\"[ws] error handler error:\", e),\n        );\n      }\n    });\n  }\n\n  /**\n   * Build the {@link ServerWebSocket} wrapper exposed to user handlers.\n   *\n   * @internal\n   */\n  private wrap(socket: NodeWebSocket, data: Data, rawReq: any): ServerWebSocket<Data> {\n    const remoteAddress: string =\n      (rawReq?.socket?.remoteAddress as string) ||\n      (rawReq?.headers?.[\"x-forwarded-for\"] as string) ||\n      \"\";\n\n    const subscribe = (topic: string) => {\n      let set = this.topics.get(topic);\n      if (!set) {\n        set = new Set();\n        this.topics.set(topic, set);\n      }\n      set.add(socket);\n      let owned = this.socketTopics.get(socket);\n      if (!owned) {\n        owned = new Set();\n        this.socketTopics.set(socket, owned);\n      }\n      owned.add(topic);\n    };\n\n    const unsubscribe = (topic: string) => {\n      this.topics.get(topic)?.delete(socket);\n      this.socketTopics.get(socket)?.delete(topic);\n    };\n\n    const publishToPeers = (topic: string, message: WSMessage) => {\n      const set = this.topics.get(topic);\n      if (!set) {\n        return;\n      }\n      const payload = toSendable(message);\n      for (const peer of set) {\n        if (peer !== socket && peer.readyState === 1) {\n          peer.send(payload);\n        }\n      }\n    };\n\n    const wrapper: ServerWebSocket<Data> = {\n      data,\n      get readyState() {\n        return socket.readyState;\n      },\n      remoteAddress,\n      send: (message, _compress) => {\n        const payload = toSendable(message);\n        socket.send(payload);\n        return typeof payload === \"string\"\n          ? Buffer.byteLength(payload)\n          : (payload as Buffer | Uint8Array).byteLength;\n      },\n      close: (code, reason) => {\n        socket.close(code, reason);\n      },\n      subscribe,\n      unsubscribe,\n      publish: publishToPeers,\n      isSubscribed: (topic) => !!this.socketTopics.get(socket)?.has(topic),\n      cork: (cb) => cb(wrapper),\n    };\n\n    return wrapper;\n  }\n}\n\n/**\n * Coerce a {@link WSMessage} into something the `ws` package can transmit.\n *\n * @param message - User-supplied payload\n * @returns A `string`, `Buffer` or `Uint8Array` ready to be sent\n *\n * @internal\n */\nfunction toSendable(message: WSMessage): string | Buffer | Uint8Array {\n  if (typeof message === \"string\") {\n    return message;\n  }\n  if (message instanceof ArrayBuffer) {\n    return Buffer.from(message);\n  }\n  return message;\n}\n"],"mappings":"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"}

package/dist/types.d.cts

@@ -0,0 +1,208 @@
+//#region src/types.d.ts
+/**
+ * Payload accepted by every `send`/`publish` method.
+ *
+ * @remarks
+ * Matches the WHATWG `WebSocket.send` signature plus the `Uint8Array`
+ * convenience accepted by Bun and the `ws` package.
+ */
+type WSMessage = string | ArrayBuffer | Uint8Array;
+/**
+ * Bag of arbitrary, user-supplied state attached to a connection on
+ * upgrade and exposed to handlers as `ws.data`.
+ *
+ * @typeParam K - String key
+ * @typeParam V - Stored value
+ */
+type WSData = Record<string, any>;
+/**
+ * The per-connection wrapper passed to every handler.
+ *
+ * @remarks
+ * The interface intentionally mirrors `Bun.ServerWebSocket` so that the
+ * same handler code works on Bun (native) and on Node.js (via
+ * {@link WebSocketServer}). Topic-based pub/sub is implemented in
+ * user-space when running outside Bun.
+ *
+ * @typeParam Data - Shape of the user-attached `data` field
+ *
+ * @example
+ * ```ts
+ * const handlers: WebSocketHandlers<{ user: string }> = {
+ *   open: (ws) => ws.subscribe(`user:${ws.data.user}`),
+ *   message: (ws, msg) => ws.publish(`user:${ws.data.user}`, msg),
+ * };
+ * ```
+ */
+interface ServerWebSocket<Data extends WSData = WSData> {
+  /** User-supplied state attached to the socket on upgrade. */
+  readonly data: Data;
+  /** Standard WHATWG ready-state (`0` connecting, `1` open, `2` closing, `3` closed). */
+  readonly readyState: number;
+  /** Remote IP, taken from `X-Forwarded-For` when present. */
+  readonly remoteAddress: string;
+  /**
+   * Send a message to this socket only.
+   *
+   * @param message - Payload to send
+   * @param compress - Whether to compress (honoured on Bun, ignored on Node)
+   * @returns Number of bytes written (best-effort on Node)
+   */
+  send(message: WSMessage, compress?: boolean): number;
+  /**
+   * Close the connection.
+   *
+   * @param code - Close code (defaults to 1000)
+   * @param reason - Optional human-readable reason
+   */
+  close(code?: number, reason?: string): void;
+  /**
+   * Subscribe this socket to a topic so it receives subsequent
+   * {@link ServerWebSocket.publish | publish} or
+   * {@link WebSocketServer.publish | server.publish} broadcasts.
+   *
+   * @param topic - Topic name
+   */
+  subscribe(topic: string): void;
+  /**
+   * Unsubscribe this socket from a previously joined topic.
+   *
+   * @param topic - Topic name
+   */
+  unsubscribe(topic: string): void;
+  /**
+   * Broadcast a message to every other socket subscribed to `topic`.
+   *
+   * @remarks
+   * The sender is excluded by default — matching Bun's default behaviour.
+   *
+   * @param topic - Topic name
+   * @param message - Payload to broadcast
+   * @param compress - Whether to compress (honoured on Bun, ignored on Node)
+   */
+  publish(topic: string, message: WSMessage, compress?: boolean): void;
+  /**
+   * Check whether this socket is currently subscribed to `topic`.
+   *
+   * @param topic - Topic name
+   * @returns `true` when subscribed
+   */
+  isSubscribed(topic: string): boolean;
+  /**
+   * Batch multiple writes inside `cb`.
+   *
+   * @remarks
+   * On Bun this corresponds to `corked()`; on Node it is a no-op alias
+   * that simply invokes `cb(this)` synchronously.
+   *
+   * @param cb - Function invoked with the same socket
+   */
+  cork(cb: (ws: ServerWebSocket<Data>) => void): void;
+}
+/**
+ * Bun-style compression dictionary identifier.
+ *
+ * @remarks
+ * Used by Bun's `perMessageDeflate` configuration. The `@hedystia/ws`
+ * server forwards the value to the underlying implementation, which only
+ * Bun interprets natively; Node falls back to defaults when the value is
+ * not a recognised `ws` shape.
+ */
+type Compressor = "disable" | "shared" | "dedicated" | "3KB" | "4KB" | "8KB" | "16KB" | "32KB" | "64KB" | "128KB" | "256KB";
+/**
+ * Per-message deflate configuration.
+ *
+ * @remarks
+ * Accepts either a boolean (`true` enables defaults, `false` disables it)
+ * or a free-form object whose shape is forwarded verbatim to the underlying
+ * implementation. Bun's {@link Compressor} strings (`"3KB"`, `"shared"`, …)
+ * and the [`ws`](https://github.com/websockets/ws) package's
+ * `PerMessageDeflateOptions` (`zlibDeflateOptions`, `threshold`, …) are
+ * both supported by simply matching whatever the runtime expects.
+ */
+type PerMessageDeflate = boolean | (Record<string, any> & {
+  compress?: boolean | Compressor;
+  decompress?: boolean | Compressor;
+});
+/**
+ * Construction options for {@link WebSocketServer}.
+ */
+interface WebSocketServerOptions {
+  /** Maximum allowed payload in bytes. Defaults to the underlying library's default. */
+  maxPayload?: number;
+  /** Per-message deflate configuration. */
+  perMessageDeflate?: PerMessageDeflate;
+}
+/**
+ * Lifecycle handlers passed to {@link WebSocketServer}.
+ *
+ * @typeParam Data - Shape of the user-attached `data` field
+ */
+interface WebSocketHandlers<Data extends WSData = WSData> {
+  /** Called for every inbound message. */
+  message: (ws: ServerWebSocket<Data>, message: WSMessage) => void | Promise<void>;
+  /** Called once the handshake completes successfully. */
+  open?: (ws: ServerWebSocket<Data>) => void | Promise<void>;
+  /** Called after the connection closes (clean or otherwise). */
+  close?: (ws: ServerWebSocket<Data>, code: number, reason: string) => void | Promise<void>;
+  /** Called when the underlying transport raises an error. */
+  error?: (ws: ServerWebSocket<Data>, error: Error) => void | Promise<void>;
+  /**
+   * Called when back-pressure is relieved.
+   *
+   * @remarks
+   * Only fired by Bun; Node-backed servers never invoke it.
+   */
+  drain?: (ws: ServerWebSocket<Data>) => void | Promise<void>;
+}
+/**
+ * Options accepted by {@link createWebSocket}.
+ */
+interface ClientWebSocketOptions {
+  /** Sub-protocols negotiated during the handshake. */
+  protocols?: string | string[];
+  /**
+   * Custom request headers.
+   *
+   * @remarks
+   * Honoured on Node via the `ws` package; runtimes that ship a WHATWG
+   * `WebSocket` (Bun, Deno, browsers, Node ≥ 22) ignore them — matching
+   * standard WebSocket semantics.
+   */
+  headers?: Record<string, string>;
+}
+/**
+ * Raw upgrade tuple consumed by {@link WebSocketServer.upgrade}.
+ *
+ * @remarks
+ * Mirrors what `node:http`'s `'upgrade'` event emits and what the `ws`
+ * package's `WebSocketServer.handleUpgrade` consumes.
+ */
+interface UpgradeRequest {
+  /** Raw `IncomingMessage`-like object exposing `headers`, `method`, `url`. */
+  rawRequest: any;
+  /** Raw duplex socket (e.g. `node:net.Socket`). */
+  socket: any;
+  /** Initial buffer captured by the HTTP parser. */
+  head: Buffer | Uint8Array;
+}
+/**
+ * Options forwarded to {@link WebSocketServer.upgrade}.
+ *
+ * @typeParam Data - Shape of the user-attached `data` field
+ */
+interface UpgradeOptions<Data extends WSData = WSData> {
+  /** Initial value of `ws.data` for the new connection. */
+  data?: Data;
+  /**
+   * Extra response headers.
+   *
+   * @remarks
+   * Forwarded to the underlying handshake when supported (Bun); ignored on
+   * Node-backed upgrades, which control headers via the `ws` package.
+   */
+  headers?: Record<string, string> | Headers;
+}
+//#endregion
+export { ClientWebSocketOptions, ServerWebSocket, UpgradeOptions, UpgradeRequest, WSData, WSMessage, WebSocketHandlers, WebSocketServerOptions };
+//# sourceMappingURL=types.d.cts.map