@forinda/kickjs-ws 1.3.2 → 1.4.1-alpha.0

package/dist/decorators.d.ts

@@ -0,0 +1,75 @@
+import 'reflect-metadata';
+/**
+ * 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) { }
+ * }
+ * ```
+ */
+export declare function WsController(namespace?: string): ClassDecorator;
+/**
+ * Handle new WebSocket connections.
+ *
+ * @example
+ * ```ts
+ * @OnConnect()
+ * handleConnect(ctx: WsContext) {
+ *   console.log(`Client ${ctx.id} connected`)
+ * }
+ * ```
+ */
+export declare const OnConnect: () => MethodDecorator;
+/**
+ * Handle WebSocket disconnections.
+ *
+ * @example
+ * ```ts
+ * @OnDisconnect()
+ * handleDisconnect(ctx: WsContext) {
+ *   console.log(`Client ${ctx.id} disconnected`)
+ * }
+ * ```
+ */
+export declare const OnDisconnect: () => MethodDecorator;
+/**
+ * Handle WebSocket errors.
+ *
+ * @example
+ * ```ts
+ * @OnError()
+ * handleError(ctx: WsContext) {
+ *   console.error('WS error:', ctx.data)
+ * }
+ * ```
+ */
+export 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}` })
+ * }
+ * ```
+ */
+export declare function OnMessage(event: string): MethodDecorator;
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAA;AAIzB;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,cAAc,CAM/D;AAiBD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,QAzBT,eAyB+C,CAAA;AAE5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,QAtCZ,eAsCqD,CAAA;AAElE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,QAnDP,eAmD2C,CAAA;AAExD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAWxD"}

package/dist/index.d.ts

