@nitronjs/framework 0.2.3 → 0.2.5

package/lib/Database/Schema/Manager.js

@@ -1,103 +1,66 @@
-import DatabaseManager from "../Manager.js";
+import DB from "../DB.js";
 import Config from "../../Core/Config.js";
 
 export default class Schema {
 
+    // Public Methods
     static async create(tableName, callback) {
         const blueprint = new (await import('./Blueprint.js')).default(tableName);
         callback(blueprint);
-
-        const sql = this.#buildCreateTableSQL(blueprint, false);
-
-        const connection = DatabaseManager.getInstance().connection();
-        await connection.raw(sql);
+        await DB.rawQuery(this.#buildCreateSQL(blueprint, false));
     }
 
     static async createIfNotExists(tableName, callback) {
         const blueprint = new (await import('./Blueprint.js')).default(tableName);
         callback(blueprint);
-
-        const sql = this.#buildCreateTableSQL(blueprint, true);
-
-        const connection = DatabaseManager.getInstance().connection();
-        await connection.raw(sql);
+        await DB.rawQuery(this.#buildCreateSQL(blueprint, true));
     }
 
     static async dropIfExists(tableName) {
-        const connection = DatabaseManager.getInstance().connection();
-        await connection.raw(`DROP TABLE IF EXISTS \`${tableName}\``);
+        await DB.rawQuery(`DROP TABLE IF EXISTS \`${tableName}\``);
     }
 
-    static #buildCreateTableSQL(blueprint, ifNotExists = false) {
-        const columns = blueprint.getColumns();
-        const columnsSql = columns.map(col => this.#buildColumnSQL(col));
-
-        const manager = DatabaseManager.getInstance();
-        const connection = manager.connection();
-        const connectionName = connection.getName();
-        const databaseConfig = Config.all('database');
-        const dbConfig = databaseConfig.connections[connectionName];
+    // Private Methods
+    static #buildCreateSQL(blueprint, ifNotExists = false) {
+        const columns = blueprint.getColumns().map(col => this.#buildColumnSQL(col));
+        const dbConfig = Config.all('database').connections.mysql;
 
         const charset = dbConfig.charset || 'utf8mb4';
         const collation = dbConfig.collation || 'utf8mb4_unicode_ci';
-
         const ifNotExistsClause = ifNotExists ? 'IF NOT EXISTS ' : '';
-        let sql = `CREATE TABLE ${ifNotExistsClause}\`${blueprint.getTableName()}\` (\n`;
-        sql += '    ' + columnsSql.join(',\n    ');
-        sql += `\n) ENGINE=InnoDB DEFAULT CHARSET=${charset} COLLATE=${collation}`;
 
-        return sql;
+        return `CREATE TABLE ${ifNotExistsClause}\`${blueprint.getTableName()}\` (\n    ${columns.join(',\n    ')}\n) ENGINE=InnoDB DEFAULT CHARSET=${charset} COLLATE=${collation}`;
     }
 
     static #buildColumnSQL(column) {
-        let sql = `\`${column.name}\` `;
-
-        switch (column.type) {
-            case 'id':
-                sql += 'BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY';
-                return sql;
-            case 'string':
-                sql += `VARCHAR(${column.length || 255})`;
-                break;
-            case 'text':
-                sql += 'TEXT';
-                break;
-            case 'integer':
-                sql += 'INT';
-                break;
-            case 'bigInteger':
-                sql += 'BIGINT';
-                break;
-            case 'boolean':
-                sql += 'TINYINT(1)';
-                break;
-            case 'timestamp':
-                sql += 'TIMESTAMP';
-                break;
-            case 'json':
-                sql += 'JSON';
-                break;
-            default:
-                throw new Error(`Unknown column type: ${column.type}`);
+        if (column.type === 'id') {
+            return `\`${column.name}\` BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY`;
         }
 
-        if (column.modifiers) {
-            if (column.modifiers.nullable) {
-                sql += ' NULL';
-            } else {
-                sql += ' NOT NULL';
-            }
+        const typeMap = {
+            string: `VARCHAR(${column.length || 255})`,
+            text: 'TEXT',
+            integer: 'INT',
+            bigInteger: 'BIGINT',
+            boolean: 'TINYINT(1)',
+            timestamp: 'TIMESTAMP',
+            json: 'JSON'
+        };
+
+        const type = typeMap[column.type];
+        if (!type) throw new Error(`Unknown column type: ${column.type}`);
+
+        let sql = `\`${column.name}\` ${type}`;
 
+        if (column.modifiers) {
+            sql += column.modifiers.nullable ? ' NULL' : ' NOT NULL';
             if (column.modifiers.default !== null) {
-                const defaultValue = typeof column.modifiers.default === 'string'
+                const val = typeof column.modifiers.default === 'string'
                     ? `'${column.modifiers.default}'`
                     : column.modifiers.default;
-                sql += ` DEFAULT ${defaultValue}`;
-            }
-
-            if (column.modifiers.unique) {
-                sql += ' UNIQUE';
+                sql += ` DEFAULT ${val}`;
             }
+            if (column.modifiers.unique) sql += ' UNIQUE';
         }
 
         return sql;

package/lib/Database/Seeder/SeederRunner.js

@@ -2,80 +2,61 @@ import fs from 'fs';
 import path from 'path';
 import { pathToFileURL } from 'url';
 import Paths from '../../Core/Paths.js';
-
-const COLORS = {
-    reset: '\x1b[0m',
-    red: '\x1b[31m',
-    green: '\x1b[32m',
-    yellow: '\x1b[33m',
-    cyan: '\x1b[36m',
-    dim: '\x1b[2m',
-    bold: '\x1b[1m'
-};
+import Output from '../../Console/Output.js';
 
 class SeederRunner {
-
     static async run(seederName = null) {
         const seedersDir = Paths.seeders;
 
         if (!fs.existsSync(seedersDir)) {
-            console.log(`${COLORS.yellow}⚠️  No seeders directory found${COLORS.reset}`);
+            Output.warn("No seeders directory found");
             return { success: true, ran: [] };
         }
 
-        let files = fs.readdirSync(seedersDir)
-            .filter(f => f.endsWith('.js'))
-            .sort();
+        let files = fs.readdirSync(seedersDir).filter(f => f.endsWith('.js')).sort();
 
         if (files.length === 0) {
-            console.log(`${COLORS.yellow}⚠️  No seeder files found${COLORS.reset}`);
+            Output.warn("No seeder files found");
             return { success: true, ran: [] };
         }
 
-        // If specific seeder name provided, filter to only that one
         if (seederName) {
             const targetFile = seederName.endsWith('.js') ? seederName : `${seederName}.js`;
             files = files.filter(f => f === targetFile);
-            
             if (files.length === 0) {
-                console.log(`${COLORS.red}❌ Seeder not found: ${seederName}${COLORS.reset}`);
+                Output.error(`Seeder not found: ${seederName}`);
                 return { success: false, ran: [], error: new Error(`Seeder not found: ${seederName}`) };
             }
         }
 
-        console.log(`${COLORS.cyan}🌱 Running seeders${COLORS.reset}\n`);
+        Output.seederHeader();
 
         const executed = [];
 
         try {
             for (const file of files) {
-                const filePath = path.join(seedersDir, file);
-                const fileUrl = pathToFileURL(filePath).href;
-
-                console.log(`${COLORS.dim}Seeding:${COLORS.reset} ${COLORS.cyan}${file}${COLORS.reset}`);
+                const fileUrl = pathToFileURL(path.join(seedersDir, file)).href;
+                Output.pending("Seeding", file);
 
                 const { default: seeder } = await import(`${fileUrl}?t=${Date.now()}`);
-
                 if (typeof seeder.run !== 'function') {
                     throw new Error(`Seeder ${file} does not have a run() method`);
                 }
 
                 await seeder.run();
                 executed.push(file);
-
-                console.log(`${COLORS.green}✅ Seeded:${COLORS.reset}  ${COLORS.cyan}${file}${COLORS.reset}\n`);
+                Output.done("Seeded", file);
             }
 
-            console.log(`${COLORS.green}${COLORS.bold}✅ All seeders completed successfully.${COLORS.reset}`);
+            Output.seederSuccess();
             return { success: true, ran: executed };
-
         }
         catch (error) {
-            console.error(`\n${COLORS.red}❌ Seeding failed: ${error.message}${COLORS.reset}`);
+            Output.newline();
+            Output.error(`Seeding failed: ${error.message}`);
             return { success: false, ran: executed, error };
         }
     }
-
 }
 
 export default SeederRunner;

package/lib/Date/DateTime.js

@@ -1,6 +1,15 @@
 import locale from './Locale.js';
 import Config from '../Core/Config.js';
 
+/**
+ * Date and time utility with timezone and localization support.
+ * Uses config/app.js timezone and locale settings.
+ * 
+ * @example
+ * DateTime.toSQL();           // "2025-01-15 10:30:00"
+ * DateTime.addDays(7);        // 7 days from now
+ * DateTime.diffForHumans(ts); // "2 hours ago"
+ */
 class DateTime {
     static #getDate(date = null) {
         const timezone = Config.get('app.timezone', 'UTC');

package/lib/Encryption/Encryption.js

@@ -0,0 +1,52 @@
+import crypto from "crypto";
+
+/**
+ * AES-256-CBC encryption and decryption utility.
+ * Uses APP_KEY from environment for secure encryption.
+ */
+class Encryption {
+    /**
+     * Encrypts a value using AES-256-CBC.
+     * @param {string|Object} value - Value to encrypt (objects are JSON stringified)
+     * @returns {string} Encrypted string in format "iv:encryptedData"
+     */
+    static encrypt(value) {
+        if (typeof value === "object") {
+            value = JSON.stringify(value);
+        }
+
+        const secretKey = crypto.createHash("sha256").update(process.env.APP_KEY).digest();
+        const iv = crypto.randomBytes(16);
+        const cipher = crypto.createCipheriv("aes-256-cbc", secretKey, iv);
+
+        let encrypted = cipher.update(value, "utf8", "hex");
+        encrypted += cipher.final("hex");
+
+        return iv.toString("hex") + ":" + encrypted;
+    }
+
+    /**
+     * Decrypts an AES-256-CBC encrypted value.
+     * @param {string} encryptedValue - Encrypted string in format "iv:encryptedData"
+     * @returns {string|false} Decrypted string or false if decryption fails
+     */
+    static decrypt(encryptedValue) {
+        try {
+            const parts = encryptedValue.split(":");
+            const iv = Buffer.from(parts.shift(), "hex");
+            const encryptedText = Buffer.from(parts.join(":"), "hex");
+            const secretKey = crypto.createHash("sha256").update(process.env.APP_KEY).digest();
+            const decipher = crypto.createDecipheriv("aes-256-cbc", secretKey, iv);
+
+            let decrypted = decipher.update(encryptedText, "hex", "utf8");
+            decrypted += decipher.final("utf8");
+
+            return decrypted;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+
+export default Encryption;

package/lib/Faker/Faker.js

@@ -8,6 +8,17 @@ import * as ColorData from './Data/Color.js';
 import * as DateData from './Data/Date.js';
 import * as PhoneData from './Data/Phone.js';
 
+/**
+ * Fake data generator for testing and seeding.
+ * Generates unique values by default to prevent duplicates.
+ * 
+ * @example
+ * import { Faker } from "@nitronjs/framework";
+ * 
+ * const name = Faker.fullName();
+ * const email = Faker.email();
+ * const phone = Faker.phoneNumber();
+ */
 class FakerClass {
 
     #usedValues = new Map();

package/lib/Filesystem/Storage.js

@@ -0,0 +1,120 @@
+import fs from "node:fs";
+import path from "node:path";
+import Paths from "../Core/Paths.js";
+
+/**
+ * File storage manager for public and private file operations.
+ * Includes security measures against directory traversal attacks.
+ */
+class Storage {
+    static #publicRoot = Paths.storagePublic;
+    static #privateRoot = Paths.storagePrivate;
+
+    /**
+     * Reads a file from storage.
+     * @param {string} filePath - Relative path to the file
+     * @param {boolean} isPrivate - Whether to read from private storage
+     * @returns {Promise<Buffer|null>} File contents or null if not found
+     */
+    static async get(filePath, isPrivate = false) {
+        const base = isPrivate ? this.#privateRoot : this.#publicRoot;
+
+        try {
+            const fullPath = this.#validatePath(base, filePath);
+
+            return await fs.promises.readFile(fullPath);
+        }
+        catch (err) {
+            if (err.message.includes("directory traversal")) {
+                throw err;
+            }
+
+            return null;
+        }
+    }
+
+    /**
+     * Saves a file to storage.
+     * @param {Object} file - File object with _buf property containing file data
+     * @param {string} dir - Directory path within storage
+     * @param {string} fileName - Name for the saved file
+     * @param {boolean} isPrivate - Whether to save to private storage
+     * @returns {Promise<boolean>} True if save successful
+     */
+    static async put(file, dir, fileName, isPrivate = false) {
+        const base = isPrivate ? this.#privateRoot : this.#publicRoot;
+        const folderPath = this.#validatePath(base, dir);
+        const fullPath = this.#validatePath(base, path.join(dir, fileName));
+
+        await fs.promises.mkdir(folderPath, { recursive: true });
+        await fs.promises.writeFile(fullPath, file._buf);
+
+        return true;
+    }
+
+    /**
+     * Deletes a file from storage.
+     * @param {string} filePath - Relative path to the file
+     * @param {boolean} isPrivate - Whether to delete from private storage
+     * @returns {Promise<void>}
+     */
+    static async delete(filePath, isPrivate = false) {
+        const base = isPrivate ? this.#privateRoot : this.#publicRoot;
+        const fullPath = this.#validatePath(base, filePath);
+
+        await fs.promises.unlink(fullPath);
+    }
+
+    /**
+     * Checks if a file exists in storage.
+     * @param {string} filePath - Relative path to the file
+     * @param {boolean} isPrivate - Whether to check private storage
+     * @returns {boolean} True if file exists
+     */
+    static exists(filePath, isPrivate = false) {
+        const base = isPrivate ? this.#privateRoot : this.#publicRoot;
+
+        try {
+            const fullPath = this.#validatePath(base, filePath);
+
+            return fs.existsSync(fullPath);
+        }
+        catch {
+            return false;
+        }
+    }
+
+    /**
+     * Gets the public URL for a file in public storage.
+     * @param {string} filePath - Relative path to the file
+     * @returns {string} Public URL path
+     */
+    static url(filePath) {
+        if (filePath.startsWith("/")) {
+            filePath = filePath.substring(1);
+        }
+
+        return `/storage/${filePath}`;
+    }
+
+    /**
+     * Validates a file path to prevent directory traversal attacks.
+     * @param {string} base - Base directory path
+     * @param {string} filePath - Relative file path to validate
+     * @returns {string} Full validated path
+     * @throws {Error} If path escapes base directory
+     * @private
+     */
+    static #validatePath(base, filePath) {
+        const normalizedBase = path.normalize(base) + path.sep;
+        const fullPath = path.normalize(path.join(base, filePath));
+
+        if (!fullPath.startsWith(normalizedBase)) {
+            throw new Error("Invalid file path: directory traversal detected");
+        }
+
+        return fullPath;
+    }
+}
+
+export default Storage;

package/lib/HMR/Server.js

@@ -1,45 +1,97 @@
 import { Server as SocketServer } from "socket.io";
+import { createRequire } from "module";
 import path from "path";
+import fs from "fs";
 
+/**
+ * HMR (Hot Module Replacement) server for development mode.
+ * Manages WebSocket connections and broadcasts file change events to connected clients.
+ * 
+ * @example
+ * // In HTTP Server
+ * HMR.registerRoutes(fastify);
+ * HMR.setup(httpServer);
+ * 
+ * // Emit updates
+ * HMR.emitViewUpdate("resources/views/Site/Home.tsx");
+ * HMR.emitCss("site_style.css");
+ */
 class HMRServer {
     #io = null;
-    #ready = false;
     #connections = 0;
+    #clientScript = null;
 
+    // Public Methods
+
+    /**
+     * Registers socket.io client script route in Fastify.
+     * Must be called before Router.setup() to ensure the route is registered.
+     * @param {import("fastify").FastifyInstance} fastify
+     */
+    registerRoutes(fastify) {
+        const require = createRequire(import.meta.url);
+        const socketIoDir = path.dirname(require.resolve("socket.io/package.json"));
+
+        this.#clientScript = path.join(socketIoDir, "client-dist", "socket.io.min.js");
+
+        fastify.get("/__nitron_hmr/socket.io.js", (req, reply) => {
+            if (!this.#clientScript || !fs.existsSync(this.#clientScript)) {
+                return reply.code(404).send("Socket.io client not found");
+            }
+
+            reply.type("application/javascript").send(fs.readFileSync(this.#clientScript, "utf-8"));
+        });
+    }
+
+    /**
+     * Initializes the WebSocket server.
+     * @param {import("http").Server} httpServer - Node.js HTTP server instance.
+     */
     setup(httpServer) {
         if (this.#io) return;
 
         this.#io = new SocketServer(httpServer, {
             path: "/__nitron_hmr",
-            transports: ["websocket", "polling"],
+            transports: ["websocket"],
             cors: { origin: "*" },
             pingTimeout: 60000,
             pingInterval: 25000,
-            serveClient: true
+            serveClient: false,
+            allowEIO3: true
         });
 
         this.#io.on("connection", (socket) => {
             this.#connections++;
-            socket.on("disconnect", () => { this.#connections--; });
+            socket.on("disconnect", () => this.#connections--);
         });
-
-        this.#ready = true;
     }
 
+    /**
+     * Whether the HMR server is ready and accepting connections.
+     * @returns {boolean}
+     */
     get isReady() {
-        return this.#ready && this.#io !== null;
+        return this.#io !== null;
     }
 
+    /**
+     * Number of currently connected clients.
+     * @returns {number}
+     */
     get connectionCount() {
         return this.#connections;
     }
 
+    /**
+     * Emits a view update event to trigger hot reload of a React component.
+     * @param {string} filePath - Absolute path to the changed view file.
+     */
     emitViewUpdate(filePath) {
         if (!this.#io) return;
 
         const normalized = filePath.replace(/\\/g, "/");
-        const viewsMatch = normalized.match(/resources\/views\/(.+)\.tsx$/);
-        const viewPath = viewsMatch ? viewsMatch[1].toLowerCase() : path.basename(filePath, ".tsx").toLowerCase();
+        const match = normalized.match(/resources\/views\/(.+)\.tsx$/);
+        const viewPath = match ? match[1].toLowerCase() : path.basename(filePath, ".tsx").toLowerCase();
 
         this.#io.emit("hmr:update", {
             type: "view",
@@ -49,24 +101,40 @@ class HMRServer {
         });
     }
 
+    /**
+     * Emits a CSS update event to refresh stylesheets without page reload.
+     * @param {string} [filePath] - Path to the changed CSS file. If null, refreshes all CSS.
+     */
     emitCss(filePath) {
         if (!this.#io) return;
+
         this.#io.emit("hmr:css", {
             file: filePath ? path.basename(filePath) : null,
             timestamp: Date.now()
         });
     }
 
+    /**
+     * Emits a full page reload event.
+     * @param {string} reason - Reason for the reload (shown in dev tools).
+     */
     emitReload(reason) {
         if (!this.#io) return;
+
         this.#io.emit("hmr:reload", {
             reason,
             timestamp: Date.now()
         });
     }
 
+    /**
+     * Emits a build error event to show error overlay in browser.
+     * @param {Error|string} error - The error that occurred.
+     * @param {string} [filePath] - Path to the file that caused the error.
+     */
     emitError(error, filePath) {
         if (!this.#io) return;
+
         this.#io.emit("hmr:error", {
             file: filePath,
             message: String(error?.message || error),
@@ -74,12 +142,15 @@ class HMRServer {
         });
     }
 
+    /**
+     * Closes the WebSocket server and cleans up resources.
+     */
     close() {
         if (this.#io) {
             this.#io.close();
             this.#io = null;
         }
-        this.#ready = false;
+
         this.#connections = 0;
     }
 }

package/lib/Hashing/Hash.js

@@ -0,0 +1,41 @@
+import bcrypt from "bcrypt";
+import Config from "../Core/Config.js";
+
+/**
+ * Secure password hashing using bcrypt with APP_KEY pepper.
+ */
+class Hash {
+    /**
+     * Hashes a plain text password.
+     * @param {string} textField - Plain text password to hash
+     * @returns {Promise<string>} Bcrypt hashed password
+     * @throws {Error} If APP_KEY is not set
+     */
+    static async make(textField) {
+        if (!process.env.APP_KEY) {
+            throw new Error("APP_KEY is required for hashing");
+        }
+
+        const saltRounds = Config.get("hash.salt_rounds", 10);
+        const salt = await bcrypt.genSalt(saltRounds);
+
+        return await bcrypt.hash(textField + process.env.APP_KEY, salt);
+    }
+
+    /**
+     * Verifies a plain text password against a hash.
+     * @param {string} textField - Plain text password to verify
+     * @param {string} hashedText - Bcrypt hash to compare against
+     * @returns {Promise<boolean>} True if password matches
+     * @throws {Error} If APP_KEY is not set
+     */
+    static async check(textField, hashedText) {
+        if (!process.env.APP_KEY) {
+            throw new Error("APP_KEY is required for hashing");
+        }
+
+        return await bcrypt.compare(textField + process.env.APP_KEY, hashedText);
+    }
+}
+
+export default Hash;