@seip/blue-bird 0.7.1 → 0.7.2

package/AGENTS.md

@@ -176,6 +176,7 @@ npx blue-bird docker ps             # Shows status of active containers
 npx blue-bird docker logs           # Tails Node.js app container logs
 npx blue-bird docker pm2 [args]     # Runs PM2 commands inside the app container (e.g. status, monit)
 npx blue-bird docker mysql          # Runs interactive MySQL client terminal inside the container
+npx blue-bird docker redis          # Runs interactive Redis client terminal inside the container
 npx blue-bird docker prune          # Cleans unused volumes, dangling images, and BuildKit caches
 ```
 
@@ -188,4 +189,21 @@ The container names and virtual networks are namespaced by the `TITLE` environme
 3. **Magic Imports**: Stick to pure relative imports or well-configured aliases (imports natively resolve from `@seip/blue-bird/...` or relative directories like `../../`).
 4. **No inline comments**: Only use JSDoc for documentation.
 
+## 10. Database Module (database.js)
+
+Blue Bird provides a unified wrapper class for MySQL databases via `mysql2` connections pool with automatic retries and built-in query caching:
+
+```javascript
+import connection from "@seip/blue-bird/core/database.js";
+
+// Basic SELECT query returning single row
+const user = await connection.query("SELECT * FROM users WHERE id = ?", [1], "return_row");
+
+// Query caching in Redis (stores results in Redis for 60 seconds)
+const stats = await connection.query("SELECT COUNT(*) as cnt FROM logs", [], { cache: 60 });
+
+// INSERT query returns insertId directly
+const newUserId = await connection.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+```
+
 _This file can be retrieved by intelligent agents reading its absolute physical path during reasoning._

package/README.md

@@ -218,6 +218,25 @@ webRouter.use(App.helmet());
 
 ---
 
+### 7. Database wrapper (`Database`)
+
+MySQL database client connection pool configuration featuring automated retry loops, query formatting utilities, and Redis query caching.
+
+```javascript
+import connection from "@seip/blue-bird/core/database.js";
+
+// Fetch single row from a SELECT query
+const user = await connection.query("SELECT * FROM users WHERE email = ?", ["test@example.com"], "return_row");
+
+// Fetch rows with 60 seconds Redis caching enabled
+const stats = await connection.query("SELECT COUNT(*) as count FROM access_logs", [], { cache: 60 });
+
+// INSERT queries return the last insert ID directly
+const newId = await connection.query("INSERT INTO users (name) VALUES (?)", ["John"]);
+```
+
+---
+
 ## 🐳 Docker CLI Workflow
 
 Blue Bird comes with a built-in Docker CLI wrapper that handles both local development database bootstrapping and full-stack VPS production deployments.
@@ -240,6 +259,7 @@ npx blue-bird docker <command> [options]
 - **`npx blue-bird docker logs [app|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`**: Connects into the container's interactive MySQL shell using credentials from `.env`.
+- **`npx blue-bird docker redis`**: Connects into the container's interactive Redis CLI terminal.
 - **`npx blue-bird docker prune`**: Safely clears orphaned volumes, dangling build caches, and images.
 
 ---

package/backend/logs/2026-07-14/info.log

@@ -0,0 +1,48 @@
+ 2026-07-14 22:04:34 -::1 -[GET] / 
+ 2026-07-14 22:04:38 -::1 -[GET] /about 
+ 2026-07-14 22:04:38 -::1 -[GET] /about 
+ 2026-07-14 22:04:39 -::1 -[GET] / 
+ 2026-07-14 22:04:39 -::1 -[GET] / 
+ 2026-07-14 22:06:26 -::1 -[GET] /api/users 
+ 2026-07-14 22:08:02 -::1 -[GET] /api/users 
+ 2026-07-14 22:08:05 -::1 -[GET] /api/ 
+ 2026-07-14 22:42:04 -::1 -[GET] /api/auth_generate 
+ 2026-07-14 22:42:05 -::1 -[GET] /api/auth_generate 
+ 2026-07-14 22:42:10 -::1 -[GET] /api/auth_verify 
+ 2026-07-14 22:42:12 -::1 -[GET] /api/auth_verify 
+ 2026-07-14 22:42:21 -::1 -[GET] /api/auth_logout 
+ 2026-07-14 22:42:24 -::1 -[GET] /api/auth_verify 
+ 2026-07-14 22:42:28 -::1 -[GET] / 
+ 2026-07-14 22:42:28 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:42:29 -::1 -[GET] / 
+ 2026-07-14 22:42:29 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:42:30 -::1 -[GET] /about 
+ 2026-07-14 22:42:31 -::1 -[GET] /about 
+ 2026-07-14 22:42:32 -::1 -[GET] / 
+ 2026-07-14 22:42:32 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:42:32 -::1 -[GET] / 
+ 2026-07-14 22:42:32 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:42:33 -::1 -[GET] /about 
+ 2026-07-14 22:42:35 -::1 -[GET] / 
+ 2026-07-14 22:42:35 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:42:37 -::1 -[GET] /about 
+ 2026-07-14 22:42:38 -::1 -[GET] / 
+ 2026-07-14 22:42:38 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:48:54 -::1 -[GET] / 
+ 2026-07-14 22:48:54 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:48:56 -::1 -[GET] /about 
+ 2026-07-14 22:48:58 -::1 -[GET] /about 
+ 2026-07-14 22:48:59 -::1 -[GET] / 
+ 2026-07-14 22:48:59 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:48:59 -::1 -[GET] / 
+ 2026-07-14 22:48:59 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:49:01 -::1 -[GET] /about 
+ 2026-07-14 22:49:02 -::1 -[GET] / 
+ 2026-07-14 22:49:02 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:49:03 -::1 -[GET] /about 
+ 2026-07-14 22:49:04 -::1 -[GET] / 
+ 2026-07-14 22:49:04 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:49:05 -::1 -[GET] /about 
+ 2026-07-14 22:49:07 -::1 -[GET] / 
+ 2026-07-14 22:49:07 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:49:07 -::1 -[GET] /about 

package/backend/routes/api.js

@@ -40,12 +40,12 @@ routerApi.get("/cache", Cache.middleware(), async (req, res) => {
 });
 
 routerApi.get("/auth_generate", async (req, res) => {
-  const token = await Auth.login(res, { id: 1, name: "John Doe" });
+  const token = await Auth.login(res, { id: 1, name: "John Doe" }, "auth");
   res.json({ message: "Auth successful", token });
 });
 
 routerApi.get("/auth_logout", async (req, res) => {
-  await Auth.logout(res);
+  await Auth.logout(res, "auth", {}, req);
   res.json({ message: "Auth successful" });
 });
 

package/core/auth.js

@@ -1,6 +1,7 @@
 import jwt from "jsonwebtoken";
 import crypto from "node:crypto";
 import Config from "./config.js";
+import { getRedisClient } from "./cache.js";
 
 const propsConfig = Config.props();
 const jwtSecret = propsConfig.jwtSecret;
@@ -57,11 +58,7 @@ class Auth {
    * @param {string} [expiresIn="24h"] - Expiration time.
    * @returns {string} The generated token.
    */
-  static generateToken(
-    payload,
-    secret = jwtSecret,
-    expiresIn = "24h"
-  ) {
+  static generateToken(payload, secret = jwtSecret, expiresIn = "24h") {
     if (!secret)
       throw new Error("FATAL: JWT_SECRET environment variable is not defined.");
     const encrypted = this.encrypt(payload, secret);
@@ -101,7 +98,7 @@ class Auth {
   static protect(options = {}) {
     const { redirect = null, key = "user", cookieKey = "auth" } = options;
 
-    return (req, res, next) => {
+    return async (req, res, next) => {
       const token =
         req.cookies?.[cookieKey] || req.headers.authorization?.split(" ")[1];
 
@@ -123,6 +120,32 @@ class Auth {
           : res.status(401).send();
       }
 
+      const redisClient = getRedisClient();
+      if (redisClient && decoded._sessionId) {
+        try {
+          const sessionData = await redisClient.get(
+            `session:${decoded._sessionId}`,
+          );
+          if (!sessionData) {
+            if (redirect && !isContentTypeJson) return res.redirect(redirect);
+            return isContentTypeJson
+              ? res.status(401).json({ message: "Unauthorized" })
+              : res.status(401).send();
+          }
+          req[key || "user"] = JSON.parse(sessionData);
+          return next();
+        } catch (err) {
+          console.error(
+            "[AUTH ERROR] Failed to get session data from Redis:",
+            err.message,
+          );
+          if (redirect && !isContentTypeJson) return res.redirect(redirect);
+          return isContentTypeJson
+            ? res.status(401).json({ message: "Unauthorized" })
+            : res.status(401).send();
+        }
+      }
+
       req[key || "user"] = decoded;
       next();
     };
@@ -142,8 +165,10 @@ class Auth {
    */
   static async login(res, data, key = "auth", options = {}) {
     const { expiresIn = "24h", cookie = {} } = options;
+    const sessionId = crypto.randomUUID();
+    const tokenPayload = { ...data, _sessionId: sessionId };
 
-    const token = this.generateToken(data, jwtSecret, expiresIn);
+    const token = this.generateToken(tokenPayload, jwtSecret, expiresIn);
 
     const defaultCookieOptions = {
       maxAge: 24 * 60 * 60 * 1000,
@@ -155,6 +180,34 @@ class Auth {
 
     const finalCookieOptions = { ...defaultCookieOptions, ...cookie };
 
+    const redisClient = getRedisClient();
+    if (redisClient) {
+      try {
+        let ttl = 86400;
+        if (typeof expiresIn === "string") {
+          const match = expiresIn.match(/^(\d+)([smhd])$/);
+          if (match) {
+            const val = parseInt(match[1]);
+            const unit = match[2];
+            if (unit === "s") ttl = val;
+            else if (unit === "m") ttl = val * 60;
+            else if (unit === "h") ttl = val * 3600;
+            else if (unit === "d") ttl = val * 86400;
+          }
+        } else if (typeof expiresIn === "number") {
+          ttl = expiresIn;
+        }
+        await redisClient.set(`session:${sessionId}`, JSON.stringify(data), {
+          EX: ttl,
+        });
+      } catch (err) {
+        console.error(
+          "[AUTH ERROR] Failed to store session in Redis:",
+          err.message,
+        );
+      }
+    }
+
     res.cookie(key, token, finalCookieOptions);
     return token;
   }
@@ -164,14 +217,37 @@ class Auth {
    * @param {import('express').Response} res - The response object.
    * @param {string} [key="auth"] - The key for the cookie.
    * @param {import('express').CookieOptions} [options={}] - Options for clearing the cookie.
+   * @param {import('express').Request} [req=null] - The request object.
    * @returns {Promise<boolean>} True if the cookie was cleared successfully.
    * @example
    * await Auth.logout(res);
    */
-  static async logout(res, key = "auth", options = {}) {
+  static async logout(res, key = "auth", options = {}, req = null) {
     const defaultOptions = {
       path: "/",
     };
+
+    if (req) {
+      const token =
+        req.cookies?.[key] || req.headers.authorization?.split(" ")[1];
+      if (token) {
+        const decoded = this.verifyToken(token);
+        if (decoded && decoded._sessionId) {
+          const redisClient = getRedisClient();
+          if (redisClient) {
+            try {
+              await redisClient.del(`session:${decoded._sessionId}`);
+            } catch (err) {
+              console.error(
+                "[AUTH ERROR] Failed to delete session from Redis:",
+                err.message,
+              );
+            }
+          }
+        }
+      }
+    }
+
     res.clearCookie(key, { ...defaultOptions, ...options });
     return true;
   }

package/core/cache.js

@@ -157,4 +157,12 @@ class Cache {
   }
 }
 
+/**
+ * Returns the active Redis client if connected.
+ * @returns {Object|null} The Redis client instance or null.
+ */
+export function getRedisClient() {
+  return isRedisConnected ? redisClient : null;
+}
+
 export default Cache;

package/core/cli/docker.js

@@ -271,6 +271,15 @@ async function pm2Command(pm2Args = []) {
   }
 }
 
+/**
+ * Handles interactive shell connections into the Redis container.
+ */
+async function redisCommand() {
+  checkComposeFile();
+  const cmdArgs = ["compose", "exec", "redis", "redis-cli"];
+  await runCmd("docker", cmdArgs);
+}
+
 /**
  * Entry point for Blue Bird CLI Docker subcommands.
  */
@@ -325,6 +334,9 @@ async function main() {
     case "pm2":
       await pm2Command(args.slice(1));
       break;
+    case "redis":
+      await redisCommand();
+      break;
     case "mysql":
     case "db": {
       let user, password, db, root = false;
@@ -351,7 +363,7 @@ async function main() {
     }
     default:
       console.log(chalk.yellow(`Unknown docker command: ${command}`));
-      console.log("Available commands: start, stop, build, ps, logs, pm2, mysql/db, df/disk, prune/clean");
+      console.log("Available commands: start, stop, build, ps, logs, pm2, mysql/db, redis, df/disk, prune/clean");
   }
 }
 

package/core/database.js

@@ -0,0 +1,182 @@
+import crypto from "node:crypto";
+import { getRedisClient } from "./cache.js";
+
+let mysqlPromise = null;
+try {
+  mysqlPromise = await import("mysql2/promise");
+} catch (err) {
+  console.error(
+    "[DATABASE ERROR] mysql2 package is not installed. Database wrapper is disabled.",
+  );
+}
+
+/**
+ * Database class wrapping mysql2 with reconnection retries, connection pool, and query caching.
+ */
+class Database {
+  /**
+   * Initializes config from DATABASE_URL or DB_* environment variables.
+   */
+  constructor(connectionLimit = 10, queueLimit = 0) {
+    this.pool = null;
+    this.config = {
+      host: process.env.DB_HOST || "localhost",
+      user: process.env.DB_USER || "root",
+      password: process.env.DB_PASSWORD || "root",
+      database: process.env.DB_NAME || "blue_bird",
+      port: parseInt(process.env.DB_PORT) || 3306,
+      charset: "utf8mb4",
+      waitForConnections: true,
+      connectionLimit: connectionLimit,
+      queueLimit: queueLimit,
+    };
+
+    if (
+      process.env.DATABASE_URL &&
+      process.env.DATABASE_URL.startsWith("mysql://")
+    ) {
+      try {
+        const url = new URL(process.env.DATABASE_URL);
+        this.config.host = url.hostname;
+        this.config.port = parseInt(url.port) || 3306;
+        this.config.user = url.username;
+        this.config.password = url.password;
+        this.config.database = url.pathname.substring(1);
+      } catch (err) {
+        console.error(
+          "[DATABASE ERROR] Failed to parse DATABASE_URL:",
+          err.message,
+        );
+      }
+    }
+  }
+
+  /**
+   * Creates the MySQL connection pool with 3 retry attempts on failure.
+   * @param {number} [retries=3] - Number of connection attempts.
+   * @returns {Promise<boolean>} True if connection pool was created.
+   */
+  async init(retries = 3) {
+    if (!mysqlPromise) return false;
+    if (this.pool) return true;
+
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      try {
+        this.pool = mysqlPromise.createPool(this.config);
+        await this.pool.query("SELECT 1");
+        return true;
+      } catch (err) {
+        this.pool = null;
+        if (attempt === retries) {
+          console.error(
+            `[DATABASE ERROR] Connection failed after ${retries} attempts:`,
+            err.message,
+          );
+          return false;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Runs a SQL query with parameters and formatting options.
+   *
+   * @param {string} sql - SQL query string.
+   * @param {Array} [params=[]] - Query parameter array.
+   * @param {Object|string} [options={}] - Query options. Supports 'return_row', 'return_rows', and 'cache' (seconds).
+   * @returns {Promise<*>| int | boolean} Formatted query result or false on error, or insert id of insert query.
+   * @example select
+   *  const result = await connection.query("SELECT * FROM users", [], { return_row: true, cache: 60 });
+   * @example insert
+   *  const result = await connection.query("INSERT INTO users (name, email, password) VALUES (?, ?, ?)", ["John Doe", "[EMAIL_ADDRESS]", "123456"]);
+   * @example update
+   *  const result = await connection.query("UPDATE users SET name = ? WHERE id = ?", ["John Doe", 1]);
+   * @example delete
+   *  const result = await connection.query("DELETE FROM users WHERE id = ?", [1]);
+   */
+  async query(sql, params = [], options = {}) {
+    if (!mysqlPromise) return false;
+    if (!this.pool) {
+      const initialized = await this.init();
+      if (!initialized) return false;
+    }
+
+    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 redisClient = getRedisClient();
+    let cacheKey = null;
+    const isDebug = queryOptions.debug ?? false;
+    if (isDebug) {
+      console.log("[DATABASE DEBUG] SQL:", sql);
+      console.log("[DATABASE DEBUG] PARAMS:", params);
+      console.log("[DATABASE DEBUG] OPTIONS:", options);
+    }
+
+    if (isSelect && queryOptions.cache && redisClient) {
+      const hash = crypto
+        .createHash("md5")
+        .update(cleanSql + JSON.stringify(params))
+        .digest("hex");
+      cacheKey = `db:${hash}`;
+      try {
+        if (isDebug) {
+          console.log("[DATABASE DEBUG ][Redis] CACHE KEY:", cacheKey);
+        }
+        const cached = await redisClient.get(cacheKey);
+        if (cached) {
+          if (isDebug) {
+            console.log("[DATABASE DEBUG ][Redis] CACHE HIT");
+          }
+          return JSON.parse(cached);
+        } else {
+          if (isDebug) {
+            console.log("[DATABASE DEBUG ][Redis] CACHE MISS");
+          }
+        }
+      } catch (err) {
+        console.error(
+          "[DATABASE ERROR] Failed to get cached data:",
+          err.message,
+        );
+      }
+    }
+
+    try {
+      const [results] = await this.pool.execute(cleanSql, params);
+
+      if (isSelect) {
+        const rows = Array.isArray(results) ? results : [];
+        if (cacheKey && queryOptions.cache && redisClient) {
+          await redisClient
+            .set(cacheKey, JSON.stringify(rows), {
+              EX: parseInt(queryOptions.cache),
+            })
+            .catch(() => {});
+        }
+        if (queryOptions.return_row) {
+          return rows.length > 0 ? rows[0] : null;
+        }
+        return rows;
+      }
+
+      if (isInsert) {
+        return results.insertId || results;
+      }
+
+      return results;
+    } catch (err) {
+      console.error("[DATABASE ERROR] Query execution failed:", err.message);
+      throw err;
+    }
+  }
+}
+
+const connection = new Database();
+export default connection;
+export { Database };

package/core/logger.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import Config from "./config.js";
+import { getRedisClient } from "./cache.js";
 
 const __dirname = Config.dirname();
 
@@ -52,47 +53,62 @@ class Logger {
   }
 
   /**
-   * Appends an informational message to the info.log file (non-blocking).
-   * @param {string} message - The message to log.
+   * Logs a message to the specified log file or Redis list.
+   * @private
+   * @param {string} file - The file name to log to.
+   * @param {string} level - The log level (e.g. info, error, warn, debug).
+   * @param {string} message - The log message.
    */
-  info(message) {
-    const logFile = path.join(this.nowFolder(), "info.log");
+  async _log(file, level, message) {
+    const redisClient = getRedisClient();
+    if (redisClient) {
+      try {
+        await redisClient.lPush(`bluebird:logs:${level}`, message);
+        return;
+      } catch (err) {
+        console.error(
+          `[LOGGER ERROR] Failed to write to Redis logs (${level}):`,
+          err.message,
+        );
+      }
+    }
+
+    const logFile = path.join(this.nowFolder(), file);
     fs.appendFile(logFile, `${message}\n`, (err) => {
       if (err) console.error("Logger write error:", err.message);
     });
   }
 
   /**
-   * Appends an error message to the error.log file (non-blocking).
+   * Appends an informational message.
+   * @param {string} message - The message to log.
+   */
+  info(message) {
+    this._log("info.log", "info", message);
+  }
+
+  /**
+   * Appends an error message.
    * @param {string} message - The error message to log.
    */
   error(message) {
-    const logFile = path.join(this.nowFolder(), "error.log");
-    fs.appendFile(logFile, `${message}\n`, (err) => {
-      if (err) console.error("Logger write error:", err.message);
-    });
+    this._log("error.log", "error", message);
   }
 
   /**
-   * Appends a warning message to the warn.log file (non-blocking).
+   * Appends a warning message.
    * @param {string} message - The warning message to log.
    */
   warning(message) {
-    const logFile = path.join(this.nowFolder(), "warn.log");
-    fs.appendFile(logFile, `${message}\n`, (err) => {
-      if (err) console.error("Logger write error:", err.message);
-    });
+    this._log("warn.log", "warn", message);
   }
 
   /**
-   * Appends a debug message to the debug.log file (non-blocking).
+   * Appends a debug message.
    * @param {string} message - The debug message to log.
    */
   debug(message) {
-    const logFile = path.join(this.nowFolder(), "debug.log");
-    fs.appendFile(logFile, `${message}\n`, (err) => {
-      if (err) console.error("Logger write error:", err.message);
-    });
+    this._log("debug.log", "debug", message);
   }
 }
 

package/index.js

@@ -16,6 +16,8 @@ const app = new App({
 
   port: process.env.PORT,
 
+  logger: true, //In production, set this to false to disable logging and stop writing to Redis
+
   astro: {
     server: true,
     serverEntry: "./frontend/dist/server/entry.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seip/blue-bird",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Express opinionated framework with HTML rendering, API architecture, built-in JWT auth, validation, caching, and SEO",
   "type": "module",
   "exports": {
@@ -65,6 +65,7 @@
     "helmet": "^8.1.0",
     "jsonwebtoken": "^9.0.2",
     "multer": "^2.0.2",
+    "mysql2": "^3.22.6",
     "redis": "^4.7.0",
     "xss": "^1.0.15"
   }