@seip/blue-bird 0.9.0 → 0.9.2

package/README.md

@@ -2,7 +2,7 @@
 
 **High-Performance Express Framework — Built for Speed, Caching, and Visual Excellence**
 
-![Blue Bird Logo](https://seip25.github.io/Blue-bird/favicon.png)
+![Blue Bird Logo](https://seip25.github.io/Blue-bird/favicon.ico)
 
 [![npm version](https://img.shields.io/npm/v/@seip/blue-bird.svg)](https://www.npmjs.com/package/@seip/blue-bird)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -95,7 +95,34 @@ project/
 
 ## 📖 Core Modules Documentation / Documentación de Módulos
 
-### 1. Routing (`Router`)
+### 1. Application Class (`App`)
+
+Initializes the Express server. If Docker/Nginx is not used (or for lightweight setups like Express + SQLite), you can configure Express to serve static frontend files directly via the `static` parameter:
+
+```javascript
+import App from "@seip/blue-bird/core/app.js";
+import routerApi from "./backend/routes/api.js";
+
+const app = new App({
+  port: process.env.PORT || 3000,
+  host: "http://localhost",
+  routes: [routerApi],
+  cors: [],
+  middlewares: [],
+  logger: false,
+  // Standalone Express Static Asset Serving (No Nginx/Docker required)
+  static: {
+    path: "../frontend", // relative directory path to frontend files
+    options: {}           // express.static options
+  }
+});
+
+app.run();
+```
+
+---
+
+### 2. Routing (`Router`)
 
 Do not use Express' native router. Always use Blue Bird's wrapper class:
 
@@ -135,57 +162,86 @@ routerApi.post("/users", validateUser.middleware(), (req, res) => {
 
 ---
 
-### 4. JWT Authentication (`Auth`)
+### 4. JWT Authentication & Redis Sessions (`Auth`)
 
-Secure user sessions using stateless AES-256-GCM encrypted JWTs stored in secure HTTP-Only cookies.
+Secure user authentication with AES-256-GCM encrypted tokens. Transmitted via HTTP-Only cookies or `Authorization` headers, with optional Redis session storage and invalidation.
 
 #### Protecting Routes
 
 ```javascript
 import Auth from "@seip/blue-bird/core/auth.js";
 
-// Secure API endpoint (returns 401 on failure)
+// 1. Secure API endpoint (returns 401 JSON on failure)
 router.get("/profile", Auth.protect(), (req, res) => {
   res.json({ user: req.user });
 });
 
-// Secure web page (redirects to /login on failure)
-router.get("/dashboard", Auth.protect({ redirect: "/login" }), (req, res) => {
-  Template.render(res, "dashboard");
+// 2. Secure web page (redirects to /login on failure)
+router.get("/dashboard", Auth.protect({ redirect: "/login", key: "user", cookieKey: "auth" }), (req, res) => {
+  res.send(`<h1>Welcome ${req.user.name}</h1>`);
 });
 ```
 
-#### Authentication Sessions
+#### Authentication Sessions & Utilities
 
 ```javascript
+// Login & Sync Session state in Redis (if active)
 router.post("/login", async (req, res) => {
-  const user = { id: 1, name: "John Doe" };
-  await Auth.login(res, user);
+  const user = { id: 1, name: "John Doe", role: "admin" };
+  await Auth.login(res, user, "auth", { expiresIn: "7d" });
   res.json({ message: "Logged in successfully" });
 });
 
+// Logout & Delete Session from Redis
 router.post("/logout", async (req, res) => {
-  await Auth.logout(res);
+  await Auth.logout(res, "auth", {}, req);
   res.json({ message: "Logged out" });
 });
+
+// Manual Encrypted JWT Tokens & AES-256-GCM Encryption
+const token = Auth.generateToken({ id: 1 }, process.env.JWT_SECRET, "2h");
+const decoded = Auth.verifyToken(token, process.env.JWT_SECRET);
+const encrypted = Auth.encrypt({ secret: "1234" }, process.env.JWT_SECRET);
+const decrypted = Auth.decrypt(encrypted, process.env.JWT_SECRET);
 ```
 
 ---
 
-### 5. Performance Cache Middleware (`Cache`)
+### 5. Performance Cache & Redis Client (`Cache`)
+
+Applies route-level response caching for JSON payloads (`res.json`) and HTML output (`res.send`). Automatically uses Redis when `REDIS_HOST` is configured, and transparently degrades to an in-memory cache if Redis is unavailable or offline.
 
-Applies caching at the route handler level. Automatically caches JSON payloads (`res.json`) and rendered outputs (`res.send`).
+#### Route Caching Middleware
 
 ```javascript
-import Cache from "@seip/blue-bird/core/cache.js";
+import Cache, { getRedisClient } from "@seip/blue-bird/core/cache.js";
 
-// Cache endpoint for 60 seconds
+// Cache endpoint for 60 seconds (sets X-Blue-Bird-Cache: HIT/MISS headers)
 router.get("/stats", Cache.middleware(60), (req, res) => {
   res.json({ usersOnline: 42 });
 });
 ```
 
-Integrates with Redis if `REDIS_HOST` is defined in the environment. Falls back to an in-memory cache automatically if Redis is not configured or not running.
+#### Custom Database & Data Caching with `getRedisClient()`
+
+```javascript
+// Direct access to the active Redis client for database query or custom key caching
+router.get("/custom-cache", async (req, res) => {
+  const redis = getRedisClient();
+  if (redis) {
+    const cached = await redis.get("my_custom_key");
+    if (cached) return res.json(JSON.parse(cached));
+
+    const dbData = await fetchHeavyDataFromDB();
+    await redis.set("my_custom_key", JSON.stringify(dbData), { EX: 120 }); // Expiry 120s
+    return res.json(dbData);
+  }
+  
+  // Fallback if Redis is disabled
+  const dbData = await fetchHeavyDataFromDB();
+  res.json(dbData);
+});
+```
 
 ---
 
@@ -237,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.
 
@@ -269,8 +395,17 @@ npx blue-bird docker <command> [options]
 - **`npx blue-bird docker ps`**: Lists running project containers and ports.
 - **`npx blue-bird docker logs [app|db|postgres|mysql]`**: Tails logs for the specified container.
 - **`npx blue-bird docker pm2 [args]`**: Runs PM2 commands inside the Node.js application container (e.g. `status`, `monit`, `reload all`).
-- **`npx blue-bird docker db`** (or `psql` / `mysql`): Connects into the container's interactive database shell (`psql` for PostgreSQL, `mysql` for MySQL) using credentials from `.env`.
-- **`npx blue-bird docker redis`**: Connects into the container's interactive Redis CLI terminal.
+- **`npx blue-bird docker db`** (or `psql` / `mysql`): Connects into the container's interactive database shell (`psql` for PostgreSQL, `mysql` for MySQL). Supports smart table queries, schema inspection, and backups:
+  - `npx blue-bird docker mysql users` -> executes `SELECT * FROM users;` formatted as ASCII table.
+  - `npx blue-bird docker mysql users --limit=10 --where="id > 5"` -> executes filtered query.
+  - `npx blue-bird docker mysql tables` -> lists database tables (`SHOW TABLES`).
+  - `npx blue-bird docker mysql columns users` -> describes table schema (`SHOW COLUMNS`).
+- **`npx blue-bird docker export [filename.sql]`** (or `npx blue-bird docker mysql export`): Dumps database schema and data into `backups/backup_YYYY-MM-DD.sql` (creates `backups/` folder automatically).
+- **`npx blue-bird docker import [filename.sql]`** (or `npx blue-bird docker mysql import`): Restores database from a `.sql` file in `backups/` (uses the most recent `.sql` backup if no filename is specified).
+- **`npx blue-bird docker redis`**: Connects into the container's interactive Redis CLI terminal. Supports smart subcommands:
+  - `npx blue-bird docker redis monitor` -> live stream of all incoming Redis commands.
+  - `npx blue-bird docker redis keys [pattern]` -> lists all matching Redis keys (defaults to `*`).
+  - `npx blue-bird docker redis key <keyname>` -> gets value for specific Redis key.
 - **`npx blue-bird docker prune`**: Safely clears orphaned volumes, dangling build caches, and images.
 
 ---

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;