@seip/blue-bird 0.9.0 → 0.9.2

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/docker/nginx.conf

@@ -66,6 +66,7 @@ http {
         }
 
         location / {
+            add_header Cache-Control "no-cache";
             try_files $uri $uri.html $uri/ @node_app;
         }
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@seip/blue-bird",
-  "version": "0.9.0",
+  "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"
   }
 }