@seip/blue-bird 0.1.7 → 0.2.0

package/core/app.js

@@ -27,6 +27,23 @@ 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.
+     * @example 
+     * const app = new App({
+     *     routes: [],
+     *     cors: {},
+     *     middlewares: [],
+     *     port: 3000,
+     *     host: "http://localhost",
+     *     logger: true,
+     *     notFound: true,
+     *     json: true,
+     *     urlencoded: true,
+     *     static: {
+     *         path: "public",
+     *         options: {}
+     *     },
+     *     cookieParser: true,
+     * });
      */
     constructor(options = {
         routes: [],
@@ -64,10 +81,25 @@ class App {
     /**
      * Registers a custom middleware or module in the Express application.
      * @param {Function|import('express').Router} record - The middleware function or Express router to register.
+     * @example
+     * app.use((req, res, next) => {
+     *     console.log("Middleware");
+     *     next();
+     * });
      */
     use(record) {
         this.app.use(record)
     }
+    /**
+     * Sets a configuration value in the Express application.
+     * @param {string} key - The configuration key.
+     * @param {*} value - The value to set for the configuration key.
+     * @example
+     * app.set("port", 3000);
+     */
+    set(key, value) {
+        this.app.set(key, value)
+    }
 
     /**
      * Bootstraps the application by configuring global middlewares and routes.

package/core/auth.js

@@ -10,6 +10,10 @@ class Auth {
      * @param {string} [secret=process.env.JWT_SECRET] - The secret key.
      * @param {string|number} [expiresIn='24h'] - Expiration time.
      * @returns {string} The generated token.
+     * @example
+     * const token = Auth.generateToken({ id: 1 });
+     * console.log(token);
+     * 
      */
     static generateToken(payload, secret = process.env.JWT_SECRET || 'blue-bird-secret', expiresIn = '24h') {
         return jwt.sign(payload, secret, { expiresIn });
@@ -20,6 +24,10 @@ class Auth {
      * @param {string} token - The token to verify.
      * @param {string} [secret=process.env.JWT_SECRET] - The secret key.
      * @returns {Object|null} The decoded payload or null if invalid.
+     * @example
+     * const token = Auth.generateToken({ id: 1 });
+     * const decoded = Auth.verifyToken(token);
+     * console.log(decoded);
      */
     static verifyToken(token, secret = process.env.JWT_SECRET || 'blue-bird-secret') {
         try {
@@ -34,6 +42,8 @@ class Auth {
      * @param {Object} options - Options for protection.
      * @param {string} [options.redirect] - URL to redirect if not authenticated (for web routes).
      * @returns {Function} Express middleware.
+     * @example
+     * app.use(Auth.protect({ redirect: "/login" }));
      */
     static protect(options = { redirect: null }) {
         return (req, res, next) => {

package/core/cli/component.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+import fs from "node:fs";
+import Config from "../config.js"; 
+
+const __dirname = Config.dirname();
+
+class ComponentCLI {
+  /**
+   * Create component react
+   * @return {void}
+   * /
+   */
+
+  create() {
+    const folder = path.join(process.cwd(), "frontend/resources/components");
+    if (!fs.existsSync(folder)) {
+      fs.mkdirSync(folder, { recursive: true });
+    }
+    let nameComponent =`Component-${Math.random().toString(36).substring(7)}`;
+    const nameParam = process.argv[2];
+    if (nameParam.length > 0 && typeof nameParam === "string") {
+        nameComponent = nameParam;
+        nameComponent = nameComponent.charAt(0).toUpperCase() + nameComponent.slice(1);
+    }
+    const filePath = path.join(folder, `${nameComponent}.jsx`);
+    const content = `import React from 'react';
+        
+export default function ${nameComponent}() {
+    return (
+        <div>
+            <h1>${nameComponent} Component</h1>
+        </div>
+    );
+}
+        `;
+    fs.writeFileSync(filePath, content);
+    console.log(`Component ${nameComponent} created at ${filePath}`);
+  }
+}
+
+const componentCLI = new ComponentCLI();
+componentCLI.create();

package/core/cli/route.js

@@ -0,0 +1,43 @@
+import path from 'path';
+import fs from 'fs';
+import Config from "../config.js";
+
+const __dirname = Config.dirname();
+
+class RouteCLI {
+  /**
+   * Create route 
+   */
+    create() {
+        let nameRoute = process.argv[2];
+        if (!nameRoute) {
+            console.log("Please provide a route name. Usage: npm run route <route-name>");
+            return;
+        }
+        nameRoute =nameRoute.charAt(0).toUpperCase() + nameRoute.slice(1);
+        const folder= path.join(__dirname, 'backend/routes');
+        if (!fs.existsSync(folder)){
+            fs.mkdirSync(folder, { recursive: true });
+        }
+        const filePath = path.join(folder, `${nameRoute}.js`);
+        if (fs.existsSync(filePath)) {
+            console.log(`Route ${nameRoute} already exists.`);
+            return;
+        }
+        const content =`import Router from "@seip/blue-bird/core/router.js" 
+
+const router${nameRoute} = new Router("/${nameRoute.toLowerCase()}");
+
+router${nameRoute}.get("/", (req, res) => {
+    res.json({ message: "Hello from ${nameRoute} route!" });
+});
+
+export default router${nameRoute};
+        `;
+        fs.writeFileSync(filePath, content);
+        console.log(`Route ${nameRoute} created successfully at ${filePath}`);
+    }
+}
+
+const routeCLI = new RouteCLI();
+routeCLI.create()

package/core/router.js

@@ -11,6 +11,11 @@ class Router {
     /**
      * Creates a new Router instance.
      * @param {string} [path="/"] - The base path for this router.
+     * @example
+     * const router = new Router("/api")
+     * router.get("/", (req, res) => {
+     *     res.json({ message: "Hello World!" })
+     * })
      */
     constructor(path = "/") {
         this.router = express.Router()
@@ -21,6 +26,20 @@ class Router {
      * Registers a GET route handler.
      * @param {string} path - The relative path for the GET route.
      * @param {...Function} callback - One or more handler functions (middlewares and controller).
+     * @example
+     * router.get("/users", (req, res) => {
+     *     const users = [
+     *         {
+     *             name: "John Doe",
+     *             email: "john.doe@example.com",
+     *         },
+     *         {
+     *             name: "Jane Doe2",
+     *             email: "jane.doe2@example.com",
+     *         },
+     *     ]
+     *     res.json(users)
+     * })
      */
     get(path, ...callback) {
         if (path === "/*" || path === "*") {
@@ -33,6 +52,10 @@ class Router {
      * Registers a POST route handler.
      * @param {string} path - The relative path for the POST route.
      * @param {...Function} callback - One or more handler functions (middlewares and controller).
+     * @example
+     * router.post("/users", (req, res) => {
+     *  return res.json({ message: "User created successfully" })
+     * })
      */
     post(path, ...callback) {
         if (path === "/*" || path === "*") {
@@ -45,6 +68,10 @@ class Router {
      * Registers a PUT route handler.
      * @param {string} path - The relative path for the PUT route.
      * @param {...Function} callback - One or more handler functions (middlewares and controller).
+     * @example
+     * router.put("/users", (req, res) => {
+     *  return res.json({ message: "User updated successfully" })
+     * })
      */
     put(path, ...callback) {
         this.router.put(path, callback)
@@ -54,6 +81,10 @@ class Router {
      * Registers a DELETE route handler.
      * @param {string} path - The relative path for the DELETE route.
      * @param {...Function} callback - One or more handler functions (middlewares and controller).
+     * @example
+     * router.delete("/users", (req, res) => {
+     *  return res.json({ message: "User deleted successfully" })
+     * })
      */
     delete(path, ...callback) {
         this.router.delete(path, callback)
@@ -63,6 +94,10 @@ class Router {
      * Registers a PATCH route handler.
      * @param {string} path - The relative path for the PATCH route.
      * @param {...Function} callback - One or more handler functions (middlewares and controller).
+     * @example
+     * router.patch("/users", (req, res) => {
+     *  return res.json({ message: "User patched successfully" })
+     * })
      */
     patch(path, ...callback) {
         this.router.patch(path, callback)
@@ -72,6 +107,10 @@ class Router {
      * Registers an OPTIONS route handler.
      * @param {string} path - The relative path for the OPTIONS route.
      * @param {...Function} callback - One or more handler functions (middlewares and controller).
+     * @example
+     * router.options("/users", (req, res) => {
+     *  return res.json({ message: "User options successfully" })
+     * })
      */
     options(path, ...callback) {
         this.router.options(path, callback)

package/core/template.js

@@ -74,22 +74,44 @@ class Template {
      * Renders a React component as an HTML string.
      * @param {string} component - The React component name.
      * @param {Object} [componentProps={}] - Props to pass to the component.
-     * @param {string} [classBody=""] - Class name to add to the body tag.
-     * @param {Array<Object>} [optionsHead=[]] - Array of objects with tag and attributes for head tags.
+     * @options {Object} options - Options for the template.
      * @returns {string} The HTML string of the React component.
+     * @example
+     * const options = {
+     *     head: [
+     *         { tag: "meta", attrs: { name: "description", content: "Description" } },
+     *         { tag: "link", attrs: { rel: "stylesheet", href: "style.css" } }
+     *     ],
+     *     classBody: "bg-gray-100",
+     *     linkStyles: [
+     *         { href: "style.css" }
+     *     ],
+     *     scriptScripts: [
+     *         { src: "script.js" }
+     *     ]
+     * };
+     * 
+     * Template.renderReact(res, "App", { title: "Example title" }, options);
      */
-    static renderReact(res, component = "App", propsReact = {}, classBody = "", optionsHead = []) {
+    static renderReact(res, component = "App", propsReact = {}, options = {}) {
+        const optionsHead = options.head || [];
+        const classBody = options.classBody || "";
+        const linkStyles = options.linkStyles || [];
+        const scriptScripts = options.scriptScripts || [];
         const html = `
 <!DOCTYPE html>
-<html lang="${props.langMeta}">
+<html lang="${this.escapeHtml(props.langMeta)}">
 <head>
     <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>${props.titleMeta}</title>
-    <meta name="description" content="${props.descriptionMeta}">
-    <meta name="keywords" content="${props.keywordsMeta}">
-    <meta name="author" content="${props.authorMeta}">
-    ${optionsHead.map(item => `<${item.tag} ${Object.entries(item.attrs).map(([key, value]) => `${key}="${value}"`).join(" ")}></${item.tag}>`).join("")}
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${this.escapeHtml(props.titleMeta)}</title>
+    <link rel="icon" href="favicon.ico" />
+    <meta name="description" content="${this.escapeHtml(props.descriptionMeta)}"/>
+    <meta name="keywords" content="${this.escapeHtml(props.keywordsMeta)}"/>
+    <meta name="author" content="${this.escapeHtml(props.authorMeta)}"/>
+    ${linkStyles.map(item => `<link rel="stylesheet" href="${item.href}" />`).join("")}
+    ${scriptScripts.map(item => `<script src="${item.src}"></script>`).join("")}
+    ${optionsHead.map(item => `<${item.tag} ${Object.entries(item.attrs).map(([key, value]) => `${key}="${value}"`).join(" ")} />`).join("")}
 </head>
 <body class="${classBody}">
     ${this.react(component, propsReact)}
@@ -99,7 +121,6 @@ class Template {
         `
         res.type("text/html");
         res.status(200);
-        res.setHeader("Content-Type", "text/html");
         return res.send(this.minifyHtml(html));
     }
 
@@ -109,8 +130,8 @@ class Template {
      * @param {Object} [componentProps={}] - Props to pass to the component.
      * @returns {string} The HTML container with data attributes for hydration.
      */
-    static react(component, componentProps = {}) {
-        const id = `react-${Math.random().toString(36).substr(2, 9)}`;
+    static react(component, componentProps = {}, divId = "root") {
+        const id = divId || `react-${Math.random().toString(36).substr(2, 9)}`;
         const propsJson = JSON.stringify(componentProps).replace(/'/g, "&apos;");
         return `<div id="${id}" data-react-component="${component}" data-props='${propsJson}'></div>`;
     }
@@ -151,10 +172,12 @@ class Template {
                     const file = entry.file;
                     const css = entry.css || [];
 
-                    let html = `<script type="module" src="/build/${file}"></script>`;
+                    let html = "";
                     css.forEach(cssFile => {
                         html += `<link rel="stylesheet" href="/build/${cssFile}">`;
                     });
+                    html += `<script type="module" src="/build/${file}"></script>`;
+
                     return html;
                 }
             } catch (e) {
@@ -165,46 +188,7 @@ class Template {
         return `<!-- Vite Manifest not found at ${manifestPath} -->`;
     }
 
-    /**
-     * Renders a full HTML page with a React component as the main entry point.
-     * Useful for SPAs or full-page React modules.
-     * @param {import('express').Response} res - The Express response object.
-     * @param {string} component - The React component name.
-     * @param {Object} [componentProps={}] - Props to pass to the React component.
-     * @param {Object} [metaOverrides={}] - Metadata overrides (title, description, keywords, etc.).
-     */
-    static reactRender(res, component, componentProps = {}, metaOverrides = {}) {
-        const meta = {
-            title: props.titleMeta,
-            description: props.descriptionMeta,
-            keywords: props.keywordsMeta,
-            author: props.authorMeta,
-            lang: props.langMeta,
-            ...metaOverrides
-        };
-
-        const scriptsReact = this.vite_assets();
-        const componentHtml = this.react(component, componentProps);
 
-        const html = `
-<!DOCTYPE html>
-<html lang="${meta.lang}">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>${meta.title}</title>
-    <meta name="description" content="${meta.description}">
-    <meta name="keywords" content="${meta.keywords}">
-    <meta name="author" content="${meta.author}">
-    ${scriptsReact}
-</head>
-<body>
-    ${componentHtml}
-</body>
-</html>`;
-
-        res.send(this.minifyHtml(html));
-    }
 
     /**
      * Minifies the HTML output by removing comments and excessive whitespace.
@@ -218,6 +202,19 @@ class Template {
             .replace(/\s{2,}/g, " ")
             .trim();
     }
+    /**
+    * Escapes HTML special characters in a string to prevent XSS attacks.
+    * @param {string} str - The input string.
+    * @returns {string} The escaped string.
+    */
+    static escapeHtml(str = "") {
+        return String(str)
+            .replace(/&/g, "&amp;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;")
+            .replace(/"/g, "&quot;")
+            .replace(/'/g, "&#39;");
+    }
 }
 
 export default Template;

package/core/upload.js

@@ -14,6 +14,8 @@ class Upload {
      * Configures storage for uploaded files.
      * @param {string} folder - The destination folder within the static path.
      * @returns {import('multer').StorageEngine}
+     * @example
+     * const storage = Upload.storage("uploads");
      */
     static storage(folder = "uploads") {
         const dest = path.join(__dirname, props.static.path, folder);
@@ -40,6 +42,8 @@ class Upload {
      * @param {number} [options.fileSize=5000000] - Max file size in bytes (default 5MB).
      * @param {Array<string>} [options.allowedTypes=[]] - Allowed mime types (e.g. ['image/png', 'image/jpeg']).
      * @returns {import('multer').Multer}
+     * @example
+     * const upload = Upload.disk({ folder: "uploads", fileSize: 5000000, allowedTypes: ["image/png", "image/jpeg"] });
      */
     static disk(options = {}) {
         const { folder = "uploads", fileSize = 5000000, allowedTypes = [] } = options;
@@ -61,6 +65,8 @@ class Upload {
      * @param {string} filename - The name of the file.
      * @param {string} [folder='uploads'] - The folder where the file is stored.
      * @returns {string} The full public URL.
+     * @example
+     * const url = Upload.url("file.jpg", "uploads");
      */
     static url(filename, folder = "uploads") {
         return `${props.host}:${props.port}/public/${folder}/${filename}`;

package/core/validate.js

@@ -128,6 +128,13 @@ class Validator {
      * Validates the request body against the defined schema.
      * @param {import('express').Request} req - The Express request object containing the body to validate.
      * @returns {Promise<{success: boolean, error: boolean, errors: Array<{field: string, message: string}>, message: Array<string>, html: Array<string>}>} Validation results.
+     * @example 
+     * const loginSchema = {
+     *     email: { required: true, email: true },
+     *     password: { required: true, min: 6 }
+     * };
+     * const loginValidator = new Validator(loginSchema, 'es');
+     * const result = await loginValidator.validate(req);
      */
     async validate(req) {
         const lang = this.lang_default ? this.lang_default : req?.session?.lang || "es";
@@ -260,6 +267,16 @@ class Validator {
      * Express middleware for automated validation of the request body.
      * Returns a 400 Bad Request response with validation results if errors occur.
      * @returns {Function} Express middleware function (req, res, next).
+     * @example
+     * 
+     * const loginSchema = {
+     *     email: { required: true, email: true },
+     *     password: { required: true, min: 6 }
+     * };
+     * const loginValidator = new Validator(loginSchema, 'es');
+     * routerUsers.post('/login', loginValidator.middleware(), (req, res) => {
+     *     res.json({ message: 'Login successful' });
+     * });
      */
     middleware() {
         return async (req, res, next) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seip/blue-bird",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Express + React opinionated framework with island architecture and built-in JWT auth",
   "type": "module",
   "bin": {
@@ -28,6 +28,8 @@
     "start": "node --env-file=.env backend/index.js",
     "create-react-app": "node core/cli/react.js",
     "react": "node core/cli/react.js",
+    "component": "node core/cli/component.js",
+    "route": "node core/cli/route.js",
     "init": "node core/cli/init.js"
   },
   "dependencies": {
@@ -39,4 +41,4 @@
     "jsonwebtoken": "^9.0.2",
     "multer": "^2.0.2"
   }
-}
+}