@moostjs/event-ws 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 moostjs
+
+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/README.md

@@ -0,0 +1,136 @@
+# @moostjs/event-ws
+
+<p align="center">
+<img src="../../moost-logo.png" width="450px"><br>
+<a  href="https://github.com/moostjs/moostjs/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" />
+</a>
+</p>
+
+Welcome to `@moostjs/event-ws`, a Moostjs library that serves as a wrapper for [@wooksjs/event-ws](https://github.com/wooksjs/wooksjs/tree/main/packages/event-ws). This package provides decorators for composing WebSocket handlers, bringing decorator-based routing, dependency injection, interceptors, and pipes to your WebSocket application.
+
+**Note:** As `@moostjs/event-ws` is under active development, breaking changes can be expected.
+
+## Overview
+
+The `@moostjs/event-ws` module makes Moost apps receptive to WebSocket events. It supports two modes:
+
+- **Standalone** — dedicated WebSocket server using `WsApp` or `MoostWs` with `listen()`
+- **HTTP-integrated** (recommended) — shares the HTTP port with `@moostjs/event-http` via `@Upgrade()` routes
+
+## Installation
+
+```bash
+npm install @moostjs/event-ws
+```
+
+For HTTP-integrated mode (recommended):
+
+```bash
+npm install @moostjs/event-ws @moostjs/event-http
+```
+
+## Quick Start
+
+### Standalone Mode
+
+```ts
+import { WsApp, Message, MessageData, Connect, ConnectionId } from '@moostjs/event-ws'
+import { Controller } from 'moost'
+
+@Controller()
+class ChatController {
+  @Connect()
+  onConnect(@ConnectionId() id: string) {
+    console.log(`Connected: ${id}`)
+  }
+
+  @Message('echo', '/echo')
+  echo(@MessageData() data: unknown) {
+    return data
+  }
+}
+
+new WsApp()
+  .controllers(ChatController)
+  .start(3000)
+```
+
+### HTTP-Integrated Mode
+
+```ts
+import { MoostHttp, Upgrade } from '@moostjs/event-http'
+import { MoostWs, Message, MessageData, useWsRooms } from '@moostjs/event-ws'
+import { Moost, Controller, Param, Inject } from 'moost'
+import type { WooksWs } from '@moostjs/event-ws'
+
+@Controller()
+class AppController {
+  constructor(@Inject('WooksWs') private ws: WooksWs) {}
+
+  @Upgrade('ws')
+  upgrade() { return this.ws.upgrade() }
+}
+
+@Controller('chat')
+class ChatController {
+  @Message('message', ':room')
+  onMessage(@Param('room') room: string, @MessageData() data: unknown) {
+    const { broadcast } = useWsRooms()
+    broadcast('message', data)
+  }
+}
+
+const app = new Moost()
+const http = new MoostHttp()
+const ws = new MoostWs({ httpApp: http.getHttpApp() })
+app.adapter(http)
+app.adapter(ws)
+app.registerControllers(AppController, ChatController)
+await http.listen(3000)
+await app.init()
+```
+
+## [Official Documentation](https://moost.org/wsapp/)
+
+## AI Agent Skills
+
+This package ships skills for AI coding agents (Claude Code, Cursor, Windsurf, Codex, OpenCode). After installing `@moostjs/event-ws`, set up the skills:
+
+```bash
+# Project-local (recommended — version-locked, commits with your repo)
+npx moostjs-event-ws-skill
+
+# Global (available across all your projects)
+npx moostjs-event-ws-skill --global
+```
+
+To auto-install skills on `npm install`, add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "moostjs-event-ws-skill --postinstall"
+  }
+}
+```
+
+## Contributing
+
+We are excited to welcome contributors who are passionate about improving Moostjs. No matter your level of experience, your unique perspective and skills can make valuable contributions to our growing community.
+
+Here are some basic steps to get you started:
+
+1. **Fork the Repo:** Navigate to [moostjs](https://github.com/moostjs/moostjs) and fork the repository to your own GitHub account.
+
+2. **Clone the Repo:** Clone the forked repository to your local machine.
+
+3. **Create a Branch:** Make a new branch for your feature or bug fix.
+
+4. **Make your Changes:** Implement your feature or fix the bug and commit the changes to your branch.
+
+5. **Make a Pull Request:** Navigate back to your forked repo and press the "New pull request" button.
+
+Don't hesitate to ask for help if you need it. We believe in fostering a friendly and respectful environment for all contributors.
+
+Thank you for your interest in Moostjs. We look forward to building something amazing together!

package/dist/index.cjs

@@ -0,0 +1,445 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const moost = __toESM(require("moost"));
+const __wooksjs_event_ws = __toESM(require("@wooksjs/event-ws"));
+const __prostojs_infact = __toESM(require("@prostojs/infact"));
+
+//#region packages/event-ws/src/decorators/ws-method.decorator.ts
+/**
+* ## Define WebSocket Message Handler
+* ### @MethodDecorator
+*
+* Registers a handler for routed WebSocket messages.
+* The event and path correspond to the WsClientMessage protocol fields.
+*
+* @param event - message event type (e.g. "message", "rpc", "subscribe")
+* @param path - route path with optional params (e.g. "/chat/rooms/:roomId")
+*/ function Message(event, path) {
+	return (0, moost.getMoostMate)().decorate("handlers", {
+		event,
+		path,
+		type: "WS_MESSAGE"
+	}, true);
+}
+/**
+* ## Define WebSocket Connection Handler
+* ### @MethodDecorator
+*
+* Registers a handler that runs when a new WebSocket connection is established.
+* Runs inside the connection context. Throwing or rejecting closes the connection.
+*/ function Connect() {
+	return (0, moost.getMoostMate)().decorate("handlers", { type: "WS_CONNECT" }, true);
+}
+/**
+* ## Define WebSocket Disconnection Handler
+* ### @MethodDecorator
+*
+* Registers a handler that runs when a WebSocket connection closes.
+*/ function Disconnect() {
+	return (0, moost.getMoostMate)().decorate("handlers", { type: "WS_DISCONNECT" }, true);
+}
+
+//#endregion
+//#region packages/event-ws/src/decorators/resolve.decorator.ts
+/**
+* Get the parsed WebSocket message payload.
+* Only available in message handlers (@Message).
+* @decorator
+* @paramType T
+*/ function MessageData() {
+	return (0, moost.Resolve)(() => (0, __wooksjs_event_ws.useWsMessage)().data, "ws_data");
+}
+/**
+* Get the raw WebSocket message (Buffer or string before parsing).
+* Only available in message handlers (@Message).
+* @decorator
+* @paramType Buffer | string
+*/ function RawMessage() {
+	return (0, moost.Resolve)(() => (0, __wooksjs_event_ws.useWsMessage)().raw, "ws_raw");
+}
+/**
+* Get the WebSocket message correlation ID.
+* Only available in message handlers (@Message).
+* @decorator
+* @paramType string | number | undefined
+*/ function MessageId() {
+	return (0, moost.Resolve)(() => (0, __wooksjs_event_ws.useWsMessage)().id, "ws_message_id");
+}
+/**
+* Get the WebSocket message event type.
+* Only available in message handlers (@Message).
+* @decorator
+* @paramType string
+*/ function MessageType() {
+	return (0, moost.Resolve)(() => (0, __wooksjs_event_ws.useWsMessage)().event, "ws_event");
+}
+/**
+* Get the WebSocket message path.
+* Only available in message handlers (@Message).
+* @decorator
+* @paramType string
+*/ function MessagePath() {
+	return (0, moost.Resolve)(() => (0, __wooksjs_event_ws.useWsMessage)().path, "ws_path");
+}
+/**
+* Get the WebSocket connection ID (UUID).
+* Available in all WS handlers (@Message, @Connect, @Disconnect).
+* @decorator
+* @paramType string
+*/ function ConnectionId() {
+	return (0, moost.Resolve)(() => (0, __wooksjs_event_ws.useWsConnection)().id, "ws_connection_id");
+}
+
+//#endregion
+//#region packages/event-ws/src/event-ws.ts
+function _define_property$1(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+	else obj[key] = value;
+	return obj;
+}
+const LOGGER_TITLE = "moost-ws";
+/**
+* ## Moost WebSocket Adapter
+*
+* Moost Adapter for WebSocket events, wrapping @wooksjs/event-ws.
+* Supports standalone and HTTP-integrated modes.
+*
+* ### HTTP-integrated mode (recommended)
+* ```ts
+* |  import { MoostHttp, Upgrade } from '@moostjs/event-http'
+* |  import { MoostWs, Message, MessageData } from '@moostjs/event-ws'
+* |  import { Moost, Param, Controller, Injectable } from 'moost'
+* |
+* |  @Controller()
+* |  class AppController {
+* |      constructor(private ws: WooksWs) {}
+* |
+* |      @Upgrade('/ws')
+* |      handleUpgrade() { return this.ws.upgrade() }
+* |  }
+* |
+* |  @Controller('chat')
+* |  class ChatController {
+* |      @Message('message', 'rooms/:roomId')
+* |      onMessage(@Param('roomId') roomId: string, @MessageData() data: unknown) {
+* |          return { received: true, roomId }
+* |      }
+* |  }
+* |
+* |  const app = new Moost()
+* |  const http = new MoostHttp()
+* |  const ws = new MoostWs({ httpApp: http.getHttpApp() })
+* |  app.adapter(http)
+* |  app.adapter(ws)
+* |  app.registerControllers(AppController, ChatController)
+* |  http.listen(3000)
+* |  app.init()
+* ```
+*/ var MoostWs = class MoostWs {
+	getWsApp() {
+		return this.wsApp;
+	}
+	/**
+	* Start a standalone WebSocket server (without HTTP integration).
+	*/ listen(port, hostname) {
+		return this.wsApp.listen(port, hostname);
+	}
+	/**
+	* Stop the server, close all connections, clean up heartbeat.
+	*/ close() {
+		return this.wsApp.close();
+	}
+	onInit(moost$1) {
+		this.moost = moost$1;
+	}
+	getProvideRegistry() {
+		return (0, __prostojs_infact.createProvideRegistry)([MoostWs, () => this], ["MoostWs", () => this], [__wooksjs_event_ws.WooksWs, () => this.getWsApp()], ["WooksWs", () => this.getWsApp()]);
+	}
+	getLogger() {
+		return this.wsApp.getLogger("[moost-ws]");
+	}
+	bindHandler(opts) {
+		for (const handler of opts.handlers) if (handler.type === "WS_MESSAGE") this.bindMessageHandler(opts, handler);
+		else if (handler.type === "WS_CONNECT") this.bindConnectHandler(opts);
+		else if (handler.type === "WS_DISCONNECT") this.bindDisconnectHandler(opts);
+	}
+	bindMessageHandler(opts, handler) {
+		const event = handler.event;
+		const path = typeof handler.path === "string" ? handler.path : typeof opts.method === "string" ? opts.method : "";
+		const targetPath = `${`${opts.prefix || ""}/${path}`.replaceAll(/\/\/+/g, "/")}`;
+		const fn = (0, moost.defineMoostEventHandler)({
+			contextType: "WS_MESSAGE",
+			loggerTitle: LOGGER_TITLE,
+			getIterceptorHandler: opts.getIterceptorHandler,
+			getControllerInstance: opts.getInstance,
+			controllerMethod: opts.method,
+			controllerName: opts.controllerName,
+			resolveArgs: opts.resolveArgs,
+			targetPath,
+			handlerType: handler.type
+		});
+		this.wsApp.onMessage(event, targetPath, fn);
+		opts.logHandler(`(ws:${event})${targetPath}`);
+		opts.register(handler, targetPath, []);
+	}
+	bindConnectHandler(opts) {
+		const fn = (0, moost.defineMoostEventHandler)({
+			contextType: "WS_CONNECT",
+			loggerTitle: LOGGER_TITLE,
+			getIterceptorHandler: opts.getIterceptorHandler,
+			getControllerInstance: opts.getInstance,
+			controllerMethod: opts.method,
+			resolveArgs: opts.resolveArgs,
+			targetPath: "__ws_connect__",
+			handlerType: "WS_CONNECT"
+		});
+		this.wsApp.onConnect(fn);
+		opts.logHandler(`(ws:connect)`);
+		opts.register({ type: "WS_CONNECT" }, "__ws_connect__", []);
+	}
+	bindDisconnectHandler(opts) {
+		const fn = (0, moost.defineMoostEventHandler)({
+			contextType: "WS_DISCONNECT",
+			loggerTitle: LOGGER_TITLE,
+			getIterceptorHandler: opts.getIterceptorHandler,
+			getControllerInstance: opts.getInstance,
+			controllerMethod: opts.method,
+			resolveArgs: opts.resolveArgs,
+			targetPath: "__ws_disconnect__",
+			handlerType: "WS_DISCONNECT"
+		});
+		this.wsApp.onDisconnect(fn);
+		opts.logHandler(`(ws:disconnect)`);
+		opts.register({ type: "WS_DISCONNECT" }, "__ws_disconnect__", []);
+	}
+	constructor(opts) {
+		_define_property$1(this, "opts", void 0);
+		_define_property$1(this, "name", void 0);
+		_define_property$1(this, "wsApp", void 0);
+		_define_property$1(this, "moost", void 0);
+		this.opts = opts;
+		this.name = "ws";
+		const wsOpts = opts?.wooksWs;
+		if (wsOpts && wsOpts instanceof __wooksjs_event_ws.WooksWs) this.wsApp = wsOpts;
+		else {
+			const httpApp = opts?.httpApp && "getHttpApp" in opts.httpApp ? opts.httpApp.getHttpApp() : opts?.httpApp;
+			if (httpApp) this.wsApp = (0, __wooksjs_event_ws.createWsApp)(httpApp, wsOpts || {});
+			else this.wsApp = (0, __wooksjs_event_ws.createWsApp)(wsOpts || {});
+		}
+	}
+};
+
+//#endregion
+//#region packages/event-ws/src/quick-ws.ts
+function _define_property(obj, key, value) {
+	if (key in obj) Object.defineProperty(obj, key, {
+		value,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+	else obj[key] = value;
+	return obj;
+}
+/**
+* Quick WS App factory class.
+*
+* Use this class to quickly build a standalone WebSocket application
+* with controllers. It extends the Moost class and wraps MoostWs initialization.
+*
+* @example
+* ```typescript
+* import { WsApp } from '@moostjs/event-ws'
+* import { ChatController } from './chat.controller.ts'
+*
+* new WsApp()
+*   .controllers(ChatController)
+*   .start(3000)
+* ```
+*/ var WsApp = class extends moost.Moost {
+	/**
+	* Registers one or more WS controllers.
+	*
+	* (Shortcut for `registerControllers` method.)
+	*/ controllers(...controllers) {
+		return this.registerControllers(...controllers);
+	}
+	/**
+	* Configures the WS options.
+	*/ useWsOptions(wsOpts) {
+		this._wsOpts = wsOpts;
+		return this;
+	}
+	/**
+	* Returns the underlying MoostWs adapter instance.
+	*/ getWsAdapter() {
+		return this._wsAdapter;
+	}
+	/**
+	* Starts the standalone WebSocket application.
+	*
+	* @param port - Port to listen on
+	* @param hostname - Optional hostname
+	*/ async start(port, hostname) {
+		this._wsAdapter = new MoostWs({ wooksWs: this._wsOpts?.ws });
+		this.adapter(this._wsAdapter);
+		await this.init();
+		return this._wsAdapter.listen(port, hostname);
+	}
+	constructor(...args) {
+		super(...args), _define_property(this, "_wsOpts", void 0), _define_property(this, "_wsAdapter", void 0);
+	}
+};
+
+//#endregion
+exports.Connect = Connect;
+exports.ConnectionId = ConnectionId;
+Object.defineProperty(exports, 'Controller', {
+  enumerable: true,
+  get: function () {
+    return moost.Controller;
+  }
+});
+Object.defineProperty(exports, 'Description', {
+  enumerable: true,
+  get: function () {
+    return moost.Description;
+  }
+});
+exports.Disconnect = Disconnect;
+Object.defineProperty(exports, 'Intercept', {
+  enumerable: true,
+  get: function () {
+    return moost.Intercept;
+  }
+});
+exports.Message = Message;
+exports.MessageData = MessageData;
+exports.MessageId = MessageId;
+exports.MessagePath = MessagePath;
+exports.MessageType = MessageType;
+exports.MoostWs = MoostWs;
+Object.defineProperty(exports, 'Param', {
+  enumerable: true,
+  get: function () {
+    return moost.Param;
+  }
+});
+exports.RawMessage = RawMessage;
+Object.defineProperty(exports, 'WooksWs', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.WooksWs;
+  }
+});
+exports.WsApp = WsApp;
+Object.defineProperty(exports, 'WsError', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.WsError;
+  }
+});
+Object.defineProperty(exports, 'WsRoomManager', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.WsRoomManager;
+  }
+});
+Object.defineProperty(exports, 'currentConnection', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.currentConnection;
+  }
+});
+Object.defineProperty(exports, 'defineAfterInterceptor', {
+  enumerable: true,
+  get: function () {
+    return moost.defineAfterInterceptor;
+  }
+});
+Object.defineProperty(exports, 'defineBeforeInterceptor', {
+  enumerable: true,
+  get: function () {
+    return moost.defineBeforeInterceptor;
+  }
+});
+Object.defineProperty(exports, 'defineInterceptor', {
+  enumerable: true,
+  get: function () {
+    return moost.defineInterceptor;
+  }
+});
+Object.defineProperty(exports, 'prepareTestWsConnectionContext', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.prepareTestWsConnectionContext;
+  }
+});
+Object.defineProperty(exports, 'prepareTestWsMessageContext', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.prepareTestWsMessageContext;
+  }
+});
+Object.defineProperty(exports, 'useWsConnection', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.useWsConnection;
+  }
+});
+Object.defineProperty(exports, 'useWsMessage', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.useWsMessage;
+  }
+});
+Object.defineProperty(exports, 'useWsRooms', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.useWsRooms;
+  }
+});
+Object.defineProperty(exports, 'useWsServer', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.useWsServer;
+  }
+});
+Object.defineProperty(exports, 'wsConnectionKind', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.wsConnectionKind;
+  }
+});
+Object.defineProperty(exports, 'wsMessageKind', {
+  enumerable: true,
+  get: function () {
+    return __wooksjs_event_ws.wsMessageKind;
+  }
+});