@forinda/kickjs-ws 2.0.1 → 2.2.0

package/dist/index.d.mts

@@ -0,0 +1,245 @@
+
+import { WebSocket, WebSocketServer } from "ws";
+import { AdapterContext, AppAdapter, Ref } from "@forinda/kickjs";
+
+//#region src/interfaces.d.ts
+declare const WS_METADATA: {
+  readonly WS_CONTROLLER: symbol;
+  readonly WS_HANDLERS: symbol;
+};
+type WsHandlerType = 'connect' | 'disconnect' | 'message' | 'error';
+interface WsHandlerDefinition {
+  type: WsHandlerType;
+  /** Event name — only for 'message' type */
+  event?: string;
+  /** Method name on the controller class */
+  handlerName: string;
+}
+interface WsAdapterOptions {
+  /** Base path for WebSocket upgrade (default: '/ws') */
+  path?: string;
+  /** Heartbeat ping interval in ms (default: 30000). Set to 0 to disable. */
+  heartbeatInterval?: number;
+  /** Maximum message payload size in bytes */
+  maxPayload?: number;
+}
+//#endregion
+//#region src/ws-adapter.d.ts
+/**
+ * WebSocket adapter for KickJS. Attaches to the HTTP server and routes
+ * WebSocket connections to @WsController classes based on namespace paths.
+ *
+ * @example
+ * ```ts
+ * import { WsAdapter } from '@forinda/kickjs-ws'
+ *
+ * bootstrap({
+ *   modules: [ChatModule],
+ *   adapters: [
+ *     new WsAdapter({ path: '/ws' }),
+ *   ],
+ * })
+ * ```
+ *
+ * Clients connect to: `ws://localhost:3000/ws/chat`
+ * Messages are JSON: `{ "event": "send", "data": { "text": "hello" } }`
+ */
+declare class WsAdapter implements AppAdapter {
+  readonly name = "WsAdapter";
+  private basePath;
+  private heartbeatInterval;
+  private maxPayload;
+  private wss;
+  private container;
+  private namespaces;
+  private roomManager;
+  private heartbeatTimer;
+  /** Total WebSocket connections ever opened */
+  readonly totalConnections: Ref<number>;
+  /** Currently active connections */
+  readonly activeConnections: Ref<number>;
+  /** Total messages received */
+  readonly messagesReceived: Ref<number>;
+  /** Total messages sent */
+  readonly messagesSent: Ref<number>;
+  /** Total errors */
+  readonly wsErrors: Ref<number>;
+  constructor(options?: WsAdapterOptions);
+  /** Get a snapshot of WebSocket stats for DevTools */
+  getStats(): {
+    totalConnections: number;
+    activeConnections: number;
+    messagesReceived: number;
+    messagesSent: number;
+    errors: number;
+    namespaces: Record<string, {
+      connections: number;
+      handlers: number;
+    }>;
+    rooms: Record<string, number>;
+  };
+  beforeStart({
+    container
+  }: AdapterContext): void;
+  afterStart({
+    server
+  }: AdapterContext): void;
+  shutdown(): void;
+  private handleConnection;
+  private invokeHandlers;
+  private safeInvoke;
+}
+//#endregion
+//#region src/room-manager.d.ts
+/**
+ * Manages WebSocket room membership and broadcasting.
+ * Standalone from ws/socket.io — can be swapped for socket.io's built-in rooms.
+ */
+declare class RoomManager {
+  /** socketId → set of room names */
+  private socketRooms;
+  /** room name → set of { socketId, socket } */
+  private roomSockets;
+  join(socketId: string, socket: WebSocket, room: string): void;
+  leave(socketId: string, room: string): void;
+  /** Remove socket from all rooms (called on disconnect) */
+  leaveAll(socketId: string): void;
+  getRooms(socketId: string): string[];
+  getSockets(room: string): Map<string, WebSocket>;
+  /** Get all rooms with their member counts */
+  getAllRooms(): Record<string, number>;
+  /** Broadcast to all sockets in a room, optionally excluding one */
+  broadcast(room: string, event: string, data: any, excludeId?: string): void;
+}
+//#endregion
+//#region src/ws-context.d.ts
+/**
+ * Context object passed to WebSocket handler methods.
+ * Analogous to RequestContext for HTTP controllers.
+ *
+ * @example
+ * ```ts
+ * @OnMessage('chat:send')
+ * handleSend(ctx: WsContext) {
+ *   console.log(ctx.data)          // parsed message payload
+ *   ctx.send('chat:ack', { ok: true })
+ *   ctx.broadcast('chat:receive', ctx.data)
+ *   ctx.join('room-1')
+ *   ctx.to('room-1').send('chat:receive', ctx.data)
+ * }
+ * ```
+ */
+declare class WsContext {
+  readonly socket: WebSocket;
+  readonly server: WebSocketServer;
+  private readonly roomManager;
+  private readonly namespaceSockets;
+  /** Unique connection ID */
+  readonly id: string;
+  /** Parsed message payload (set for @OnMessage handlers) */
+  data: any;
+  /** Event name from the message envelope (set for @OnMessage handlers) */
+  event: string;
+  /** The namespace this connection belongs to */
+  readonly namespace: string;
+  private metadata;
+  constructor(socket: WebSocket, server: WebSocketServer, roomManager: RoomManager, namespaceSockets: Map<string, WebSocket>, id: string, namespace: string);
+  /** Get a metadata value */
+  get<T = any>(key: string): T | undefined;
+  /** Set a metadata value (persists for the lifetime of the connection) */
+  set(key: string, value: any): void;
+  /** Send a message to this socket */
+  send(event: string, data: any): void;
+  /** Send to all sockets in the same namespace except this one */
+  broadcast(event: string, data: any): void;
+  /** Send to all sockets in the same namespace including this one */
+  broadcastAll(event: string, data: any): void;
+  /** Join a room */
+  join(room: string): void;
+  /** Leave a room */
+  leave(room: string): void;
+  /** Get all rooms this socket is in */
+  rooms(): string[];
+  /** Send to all sockets in a room */
+  to(room: string): {
+    send(event: string, data: any): void;
+  };
+}
+//#endregion
+//#region src/decorators.d.ts
+/**
+ * Mark a class as a WebSocket controller with a namespace path.
+ * Registers the class in the DI container and the WS controller registry.
+ *
+ * @example
+ * ```ts
+ * @WsController('/chat')
+ * export class ChatController {
+ *   @OnConnect()
+ *   handleConnect(ctx: WsContext) { }
+ *
+ *   @OnMessage('send')
+ *   handleSend(ctx: WsContext) { }
+ * }
+ * ```
+ */
+declare function WsController(namespace?: string): ClassDecorator;
+/**
+ * Handle new WebSocket connections.
+ *
+ * @example
+ * ```ts
+ * @OnConnect()
+ * handleConnect(ctx: WsContext) {
+ *   console.log(`Client ${ctx.id} connected`)
+ * }
+ * ```
+ */
+declare const OnConnect: () => MethodDecorator;
+/**
+ * Handle WebSocket disconnections.
+ *
+ * @example
+ * ```ts
+ * @OnDisconnect()
+ * handleDisconnect(ctx: WsContext) {
+ *   console.log(`Client ${ctx.id} disconnected`)
+ * }
+ * ```
+ */
+declare const OnDisconnect: () => MethodDecorator;
+/**
+ * Handle WebSocket errors.
+ *
+ * @example
+ * ```ts
+ * @OnError()
+ * handleError(ctx: WsContext) {
+ *   console.error('WS error:', ctx.data)
+ * }
+ * ```
+ */
+declare const OnError: () => MethodDecorator;
+/**
+ * Handle a specific WebSocket message event.
+ * Use '*' as a catch-all for unmatched events.
+ *
+ * Messages must be JSON: `{ "event": "chat:send", "data": { ... } }`
+ *
+ * @example
+ * ```ts
+ * @OnMessage('chat:send')
+ * handleChatSend(ctx: WsContext) {
+ *   ctx.broadcast('chat:receive', ctx.data)
+ * }
+ *
+ * @OnMessage('*')
+ * handleUnknown(ctx: WsContext) {
+ *   ctx.send('error', { message: `Unknown event: ${ctx.event}` })
+ * }
+ * ```
+ */
+declare function OnMessage(event: string): MethodDecorator;
+//#endregion
+export { OnConnect, OnDisconnect, OnError, OnMessage, RoomManager, WS_METADATA, WsAdapter, type WsAdapterOptions, WsContext, WsController, type WsHandlerDefinition, type WsHandlerType };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/interfaces.ts","../src/ws-adapter.ts","../src/room-manager.ts","../src/ws-context.ts","../src/decorators.ts"],"mappings":";;;;;cAEa,WAAA;EAAA,SAGH,aAAA;EAAA,SAAA,WAAA;AAAA;AAAA,KAEE,aAAA;AAAA,UAEK,mBAAA;EACf,IAAA,EAAM,aAAA;;EAEN,KAAA;EALuB;EAOvB,WAAA;AAAA;AAAA,UAGe,gBAAA;EARA;EAUf,IAAA;;EAEA,iBAAA;EAXA;EAaA,UAAA;AAAA;;;;;AArBF;;;;;AAKA;;;;;AAEA;;;;;;;cC2Ca,SAAA,YAAqB,UAAA;EAAA,SACvB,IAAA;EAAA,QAED,QAAA;EAAA,QACA,iBAAA;EAAA,QACA,UAAA;EAAA,QACA,GAAA;EAAA,QACA,SAAA;EAAA,QACA,UAAA;EAAA,QACA,WAAA;EAAA,QACA,cAAA;EDvCE;EAAA,SC2CD,gBAAA,EAAkB,GAAA;;WAElB,iBAAA,EAAmB,GAAA;;WAEnB,gBAAA,EAAkB,GAAA;EAlBN;EAAA,SAoBZ,YAAA,EAAc,GAAA;EANI;EAAA,SAQlB,QAAA,EAAU,GAAA;cAEP,OAAA,GAAS,gBAAA;EAJE;EAiBvB,QAAA,CAAA;;;;;;;;;;;;EAmBA,WAAA,CAAA;IAAc;EAAA,GAAa,cAAA;EA4B3B,UAAA,CAAA;IAAa;EAAA,GAAU,cAAA;EAiDvB,QAAA,CAAA;EAAA,QAmBQ,gBAAA;EAAA,QAgFA,cAAA;EAAA,QAaA,UAAA;AAAA;;;;;;ADvSV;cEIa,WAAA;;UAEH,WAAA;;UAEA,WAAA;EAER,IAAA,CAAK,QAAA,UAAkB,MAAA,EAAQ,SAAA,EAAW,IAAA;EAY1C,KAAA,CAAM,QAAA,UAAkB,IAAA;EFjBD;EE4BvB,QAAA,CAAS,QAAA;EAaT,QAAA,CAAS,QAAA;EAIT,UAAA,CAAW,IAAA,WAAe,GAAA,SAAY,SAAA;;EAKtC,WAAA,CAAA,GAAe,MAAA;EF/Cf;EEwDA,SAAA,CAAU,IAAA,UAAc,KAAA,UAAe,IAAA,OAAW,SAAA;AAAA;;;;;AFhEpD;;;;;AAKA;;;;;AAEA;;;;cGUa,SAAA;EAAA,SAaA,MAAA,EAAQ,SAAA;EAAA,SACR,MAAA,EAAQ,eAAA;EAAA,iBACA,WAAA;EAAA,iBACA,gBAAA;EHrBR;EAAA,SGOF,EAAA;EHJsB;EGM/B,IAAA;EHN+B;EGQ/B,KAAA;EHJA;EAAA,SGMS,SAAA;EAAA,QAED,QAAA;cAGG,MAAA,EAAQ,SAAA,EACR,MAAA,EAAQ,eAAA,EACA,WAAA,EAAa,WAAA,EACb,gBAAA,EAAkB,GAAA,SAAY,SAAA,GAC/C,EAAA,UACA,SAAA;;EASF,GAAA,SAAA,CAAa,GAAA,WAAc,CAAA;;EAK3B,GAAA,CAAI,GAAA,UAAa,KAAA;EFCI;EEIrB,IAAA,CAAK,KAAA,UAAe,IAAA;EFUO;EEH3B,SAAA,CAAU,KAAA,UAAe,IAAA;EFOE;EEG3B,YAAA,CAAa,KAAA,UAAe,IAAA;EFCT;EESnB,IAAA,CAAK,IAAA;;EAKL,KAAA,CAAM,IAAA;EFoBQ;EEfd,KAAA,CAAA;EF2Ca;EEtCb,EAAA,CAAG,IAAA;IAAiB,IAAA,CAAK,KAAA,UAAe,IAAA;EAAA;AAAA;;;;;;;AHhG1C;;;;;AAKA;;;;;AAEA;;iBIUgB,YAAA,CAAa,SAAA,YAAqB,cAAA;;;;;;;;AJFlD;;;;cIiCa,SAAA,QAtBA,eAAA;;;;;;;;AHwBb;;;;cGWa,YAAA,QAnCA,eAAA;;;;;;;;;;;;cAgDA,OAAA,QAhDA,eAAA;;;;;;;;;;;;;;;;;;;;iBAqEG,SAAA,CAAU,KAAA,WAAgB,eAAA"}