@@ -1,234 +1,6 @@
-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 };
+export { WsAdapter } from './ws-adapter';
+export { WsContext } from './ws-context';
+export { WsController, OnConnect, OnDisconnect, OnMessage, OnError } from './decorators';
+export { RoomManager } from './room-manager';
+export { WS_METADATA, type WsAdapterOptions, type WsHandlerDefinition, type WsHandlerType, } from './interfaces';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAGxC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAGxC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGxF,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAG5C,OAAO,EACL,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -1,3 +1,261 @@
-var A=Object.defineProperty;var r=(i,e)=>A(i,"name",{value:e,configurable:!0});import{randomUUID as x}from"crypto";import{WebSocketServer as C}from"ws";import{createLogger as N,ref as g}from"@forinda/kickjs-core";var l={WS_CONTROLLER:Symbol("kick:ws:controller"),WS_HANDLERS:Symbol("kick:ws:handlers")},v=new Set;var d=class{static{r(this,"WsContext")}socket;server;roomManager;namespaceSockets;id;data;event;namespace;metadata=new Map;constructor(e,t,s,o,a,n){this.socket=e,this.server=t,this.roomManager=s,this.namespaceSockets=o,this.id=a,this.namespace=n,this.data=null,this.event=""}get(e){return this.metadata.get(e)}set(e,t){this.metadata.set(e,t)}send(e,t){this.socket.readyState===this.socket.OPEN&&this.socket.send(JSON.stringify({event:e,data:t}))}broadcast(e,t){let s=JSON.stringify({event:e,data:t});for(let[o,a]of this.namespaceSockets)o!==this.id&&a.readyState===a.OPEN&&a.send(s)}broadcastAll(e,t){let s=JSON.stringify({event:e,data:t});for(let[,o]of this.namespaceSockets)o.readyState===o.OPEN&&o.send(s)}join(e){this.roomManager.join(this.id,this.socket,e)}leave(e){this.roomManager.leave(this.id,e)}rooms(){return this.roomManager.getRooms(this.id)}to(e){return{send:r((t,s)=>{this.roomManager.broadcast(e,t,s)},"send")}}};var f=class{static{r(this,"RoomManager")}socketRooms=new Map;roomSockets=new Map;join(e,t,s){this.socketRooms.has(e)||this.socketRooms.set(e,new Set),this.socketRooms.get(e).add(s),this.roomSockets.has(s)||this.roomSockets.set(s,new Map),this.roomSockets.get(s).set(e,t)}leave(e,t){this.socketRooms.get(e)?.delete(t),this.roomSockets.get(t)?.delete(e),this.roomSockets.get(t)?.size===0&&this.roomSockets.delete(t)}leaveAll(e){let t=this.socketRooms.get(e);if(t)for(let s of t)this.roomSockets.get(s)?.delete(e),this.roomSockets.get(s)?.size===0&&this.roomSockets.delete(s);this.socketRooms.delete(e)}getRooms(e){return Array.from(this.socketRooms.get(e)??[])}getSockets(e){return this.roomSockets.get(e)??new Map}getAllRooms(){let e={};for(let[t,s]of this.roomSockets)e[t]=s.size;return e}broadcast(e,t,s,o){let a=this.roomSockets.get(e);if(!a)return;let n=JSON.stringify({event:t,data:s});for(let[h,c]of a)h!==o&&c.readyState===c.OPEN&&c.send(n)}};var u=N("WsAdapter"),k=class{static{r(this,"WsAdapter")}name="WsAdapter";basePath;heartbeatInterval;maxPayload;wss=null;container=null;namespaces=new Map;roomManager=new f;heartbeatTimer=null;totalConnections;activeConnections;messagesReceived;messagesSent;wsErrors;constructor(e={}){this.basePath=e.path??"/ws",this.heartbeatInterval=e.heartbeatInterval??3e4,this.maxPayload=e.maxPayload,this.totalConnections=g(0),this.activeConnections=g(0),this.messagesReceived=g(0),this.messagesSent=g(0),this.wsErrors=g(0)}getStats(){let e={};for(let[t,s]of this.namespaces)e[t]={connections:s.sockets.size,handlers:s.handlers.length};return{totalConnections:this.totalConnections.value,activeConnections:this.activeConnections.value,messagesReceived:this.messagesReceived.value,messagesSent:this.messagesSent.value,errors:this.wsErrors.value,namespaces:e,rooms:this.roomManager.getAllRooms()}}beforeStart(e,t){this.container=t;for(let s of v){let o=Reflect.getMetadata(l.WS_CONTROLLER,s);if(o===void 0)continue;let a=Reflect.getMetadata(l.WS_HANDLERS,s)||[],n=this.basePath+(o==="/"?"":o);this.namespaces.set(n,{namespace:o,controllerClass:s,handlers:a,sockets:new Map,contexts:new Map}),u.info(`Registered WS namespace: ${n} (${s.name})`)}}afterStart(e,t){this.wss=new C({noServer:!0,maxPayload:this.maxPayload}),e.on("upgrade",(o,a,n)=>{let c=(o.url||"/").split("?")[0],p=this.namespaces.get(c);if(!p){a.write(`HTTP/1.1 404 Not Found\r
+import { randomUUID as k } from "node:crypto";
+import { WebSocketServer as u } from "ws";
+import { Service as p, createLogger as R, ref as h } from "@forinda/kickjs-core";
+import "reflect-metadata";
+var i = {
+  WS_CONTROLLER: /* @__PURE__ */ Symbol("kick:ws:controller"),
+  WS_HANDLERS: /* @__PURE__ */ Symbol("kick:ws:handlers")
+}, S = /* @__PURE__ */ new Set(), M = class {
+  id;
+  data;
+  event;
+  namespace;
+  metadata = /* @__PURE__ */ new Map();
+  constructor(e, t, s, a, o, n) {
+    this.socket = e, this.server = t, this.roomManager = s, this.namespaceSockets = a, this.id = o, this.namespace = n, this.data = null, this.event = "";
+  }
+  get(e) {
+    return this.metadata.get(e);
+  }
+  set(e, t) {
+    this.metadata.set(e, t);
+  }
+  send(e, t) {
+    this.socket.readyState === this.socket.OPEN && this.socket.send(JSON.stringify({
+      event: e,
+      data: t
+    }));
+  }
+  broadcast(e, t) {
+    const s = JSON.stringify({
+      event: e,
+      data: t
+    });
+    for (const [a, o] of this.namespaceSockets) a !== this.id && o.readyState === o.OPEN && o.send(s);
+  }
+  broadcastAll(e, t) {
+    const s = JSON.stringify({
+      event: e,
+      data: t
+    });
+    for (const [, a] of this.namespaceSockets) a.readyState === a.OPEN && a.send(s);
+  }
+  join(e) {
+    this.roomManager.join(this.id, this.socket, e);
+  }
+  leave(e) {
+    this.roomManager.leave(this.id, e);
+  }
+  rooms() {
+    return this.roomManager.getRooms(this.id);
+  }
+  to(e) {
+    return { send: (t, s) => {
+      this.roomManager.broadcast(e, t, s);
+    } };
+  }
+}, N = class {
+  socketRooms = /* @__PURE__ */ new Map();
+  roomSockets = /* @__PURE__ */ new Map();
+  join(e, t, s) {
+    this.socketRooms.has(e) || this.socketRooms.set(e, /* @__PURE__ */ new Set()), this.socketRooms.get(e).add(s), this.roomSockets.has(s) || this.roomSockets.set(s, /* @__PURE__ */ new Map()), this.roomSockets.get(s).set(e, t);
+  }
+  leave(e, t) {
+    this.socketRooms.get(e)?.delete(t), this.roomSockets.get(t)?.delete(e), this.roomSockets.get(t)?.size === 0 && this.roomSockets.delete(t);
+  }
+  leaveAll(e) {
+    const t = this.socketRooms.get(e);
+    if (t) for (const s of t)
+      this.roomSockets.get(s)?.delete(e), this.roomSockets.get(s)?.size === 0 && this.roomSockets.delete(s);
+    this.socketRooms.delete(e);
+  }
+  getRooms(e) {
+    return Array.from(this.socketRooms.get(e) ?? []);
+  }
+  getSockets(e) {
+    return this.roomSockets.get(e) ?? /* @__PURE__ */ new Map();
+  }
+  getAllRooms() {
+    const e = {};
+    for (const [t, s] of this.roomSockets) e[t] = s.size;
+    return e;
+  }
+  broadcast(e, t, s, a) {
+    const o = this.roomSockets.get(e);
+    if (!o) return;
+    const n = JSON.stringify({
+      event: t,
+      data: s
+    });
+    for (const [c, r] of o) c !== a && r.readyState === r.OPEN && r.send(n);
+  }
+}, d = R("WsAdapter"), A = class {
+  name = "WsAdapter";
+  basePath;
+  heartbeatInterval;
+  maxPayload;
+  wss = null;
+  container = null;
+  namespaces = /* @__PURE__ */ new Map();
+  roomManager = new N();
+  heartbeatTimer = null;
+  totalConnections;
+  activeConnections;
+  messagesReceived;
+  messagesSent;
+  wsErrors;
+  constructor(e = {}) {
+    this.basePath = e.path ?? "/ws", this.heartbeatInterval = e.heartbeatInterval ?? 3e4, this.maxPayload = e.maxPayload, this.totalConnections = h(0), this.activeConnections = h(0), this.messagesReceived = h(0), this.messagesSent = h(0), this.wsErrors = h(0);
+  }
+  getStats() {
+    const e = {};
+    for (const [t, s] of this.namespaces) e[t] = {
+      connections: s.sockets.size,
+      handlers: s.handlers.length
+    };
+    return {
+      totalConnections: this.totalConnections.value,
+      activeConnections: this.activeConnections.value,
+      messagesReceived: this.messagesReceived.value,
+      messagesSent: this.messagesSent.value,
+      errors: this.wsErrors.value,
+      namespaces: e,
+      rooms: this.roomManager.getAllRooms()
+    };
+  }
+  beforeStart(e, t) {
+    this.container = t;
+    for (const s of S) {
+      const a = Reflect.getMetadata(i.WS_CONTROLLER, s);
+      if (a === void 0) continue;
+      const o = Reflect.getMetadata(i.WS_HANDLERS, s) || [], n = this.basePath + (a === "/" ? "" : a);
+      this.namespaces.set(n, {
+        namespace: a,
+        controllerClass: s,
+        handlers: o,
+        sockets: /* @__PURE__ */ new Map(),
+        contexts: /* @__PURE__ */ new Map()
+      }), d.info(`Registered WS namespace: ${n} (${s.name})`);
+    }
+  }
+  afterStart(e, t) {
+    this.wss = new u({
+      noServer: !0,
+      maxPayload: this.maxPayload
+    }), e.on("upgrade", (a, o, n) => {
+      const c = (a.url || "/").split("?")[0], r = this.namespaces.get(c);
+      if (!r) {
+        o.write(`HTTP/1.1 404 Not Found\r
 \r
-`),a.destroy();return}this.wss.handleUpgrade(o,a,n,S=>{this.handleConnection(S,p)})}),this.heartbeatInterval>0&&(this.heartbeatTimer=setInterval(()=>{for(let[,o]of this.namespaces)for(let[,a]of o.sockets){if(a.__alive===!1){a.terminate();continue}a.__alive=!1,a.ping()}},this.heartbeatInterval));let s=Array.from(this.namespaces.values()).reduce((o,a)=>o+a.handlers.length,0);u.info(`WebSocket ready \u2014 ${this.namespaces.size} namespace(s), ${s} handler(s)`)}shutdown(){this.heartbeatTimer&&clearInterval(this.heartbeatTimer);for(let[,e]of this.namespaces){for(let[,t]of e.sockets)t.close(1001,"Server shutting down");e.sockets.clear(),e.contexts.clear()}this.wss?.close()}handleConnection(e,t){let s=x();e.__alive=!0,t.sockets.set(s,e),this.totalConnections.value++,this.activeConnections.value++;let o=new d(e,this.wss,this.roomManager,t.sockets,s,t.namespace);t.contexts.set(s,o);let a=this.container.resolve(t.controllerClass);e.on("pong",()=>{e.__alive=!0}),this.invokeHandlers(a,t.handlers,"connect",o),e.on("message",n=>{this.messagesReceived.value++;try{let h=JSON.parse(n.toString()),c=h.event,p=h.data;if(!c||typeof c!="string"){o.send("error",{message:'Invalid message format: missing "event" field'});return}o.event=c,o.data=p;let S=t.handlers.find(m=>m.type==="message"&&m.event===c);if(S)this.safeInvoke(a,S.handlerName,o);else{let m=t.handlers.find(M=>M.type==="message"&&M.event==="*");m&&this.safeInvoke(a,m.handlerName,o)}}catch{o.data={message:"Invalid JSON"},this.invokeHandlers(a,t.handlers,"error",o)}}),e.on("close",()=>{this.activeConnections.value--,this.invokeHandlers(a,t.handlers,"disconnect",o),this.roomManager.leaveAll(s),t.sockets.delete(s),t.contexts.delete(s)}),e.on("error",n=>{this.wsErrors.value++,o.data={message:n.message,name:n.name},this.invokeHandlers(a,t.handlers,"error",o)})}invokeHandlers(e,t,s,o){for(let a of t)a.type===s&&this.safeInvoke(e,a.handlerName,o)}safeInvoke(e,t,s){try{let o=e[t](s);o instanceof Promise&&o.catch(a=>{u.error({err:a},`WS handler error in ${t}`)})}catch(o){u.error({err:o},`WS handler error in ${t}`)}}};import"reflect-metadata";import{Service as w}from"@forinda/kickjs-core";function O(i){return e=>{w()(e),Reflect.defineMetadata(l.WS_CONTROLLER,i||"/",e),v.add(e)}}r(O,"WsController");function R(i,e){return()=>(t,s)=>{let o=Reflect.getMetadata(l.WS_HANDLERS,t.constructor)||[];o.push({type:i,event:e,handlerName:s}),Reflect.defineMetadata(l.WS_HANDLERS,o,t.constructor)}}r(R,"createWsHandlerDecorator");var W=R("connect"),E=R("disconnect"),_=R("error");function b(i){return(e,t)=>{let s=Reflect.getMetadata(l.WS_HANDLERS,e.constructor)||[];s.push({type:"message",event:i,handlerName:t}),Reflect.defineMetadata(l.WS_HANDLERS,s,e.constructor)}}r(b,"OnMessage");export{W as OnConnect,E as OnDisconnect,_ as OnError,b as OnMessage,f as RoomManager,l as WS_METADATA,k as WsAdapter,d as WsContext,O as WsController};
+`), o.destroy();
+        return;
+      }
+      this.wss.handleUpgrade(a, o, n, (m) => {
+        this.handleConnection(m, r);
+      });
+    }), this.heartbeatInterval > 0 && (this.heartbeatTimer = setInterval(() => {
+      for (const [, a] of this.namespaces) for (const [, o] of a.sockets) {
+        if (o.__alive === !1) {
+          o.terminate();
+          continue;
+        }
+        o.__alive = !1, o.ping();
+      }
+    }, this.heartbeatInterval));
+    const s = Array.from(this.namespaces.values()).reduce((a, o) => a + o.handlers.length, 0);
+    d.info(`WebSocket ready — ${this.namespaces.size} namespace(s), ${s} handler(s)`);
+  }
+  shutdown() {
+    this.heartbeatTimer && clearInterval(this.heartbeatTimer);
+    for (const [, e] of this.namespaces) {
+      for (const [, t] of e.sockets) t.close(1001, "Server shutting down");
+      e.sockets.clear(), e.contexts.clear();
+    }
+    this.wss?.close();
+  }
+  handleConnection(e, t) {
+    const s = k();
+    e.__alive = !0, t.sockets.set(s, e), this.totalConnections.value++, this.activeConnections.value++;
+    const a = new M(e, this.wss, this.roomManager, t.sockets, s, t.namespace);
+    t.contexts.set(s, a);
+    const o = this.container.resolve(t.controllerClass);
+    e.on("pong", () => {
+      e.__alive = !0;
+    }), this.invokeHandlers(o, t.handlers, "connect", a), e.on("message", (n) => {
+      this.messagesReceived.value++;
+      try {
+        const c = JSON.parse(n.toString()), r = c.event, m = c.data;
+        if (!r || typeof r != "string") {
+          a.send("error", { message: 'Invalid message format: missing "event" field' });
+          return;
+        }
+        a.event = r, a.data = m;
+        const v = t.handlers.find((l) => l.type === "message" && l.event === r);
+        if (v) this.safeInvoke(o, v.handlerName, a);
+        else {
+          const l = t.handlers.find((g) => g.type === "message" && g.event === "*");
+          l && this.safeInvoke(o, l.handlerName, a);
+        }
+      } catch {
+        a.data = { message: "Invalid JSON" }, this.invokeHandlers(o, t.handlers, "error", a);
+      }
+    }), e.on("close", () => {
+      this.activeConnections.value--, this.invokeHandlers(o, t.handlers, "disconnect", a), this.roomManager.leaveAll(s), t.sockets.delete(s), t.contexts.delete(s);
+    }), e.on("error", (n) => {
+      this.wsErrors.value++, a.data = {
+        message: n.message,
+        name: n.name
+      }, this.invokeHandlers(o, t.handlers, "error", a);
+    });
+  }
+  invokeHandlers(e, t, s, a) {
+    for (const o of t) o.type === s && this.safeInvoke(e, o.handlerName, a);
+  }
+  safeInvoke(e, t, s) {
+    try {
+      const a = e[t](s);
+      a instanceof Promise && a.catch((o) => {
+        d.error({ err: o }, `WS handler error in ${t}`);
+      });
+    } catch (a) {
+      d.error({ err: a }, `WS handler error in ${t}`);
+    }
+  }
+};
+function O(e) {
+  return (t) => {
+    p()(t), Reflect.defineMetadata(i.WS_CONTROLLER, e || "/", t), S.add(t);
+  };
+}
+function f(e, t) {
+  return () => (s, a) => {
+    const o = Reflect.getMetadata(i.WS_HANDLERS, s.constructor) || [];
+    o.push({
+      type: e,
+      event: t,
+      handlerName: a
+    }), Reflect.defineMetadata(i.WS_HANDLERS, o, s.constructor);
+  };
+}
+var _ = f("connect"), y = f("disconnect"), E = f("error");
+function P(e) {
+  return (t, s) => {
+    const a = Reflect.getMetadata(i.WS_HANDLERS, t.constructor) || [];
+    a.push({
+      type: "message",
+      event: e,
+      handlerName: s
+    }), Reflect.defineMetadata(i.WS_HANDLERS, a, t.constructor);
+  };
+}
+export {
+  _ as OnConnect,
+  y as OnDisconnect,
+  E as OnError,
+  P as OnMessage,
+  N as RoomManager,
+  i as WS_METADATA,
+  A as WsAdapter,
+  M as WsContext,
+  O as WsController
+};

