@seip/blue-bird 0.9.1 → 0.9.2

package/README.md

@@ -293,11 +293,81 @@ const stats = await connection.query("SELECT COUNT(*) as count FROM access_logs"
 
 // 3. INSERT query (returns insertId for MySQL, or inserted row ID / rowCount for PostgreSQL)
 const newId = await connection.query("INSERT INTO users (name) VALUES (?)", ["John"]);
+
+// 4. Automatic SQL Query Pagination (Runs count query + LIMIT/OFFSET calculation)
+const paginated = await connection.paginate(
+  "SELECT * FROM users WHERE status = ?",
+  ["active"],
+  { page: 1, limit: 10, cache: 60 }
+);
+
+// 5. Atomic Database Transactions with Automatic Commit & Rollback
+const txUserId = await connection.transaction(async (tx) => {
+  const userId = await tx.query("INSERT INTO users (name, email) VALUES (?, ?)", ["Alice", "alice@example.com"]);
+  await tx.query("INSERT INTO profiles (user_id) VALUES (?)", [userId]);
+  return userId;
+});
+```
+
+---
+
+### 8. Real-Time WebSockets Engine (`WebSocketManager`)
+
+Built-in high-performance vanilla WebSocket server (`ws`) sharing the **exact same HTTP server and port as Express** (port 3000), supporting room subscriptions, JWT authentication, 30s heartbeat ping/pong, and Redis Pub/Sub cluster synchronization:
+
+```javascript
+import App from "@seip/blue-bird/core/app.js";
+
+const app = new App({ ... });
+
+// 1. Initialize WebSocket server on route /ws with optional JWT Auth check
+const ws = app.websocket({ path: "/ws", auth: true });
+
+ws.onConnection((socket, req) => {
+  socket.join("lobby");
+  socket.sendJSON({ status: "connected", user: socket.user });
+
+  socket.on("message", (raw) => {
+    // Broadcast to room (synced across PM2 cluster via Redis Pub/Sub)
+    ws.broadcast({ room: "lobby", text: raw.toString() }, "lobby");
+  });
+});
+
+app.run();
+```
+
+#### Broadcasting from Express API Routes:
+```javascript
+router.post("/api/comments", async (req, res) => {
+  // 1. Save comment into database...
+  const comment = { id: 1, text: req.body.text };
+
+  // 2. Broadcast in real time to all WebSocket clients in the "lobby" room
+  app.wsManager.broadcast({ type: "NEW_COMMENT", data: comment }, "lobby");
+
+  return res.success(comment, "Comment created");
+});
+```
+
+#### Native Client Connection (Browser & Node.js v22+):
+```javascript
+// Native W3C Standard WebSocket Client (Browser & Node.js v22+)
+const socket = new WebSocket("ws://localhost:3000/ws");
+
+socket.addEventListener("open", () => {
+  console.log("Connected to WebSocket server!");
+  socket.send("Hello server from native client!");
+});
+
+socket.addEventListener("message", (event) => {
+  const data = JSON.parse(event.data);
+  console.log("Message received from server:", data);
+});
 ```
 
 ---
 
-### 8. Nginx Static Asset Caching
+### 9. Nginx Static Asset Caching
 
 Nginx is configured to explicitly cache static assets (`.js`, `.css`, `.jpg`, `.png`, etc.) in the user's browser with the `Cache-Control` header (valid for 1 month). HTML and API endpoints (`/api/*`) are not cached by Nginx to ensure they serve dynamic and up-to-date content, relying instead on the Node.js application and Redis for data-layer caching.
 

package/core/app.js

@@ -1,3 +1,4 @@
+import http from "node:http";
 import express from "express";
 import cors from "cors";
 import path from "path";
@@ -10,6 +11,7 @@ import compression from "compression";
 import Config from "./config.js";
 import Logger from "./logger.js";
 import Debug from "./debug.js";
+import WebSocketManager from "./ws.js";
 
 const __dirname = Config.dirname();
 const props = Config.props();
@@ -58,6 +60,8 @@ class App {
    */
   constructor(options = {}) {
     this.app = express();
+    this.server = http.createServer(this.app);
+    this.wsManager = null;
     this.routes = options.routes || [];
     this.cors = options.cors || {};
     this.middlewares = options.middlewares || [];
@@ -114,6 +118,42 @@ class App {
     this.app.use((req, res, next) => {
       req.lang = req.query?.lang || req.body?.lang || req.cookies?.lang || "en";
       res.locals.lang = req.lang;
+
+      res.success = (data = null, message = "Success", statusCode = 200) => {
+        return res.status(statusCode).json({
+          status: "success",
+          message,
+          data,
+        });
+      };
+
+      res.error = (message = "Error", statusCode = 400, errors = []) => {
+        return res.status(statusCode).json({
+          status: "error",
+          message,
+          errors,
+        });
+      };
+
+      res.paginate = (data = [], pagination = {}, message = "Success") => {
+        const page = Number(pagination.page) || 1;
+        const limit = Number(pagination.limit) || data.length;
+        const total = Number(pagination.total) || data.length;
+        const totalPages = limit > 0 ? Math.ceil(total / limit) : 1;
+
+        return res.status(200).json({
+          status: "success",
+          message,
+          data,
+          pagination: {
+            page,
+            limit,
+            total,
+            totalPages,
+          },
+        });
+      };
+
       next();
     });
 
@@ -241,25 +281,23 @@ class App {
    */
   _errorHandler() {
     this.app.use((err, req, res, next) => {
-      const status = err.status || 500;
+      const statusCode = err.statusCode || err.status || 500;
       const message = err.message || "Internal Server Error";
+      const errors = err.errors || [];
 
-      this.loggerInstance.error(`[${status}] ${message} - ${err.stack}`);
+      this.loggerInstance.error(`[${statusCode}] ${message} - ${err.stack}`);
 
-      if (props.debug) {
-        return res.status(status).json({
-          success: false,
-          error: true,
-          message: message,
-          stack: err.stack,
-        });
+      const responsePayload = {
+        status: "error",
+        message: statusCode === 500 && !props.debug ? "Internal Server Error" : message,
+        errors,
+      };
+
+      if (props.debug && err.stack) {
+        responsePayload.stack = err.stack;
       }
 
-      return res.status(status).json({
-        success: false,
-        error: true,
-        message: status === 500 ? "Internal Server Error" : message,
-      });
+      return res.status(statusCode).json(responsePayload);
     });
   }
 
@@ -295,7 +333,7 @@ class App {
   run() {
     this._ready
       .then(() => {
-        this.app.listen(this.port, () => {
+        this.server.listen(this.port, () => {
           console.log(
             chalk.bold.blue("Blue Bird Server Online\n") +
               chalk.bold.cyan("App URL: ") +
@@ -318,6 +356,29 @@ class App {
       });
   }
 
+  /**
+   * Initializes and returns the WebSocket manager attached to the Express HTTP server instance.
+   * @param {Function|Object} [options] - Connection callback handler: (ws, req) => {} or options object.
+   * @returns {WebSocketManager}
+   * @example
+   * app.websocket((ws, req) => {
+   *   ws.join("chat");
+   *   ws.sendJSON({ message: "Welcome to Blue Bird WebSockets" });
+   * });
+   */
+  websocket(options = {}) {
+    const handler = typeof options === "function" ? options : null;
+    const wsOptions = typeof options === "object" && options !== null ? options : {};
+
+    if (!this.wsManager) {
+      this.wsManager = new WebSocketManager(this.server, wsOptions);
+    }
+    if (handler) {
+      this.wsManager.onConnection(handler);
+    }
+    return this.wsManager;
+  }
+
   /**
    * Returns a pre-configured Helmet middleware for use on specific routers.
    * @param {Object} [options={}] - Helmet options to override defaults.
@@ -335,4 +396,24 @@ class App {
   }
 }
 
+/**
+ * Operational application error class for standardizing custom API errors.
+ */
+export class AppError extends Error {
+  /**
+   * Creates an AppError instance.
+   * @param {string} message - Error message description.
+   * @param {number} [statusCode=500] - HTTP status code.
+   * @param {Array|Object} [errors=[]] - Array or object of detailed errors.
+   */
+  constructor(message, statusCode = 500, errors = []) {
+    super(message);
+    this.name = "AppError";
+    this.statusCode = statusCode;
+    this.errors = errors;
+    this.isOperational = true;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
 export default App;

package/core/database.js

@@ -258,6 +258,142 @@ class Database {
       throw err;
     }
   }
+
+  /**
+   * Executes a paginated SQL query.
+   * Runs an automatic count query to calculate total records and pages, then appends LIMIT and OFFSET.
+   *
+   * @param {string} sql - SQL query string.
+   * @param {Array} [params=[]] - Query parameters.
+   * @param {Object} [options={}] - Pagination options: page, limit, cache.
+   * @returns {Promise<{data: Array, total: number, page: number, limit: number, totalPages: number}>}
+   * @example const result = await connection.paginate("SELECT * FROM users WHERE status = ?", ["active"], { page: 1, limit: 10 });
+   */
+  async paginate(sql, params = [], options = {}) {
+    const page = Math.max(1, parseInt(options.page) || 1);
+    const limit = Math.max(1, parseInt(options.limit) || 10);
+    const offset = (page - 1) * limit;
+
+    const cleanSql = sql.trim().replace(/;$/, "");
+    const countSql = `SELECT COUNT(*) as total FROM (${cleanSql}) as _count_subquery`;
+
+    const countResult = await this.query(countSql, params, { return_row: true });
+    const total = Number(countResult?.total || countResult?.count || 0);
+    const totalPages = Math.ceil(total / limit);
+
+    const paginatedSql = `${cleanSql} LIMIT ${limit} OFFSET ${offset}`;
+    const rows = await this.query(paginatedSql, params, options);
+
+    return {
+      data: Array.isArray(rows) ? rows : [],
+      total,
+      page,
+      limit,
+      totalPages,
+    };
+  }
+
+  /**
+   * Executes a database transaction with automatic commit and rollback.
+   * @param {Function} callback - Async function receiving transaction client: async (tx) => { ... }
+   * @returns {Promise<*>} Value returned from callback.
+   * @example
+   * const userId = await connection.transaction(async (tx) => {
+   *   const id = await tx.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+   *   await tx.query("INSERT INTO profiles (user_id) VALUES (?)", [id]);
+   *   return id;
+   * });
+   */
+  async transaction(callback) {
+    if (!mysqlPromise && !pgPromise) throw new Error("[DATABASE ERROR] No database driver available.");
+    if (!this.pool) {
+      const initialized = await this.init();
+      if (!initialized) throw new Error("[DATABASE ERROR] Failed to initialize database pool.");
+    }
+
+    if (this.type === "postgres" && pgPromise) {
+      const client = await this.pool.connect();
+      try {
+        await client.query("BEGIN");
+
+        const tx = {
+          query: async (sql, params = [], options = {}) => {
+            const queryOptions = typeof options === "string" ? { [options]: true } : options;
+            const cleanSql = sql.trim();
+            const isSelect = cleanSql.toLowerCase().startsWith("select");
+            const isInsert = cleanSql.toLowerCase().startsWith("insert");
+
+            let paramIndex = 1;
+            const pgSql = cleanSql.replace(/\?/g, () => `$${paramIndex++}`);
+            const res = await client.query(pgSql, params);
+
+            if (isSelect) {
+              const rows = res.rows || [];
+              return queryOptions.return_row ? (rows[0] || null) : rows;
+            }
+            if (isInsert) {
+              if (res.rows && res.rows.length > 0) return res.rows[0].id || res.rows[0];
+              return res.rowCount;
+            }
+            return res.rowCount;
+          }
+        };
+
+        const result = await callback(tx);
+        await client.query("COMMIT");
+        return result;
+      } catch (err) {
+        await client.query("ROLLBACK").catch(() => {});
+        console.error("[DATABASE ERROR] Transaction rolled back:", err.message);
+        throw err;
+      } finally {
+        client.release();
+      }
+    } else {
+      const connection = await this.pool.getConnection();
+      try {
+        await connection.beginTransaction();
+
+        const tx = {
+          query: async (sql, params = [], options = {}) => {
+            const queryOptions = typeof options === "string" ? { [options]: true } : options;
+            const cleanSql = sql.trim();
+            const isSelect = cleanSql.toLowerCase().startsWith("select");
+            const isInsert = cleanSql.toLowerCase().startsWith("insert");
+
+            const [results] = await connection.execute(cleanSql, params);
+
+            if (isSelect) {
+              const rows = Array.isArray(results) ? results : [];
+              return queryOptions.return_row ? (rows[0] || null) : rows;
+            }
+            if (isInsert) {
+              return results.insertId || results;
+            }
+            return results;
+          }
+        };
+
+        const result = await callback(tx);
+        await connection.commit();
+        return result;
+      } catch (err) {
+        await connection.rollback().catch(() => {});
+        console.error("[DATABASE ERROR] Transaction rolled back:", err.message);
+        throw err;
+      } finally {
+        connection.release();
+      }
+    }
+  }
+
+  /**
+   * Alias for transaction().
+   * @param {Function} callback
+   */
+  async executeTransaction(callback) {
+    return this.transaction(callback);
+  }
 }
 
 export { Database, DB_TYPE };

package/core/index.d.ts

@@ -0,0 +1,132 @@
+import { Router as ExpressRouter, Request, Response, NextFunction } from "express";
+
+declare global {
+  namespace Express {
+    interface Response {
+      /**
+       * Sends a standardized JSON success response.
+       * @param data Data payload to return.
+       * @param message Success message.
+       * @param statusCode HTTP status code (default: 200).
+       */
+      success(data?: any, message?: string, statusCode?: number): Response;
+
+      /**
+       * Sends a standardized JSON error response.
+       * @param message Error message.
+       * @param statusCode HTTP status code (default: 400).
+       * @param errors Array or object of detailed errors.
+       */
+      error(message?: string, statusCode?: number, errors?: any): Response;
+
+      /**
+       * Sends a standardized paginated JSON response.
+       * @param data Array of records for current page.
+       * @param pagination Object containing page, limit, and total count.
+       * @param message Success message.
+       */
+      paginate(
+        data?: any[],
+        pagination?: { page?: number; limit?: number; total?: number },
+        message?: string
+      ): Response;
+    }
+  }
+}
+
+export class AppError extends Error {
+  statusCode: number;
+  errors: any;
+  isOperational: boolean;
+
+  constructor(message: string, statusCode?: number, errors?: any);
+}
+
+export class App {
+  constructor(options?: {
+    routes?: any[];
+    cors?: any;
+    middlewares?: any[];
+    port?: number | string;
+    host?: string;
+    logger?: boolean;
+    notFound?: boolean;
+    json?: boolean;
+    urlencoded?: boolean;
+    static?: { path: string; options?: any };
+    cookieParser?: boolean;
+    rateLimit?: boolean | any;
+    swagger?: boolean | any;
+    compression?: boolean;
+  });
+
+  use(record: any): void;
+  set(key: string, value: any): void;
+  websocket(
+    options?:
+      | ((ws: any, req: any) => void)
+      | { path?: string; auth?: boolean }
+  ): WebSocketManager;
+  run(): void;
+
+  static helmet(options?: any): any;
+}
+
+export class WebSocketManager {
+  constructor(server: any, options?: { path?: string; auth?: boolean });
+  onConnection(handler: (ws: any, req: any) => void): void;
+  join(room: string, ws: any): void;
+  leave(room: string, ws: any): void;
+  broadcast(data: any, room?: string | null): void;
+}
+
+export class Router {
+  constructor(path?: string, options?: { seo?: boolean; languages?: string[] });
+
+  use(...middleware: any[]): void;
+  get(path: string | RegExp, ...callback: any[]): void;
+  post(path: string | RegExp, ...callback: any[]): void;
+  put(path: string | RegExp, ...callback: any[]): void;
+  delete(path: string | RegExp, ...callback: any[]): void;
+  patch(path: string | RegExp, ...callback: any[]): void;
+  options(path: string | RegExp, ...callback: any[]): void;
+  getRouter(): ExpressRouter;
+  getPath(): string;
+}
+
+export class Validator {
+  constructor(schema: Record<string, any>, lang?: string);
+  middleware(): (req: Request, res: Response, next: NextFunction) => void;
+  validate(data: Record<string, any>): { valid: boolean; errors: any[] };
+}
+
+export class Auth {
+  static encrypt(payload: any, secret: string): string;
+  static decrypt(data: string, secret: string): any;
+  static generateToken(payload: any, secret?: string, expiresIn?: string | number): string;
+  static verifyToken(token: string, secret?: string): any;
+  static protect(options?: { redirect?: string | null; key?: string; cookieKey?: string }): (req: Request, res: Response, next: NextFunction) => Promise<any>;
+  static login(res: Response, data: any, key?: string, options?: { expiresIn?: string | number; cookie?: any }): Promise<string>;
+  static logout(res: Response, key?: string, options?: any, req?: Request): Promise<boolean>;
+}
+
+export class Cache {
+  static middleware(seconds?: number): (req: Request, res: Response, next: NextFunction) => Promise<any>;
+}
+
+export function getRedisClient(): any;
+
+export class Database {
+  constructor(connectionLimit?: number, queueLimit?: number, config?: any);
+  init(retries?: number): Promise<boolean>;
+  query(sql: string, params?: any[], options?: any): Promise<any>;
+  paginate(
+    sql: string,
+    params?: any[],
+    options?: { page?: number; limit?: number; cache?: number }
+  ): Promise<{ data: any[]; total: number; page: number; limit: number; totalPages: number }>;
+  transaction<T = any>(callback: (tx: { query: (sql: string, params?: any[], options?: any) => Promise<any> }) => Promise<T>): Promise<T>;
+  executeTransaction<T = any>(callback: (tx: { query: (sql: string, params?: any[], options?: any) => Promise<any> }) => Promise<T>): Promise<T>;
+}
+
+export default App;

package/core/router.js

@@ -4,6 +4,25 @@ import Config from "./config.js";
 
 const props = Config.props();
 
+/**
+ * Wraps route handlers to automatically catch async rejections and forward them to next(err).
+ * @param {Function} fn - Handler function.
+ * @returns {Function} Wrapped handler.
+ */
+function wrapAsync(fn) {
+  if (typeof fn !== "function") return fn;
+  return (req, res, next) => {
+    try {
+      const result = fn(req, res, next);
+      if (result && typeof result.catch === "function") {
+        result.catch(next);
+      }
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
 /**
  * Router wrapper class for handling Express routing logic.
  * When created with { seo: true }, all GET routes registered on this router
@@ -37,7 +56,8 @@ class Router {
    * router.use(App.helmet());
    */
   use(...middleware) {
-    this.router.use(...middleware);
+    const handlers = middleware.map(wrapAsync);
+    this.router.use(...handlers);
   }
 
   /**
@@ -57,8 +77,8 @@ class Router {
     if (path === "/*" || path === "*") {
       path = /.*/;
     }
-
-    this.router.get(path, callback);
+    const handlers = callback.map(wrapAsync);
+    this.router.get(path, ...handlers);
   }
 
   /**
@@ -74,7 +94,8 @@ class Router {
     if (path === "/*" || path === "*") {
       path = /.*/;
     }
-    this.router.post(path, callback);
+    const handlers = callback.map(wrapAsync);
+    this.router.post(path, ...handlers);
   }
 
   /**
@@ -87,7 +108,8 @@ class Router {
    * })
    */
   put(path, ...callback) {
-    this.router.put(path, callback);
+    const handlers = callback.map(wrapAsync);
+    this.router.put(path, ...handlers);
   }
 
   /**
@@ -100,7 +122,8 @@ class Router {
    * })
    */
   delete(path, ...callback) {
-    this.router.delete(path, callback);
+    const handlers = callback.map(wrapAsync);
+    this.router.delete(path, ...handlers);
   }
 
   /**
@@ -113,7 +136,8 @@ class Router {
    * })
    */
   patch(path, ...callback) {
-    this.router.patch(path, callback);
+    const handlers = callback.map(wrapAsync);
+    this.router.patch(path, ...handlers);
   }
 
   /**
@@ -122,7 +146,8 @@ class Router {
    * @param {...Function} callback - One or more handler functions (middlewares and controller).
    */
   options(path, ...callback) {
-    this.router.options(path, callback);
+    const handlers = callback.map(wrapAsync);
+    this.router.options(path, ...handlers);
   }
 
   /**

package/core/ws.js

@@ -0,0 +1,210 @@
+import { WebSocketServer, WebSocket } from "ws";
+import { getRedisClient } from "./cache.js";
+import Auth from "./auth.js";
+
+/**
+ * High-performance WebSocketManager providing real-time channels, room management,
+ * heartbeat ping/pong, Auth token verification, and Redis Pub/Sub multi-process cluster scaling.
+ */
+class WebSocketManager {
+  /**
+   * Initializes the WebSocket manager attached to an HTTP server.
+   * @param {import('http').Server} server - Express HTTP server instance.
+   * @param {Object} [options={}] - Configuration options.
+   * @param {string} [options.path="/ws"] - WebSocket endpoint route.
+   * @param {boolean} [options.auth=false] - Require valid Auth JWT token on connection.
+   */
+  constructor(server, options = {}) {
+    this.server = server;
+    this.path = options.path || "/ws";
+    this.requireAuth = options.auth ?? false;
+    this.rooms = new Map();
+    this.clients = new Set();
+    this.connectionHandler = null;
+    this.redisPublisher = null;
+    this.redisSubscriber = null;
+
+    this.wss = new WebSocketServer({ noServer: true });
+
+    this._setupUpgrade();
+    this._setupHeartbeat();
+    this._setupRedisPubSub();
+  }
+
+  /**
+   * Attaches the HTTP Upgrade listener to the Express HTTP server instance.
+   * @private
+   */
+  _setupUpgrade() {
+    this.server.on("upgrade", async (request, socket, head) => {
+      const urlObj = new URL(request.url, `http://${request.headers.host || "localhost"}`);
+      if (urlObj.pathname !== this.path) {
+        return;
+      }
+
+      if (this.requireAuth) {
+        const cookieHeader = request.headers.cookie || "";
+        const cookies = {};
+        cookieHeader.split(";").forEach((c) => {
+          const parts = c.trim().split("=");
+          if (parts[0]) cookies[parts[0]] = decodeURIComponent(parts[1] || "");
+        });
+
+        const token = cookies.auth || urlObj.searchParams.get("token") || request.headers.authorization?.split(" ")[1];
+        const user = token ? Auth.verifyToken(token) : null;
+
+        if (!user) {
+          socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+          socket.destroy();
+          return;
+        }
+        request.user = user;
+      }
+
+      this.wss.handleUpgrade(request, socket, head, (ws) => {
+        this.wss.emit("connection", ws, request);
+      });
+    });
+
+    this.wss.on("connection", (ws, req) => {
+      ws.isAlive = true;
+      ws.user = req.user || null;
+      ws.rooms = new Set();
+      this.clients.add(ws);
+
+      ws.on("pong", () => {
+        ws.isAlive = true;
+      });
+
+      ws.on("close", () => {
+        this.clients.delete(ws);
+        ws.rooms.forEach((room) => this.leave(room, ws));
+      });
+
+      ws.on("error", () => {
+        this.clients.delete(ws);
+      });
+
+      ws.join = (room) => this.join(room, ws);
+      ws.leave = (room) => this.leave(room, ws);
+      ws.sendJSON = (data) => {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(JSON.stringify(data));
+        }
+      };
+
+      if (this.connectionHandler) {
+        this.connectionHandler(ws, req);
+      }
+    });
+  }
+
+  /**
+   * Registers a connection callback handler.
+   * @param {Function} handler - Callback function: (ws, req) => {}
+   */
+  onConnection(handler) {
+    this.connectionHandler = handler;
+  }
+
+  /**
+   * Subscribes a WebSocket connection to a room.
+   * @param {string} room - Room identifier.
+   * @param {WebSocket} ws - Target WebSocket instance.
+   */
+  join(room, ws) {
+    if (!this.rooms.has(room)) {
+      this.rooms.set(room, new Set());
+    }
+    this.rooms.get(room).add(ws);
+    ws.rooms.add(room);
+  }
+
+  /**
+   * Unsubscribes a WebSocket connection from a room.
+   * @param {string} room - Room identifier.
+   * @param {WebSocket} ws - Target WebSocket instance.
+   */
+  leave(room, ws) {
+    if (this.rooms.has(room)) {
+      this.rooms.get(room).delete(ws);
+      if (this.rooms.get(room).size === 0) {
+        this.rooms.delete(room);
+      }
+    }
+    ws.rooms.delete(room);
+  }
+
+  /**
+   * Broadcasts a JSON payload or string to all connected clients (or specific room).
+   * Automatically synchronizes across PM2 cluster workers via Redis Pub/Sub if Redis is active.
+   * @param {any} data - Data to send.
+   * @param {string} [room=null] - Optional target room.
+   */
+  broadcast(data, room = null) {
+    const payload = typeof data === "string" ? data : JSON.stringify(data);
+
+    this._sendLocal(payload, room);
+
+    if (this.redisPublisher && this.redisPublisher.isOpen) {
+      this.redisPublisher.publish("bluebird:ws:broadcast", JSON.stringify({ room, payload })).catch(() => {});
+    }
+  }
+
+  /**
+   * Transmits payload to local WebSocket connections.
+   * @private
+   */
+  _sendLocal(payload, room = null) {
+    const targetSockets = room && this.rooms.has(room) ? this.rooms.get(room) : this.clients;
+    targetSockets.forEach((client) => {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(payload);
+      }
+    });
+  }
+
+  /**
+   * Sets up 30s ping/pong heartbeat to clear dead TCP sockets.
+   * @private
+   */
+  _setupHeartbeat() {
+    this.heartbeatInterval = setInterval(() => {
+      this.clients.forEach((ws) => {
+        if (ws.isAlive === false) {
+          this.clients.delete(ws);
+          return ws.terminate();
+        }
+        ws.isAlive = false;
+        ws.ping();
+      });
+    }, 30000);
+    this.heartbeatInterval.unref();
+  }
+
+  /**
+   * Initializes Redis Pub/Sub channels for multi-process PM2 cluster synchronization.
+   * @private
+   */
+  async _setupRedisPubSub() {
+    try {
+      const redisClient = getRedisClient();
+      if (!redisClient) return;
+
+      this.redisPublisher = redisClient.duplicate();
+      this.redisSubscriber = redisClient.duplicate();
+
+      await this.redisPublisher.connect();
+      await this.redisSubscriber.connect();
+
+      await this.redisSubscriber.subscribe("bluebird:ws:broadcast", (message) => {
+        try {
+          const { room, payload } = JSON.parse(message);
+          this._sendLocal(payload, room);
+        } catch {}
+      });
+    } catch {}
+  }
+}
+
+export default WebSocketManager;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@seip/blue-bird",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Express opinionated API framework with built-in JWT auth, validation, and caching",
   "type": "module",
+  "types": "core/index.d.ts",
   "exports": {
     "./*": "./*"
   },
@@ -59,6 +60,7 @@
     "jsonwebtoken": "^9.0.2",
     "multer": "^2.0.2",
     "redis": "^6.1.0",
+    "ws": "^8.18.0",
     "xss": "^1.0.15"
   }
 }