package/dist/index.mjs

@@ -0,0 +1,458 @@
+/**
+ * @forinda/kickjs-ws v2.2.0
+ *
+ * Copyright (c) Felix Orinda
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+import { randomUUID } from "node:crypto";
+import { WebSocketServer } from "ws";
+import { Service, createLogger, getClassMeta, getClassMetaOrUndefined, pushClassMeta, ref, setClassMeta } from "@forinda/kickjs";
+//#region src/interfaces.ts
+const WS_METADATA = {
+	WS_CONTROLLER: Symbol("kick:ws:controller"),
+	WS_HANDLERS: Symbol("kick:ws:handlers")
+};
+/** Registry of all @WsController classes — populated at decorator time */
+const wsControllerRegistry = /* @__PURE__ */ new Set();
+//#endregion
+//#region src/ws-context.ts
+/**
+* Context object passed to WebSocket handler methods.
+* Analogous to RequestContext for HTTP controllers.
+*
+* @example
+* ```ts
+* @OnMessage('chat:send')
+* handleSend(ctx: WsContext) {
+*   console.log(ctx.data)          // parsed message payload
+*   ctx.send('chat:ack', { ok: true })
+*   ctx.broadcast('chat:receive', ctx.data)
+*   ctx.join('room-1')
+*   ctx.to('room-1').send('chat:receive', ctx.data)
+* }
+* ```
+*/
+var WsContext = class {
+	/** Unique connection ID */
+	id;
+	/** Parsed message payload (set for @OnMessage handlers) */
+	data;
+	/** Event name from the message envelope (set for @OnMessage handlers) */
+	event;
+	/** The namespace this connection belongs to */
+	namespace;
+	metadata = /* @__PURE__ */ new Map();
+	constructor(socket, server, roomManager, namespaceSockets, id, namespace) {
+		this.socket = socket;
+		this.server = server;
+		this.roomManager = roomManager;
+		this.namespaceSockets = namespaceSockets;
+		this.id = id;
+		this.namespace = namespace;
+		this.data = null;
+		this.event = "";
+	}
+	/** Get a metadata value */
+	get(key) {
+		return this.metadata.get(key);
+	}
+	/** Set a metadata value (persists for the lifetime of the connection) */
+	set(key, value) {
+		this.metadata.set(key, value);
+	}
+	/** Send a message to this socket */
+	send(event, data) {
+		if (this.socket.readyState === this.socket.OPEN) this.socket.send(JSON.stringify({
+			event,
+			data
+		}));
+	}
+	/** Send to all sockets in the same namespace except this one */
+	broadcast(event, data) {
+		const message = JSON.stringify({
+			event,
+			data
+		});
+		for (const [id, socket] of this.namespaceSockets) if (id !== this.id && socket.readyState === socket.OPEN) socket.send(message);
+	}
+	/** Send to all sockets in the same namespace including this one */
+	broadcastAll(event, data) {
+		const message = JSON.stringify({
+			event,
+			data
+		});
+		for (const [, socket] of this.namespaceSockets) if (socket.readyState === socket.OPEN) socket.send(message);
+	}
+	/** Join a room */
+	join(room) {
+		this.roomManager.join(this.id, this.socket, room);
+	}
+	/** Leave a room */
+	leave(room) {
+		this.roomManager.leave(this.id, room);
+	}
+	/** Get all rooms this socket is in */
+	rooms() {
+		return this.roomManager.getRooms(this.id);
+	}
+	/** Send to all sockets in a room */
+	to(room) {
+		return { send: (event, data) => {
+			this.roomManager.broadcast(room, event, data);
+		} };
+	}
+};
+//#endregion
+//#region src/room-manager.ts
+/**
+* Manages WebSocket room membership and broadcasting.
+* Standalone from ws/socket.io — can be swapped for socket.io's built-in rooms.
+*/
+var RoomManager = class {
+	/** socketId → set of room names */
+	socketRooms = /* @__PURE__ */ new Map();
+	/** room name → set of { socketId, socket } */
+	roomSockets = /* @__PURE__ */ new Map();
+	join(socketId, socket, room) {
+		if (!this.socketRooms.has(socketId)) this.socketRooms.set(socketId, /* @__PURE__ */ new Set());
+		this.socketRooms.get(socketId).add(room);
+		if (!this.roomSockets.has(room)) this.roomSockets.set(room, /* @__PURE__ */ new Map());
+		this.roomSockets.get(room).set(socketId, socket);
+	}
+	leave(socketId, room) {
+		this.socketRooms.get(socketId)?.delete(room);
+		this.roomSockets.get(room)?.delete(socketId);
+		if (this.roomSockets.get(room)?.size === 0) this.roomSockets.delete(room);
+	}
+	/** Remove socket from all rooms (called on disconnect) */
+	leaveAll(socketId) {
+		const rooms = this.socketRooms.get(socketId);
+		if (rooms) for (const room of rooms) {
+			this.roomSockets.get(room)?.delete(socketId);
+			if (this.roomSockets.get(room)?.size === 0) this.roomSockets.delete(room);
+		}
+		this.socketRooms.delete(socketId);
+	}
+	getRooms(socketId) {
+		return Array.from(this.socketRooms.get(socketId) ?? []);
+	}
+	getSockets(room) {
+		return this.roomSockets.get(room) ?? /* @__PURE__ */ new Map();
+	}
+	/** Get all rooms with their member counts */
+	getAllRooms() {
+		const result = {};
+		for (const [room, sockets] of this.roomSockets) result[room] = sockets.size;
+		return result;
+	}
+	/** Broadcast to all sockets in a room, optionally excluding one */
+	broadcast(room, event, data, excludeId) {
+		const sockets = this.roomSockets.get(room);
+		if (!sockets) return;
+		const message = JSON.stringify({
+			event,
+			data
+		});
+		for (const [id, socket] of sockets) if (id !== excludeId && socket.readyState === socket.OPEN) socket.send(message);
+	}
+};
+//#endregion
+//#region src/ws-adapter.ts
+const log = createLogger("WsAdapter");
+/**
+* WebSocket adapter for KickJS. Attaches to the HTTP server and routes
+* WebSocket connections to @WsController classes based on namespace paths.
+*
+* @example
+* ```ts
+* import { WsAdapter } from '@forinda/kickjs-ws'
+*
+* bootstrap({
+*   modules: [ChatModule],
+*   adapters: [
+*     new WsAdapter({ path: '/ws' }),
+*   ],
+* })
+* ```
+*
+* Clients connect to: `ws://localhost:3000/ws/chat`
+* Messages are JSON: `{ "event": "send", "data": { "text": "hello" } }`
+*/
+var WsAdapter = class {
+	name = "WsAdapter";
+	basePath;
+	heartbeatInterval;
+	maxPayload;
+	wss = null;
+	container = null;
+	namespaces = /* @__PURE__ */ new Map();
+	roomManager = new RoomManager();
+	heartbeatTimer = null;
+	/** Total WebSocket connections ever opened */
+	totalConnections;
+	/** Currently active connections */
+	activeConnections;
+	/** Total messages received */
+	messagesReceived;
+	/** Total messages sent */
+	messagesSent;
+	/** Total errors */
+	wsErrors;
+	constructor(options = {}) {
+		this.basePath = options.path ?? "/ws";
+		this.heartbeatInterval = options.heartbeatInterval ?? 3e4;
+		this.maxPayload = options.maxPayload;
+		this.totalConnections = ref(0);
+		this.activeConnections = ref(0);
+		this.messagesReceived = ref(0);
+		this.messagesSent = ref(0);
+		this.wsErrors = ref(0);
+	}
+	/** Get a snapshot of WebSocket stats for DevTools */
+	getStats() {
+		const namespaceStats = {};
+		for (const [path, entry] of this.namespaces) namespaceStats[path] = {
+			connections: entry.sockets.size,
+			handlers: entry.handlers.length
+		};
+		return {
+			totalConnections: this.totalConnections.value,
+			activeConnections: this.activeConnections.value,
+			messagesReceived: this.messagesReceived.value,
+			messagesSent: this.messagesSent.value,
+			errors: this.wsErrors.value,
+			namespaces: namespaceStats,
+			rooms: this.roomManager.getAllRooms()
+		};
+	}
+	beforeStart({ container }) {
+		this.container = container;
+		for (const controllerClass of wsControllerRegistry) {
+			const namespace = getClassMetaOrUndefined(WS_METADATA.WS_CONTROLLER, controllerClass);
+			if (namespace === void 0) continue;
+			const handlers = getClassMeta(WS_METADATA.WS_HANDLERS, controllerClass, []);
+			const fullPath = this.basePath + (namespace === "/" ? "" : namespace);
+			this.namespaces.set(fullPath, {
+				namespace,
+				controllerClass,
+				handlers,
+				sockets: /* @__PURE__ */ new Map(),
+				contexts: /* @__PURE__ */ new Map()
+			});
+			log.info(`Registered WS namespace: ${fullPath} (${controllerClass.name})`);
+		}
+	}
+	afterStart({ server }) {
+		if (!server) return;
+		this.wss = new WebSocketServer({
+			noServer: true,
+			maxPayload: this.maxPayload
+		});
+		server.on("upgrade", (request, socket, head) => {
+			const pathname = (request.url || "/").split("?")[0];
+			const entry = this.namespaces.get(pathname);
+			if (!entry) {
+				socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+				socket.destroy();
+				return;
+			}
+			this.wss.handleUpgrade(request, socket, head, (ws) => {
+				this.handleConnection(ws, entry);
+			});
+		});
+		if (this.heartbeatInterval > 0) this.heartbeatTimer = setInterval(() => {
+			for (const [, entry] of this.namespaces) for (const [, socket] of entry.sockets) {
+				if (socket.__alive === false) {
+					socket.terminate();
+					continue;
+				}
+				socket.__alive = false;
+				socket.ping();
+			}
+		}, this.heartbeatInterval);
+		const totalHandlers = Array.from(this.namespaces.values()).reduce((sum, e) => sum + e.handlers.length, 0);
+		log.info(`WebSocket ready — ${this.namespaces.size} namespace(s), ${totalHandlers} handler(s)`);
+	}
+	shutdown() {
+		if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+		for (const [, entry] of this.namespaces) {
+			for (const [, socket] of entry.sockets) socket.close(1001, "Server shutting down");
+			entry.sockets.clear();
+			entry.contexts.clear();
+		}
+		this.wss?.close();
+	}
+	handleConnection(ws, entry) {
+		const socketId = randomUUID();
+		ws.__alive = true;
+		entry.sockets.set(socketId, ws);
+		this.totalConnections.value++;
+		this.activeConnections.value++;
+		const ctx = new WsContext(ws, this.wss, this.roomManager, entry.sockets, socketId, entry.namespace);
+		entry.contexts.set(socketId, ctx);
+		const controller = this.container.resolve(entry.controllerClass);
+		ws.on("pong", () => {
+			ws.__alive = true;
+		});
+		this.invokeHandlers(controller, entry.handlers, "connect", ctx);
+		ws.on("message", (raw) => {
+			this.messagesReceived.value++;
+			try {
+				const parsed = JSON.parse(raw.toString());
+				const event = parsed.event;
+				const data = parsed.data;
+				if (!event || typeof event !== "string") {
+					ctx.send("error", { message: "Invalid message format: missing \"event\" field" });
+					return;
+				}
+				ctx.event = event;
+				ctx.data = data;
+				const handler = entry.handlers.find((h) => h.type === "message" && h.event === event);
+				if (handler) this.safeInvoke(controller, handler.handlerName, ctx);
+				else {
+					const catchAll = entry.handlers.find((h) => h.type === "message" && h.event === "*");
+					if (catchAll) this.safeInvoke(controller, catchAll.handlerName, ctx);
+				}
+			} catch {
+				ctx.data = { message: "Invalid JSON" };
+				this.invokeHandlers(controller, entry.handlers, "error", ctx);
+			}
+		});
+		ws.on("close", () => {
+			this.activeConnections.value--;
+			this.invokeHandlers(controller, entry.handlers, "disconnect", ctx);
+			this.roomManager.leaveAll(socketId);
+			entry.sockets.delete(socketId);
+			entry.contexts.delete(socketId);
+		});
+		ws.on("error", (err) => {
+			this.wsErrors.value++;
+			ctx.data = {
+				message: err.message,
+				name: err.name
+			};
+			this.invokeHandlers(controller, entry.handlers, "error", ctx);
+		});
+	}
+	invokeHandlers(controller, handlers, type, ctx) {
+		for (const handler of handlers) if (handler.type === type) this.safeInvoke(controller, handler.handlerName, ctx);
+	}
+	safeInvoke(controller, method, ctx) {
+		try {
+			const result = controller[method](ctx);
+			if (result instanceof Promise) result.catch((err) => {
+				log.error({ err }, `WS handler error in ${method}`);
+			});
+		} catch (err) {
+			log.error({ err }, `WS handler error in ${method}`);
+		}
+	}
+};
+//#endregion
+//#region src/decorators.ts
+/**
+* Mark a class as a WebSocket controller with a namespace path.
+* Registers the class in the DI container and the WS controller registry.
+*
+* @example
+* ```ts
+* @WsController('/chat')
+* export class ChatController {
+*   @OnConnect()
+*   handleConnect(ctx: WsContext) { }
+*
+*   @OnMessage('send')
+*   handleSend(ctx: WsContext) { }
+* }
+* ```
+*/
+function WsController(namespace) {
+	return (target) => {
+		Service()(target);
+		setClassMeta(WS_METADATA.WS_CONTROLLER, namespace || "/", target);
+		wsControllerRegistry.add(target);
+	};
+}
+function createWsHandlerDecorator(type, event) {
+	return () => {
+		return (target, propertyKey) => {
+			pushClassMeta(WS_METADATA.WS_HANDLERS, target.constructor, {
+				type,
+				event,
+				handlerName: propertyKey
+			});
+		};
+	};
+}
+/**
+* Handle new WebSocket connections.
+*
+* @example
+* ```ts
+* @OnConnect()
+* handleConnect(ctx: WsContext) {
+*   console.log(`Client ${ctx.id} connected`)
+* }
+* ```
+*/
+const OnConnect = createWsHandlerDecorator("connect");
+/**
+* Handle WebSocket disconnections.
+*
+* @example
+* ```ts
+* @OnDisconnect()
+* handleDisconnect(ctx: WsContext) {
+*   console.log(`Client ${ctx.id} disconnected`)
+* }
+* ```
+*/
+const OnDisconnect = createWsHandlerDecorator("disconnect");
+/**
+* Handle WebSocket errors.
+*
+* @example
+* ```ts
+* @OnError()
+* handleError(ctx: WsContext) {
+*   console.error('WS error:', ctx.data)
+* }
+* ```
+*/
+const OnError = createWsHandlerDecorator("error");
+/**
+* Handle a specific WebSocket message event.
+* Use '*' as a catch-all for unmatched events.
+*
+* Messages must be JSON: `{ "event": "chat:send", "data": { ... } }`
+*
+* @example
+* ```ts
+* @OnMessage('chat:send')
+* handleChatSend(ctx: WsContext) {
+*   ctx.broadcast('chat:receive', ctx.data)
+* }
+*
+* @OnMessage('*')
+* handleUnknown(ctx: WsContext) {
+*   ctx.send('error', { message: `Unknown event: ${ctx.event}` })
+* }
+* ```
+*/
+function OnMessage(event) {
+	return (target, propertyKey) => {
+		pushClassMeta(WS_METADATA.WS_HANDLERS, target.constructor, {
+			type: "message",
+			event,
+			handlerName: propertyKey
+		});
+	};
+}
+//#endregion
+export { OnConnect, OnDisconnect, OnError, OnMessage, RoomManager, WS_METADATA, WsAdapter, WsContext, WsController };
+
+//# sourceMappingURL=index.mjs.map