package/dist/interfaces.d.ts

@@ -0,0 +1,25 @@
+type Constructor = new (...args: any[]) => any;
+export declare const WS_METADATA: {
+    readonly WS_CONTROLLER: symbol;
+    readonly WS_HANDLERS: symbol;
+};
+export type WsHandlerType = 'connect' | 'disconnect' | 'message' | 'error';
+export interface WsHandlerDefinition {
+    type: WsHandlerType;
+    /** Event name — only for 'message' type */
+    event?: string;
+    /** Method name on the controller class */
+    handlerName: string;
+}
+export 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;
+}
+/** Registry of all @WsController classes — populated at decorator time */
+export declare const wsControllerRegistry: Set<Constructor>;
+export {};
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA,KAAK,WAAW,GAAG,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAA;AAE9C,eAAO,MAAM,WAAW;;;CAGd,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,CAAA;AAE1E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,aAAa,CAAA;IACnB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,kBAAyB,CAAA"}

package/dist/room-manager.d.ts

@@ -0,0 +1,22 @@
+import type { WebSocket } from 'ws';
+/**
+ * Manages WebSocket room membership and broadcasting.
+ * Standalone from ws/socket.io — can be swapped for socket.io's built-in rooms.
+ */
+export 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;
+}
+//# sourceMappingURL=room-manager.d.ts.map

