@nitronjs/framework 0.2.2 → 0.2.4

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,11 +1,52 @@
 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;
 
@@ -15,31 +56,41 @@ class HMRServer {
             cors: { origin: "*" },
             pingTimeout: 60000,
             pingInterval: 25000,
-            serveClient: true
+            serveClient: false
         });
 
         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 +100,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 +141,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;