wxexpress 1.0.0

package/README.md

@@ -0,0 +1,150 @@
+wsexpress
+WebSocket routing for Express applications.
+wsexpress lets you define WebSocket endpoints exactly like normal Express routes and allows you to use Express middleware with WebSockets.
+It internally uses the powerful ws WebSocket library.
+ 
+✅ Features
+• 
+Define WebSocket routes just like HTTP routes
+• 
+Works with Express middleware
+• 
+Supports Express Routers
+• 
+Built on top of the fast ws library
+• 
+Simple API and lightweight
+ 
+📦 Installation
+bash
+Copy
+npm install --save wsexpress
+ 
+🚀 Quick Start
+First, attach wsexpress to your Express app:
+javascript
+Copy
+const express = require('express');
+const app = express();
+
+require('wsexpress')(app);
+⚠️ Important:
+Initialize wsexpress before defining routers or routes.
+Otherwise, you may see an error like:
+vbnet
+Copy
+router.ws is not a function
+ 
+🧩 Basic WebSocket Route
+Create a simple echo WebSocket server:
+javascript
+Copy
+app.ws('/echo', (ws, req) => {
+  ws.on('message', msg => {
+    ws.send(msg);
+  });
+});
+The ws object is a standard WebSocket instance from the ws library.
+ 
+📂 Using with Express Router
+You can also use WebSocket routes inside routers:
+javascript
+Copy
+const express = require('express');
+const router = express.Router();
+
+router.ws('/echo', (ws, req) => {
+  ws.on('message', msg => {
+    ws.send(msg);
+  });
+});
+
+app.use('/ws-stuff', router);
+This creates a WebSocket endpoint at:
+bash
+Copy
+/ws-stuff/echo
+ 
+🧪 Full Example
+javascript
+Copy
+const express = require('express');
+const app = express();
+
+const wsExpress = require('wsexpress')(app);
+
+// middleware
+app.use((req, res, next) => {
+  console.log('middleware executed');
+  req.testing = 'testing';
+  next();
+});
+
+// HTTP route
+app.get('/', (req, res) => {
+  console.log('GET route:', req.testing);
+  res.end('Hello HTTP');
+});
+
+// WebSocket route
+app.ws('/', (ws, req) => {
+  console.log('WebSocket connected:', req.testing);
+
+  ws.on('message', msg => {
+    console.log('Received:', msg.toString());
+  });
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+ 
+📘 API
+wsexpress(app, server?, options?)
+Initializes WebSocket support on an Express app.
+Parameters
+• 
+app
+Your Express application.
+• 
+server (optional)
+Custom http.Server instance.
+If not provided, the server created by app.listen() is used.
+• 
+options (optional)
+Configuration object:
+• 
+leaveRouterUntouched (boolean)
+If true, routers are not automatically patched.
+You must manually apply WebSocket support using applyTo().
+• 
+wsOptions (object)
+Options passed directly to the WebSocketServer.
+ 
+wsInstance.app
+Returns the Express app instance used by wsexpress.
+ 
+wsInstance.getWss()
+Returns the underlying WebSocket server.
+Example:
+javascript
+Copy
+wsInstance.getWss().clients
+⚠️ This returns all connected clients across all routes, so use carefully.
+ 
+wsInstance.applyTo(router)
+Manually enables WebSocket support for a router.
+You only need this if:
+1. 
+leaveRouterUntouched is enabled, or
+2. 
+You are using a custom router implementation.
+ 
+🛠 Development
+• 
+Written in ES6
+• 
+Uses ESM internally
+• 
+Lightweight and production ready
+