@nitronjs/framework 0.2.3 → 0.2.4

package/lib/Session/Session.js

@@ -1,114 +1,97 @@
 import crypto from "crypto";
 
 /**
- * Session
- * 
- * Represents a single user session with secure data storage.
- * All data is private and accessed through controlled methods.
- * 
- * Features:
- * - Private data storage (no external mutation)
- * - CSRF token generation and verification
- * - Flash messages (one-time messages)
- * - Session regeneration (security)
- * - Session destruction (logout)
+ * Represents a single user session.
+ * Provides secure data storage, CSRF protection, and flash messages.
  */
 class Session {
-    // Private fields
     #id;
     #data;
     #createdAt;
     #lastActivity;
-    #flags = {
-        shouldRegenerate: false,
-        oldId: null
-    };
+    #oldId = null;
+    #regenerated = false;
 
-    constructor (id, sessionData) {
+    constructor(id, sessionData) {
         this.#id = id;
         this.#data = sessionData.data || {};
         this.#createdAt = sessionData.createdAt || Date.now();
         this.#lastActivity = sessionData.lastActivity || null;
     }
 
-    // ========================================
-    // Getters
-    // ========================================
-
-    get id () {
+    get id() {
         return this.#id;
     }
 
-    get createdAt () {
+    get createdAt() {
         return this.#createdAt;
     }
 
-    get lastActivity () {
+    get lastActivity() {
         return this.#lastActivity;
     }
 
-    // ========================================
-    // Data Management
-    // ========================================
-
     /**
-     * Get a session value
+     * Gets a session value.
+     * @param {string} key
+     * @returns {*}
      */
-    get (key) {
+    get(key) {
         return this.#data[key];
     }
 
     /**
-     * Set a session value
+     * Sets a session value.
+     * @param {string} key
+     * @param {*} value
      */
-    set (key, value) {
+    set(key, value) {
         this.#data[key] = value;
     }
 
     /**
-     * Get all session data (copy to prevent mutations)
+     * Gets all session data (copy).
+     * @returns {Object}
      */
-    all () {
+    all() {
         return { ...this.#data };
     }
 
-    // ========================================
-    // CSRF Protection
-    // ========================================
-
     /**
-     * Generate new CSRF token
-     * @returns {string} Generated token
+     * Generates a new CSRF token.
+     * @returns {string}
      */
-    generateCsrfToken () {
-        const token = crypto.randomBytes(32).toString('hex');
-        this.set('_csrf', token);
+    generateCsrfToken() {
+        const token = crypto.randomBytes(32).toString("hex");
+        this.set("_csrf", token);
 
         return token;
     }
 
     /**
-     * Get CSRF token (generate if doesn't exist)
-     * @returns {string} CSRF token
+     * Gets the CSRF token, generating one if needed.
+     * @returns {string}
      */
-    getCsrfToken () {
-        return this.get('_csrf') || this.generateCsrfToken();
+    getCsrfToken() {
+        return this.get("_csrf") || this.generateCsrfToken();
     }
 
     /**
-     * Verify CSRF token (timing-safe comparison)
-     * @param {string} token - Token to verify
-     * @returns {boolean} True if valid
+     * Verifies a CSRF token using timing-safe comparison.
+     * @param {string} token
+     * @returns {boolean}
      */
-    verifyCsrfToken (token) {
-        const sessionToken = this.get('_csrf');
-        
-        if (!sessionToken || !token) return false;
-        
+    verifyCsrfToken(token) {
+        const sessionToken = this.get("_csrf");
+
+        if (!sessionToken || !token) {
+            return false;
+        }
+
         try {
             return crypto.timingSafeEqual(
-                Buffer.from(sessionToken, 'hex'),
-                Buffer.from(token, 'hex')
+                Buffer.from(sessionToken, "hex"),
+                Buffer.from(token, "hex")
             );
         }
         catch {
@@ -116,80 +99,61 @@ class Session {
         }
     }
 
-    // ========================================
-    // Flash Messages
-    // ========================================
-
     /**
-     * Store a flash message (available only for the next request)
-     * @param {string} key - Message key
-     * @param {any} value - Message value
+     * Stores a flash message (available only for next request).
+     * @param {string} key
+     * @param {*} value
      */
-    flash (key, value) {
+    flash(key, value) {
         if (!this.#data._flash) {
             this.#data._flash = {};
         }
-        
+
         this.#data._flash[key] = value;
     }
 
     /**
-     * Get and remove a flash message
-     * @param {string} key - Message key
-     * @returns {any} Message value or undefined
+     * Gets and removes a flash message.
+     * @param {string} key
+     * @returns {*}
      */
-    getFlash (key) {
-        if (!this.#data._flash?.[key]) return undefined;
-        
-        const value = this.#data._flash[key];
+    getFlash(key) {
+        if (!this.#data._flash?.[key]) {
+            return undefined;
+        }
 
+        const value = this.#data._flash[key];
         delete this.#data._flash[key];
 
         return value;
     }
 
-    // ========================================
-    // Lifecycle Management
-    // ========================================
-
     /**
-     * Regenerate session ID and CSRF token
-     * 
-     * Prevents session fixation attacks by creating a new session ID.
-     * Call this after login, logout, or any privilege escalation.
-     * 
-     * @returns {object} {oldId, newId}
+     * Regenerates session ID and CSRF token.
+     * Prevents session fixation attacks.
+     * @returns {{ oldId: string, newId: string }}
      */
-    regenerate () {
-        // Guard: Prevent concurrent regeneration (idempotent)
-        if (this.#flags.shouldRegenerate) {
-            return {
-                oldId: this.#flags.oldId,
-                newId: this.#id
-            };
+    regenerate() {
+        if (this.#regenerated) {
+            return { oldId: this.#oldId, newId: this.#id };
         }
-        
-        this.#flags.oldId = this.#id;
-        this.#id = crypto.randomBytes(32).toString('hex');
-        this.#flags.shouldRegenerate = true;
+
+        this.#oldId = this.#id;
+        this.#id = crypto.randomBytes(32).toString("hex");
+        this.#regenerated = true;
         this.generateCsrfToken();
-        
-        return {
-            oldId: this.#flags.oldId,
-            newId: this.#id
-        };
-    }
 
-    // ========================================
-    // Internal Flags (used by Manager)
-    // ========================================
+        return { oldId: this.#oldId, newId: this.#id };
+    }
 
-    shouldRegenerate () {
-        return this.#flags.shouldRegenerate;
+    /** @private */
+    shouldRegenerate() {
+        return this.#regenerated;
     }
 
-    getOldId () {
-        return this.#flags.oldId;
+    /** @private */
+    getOldId() {
+        return this.#oldId;
     }
 }
 

package/lib/Support/Str.js

@@ -1,4 +1,17 @@
+/**
+ * String utility class with helper methods.
+ * Provides Laravel-style string manipulation functions.
+ * 
+ * @example
+ * Str.slug("Hello World"); // "hello-world"
+ * Str.camel("user_name");  // "userName"
+ */
 class Str {
+    /**
+     * Generates a random alphanumeric string.
+     * @param {number} length - Desired string length
+     * @returns {string} Random string
+     */
     static random(length) {
         const characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
         let result = "";
@@ -11,6 +24,11 @@ class Str {
         return result;
     }
 
+    /**
+     * Converts a string to URL-friendly slug.
+     * @param {string} text - Input text
+     * @returns {string} Slugified string
+     */
     static slug(text) {
         const normalizedInput = text
             .toLowerCase()
@@ -25,28 +43,55 @@ class Str {
         return slug;
     }
 
+    /**
+     * Capitalizes the first character.
+     * @param {string} str - Input string
+     * @returns {string} String with first char uppercase
+     */
     static ucfirst(str) {
         if (!str) return "";
+
         return str.charAt(0).toUpperCase() + str.slice(1);
     }
 
+    /**
+     * Lowercases the first character.
+     * @param {string} str - Input string
+     * @returns {string} String with first char lowercase
+     */
     static lcfirst(str) {
         if (!str) return "";
+
         return str.charAt(0).toLowerCase() + str.slice(1);
     }
 
+    /**
+     * Converts to camelCase.
+     * @param {string} str - Input string
+     * @returns {string} camelCased string
+     */
     static camel(str) {
         return str
             .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""))
             .replace(/^(.)/, (c) => c.toLowerCase());
     }
 
+    /**
+     * Converts to PascalCase.
+     * @param {string} str - Input string
+     * @returns {string} PascalCased string
+     */
     static pascal(str) {
         return str
             .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""))
             .replace(/^(.)/, (c) => c.toUpperCase());
     }
 
+    /**
+     * Converts to snake_case.
+     * @param {string} str - Input string
+     * @returns {string} snake_cased string
+     */
     static snake(str) {
         return str
             .replace(/([a-z])([A-Z])/g, "$1_$2")
@@ -54,6 +99,11 @@ class Str {
             .toLowerCase();
     }
 
+    /**
+     * Converts to kebab-case.
+     * @param {string} str - Input string
+     * @returns {string} kebab-cased string
+     */
     static kebab(str) {
         return str
             .replace(/([a-z])([A-Z])/g, "$1-$2")
@@ -61,38 +111,91 @@ class Str {
             .toLowerCase();
     }
 
+    /**
+     * Limits string to specified length.
+     * @param {string} str - Input string
+     * @param {number} length - Maximum length
+     * @param {string} suffix - Suffix to append (default: "...")
+     * @returns {string} Truncated string
+     */
     static limit(str, length, suffix = "...") {
         if (!str || str.length <= length) return str;
+
         return str.substring(0, length) + suffix;
     }
 
+    /**
+     * Limits string to specified word count.
+     * @param {string} str - Input string
+     * @param {number} count - Maximum word count
+     * @param {string} suffix - Suffix to append (default: "...")
+     * @returns {string} Truncated string
+     */
     static words(str, count, suffix = "...") {
         const wordsArray = str.split(/\s+/);
+
         if (wordsArray.length <= count) return str;
+
         return wordsArray.slice(0, count).join(" ") + suffix;
     }
 
+    /**
+     * Checks if string contains substring.
+     * @param {string} haystack - String to search in
+     * @param {string} needle - String to search for
+     * @returns {boolean} True if found
+     */
     static contains(haystack, needle) {
         return haystack.includes(needle);
     }
 
+    /**
+     * Checks if string starts with substring.
+     * @param {string} haystack - String to check
+     * @param {string} needle - Prefix to look for
+     * @returns {boolean} True if starts with
+     */
     static startsWith(haystack, needle) {
         return haystack.startsWith(needle);
     }
 
+    /**
+     * Checks if string ends with substring.
+     * @param {string} haystack - String to check
+     * @param {string} needle - Suffix to look for
+     * @returns {boolean} True if ends with
+     */
     static endsWith(haystack, needle) {
         return haystack.endsWith(needle);
     }
 
+    /**
+     * Replaces first occurrence of search string.
+     * @param {string} str - Input string
+     * @param {string} search - String to find
+     * @param {string} replace - Replacement string
+     * @returns {string} Modified string
+     */
     static replaceFirst(str, search, replace) {
         const pos = str.indexOf(search);
+
         if (pos === -1) return str;
+
         return str.substring(0, pos) + replace + str.substring(pos + search.length);
     }
 
+    /**
+     * Replaces last occurrence of search string.
+     * @param {string} str - Input string
+     * @param {string} search - String to find
+     * @param {string} replace - Replacement string
+     * @returns {string} Modified string
+     */
     static replaceLast(str, search, replace) {
         const pos = str.lastIndexOf(search);
+
         if (pos === -1) return str;
+
         return str.substring(0, pos) + replace + str.substring(pos + search.length);
     }
 }

package/lib/Translation/Lang.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import Paths from "../Core/Paths.js";
+
+/**
+ * Translation manager for multi-language support.
+ * Loads translations from JSON files and supports parameter replacement.
+ */
+class Lang {
+    static #cache = new Map();
+
+    /**
+     * Gets a translated string for the current request language.
+     * @param {import("fastify").FastifyRequest} req - Fastify request with language property
+     * @param {string} key - Translation key to look up
+     * @param {Object|null} params - Optional parameters to replace in translation (e.g., { name: "John" } for ":name")
+     * @returns {string} Translated string or the key if not found
+     */
+    static get(req, key, params = null) {
+        const currentLang = req.language;
+        const langPath = path.join(Paths.langs, currentLang + ".json");
+
+        if (!fs.existsSync(langPath)) {
+            return key;
+        }
+
+        let translations = this.#cache.get(currentLang);
+
+        if (!translations) {
+            const langFile = fs.readFileSync(langPath, { encoding: "utf-8", flag: "r" });
+            translations = JSON.parse(langFile);
+            this.#cache.set(currentLang, translations);
+        }
+
+        let translation = translations[key] || key;
+
+        if (params) {
+            for (const [paramKey, paramValue] of Object.entries(params)) {
+                translation = translation.replaceAll(":" + paramKey, paramValue);
+            }
+        }
+
+        return translation;
+    }
+
+    /**
+     * Clears the translation cache. Useful for development hot reload.
+     */
+    static clearCache() {
+        this.#cache.clear();
+    }
+}
+
+export default Lang;