@seip/blue-bird 0.2.4 → 0.2.6

package/.env_example

@@ -9,4 +9,5 @@ VERSION="1.0.0"
 LANGMETA="en"
 HOST="http://localhost"
 PORT=3001
-STATIC_PATH="frontend/public"
+STATIC_PATH="frontend/public"
+JWT_SECRET="JWT_SECRET"

package/backend/index.js

@@ -4,8 +4,7 @@ import routerUsers from "./routes/app.js";
 const app = new App({
     routes: [routerUsers],
     cors: [],
-    middlewares: [],
-    port: 3000,
+    middlewares: [], 
     host: "http://localhost"
 })
 

package/backend/routes/app.js

@@ -5,6 +5,18 @@ import Template from "@seip/blue-bird/core/template.js"
 
 const routerUsers = new Router("/")
 
+//Example swagger docs 
+/**
+ * @swagger
+ * /users:
+ *   get:
+ *     summary: Get all users
+ *     tags: [Users]
+ *     responses:
+ *       200:
+ *         description: List of users
+ *        
+ */
 routerUsers.get("/users", (req, res) => {
     const users = [
         {
@@ -25,7 +37,41 @@ const loginSchema = {
 };
 
 const loginValidator = new Validator(loginSchema, 'es');
-
+ /**
+ * @swagger
+ * /login:
+ *   post:
+ *     summary: Login 
+ *     tags: [Users]
+ *     description: Login with email and password
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required:
+ *               - email
+ *               - password
+ *             properties:
+ *               email:
+ *                 type: string
+ *                 format: email
+ *                 example: example@email.com
+ *               password:
+ *                 type: string
+ *                 format: password
+ *                 example: 123456
+ *     responses:
+ *       200:
+ *         description: Login success
+ *         
+ *       400:
+ *         description: Error  
+ *       401:
+ *         description: Error in request
+ */
+ 
 routerUsers.post('/login', loginValidator.middleware(), (req, res) => {
     res.json({ message: 'Login successful' });
 });

package/core/app.js

@@ -3,8 +3,13 @@ import cors from "cors"
 import path from "path"
 import chalk from "chalk"
 import cookieParser from "cookie-parser"
+import rateLimit from "express-rate-limit"
+import xss from "xss"
+import helmet from "helmet"
 import Config from "./config.js"
 import Logger from "./logger.js"
+import Debug from "./debug.js"
+import Swagger from "./swagger.js"
 
 const __dirname = Config.dirname()
 const props = Config.props()
@@ -27,10 +32,14 @@ class App {
      * @param {boolean} [options.urlencoded=true] - Whether to enable URL-encoded body parsing.
      * @param {Object} [options.static={path: null, options: {}}] - Static file configuration.
      * @param {boolean} [options.cookieParser=true] - Whether to enable cookie parsing.
+     * @param {boolean|Object} [options.rateLimit=false] - Enable global rate limiting.
+     * @param {boolean|Object} [options.helmet=true] - Enable Helmet security headers.
+     * @param {boolean} [options.xssClean=true] - Enable XSS body sanitization.
+     * @param {boolean|Object} [options.swagger=true] - Enable swagger
      * @example 
      * const app = new App({
      *     routes: [],
-     *     cors: {},
+     *     cors: {}, // { origin: "https://domain:port" }
      *     middlewares: [],
      *     port: 3000,
      *     host: "http://localhost",
@@ -42,7 +51,21 @@ class App {
      *         path: "public",
      *         options: {}
      *     },
-     *     cookieParser: true,
+     *      cookieParser: true,
+     *      rateLimit: {
+     *       windowMs: 10 * 60 * 1000, 
+     *        max: 50
+     *         },
+     *          helmet:true,
+     *          xssClean:true,
+     *          swagger:{
+     *          info: {
+     *             title: "Blue Bird API",
+     *             version: "1.0.0",
+     *             description: "Blue Bird Framework API Documentation"
+     *            },
+     *           url : "http://localhost:8000"
+     *          }
      * });
      */
     constructor(options = {
@@ -60,6 +83,10 @@ class App {
             options: {}
         },
         cookieParser: true,
+        rateLimit: false,
+        helmet: false,
+        xssClean: true,
+        swagger: true
 
     }) {
         this.app = express()
@@ -68,12 +95,16 @@ class App {
         this.middlewares = options.middlewares || []
         this.port = options.port || props.port
         this.host = options.host || props.host
-        this.logger = options.logger || true
-        this.notFound = options.notFound || true
-        this.json = options.json || true
-        this.urlencoded = options.urlencoded || true
+        this.logger = options.logger ?? true
+        this.notFound = options.notFound ?? true
+        this.json = options.json ?? true
+        this.urlencoded = options.urlencoded ?? true
         this.static = options.static || props.static
-        this.cookieParser = options.cookieParser || true
+        this.cookieParser = options.cookieParser ?? true
+        this.rateLimit = options.rateLimit ?? false
+        this.helmet = options.helmet ?? true
+        this.xssClean = options.xssClean ?? true
+        this.swagger = options.swagger ?? true
         this.dispatch()
 
     }
@@ -110,15 +141,91 @@ class App {
         if (this.urlencoded) this.app.use(express.urlencoded({ extended: true }))
         if (this.cookieParser) this.app.use(cookieParser())
         if (this.static.path) this.app.use(express.static(path.join(__dirname, this.static.path), this.static.options))
+
         this.app.use(cors(this.cors))
+        if (this.rateLimit) {
+            if (!this.app.get('trust proxy')) {
+                this.app.set('trust proxy', 1);
+            }
+            const defaultRateLimit = {
+                windowMs: 15 * 60 * 1000,
+                max: 100,
+                standardHeaders: true,
+                legacyHeaders: false,
+                message: {
+                    success: false,
+                    message: "Too many requests, please try again later."
+                }
+            };
+            const optionsRateLimiter = {
+                ...defaultRateLimit,
+                ...(typeof this.rateLimit === "object" ? this.rateLimit : {})
+            };
+
+            if (props.debug) {
+                optionsRateLimiter.skip = (req) =>
+                    req.path.startsWith("/debug");
+            }
+
+            const limiter = rateLimit(optionsRateLimiter);
+
+            this.app.use(limiter);
+        }
+        if (this.helmet) {
+
+            const defaultHelmetOptions = {
+                contentSecurityPolicy: props.debug
+                    ? false
+                    : undefined
+            };
+
+            const helmetOptions = {
+                ...defaultHelmetOptions,
+                ...(typeof this.helmet === "object" ? this.helmet : {})
+            };
+
+            this.app.use(helmet(helmetOptions));
+        }
+
+        if (this.xssClean) {
+            this.app.use(this.xssMiddleware());
+        }
         this.middlewares.map(middleware => {
             this.app.use(middleware)
         })
+
         if (this.logger) this.middlewareLogger()
+
         this.app.use((req, res, next) => {
             res.setHeader('X-Powered-By', 'Blue Bird');
             next();
         });
+
+        if (props.debug) {
+            Debug.middlewareMetrics(this.app);
+        }
+        this.errorHandler();
+
+        if (this.swagger) {
+
+            const defaultSwaggerOptions = {
+                info: {
+                    title: "Blue Bird API",
+                    version: "1.0.0",
+                    description: "Blue Bird Framework API Documentation"
+                },
+                url: `${this.host}:${this.port}`,
+                route: "/docs"
+            };
+
+            const swaggerOptions = {
+                ...defaultSwaggerOptions,
+                ...(typeof this.swagger === "object" ? this.swagger : {})
+            };
+
+            Swagger.init(this.app, swaggerOptions);
+        }
+
         this.dispatchRoutes()
 
         if (this.notFound) this.notFoundDefault()
@@ -131,7 +238,7 @@ class App {
     middlewareLogger() {
         this.app.use((req, res, next) => {
             const method = req.method
-            const url = req.url
+            const url = req.url.replace(/(password|token|authorization)=([^&]+)/gi, "$1=***")
             const params = Object.keys(req.params).length > 0 ? ` ${JSON.stringify(req.params)}` : ""
             const ip = req.ip
             const now = new Date().toISOString()
@@ -146,14 +253,84 @@ class App {
             next()
         })
     }
+    errorHandler() {
+        this.app.use((err, req, res, next) => {
+            const logger = new Logger();
+            logger.error(err.stack || err.message);
+
+            if (props.debug) {
+                return res.status(err.status || 500).json({
+                    success: false,
+                    message: err.message,
+                    stack: err.stack
+                });
+            }
+
+            return res.status(err.status || 500).json({
+                success: false
+            });
+        });
+    }
+
+    sanitizeObject(obj) {
+        if (typeof obj === "string") return xss(obj);
+
+        if (Array.isArray(obj)) {
+            return obj.map(item => this.sanitizeObject(item));
+        }
+
+        if (typeof obj === "object" && obj !== null) {
+            const sanitized = {};
+            for (const key in obj) {
+                sanitized[key] = this.sanitizeObject(obj[key]);
+            }
+            return sanitized;
+        }
+
+        return obj;
+    }
+
+    xssMiddleware() {
+        return (req, res, next) => {
+
+            if (req.body && typeof req.body === "object") {
+                this.mutateSanitized(req.body);
+            }
+
+            if (req.query && typeof req.query === "object") {
+                this.mutateSanitized(req.query);
+            }
 
+            if (req.params && typeof req.params === "object") {
+                this.mutateSanitized(req.params);
+            }
+
+            next();
+        };
+    }
+    mutateSanitized(obj) {
+        for (const key in obj) {
+            if (typeof obj[key] === "string") {
+                obj[key] = xss(obj[key]);
+            } else if (typeof obj[key] === "object" && obj[key] !== null) {
+                this.mutateSanitized(obj[key]);
+            }
+        }
+    }
     /**
      * Iterates through the stored routes and attaches them to the Express application instance.
      */
     dispatchRoutes() {
+        if (props.debug) {
+            const debug = new Debug();
+            const debugRouter = debug.getRouter();
+            this.app.use(debugRouter.path, debugRouter.router);
+        }
         this.routes.map(route => {
             this.app.use(route.path, route.router)
         })
+
+
     }
     /**
      * Default 404 handler for unmatched routes.

package/core/cache.js

@@ -0,0 +1,36 @@
+const CACHE = {};
+/**
+ * Cache Middleware
+ * @example 
+ * router.get("/stats",
+    Cache.middleware(120),
+    controller.stats
+);
+ * */
+class Cache {
+
+    static middleware(seconds = 60) {
+        return (req, res, next) => {
+
+            const key = req.originalUrl;
+
+            if (CACHE[key] && CACHE[key].expiry > Date.now()) {
+                return res.json(CACHE[key].data);
+            }
+
+            const originalJson = res.json.bind(res);
+
+            res.json = (body) => {
+                CACHE[key] = {
+                    data: body,
+                    expiry: Date.now() + seconds * 1000
+                };
+                return originalJson(body);
+            };
+
+            next();
+        };
+    }
+}
+
+export default Cache;

package/core/cli/init.js

@@ -110,7 +110,7 @@ const command = args[0];
 
 if (command === "react") import("./react.js");
 else if (command === "route") import("./route.js")
-else if (command === "component") import("./route.js")
+else if (command === "component") import("./component.js")
 else initializer.run();
 
 

package/core/debug.js

@@ -0,0 +1,249 @@
+import Router from "./router.js";
+
+/**
+ * Advanced Debug module for Blue Bird.
+ * Provides metrics history, route statistics and live monitoring.
+ */
+class Debug {
+
+    constructor() {
+        this.router = new Router("/debug");
+        this.limit = 50;
+        this.initStore();
+        this.registerRoutes();
+    }
+
+    initStore() {
+        if (!global.__bluebird_debug_store__) {
+            global.__bluebird_debug_store__ = {
+                requests: [],
+                routes: {},
+                errors4xx: 0,
+                errors5xx: 0
+            };
+        }
+    }
+
+    static shouldTrack(req) {
+        const url = req.originalUrl || "";
+
+        if (url.startsWith("/debug")) return false;
+
+        if (/\.(json|css|js|map|png|jpg|jpeg|gif|svg|ico|webp)$/i.test(url)) {
+            return false;
+        }
+
+        if (req.method === "OPTIONS") return false;
+
+        return true;
+    }
+
+    static middlewareMetrics(app) {
+        app.use((req, res, next) => {
+
+            if (!Debug.shouldTrack(req)) return next();
+
+            const start = process.hrtime();
+
+            res.on("finish", () => {
+
+                const diff = process.hrtime(start);
+                const responseTime = diff[0] * 1e3 + diff[1] / 1e6;
+
+                const memory = process.memoryUsage();
+                const ramUsedMB = memory.rss / 1024 / 1024;
+
+                const cpuUsage = process.cpuUsage();
+                const cpuUsedMS = (cpuUsage.user + cpuUsage.system) / 1000;
+
+                const record = {
+                    method: req.method,
+                    url: req.originalUrl,
+                    status: res.statusCode,
+                    responseTime: Number(responseTime.toFixed(2)),
+                    ramUsedMB: Number(ramUsedMB.toFixed(2)),
+                    cpuUsedMS: Number(cpuUsedMS.toFixed(2)),
+                    date: new Date().toISOString()
+                };
+
+                const store = global.__bluebird_debug_store__;
+
+                store.requests.unshift(record);
+                if (store.requests.length > 50) store.requests.pop();
+
+                const routeKey = `${req.method} ${req.route?.path || req.path}`;
+
+                if (!store.routes[routeKey]) {
+                    store.routes[routeKey] = {
+                        count: 0,
+                        totalTime: 0
+                    };
+                }
+
+                store.routes[routeKey].count += 1;
+                store.routes[routeKey].totalTime += record.responseTime;
+
+                if (record.status >= 400 && record.status < 500) store.errors4xx++;
+                if (record.status >= 500) store.errors5xx++;
+            });
+
+            next();
+        });
+    }
+
+    registerRoutes() {
+
+        this.router.get("/", (req, res) => {
+
+            const store = global.__bluebird_debug_store__;
+
+            if (req.query.fetch === "true") {
+                return res.json(store);
+            }
+
+            if (req.query.reset === "true") {
+                global.__bluebird_debug_store__ = {
+                    requests: [],
+                    routes: {},
+                    errors4xx: 0,
+                    errors5xx: 0
+                };
+                return res.json({ ok: true });
+            }
+
+            res.send(`
+<!DOCTYPE html>
+<html>
+<head>
+<script src="https://cdn.tailwindcss.com"></script>
+<title>Blue Bird Debug</title>
+</head>
+<body class="bg-gray-100 text-gray-800 p-10">
+
+<div class="max-w-7xl mx-auto">
+
+<div class="flex justify-between items-center mb-8">
+<h1 class="text-3xl font-bold text-blue-600">Blue Bird Debug Panel</h1>
+<button onclick="resetData()" class="bg-red-500 hover:bg-red-600 text-white px-4 py-2 rounded-lg shadow">
+Reset
+</button>
+</div>
+
+<div class="grid grid-cols-3 gap-6 mb-8">
+
+<div class="bg-white p-6 rounded-xl shadow">
+<h3 class="text-gray-500 text-sm">Total Requests</h3>
+<p id="totalReq" class="text-2xl font-bold">0</p>
+</div>
+
+<div class="bg-yellow-100 p-6 rounded-xl shadow">
+<h3 class="text-yellow-600 text-sm">4xx Errors</h3>
+<p id="err4" class="text-2xl font-bold text-yellow-700">0</p>
+</div>
+
+<div class="bg-red-100 p-6 rounded-xl shadow">
+<h3 class="text-red-600 text-sm">5xx Errors</h3>
+<p id="err5" class="text-2xl font-bold text-red-700">0</p>
+</div>
+
+</div>
+
+<div class="grid grid-cols-2 gap-10">
+
+<div class="bg-white p-6 rounded-xl shadow">
+<h2 class="text-lg font-semibold mb-4">Route Stats</h2>
+<table class="table-fixed w-full text-sm">
+<thead>
+<tr class="border-b">
+<th class="text-left w-1/2 py-2">Route</th>
+<th class="text-left w-1/4">Hits</th>
+<th class="text-left w-1/4">Avg Time</th>
+</tr>
+</thead>
+<tbody id="routesBody"></tbody>
+</table>
+</div>
+
+<div class="bg-white p-6 rounded-xl shadow">
+<h2 class="text-lg font-semibold mb-4">Last Requests</h2>
+<table class="table-fixed w-full text-sm">
+<thead>
+<tr class="border-b">
+<th class="text-left w-1/2 py-2">URL</th>
+<th class="text-left w-1/6">Method</th>
+<th class="text-left w-1/6">Status</th>
+<th class="text-left w-1/6">Time</th>
+</tr>
+</thead>
+<tbody id="historyBody"></tbody>
+</table>
+</div>
+
+</div>
+
+</div>
+
+<script>
+async function loadData() {
+    const res = await fetch('/debug?fetch=true');
+    const data = await res.json();
+
+    document.getElementById("totalReq").innerText = data.requests.length;
+    document.getElementById("err4").innerText = data.errors4xx;
+    document.getElementById("err5").innerText = data.errors5xx;
+
+    const routesBody = document.getElementById("routesBody");
+    const historyBody = document.getElementById("historyBody");
+
+    routesBody.innerHTML = "";
+    historyBody.innerHTML = "";
+
+    Object.entries(data.routes).forEach(([key, value]) => {
+        const avg = (value.totalTime / value.count).toFixed(2);
+        let color = "";
+        if (avg > 500) color = "text-red-600 font-semibold";
+        else if (avg > 200) color = "text-yellow-600";
+
+        routesBody.innerHTML += \`
+        <tr class="border-b">
+            <td class="py-1 truncate">\${key}</td>
+            <td>\${value.count}</td>
+            <td class="\${color}">\${avg} ms</td>
+        </tr>\`;
+    });
+
+    data.requests.forEach(r => {
+        historyBody.innerHTML += \`
+        <tr class="border-b text-xs">
+            <td class="truncate">\${r.url}</td>
+            <td>\${r.method}</td>
+            <td>\${r.status}</td>
+            <td>\${r.responseTime} ms</td>
+        </tr>\`;
+    });
+}
+
+async function resetData() {
+    await fetch('/debug?reset=true');
+    loadData();
+}
+
+loadData();
+setInterval(loadData, 3000);
+</script>
+
+</body>
+</html>
+            `);
+        });
+    }
+
+    getRouter() {
+        return {
+            path: this.router.getPath(),
+            router: this.router.getRouter()
+        };
+    }
+}
+
+export default Debug;

package/core/swagger.js

@@ -0,0 +1,25 @@
+import swaggerUi from "swagger-ui-express";
+import swaggerJSDoc from "swagger-jsdoc";
+
+class Swagger {
+
+    static init(app, options) {
+
+        const optionsJsDoc = {
+            definition: {
+                openapi: "3.0.0",
+                info: options.info,
+                servers: [
+                    { url: options.url }
+                ]
+            },
+            apis: ["./backend/routes/*.js"]
+        };
+
+        const specs = swaggerJSDoc(optionsJsDoc);
+
+        app.use("/docs", swaggerUi.serve, swaggerUi.setup(specs));
+    }
+}
+
+export default Swagger;

package/core/validate.js

@@ -255,8 +255,7 @@ class Validator {
                 success: false,
                 error: true,
                 errors: errors,
-                message: messages,
-                html: messages.map(e => `<p class="text-red-500 text-danger">${e}</p>`)
+                message: messages 
             };
         }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seip/blue-bird",
- "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Express + React opinionated framework with SPA or API architecture and built-in JWT auth",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
   "keywords": [
     "express",
     "react",
-    "framework", 
+    "framework",
     "vite"
   ],
   "author": "Seip25",
@@ -34,9 +34,14 @@
   "dependencies": {
     "chalk": "^5.6.2",
     "cookie-parser": "^1.4.7",
-    "cors": "^2.8.6", 
+    "cors": "^2.8.6",
     "express": "^5.2.1",
+    "express-rate-limit": "^8.2.1",
+    "helmet": "^8.1.0",
     "jsonwebtoken": "^9.0.2",
-    "multer": "^2.0.2"
+    "multer": "^2.0.2",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1",
+    "xss": "^1.0.15"
   }
-}
+}