@forinda/kickjs-ws 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Felix Orinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+import { AppAdapter, Ref, Container } from '@forinda/kickjs-core';
+import { WebSocket, WebSocketServer } from 'ws';
+
+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;
+}
+
+/**
+ * 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(_app: any, container: Container): void;
+    afterStart(server: any, _container: Container): void;
+    shutdown(): void;
+    private handleConnection;
+    private invokeHandlers;
+    private safeInvoke;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+    };
+}
+
+/**
+ * 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;
+
+export { OnConnect, OnDisconnect, OnError, OnMessage, RoomManager, WS_METADATA, WsAdapter, type WsAdapterOptions, WsContext, WsController, type WsHandlerDefinition, type WsHandlerType };

package/dist/index.js

@@ -0,0 +1,434 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/ws-adapter.ts
+import { randomUUID } from "crypto";
+import { WebSocketServer } from "ws";
+import { createLogger, ref } from "@forinda/kickjs-core";
+
+// src/interfaces.ts
+var WS_METADATA = {
+  WS_CONTROLLER: /* @__PURE__ */ Symbol("kick:ws:controller"),
+  WS_HANDLERS: /* @__PURE__ */ Symbol("kick:ws:handlers")
+};
+var wsControllerRegistry = /* @__PURE__ */ new Set();
+
+// src/ws-context.ts
+var WsContext = class {
+  static {
+    __name(this, "WsContext");
+  }
+  socket;
+  server;
+  roomManager;
+  namespaceSockets;
+  /** 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: /* @__PURE__ */ __name((event, data) => {
+        this.roomManager.broadcast(room, event, data);
+      }, "send")
+    };
+  }
+};
+
+// src/room-manager.ts
+var RoomManager = class {
+  static {
+    __name(this, "RoomManager");
+  }
+  /** 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);
+      }
+    }
+  }
+};
+
+// src/ws-adapter.ts
+var log = createLogger("WsAdapter");
+var WsAdapter = class {
+  static {
+    __name(this, "WsAdapter");
+  }
+  name = "WsAdapter";
+  basePath;
+  heartbeatInterval;
+  maxPayload;
+  wss = null;
+  container = null;
+  namespaces = /* @__PURE__ */ new Map();
+  roomManager = new RoomManager();
+  heartbeatTimer = null;
+  // ── Reactive Stats (exposed for DevToolsAdapter) ─────────────────────
+  /** 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(_app, container) {
+    this.container = container;
+    for (const controllerClass of wsControllerRegistry) {
+      const namespace = Reflect.getMetadata(WS_METADATA.WS_CONTROLLER, controllerClass);
+      if (namespace === void 0) continue;
+      const handlers = Reflect.getMetadata(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, _container) {
+    this.wss = new WebSocketServer({
+      noServer: true,
+      maxPayload: this.maxPayload
+    });
+    server.on("upgrade", (request, socket, head) => {
+      const url = request.url || "/";
+      const pathname = 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 \u2014 ${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();
+  }
+  // ── Internal ───────────────────────────────────────────────────────────
+  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}`);
+    }
+  }
+};
+
+// src/decorators.ts
+import "reflect-metadata";
+import { Service } from "@forinda/kickjs-core";
+function WsController(namespace) {
+  return (target) => {
+    Service()(target);
+    Reflect.defineMetadata(WS_METADATA.WS_CONTROLLER, namespace || "/", target);
+    wsControllerRegistry.add(target);
+  };
+}
+__name(WsController, "WsController");
+function createWsHandlerDecorator(type, event) {
+  return () => {
+    return (target, propertyKey) => {
+      const handlers = Reflect.getMetadata(WS_METADATA.WS_HANDLERS, target.constructor) || [];
+      handlers.push({
+        type,
+        event,
+        handlerName: propertyKey
+      });
+      Reflect.defineMetadata(WS_METADATA.WS_HANDLERS, handlers, target.constructor);
+    };
+  };
+}
+__name(createWsHandlerDecorator, "createWsHandlerDecorator");
+var OnConnect = createWsHandlerDecorator("connect");
+var OnDisconnect = createWsHandlerDecorator("disconnect");
+var OnError = createWsHandlerDecorator("error");
+function OnMessage(event) {
+  return (target, propertyKey) => {
+    const handlers = Reflect.getMetadata(WS_METADATA.WS_HANDLERS, target.constructor) || [];
+    handlers.push({
+      type: "message",
+      event,
+      handlerName: propertyKey
+    });
+    Reflect.defineMetadata(WS_METADATA.WS_HANDLERS, handlers, target.constructor);
+  };
+}
+__name(OnMessage, "OnMessage");
+export {
+  OnConnect,
+  OnDisconnect,
+  OnError,
+  OnMessage,
+  RoomManager,
+  WS_METADATA,
+  WsAdapter,
+  WsContext,
+  WsController
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ws-adapter.ts","../src/interfaces.ts","../src/ws-context.ts","../src/room-manager.ts","../src/decorators.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto'\nimport { WebSocketServer, type WebSocket } from 'ws'\nimport type { IncomingMessage } from 'node:http'\nimport type { Duplex } from 'node:stream'\nimport { type AppAdapter, type Container, createLogger, ref, type Ref } from '@forinda/kickjs-core'\nimport {\n  WS_METADATA,\n  wsControllerRegistry,\n  type WsAdapterOptions,\n  type WsHandlerDefinition,\n} from './interfaces'\nimport { WsContext } from './ws-context'\nimport { RoomManager } from './room-manager'\n\nconst log = createLogger('WsAdapter')\n\ninterface NamespaceEntry {\n  namespace: string\n  controllerClass: any\n  handlers: WsHandlerDefinition[]\n  sockets: Map<string, WebSocket>\n  contexts: Map<string, WsContext>\n}\n\n/**\n * WebSocket adapter for KickJS. Attaches to the HTTP server and routes\n * WebSocket connections to @WsController classes based on namespace paths.\n *\n * @example\n * ```ts\n * import { WsAdapter } from '@forinda/kickjs-ws'\n *\n * bootstrap({\n *   modules: [ChatModule],\n *   adapters: [\n *     new WsAdapter({ path: '/ws' }),\n *   ],\n * })\n * ```\n *\n * Clients connect to: `ws://localhost:3000/ws/chat`\n * Messages are JSON: `{ \"event\": \"send\", \"data\": { \"text\": \"hello\" } }`\n */\nexport class WsAdapter implements AppAdapter {\n  readonly name = 'WsAdapter'\n\n  private basePath: string\n  private heartbeatInterval: number\n  private maxPayload: number | undefined\n  private wss: WebSocketServer | null = null\n  private container: Container | null = null\n  private namespaces = new Map<string, NamespaceEntry>()\n  private roomManager = new RoomManager()\n  private heartbeatTimer: ReturnType<typeof setInterval> | null = null\n\n  // ── Reactive Stats (exposed for DevToolsAdapter) ─────────────────────\n  /** Total WebSocket connections ever opened */\n  readonly totalConnections: Ref<number>\n  /** Currently active connections */\n  readonly activeConnections: Ref<number>\n  /** Total messages received */\n  readonly messagesReceived: Ref<number>\n  /** Total messages sent */\n  readonly messagesSent: Ref<number>\n  /** Total errors */\n  readonly wsErrors: Ref<number>\n\n  constructor(options: WsAdapterOptions = {}) {\n    this.basePath = options.path ?? '/ws'\n    this.heartbeatInterval = options.heartbeatInterval ?? 30000\n    this.maxPayload = options.maxPayload\n\n    this.totalConnections = ref(0)\n    this.activeConnections = ref(0)\n    this.messagesReceived = ref(0)\n    this.messagesSent = ref(0)\n    this.wsErrors = ref(0)\n  }\n\n  /** Get a snapshot of WebSocket stats for DevTools */\n  getStats() {\n    const namespaceStats: Record<string, { connections: number; handlers: number }> = {}\n    for (const [path, entry] of this.namespaces) {\n      namespaceStats[path] = {\n        connections: entry.sockets.size,\n        handlers: entry.handlers.length,\n      }\n    }\n    return {\n      totalConnections: this.totalConnections.value,\n      activeConnections: this.activeConnections.value,\n      messagesReceived: this.messagesReceived.value,\n      messagesSent: this.messagesSent.value,\n      errors: this.wsErrors.value,\n      namespaces: namespaceStats,\n      rooms: this.roomManager.getAllRooms(),\n    }\n  }\n\n  beforeStart(_app: any, container: Container): void {\n    this.container = container\n\n    // Discover all @WsController classes and build routing table\n    for (const controllerClass of wsControllerRegistry) {\n      const namespace: string | undefined = Reflect.getMetadata(\n        WS_METADATA.WS_CONTROLLER,\n        controllerClass,\n      )\n      if (namespace === undefined) continue\n\n      const handlers: WsHandlerDefinition[] =\n        Reflect.getMetadata(WS_METADATA.WS_HANDLERS, controllerClass) || []\n\n      const fullPath = this.basePath + (namespace === '/' ? '' : namespace)\n\n      this.namespaces.set(fullPath, {\n        namespace,\n        controllerClass,\n        handlers,\n        sockets: new Map(),\n        contexts: new Map(),\n      })\n\n      log.info(`Registered WS namespace: ${fullPath} (${controllerClass.name})`)\n    }\n  }\n\n  afterStart(server: any, _container: Container): void {\n    this.wss = new WebSocketServer({\n      noServer: true,\n      maxPayload: this.maxPayload,\n    })\n\n    // Handle upgrade requests — route to correct namespace\n    server.on('upgrade', (request: IncomingMessage, socket: Duplex, head: Buffer) => {\n      const url = request.url || '/'\n      // Parse pathname without relying on host header\n      const pathname = url.split('?')[0]\n\n      const entry = this.namespaces.get(pathname)\n      if (!entry) {\n        socket.write('HTTP/1.1 404 Not Found\\r\\n\\r\\n')\n        socket.destroy()\n        return\n      }\n\n      this.wss!.handleUpgrade(request, socket, head, (ws) => {\n        this.handleConnection(ws, entry)\n      })\n    })\n\n    // Heartbeat ping/pong\n    if (this.heartbeatInterval > 0) {\n      this.heartbeatTimer = setInterval(() => {\n        for (const [, entry] of this.namespaces) {\n          for (const [, socket] of entry.sockets) {\n            if ((socket as any).__alive === false) {\n              socket.terminate()\n              continue\n            }\n            ;(socket as any).__alive = false\n            socket.ping()\n          }\n        }\n      }, this.heartbeatInterval)\n    }\n\n    const totalHandlers = Array.from(this.namespaces.values()).reduce(\n      (sum, e) => sum + e.handlers.length,\n      0,\n    )\n    log.info(`WebSocket ready — ${this.namespaces.size} namespace(s), ${totalHandlers} handler(s)`)\n  }\n\n  shutdown(): void {\n    if (this.heartbeatTimer) {\n      clearInterval(this.heartbeatTimer)\n    }\n\n    // Close all connections\n    for (const [, entry] of this.namespaces) {\n      for (const [, socket] of entry.sockets) {\n        socket.close(1001, 'Server shutting down')\n      }\n      entry.sockets.clear()\n      entry.contexts.clear()\n    }\n\n    this.wss?.close()\n  }\n\n  // ── Internal ───────────────────────────────────────────────────────────\n\n  private handleConnection(ws: WebSocket, entry: NamespaceEntry): void {\n    const socketId = randomUUID()\n    ;(ws as any).__alive = true\n\n    entry.sockets.set(socketId, ws)\n    this.totalConnections.value++\n    this.activeConnections.value++\n\n    const ctx = new WsContext(\n      ws,\n      this.wss!,\n      this.roomManager,\n      entry.sockets,\n      socketId,\n      entry.namespace,\n    )\n    entry.contexts.set(socketId, ctx)\n\n    // Resolve controller from DI\n    const controller = this.container!.resolve(entry.controllerClass)\n\n    // Pong handler for heartbeat\n    ws.on('pong', () => {\n      ;(ws as any).__alive = true\n    })\n\n    // @OnConnect handlers\n    this.invokeHandlers(controller, entry.handlers, 'connect', ctx)\n\n    // Message handler\n    ws.on('message', (raw: Buffer | string) => {\n      this.messagesReceived.value++\n      try {\n        const parsed = JSON.parse(raw.toString())\n        const event = parsed.event as string\n        const data = parsed.data\n\n        if (!event || typeof event !== 'string') {\n          ctx.send('error', { message: 'Invalid message format: missing \"event\" field' })\n          return\n        }\n\n        ctx.event = event\n        ctx.data = data\n\n        // Find matching @OnMessage handler\n        const handler = entry.handlers.find((h) => h.type === 'message' && h.event === event)\n\n        if (handler) {\n          this.safeInvoke(controller, handler.handlerName, ctx)\n        } else {\n          // Try catch-all @OnMessage('*')\n          const catchAll = entry.handlers.find((h) => h.type === 'message' && h.event === '*')\n          if (catchAll) {\n            this.safeInvoke(controller, catchAll.handlerName, ctx)\n          }\n        }\n      } catch {\n        ctx.data = { message: 'Invalid JSON' }\n        this.invokeHandlers(controller, entry.handlers, 'error', ctx)\n      }\n    })\n\n    // Close handler\n    ws.on('close', () => {\n      this.activeConnections.value--\n      this.invokeHandlers(controller, entry.handlers, 'disconnect', ctx)\n      this.roomManager.leaveAll(socketId)\n      entry.sockets.delete(socketId)\n      entry.contexts.delete(socketId)\n    })\n\n    // Error handler\n    ws.on('error', (err: Error) => {\n      this.wsErrors.value++\n      ctx.data = { message: err.message, name: err.name }\n      this.invokeHandlers(controller, entry.handlers, 'error', ctx)\n    })\n  }\n\n  private invokeHandlers(\n    controller: any,\n    handlers: WsHandlerDefinition[],\n    type: WsHandlerDefinition['type'],\n    ctx: WsContext,\n  ): void {\n    for (const handler of handlers) {\n      if (handler.type === type) {\n        this.safeInvoke(controller, handler.handlerName, ctx)\n      }\n    }\n  }\n\n  private safeInvoke(controller: any, method: string, ctx: WsContext): void {\n    try {\n      const result = controller[method](ctx)\n      if (result instanceof Promise) {\n        result.catch((err: Error) => {\n          log.error({ err }, `WS handler error in ${method}`)\n        })\n      }\n    } catch (err) {\n      log.error({ err }, `WS handler error in ${method}`)\n    }\n  }\n}\n","type Constructor = new (...args: any[]) => any\n\nexport const WS_METADATA = {\n  WS_CONTROLLER: Symbol('kick:ws:controller'),\n  WS_HANDLERS: Symbol('kick:ws:handlers'),\n} as const\n\nexport type WsHandlerType = 'connect' | 'disconnect' | 'message' | 'error'\n\nexport interface WsHandlerDefinition {\n  type: WsHandlerType\n  /** Event name — only for 'message' type */\n  event?: string\n  /** Method name on the controller class */\n  handlerName: string\n}\n\nexport interface WsAdapterOptions {\n  /** Base path for WebSocket upgrade (default: '/ws') */\n  path?: string\n  /** Heartbeat ping interval in ms (default: 30000). Set to 0 to disable. */\n  heartbeatInterval?: number\n  /** Maximum message payload size in bytes */\n  maxPayload?: number\n}\n\n/** Registry of all @WsController classes — populated at decorator time */\nexport const wsControllerRegistry = new Set<Constructor>()\n","import type { WebSocket, WebSocketServer } from 'ws'\nimport type { RoomManager } from './room-manager'\n\n/**\n * Context object passed to WebSocket handler methods.\n * Analogous to RequestContext for HTTP controllers.\n *\n * @example\n * ```ts\n * @OnMessage('chat:send')\n * handleSend(ctx: WsContext) {\n *   console.log(ctx.data)          // parsed message payload\n *   ctx.send('chat:ack', { ok: true })\n *   ctx.broadcast('chat:receive', ctx.data)\n *   ctx.join('room-1')\n *   ctx.to('room-1').send('chat:receive', ctx.data)\n * }\n * ```\n */\nexport class WsContext {\n  /** Unique connection ID */\n  readonly id: string\n  /** Parsed message payload (set for @OnMessage handlers) */\n  data: any\n  /** Event name from the message envelope (set for @OnMessage handlers) */\n  event: string\n  /** The namespace this connection belongs to */\n  readonly namespace: string\n\n  private metadata = new Map<string, any>()\n\n  constructor(\n    readonly socket: WebSocket,\n    readonly server: WebSocketServer,\n    private readonly roomManager: RoomManager,\n    private readonly namespaceSockets: Map<string, WebSocket>,\n    id: string,\n    namespace: string,\n  ) {\n    this.id = id\n    this.namespace = namespace\n    this.data = null\n    this.event = ''\n  }\n\n  /** Get a metadata value */\n  get<T = any>(key: string): T | undefined {\n    return this.metadata.get(key)\n  }\n\n  /** Set a metadata value (persists for the lifetime of the connection) */\n  set(key: string, value: any): void {\n    this.metadata.set(key, value)\n  }\n\n  /** Send a message to this socket */\n  send(event: string, data: any): void {\n    if (this.socket.readyState === this.socket.OPEN) {\n      this.socket.send(JSON.stringify({ event, data }))\n    }\n  }\n\n  /** Send to all sockets in the same namespace except this one */\n  broadcast(event: string, data: any): void {\n    const message = JSON.stringify({ event, data })\n    for (const [id, socket] of this.namespaceSockets) {\n      if (id !== this.id && socket.readyState === socket.OPEN) {\n        socket.send(message)\n      }\n    }\n  }\n\n  /** Send to all sockets in the same namespace including this one */\n  broadcastAll(event: string, data: any): void {\n    const message = JSON.stringify({ event, data })\n    for (const [, socket] of this.namespaceSockets) {\n      if (socket.readyState === socket.OPEN) {\n        socket.send(message)\n      }\n    }\n  }\n\n  /** Join a room */\n  join(room: string): void {\n    this.roomManager.join(this.id, this.socket, room)\n  }\n\n  /** Leave a room */\n  leave(room: string): void {\n    this.roomManager.leave(this.id, room)\n  }\n\n  /** Get all rooms this socket is in */\n  rooms(): string[] {\n    return this.roomManager.getRooms(this.id)\n  }\n\n  /** Send to all sockets in a room */\n  to(room: string): { send(event: string, data: any): void } {\n    return {\n      send: (event: string, data: any) => {\n        this.roomManager.broadcast(room, event, data)\n      },\n    }\n  }\n}\n","import type { WebSocket } from 'ws'\n\n/**\n * Manages WebSocket room membership and broadcasting.\n * Standalone from ws/socket.io — can be swapped for socket.io's built-in rooms.\n */\nexport class RoomManager {\n  /** socketId → set of room names */\n  private socketRooms = new Map<string, Set<string>>()\n  /** room name → set of { socketId, socket } */\n  private roomSockets = new Map<string, Map<string, WebSocket>>()\n\n  join(socketId: string, socket: WebSocket, room: string): void {\n    if (!this.socketRooms.has(socketId)) {\n      this.socketRooms.set(socketId, new Set())\n    }\n    this.socketRooms.get(socketId)!.add(room)\n\n    if (!this.roomSockets.has(room)) {\n      this.roomSockets.set(room, new Map())\n    }\n    this.roomSockets.get(room)!.set(socketId, socket)\n  }\n\n  leave(socketId: string, room: string): void {\n    this.socketRooms.get(socketId)?.delete(room)\n    this.roomSockets.get(room)?.delete(socketId)\n\n    // Clean up empty rooms\n    if (this.roomSockets.get(room)?.size === 0) {\n      this.roomSockets.delete(room)\n    }\n  }\n\n  /** Remove socket from all rooms (called on disconnect) */\n  leaveAll(socketId: string): void {\n    const rooms = this.socketRooms.get(socketId)\n    if (rooms) {\n      for (const room of rooms) {\n        this.roomSockets.get(room)?.delete(socketId)\n        if (this.roomSockets.get(room)?.size === 0) {\n          this.roomSockets.delete(room)\n        }\n      }\n    }\n    this.socketRooms.delete(socketId)\n  }\n\n  getRooms(socketId: string): string[] {\n    return Array.from(this.socketRooms.get(socketId) ?? [])\n  }\n\n  getSockets(room: string): Map<string, WebSocket> {\n    return this.roomSockets.get(room) ?? new Map()\n  }\n\n  /** Get all rooms with their member counts */\n  getAllRooms(): Record<string, number> {\n    const result: Record<string, number> = {}\n    for (const [room, sockets] of this.roomSockets) {\n      result[room] = sockets.size\n    }\n    return result\n  }\n\n  /** Broadcast to all sockets in a room, optionally excluding one */\n  broadcast(room: string, event: string, data: any, excludeId?: string): void {\n    const sockets = this.roomSockets.get(room)\n    if (!sockets) return\n\n    const message = JSON.stringify({ event, data })\n    for (const [id, socket] of sockets) {\n      if (id !== excludeId && socket.readyState === socket.OPEN) {\n        socket.send(message)\n      }\n    }\n  }\n}\n","import 'reflect-metadata'\nimport { Service } from '@forinda/kickjs-core'\nimport { WS_METADATA, wsControllerRegistry, type WsHandlerDefinition } from './interfaces'\n\n/**\n * Mark a class as a WebSocket controller with a namespace path.\n * Registers the class in the DI container and the WS controller registry.\n *\n * @example\n * ```ts\n * @WsController('/chat')\n * export class ChatController {\n *   @OnConnect()\n *   handleConnect(ctx: WsContext) { }\n *\n *   @OnMessage('send')\n *   handleSend(ctx: WsContext) { }\n * }\n * ```\n */\nexport function WsController(namespace?: string): ClassDecorator {\n  return (target: any) => {\n    Service()(target)\n    Reflect.defineMetadata(WS_METADATA.WS_CONTROLLER, namespace || '/', target)\n    wsControllerRegistry.add(target)\n  }\n}\n\nfunction createWsHandlerDecorator(type: WsHandlerDefinition['type'], event?: string) {\n  return (): MethodDecorator => {\n    return (target, propertyKey) => {\n      const handlers: WsHandlerDefinition[] =\n        Reflect.getMetadata(WS_METADATA.WS_HANDLERS, target.constructor) || []\n      handlers.push({\n        type,\n        event,\n        handlerName: propertyKey as string,\n      })\n      Reflect.defineMetadata(WS_METADATA.WS_HANDLERS, handlers, target.constructor)\n    }\n  }\n}\n\n/**\n * Handle new WebSocket connections.\n *\n * @example\n * ```ts\n * @OnConnect()\n * handleConnect(ctx: WsContext) {\n *   console.log(`Client ${ctx.id} connected`)\n * }\n * ```\n */\nexport const OnConnect = createWsHandlerDecorator('connect')\n\n/**\n * Handle WebSocket disconnections.\n *\n * @example\n * ```ts\n * @OnDisconnect()\n * handleDisconnect(ctx: WsContext) {\n *   console.log(`Client ${ctx.id} disconnected`)\n * }\n * ```\n */\nexport const OnDisconnect = createWsHandlerDecorator('disconnect')\n\n/**\n * Handle WebSocket errors.\n *\n * @example\n * ```ts\n * @OnError()\n * handleError(ctx: WsContext) {\n *   console.error('WS error:', ctx.data)\n * }\n * ```\n */\nexport const OnError = createWsHandlerDecorator('error')\n\n/**\n * Handle a specific WebSocket message event.\n * Use '*' as a catch-all for unmatched events.\n *\n * Messages must be JSON: `{ \"event\": \"chat:send\", \"data\": { ... } }`\n *\n * @example\n * ```ts\n * @OnMessage('chat:send')\n * handleChatSend(ctx: WsContext) {\n *   ctx.broadcast('chat:receive', ctx.data)\n * }\n *\n * @OnMessage('*')\n * handleUnknown(ctx: WsContext) {\n *   ctx.send('error', { message: `Unknown event: ${ctx.event}` })\n * }\n * ```\n */\nexport function OnMessage(event: string): MethodDecorator {\n  return (target, propertyKey) => {\n    const handlers: WsHandlerDefinition[] =\n      Reflect.getMetadata(WS_METADATA.WS_HANDLERS, target.constructor) || []\n    handlers.push({\n      type: 'message',\n      event,\n      handlerName: propertyKey as string,\n    })\n    Reflect.defineMetadata(WS_METADATA.WS_HANDLERS, handlers, target.constructor)\n  }\n}\n"],"mappings":"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","names":["randomUUID","WebSocketServer","createLogger","ref","WS_METADATA","WS_CONTROLLER","Symbol","WS_HANDLERS","wsControllerRegistry","Set","WsContext","id","data","event","namespace","metadata","Map","socket","server","roomManager","namespaceSockets","get","key","set","value","send","readyState","OPEN","JSON","stringify","broadcast","message","broadcastAll","join","room","leave","rooms","getRooms","to","RoomManager","socketRooms","Map","roomSockets","join","socketId","socket","room","has","set","Set","get","add","leave","delete","size","leaveAll","rooms","getRooms","Array","from","getSockets","getAllRooms","result","sockets","broadcast","event","data","excludeId","message","JSON","stringify","id","readyState","OPEN","send","log","createLogger","WsAdapter","name","basePath","heartbeatInterval","maxPayload","wss","container","namespaces","Map","roomManager","RoomManager","heartbeatTimer","totalConnections","activeConnections","messagesReceived","messagesSent","wsErrors","options","path","ref","getStats","namespaceStats","entry","connections","sockets","size","handlers","length","value","errors","rooms","getAllRooms","beforeStart","_app","controllerClass","wsControllerRegistry","namespace","Reflect","getMetadata","WS_METADATA","WS_CONTROLLER","undefined","WS_HANDLERS","fullPath","set","contexts","info","afterStart","server","_container","WebSocketServer","noServer","on","request","socket","head","url","pathname","split","get","write","destroy","handleUpgrade","ws","handleConnection","setInterval","__alive","terminate","ping","totalHandlers","Array","from","values","reduce","sum","e","shutdown","clearInterval","close","clear","socketId","randomUUID","ctx","WsContext","controller","resolve","invokeHandlers","raw","parsed","JSON","parse","toString","event","data","send","message","handler","find","h","type","safeInvoke","handlerName","catchAll","leaveAll","delete","err","method","result","Promise","catch","error","Service","WsController","namespace","target","Service","Reflect","defineMetadata","WS_METADATA","WS_CONTROLLER","wsControllerRegistry","add","createWsHandlerDecorator","type","event","propertyKey","handlers","getMetadata","WS_HANDLERS","push","handlerName","OnConnect","OnDisconnect","OnError","OnMessage"]}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@forinda/kickjs-ws",
+  "version": "0.5.0",
+  "description": "WebSocket support with decorators, namespaces, rooms, and DI integration for KickJS",
+  "keywords": [
+    "kickjs",
+    "nodejs",
+    "typescript",
+    "express",
+    "decorators",
+    "dependency-injection",
+    "backend",
+    "api",
+    "framework",
+    "websocket",
+    "ws",
+    "realtime",
+    "rooms",
+    "namespaces",
+    "@forinda/kickjs-core",
+    "@forinda/kickjs-http",
+    "@forinda/kickjs-config",
+    "@forinda/kickjs-cli",
+    "@forinda/kickjs-swagger",
+    "@forinda/kickjs-testing",
+    "@forinda/kickjs-prisma",
+    "@forinda/kickjs-ws"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "ws": "^8.18.0",
+    "@forinda/kickjs-core": "0.5.0"
+  },
+  "devDependencies": {
+    "@swc/core": "^1.7.28",
+    "@types/node": "^24.5.2",
+    "@types/ws": "^8.18.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Felix Orinda",
+  "engines": {
+    "node": ">=20.0"
+  },
+  "homepage": "https://forinda.github.io/kick-js/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forinda/kick-js.git",
+    "directory": "packages/ws"
+  },
+  "bugs": {
+    "url": "https://github.com/forinda/kick-js/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo",
+    "lint": "tsc --noEmit"
+  }
+}