package/dist/room-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room-manager.d.ts","sourceRoot":"","sources":["../src/room-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAA;AAEnC;;;GAGG;AACH,qBAAa,WAAW;IACtB,mCAAmC;IACnC,OAAO,CAAC,WAAW,CAAiC;IACpD,8CAA8C;IAC9C,OAAO,CAAC,WAAW,CAA4C;IAE/D,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAY7D,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAU3C,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAahC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAIpC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC;IAIhD,6CAA6C;IAC7C,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAQrC,mEAAmE;IACnE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI;CAW5E"}

package/dist/ws-adapter.d.ts

@@ -0,0 +1,63 @@
+import { type AppAdapter, type Container, type Ref } from '@forinda/kickjs-core';
+import { type WsAdapterOptions } from './interfaces';
+/**
+ * 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" } }`
+ */
+export 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;
+}
+//# sourceMappingURL=ws-adapter.d.ts.map

package/dist/ws-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-adapter.d.ts","sourceRoot":"","sources":["../src/ws-adapter.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAqB,KAAK,GAAG,EAAE,MAAM,sBAAsB,CAAA;AACnG,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,cAAc,CAAA;AAcrB;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,SAAU,YAAW,UAAU;IAC1C,QAAQ,CAAC,IAAI,eAAc;IAE3B,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,iBAAiB,CAAQ;IACjC,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,GAAG,CAA+B;IAC1C,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,cAAc,CAA8C;IAGpE,8CAA8C;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACtC,mCAAmC;IACnC,QAAQ,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACvC,8BAA8B;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IACtC,0BAA0B;IAC1B,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAClC,mBAAmB;IACnB,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;gBAElB,OAAO,GAAE,gBAAqB;IAY1C,qDAAqD;IACrD,QAAQ;;;;;;;yBAC8C,MAAM;sBAAY,MAAM;;;;IAkB9E,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IA4BlD,UAAU,CAAC,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,SAAS,GAAG,IAAI;IA+CpD,QAAQ,IAAI,IAAI;IAmBhB,OAAO,CAAC,gBAAgB;IAgFxB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,UAAU;CAYnB"}

package/dist/ws-context.d.ts

@@ -0,0 +1,55 @@
+import type { WebSocket, WebSocketServer } from 'ws';
+import type { RoomManager } from './room-manager';
+/**
+ * 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)
+ * }
+ * ```
+ */
+export 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;
+    };
+}
+//# sourceMappingURL=ws-context.d.ts.map

package/dist/ws-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-context.d.ts","sourceRoot":"","sources":["../src/ws-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,IAAI,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,SAAS;IAalB,QAAQ,CAAC,MAAM,EAAE,SAAS;IAC1B,QAAQ,CAAC,MAAM,EAAE,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAfnC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,IAAI,EAAE,GAAG,CAAA;IACT,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAA;IACb,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAE1B,OAAO,CAAC,QAAQ,CAAyB;gBAG9B,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,eAAe,EACf,WAAW,EAAE,WAAW,EACxB,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EACzD,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM;IAQnB,2BAA2B;IAC3B,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIxC,yEAAyE;IACzE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAIlC,oCAAoC;IACpC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI;IAMpC,gEAAgE;IAChE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI;IASzC,mEAAmE;IACnE,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI;IAS5C,kBAAkB;IAClB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIxB,mBAAmB;IACnB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIzB,sCAAsC;IACtC,KAAK,IAAI,MAAM,EAAE;IAIjB,oCAAoC;IACpC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,IAAI,CAAA;KAAE;CAO3D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forinda/kickjs-ws",
-  "version": "1.3.2",
+  "version": "1.4.1-alpha.0",
   "description": "WebSocket support with decorators, namespaces, rooms, and DI integration for KickJS",
   "keywords": [
     "kickjs",
@@ -34,7 +34,8 @@
     "@forinda/kickjs-queue",
     "@forinda/kickjs-multi-tenant",
     "@forinda/kickjs-devtools",
-    "@forinda/kickjs-notifications"
+    "@forinda/kickjs-notifications",
+    "vite"
   ],
   "type": "module",
   "main": "dist/index.js",
@@ -50,16 +51,15 @@
   ],
   "dependencies": {
     "reflect-metadata": "^0.2.2",
-    "ws": "^8.18.0",
-    "@forinda/kickjs-core": "1.3.2"
+    "ws": "^8.20.0",
+    "@forinda/kickjs-core": "1.4.1-alpha.0"
   },
   "devDependencies": {
     "@swc/core": "^1.7.28",
-    "@types/node": "^24.5.2",
+    "@types/node": "^25.0.0",
     "@types/ws": "^8.18.0",
-    "tsup": "^8.5.0",
     "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.1"
   },
   "publishConfig": {
     "access": "public"
@@ -79,8 +79,9 @@
     "url": "https://github.com/forinda/kick-js/issues"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "vite build && pnpm build:types",
+    "build:types": "tsc -p tsconfig.build.json",
+    "dev": "vite build --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",