@nitronjs/framework 0.2.3 → 0.2.5

package/lib/Logging/{Manager.js → Log.js}

@@ -1,86 +1,89 @@
-import fs from "fs";
-import path from "path";
+import fs from "node:fs";
+import path from "node:path";
 import Config from "../Core/Config.js";
 
-class LogManager {
-    static #levels = {
-        debug: 0,
-        info: 1,
-        warn: 2,
-        error: 3,
-        fatal: 4
-    };
-
-    static #levelLabels = {
-        debug: "DEBUG",
-        info: "INFO ",
-        warn: "WARN ",
-        error: "ERROR",
-        fatal: "FATAL"
-    };
-
+/**
+ * Application logger with console and file output support.
+ * Supports multiple log levels: debug, info, warn, error, fatal.
+ */
+class Log {
+    static #levels = { debug: 0, info: 1, warn: 2, error: 3, fatal: 4 };
+    static #levelLabels = { debug: "DEBUG", info: "INFO", warn: "WARN", error: "ERROR", fatal: "FATAL" };
+
+    /**
+     * Logs a debug message.
+     * @param {string} message - Log message
+     * @param {Object} context - Additional context data
+     */
     static debug(message, context = {}) {
         this.#log("debug", message, context);
     }
 
+    /**
+     * Logs an info message.
+     * @param {string} message - Log message
+     * @param {Object} context - Additional context data
+     */
     static info(message, context = {}) {
         this.#log("info", message, context);
     }
 
+    /**
+     * Logs a warning message.
+     * @param {string} message - Log message
+     * @param {Object} context - Additional context data
+     */
     static warn(message, context = {}) {
         this.#log("warn", message, context);
     }
 
+    /**
+     * Logs an error message.
+     * @param {string} message - Log message
+     * @param {Object} context - Additional context data
+     */
     static error(message, context = {}) {
         this.#log("error", message, context);
     }
 
+    /**
+     * Logs a fatal error message.
+     * @param {string} message - Log message
+     * @param {Object} context - Additional context data
+     */
     static fatal(message, context = {}) {
         this.#log("fatal", message, context);
     }
 
-    static #getConfig() {
-        return {
-            channel: Config.get("server.log.channel", "console"),
-            level: Config.get("server.log.level", "info"),
-            file: Config.get("server.log.file", "./storage/logs/app.log"),
-            sync: Config.get("server.log.sync", false)
-        };
-    }
-
+    /** @private */
     static #log(level, message, context) {
         try {
-            const config = this.#getConfig();
-
-            if (!this.#shouldLog(level, config)) {
+            const config = {
+                channel: Config.get("server.log.channel", "console"),
+                level: Config.get("server.log.level", "info"),
+                file: Config.get("server.log.file", "./storage/logs/app.log"),
+                sync: Config.get("server.log.sync", false)
+            };
+
+            if (this.#levels[level] < this.#levels[config.level] || config.channel === "none") {
                 return;
             }
 
             const timestamp = new Date();
 
-            const channel = config.channel;
-
-            if (channel === "none") {
-                return;
-            }
-
-            if (channel === "console") {
+            if (config.channel === "console") {
                 this.#logToConsole(level, message, context, timestamp);
             }
-
-            if (channel === "file") {
+            else if (config.channel === "file") {
                 this.#logToFile(level, message, context, timestamp, config);
             }
-        } catch (e) {
+        }
+        catch (e) {
             console.error("Logger failure:", e.message);
         }
     }
 
-    static #shouldLog(level, config) {
-        const configLevel = config.level;
-        return this.#levels[level] >= this.#levels[configLevel];
-    }
-
+    /** @private */
     static #formatTimestamp(date) {
         const year = date.getFullYear();
         const month = String(date.getMonth() + 1).padStart(2, "0");
@@ -89,32 +92,19 @@ class LogManager {
         const minutes = String(date.getMinutes()).padStart(2, "0");
         const seconds = String(date.getSeconds()).padStart(2, "0");
         const ms = String(date.getMilliseconds()).padStart(3, "0");
+
         return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${ms}`;
     }
 
+    /** @private */
     static #logToConsole(level, message, context, timestamp) {
-        const colors = {
-            debug: "\x1b[90m",
-            info: "\x1b[36m",
-            warn: "\x1b[33m",
-            error: "\x1b[31m",
-            fatal: "\x1b[35m"
-        };
-
-        const icons = {
-            debug: "◆",
-            info: "●",
-            warn: "⚠",
-            error: "✕",
-            fatal: "■"
-        };
-
+        const colors = { debug: "\x1b[90m", info: "\x1b[36m", warn: "\x1b[33m", error: "\x1b[31m", fatal: "\x1b[35m" };
+        const icons = { debug: "◆", info: "●", warn: "⚠", error: "✕", fatal: "■" };
         const color = colors[level] || "";
         const icon = icons[level] || "";
         const reset = "\x1b[0m";
         const bold = "\x1b[1m";
         const dim = "\x1b[2m";
-
         const time = this.#formatTimestamp(timestamp);
         const width = process.stdout.columns || 80;
 
@@ -128,8 +118,7 @@ class LogManager {
 
         if (Object.keys(context).length > 0) {
             console.log(`${color}│${reset} ${dim}Context:${reset}`);
-            const contextJson = JSON.stringify(context, null, 2);
-            contextJson.split("\n").forEach(line => {
+            JSON.stringify(context, null, 2).split("\n").forEach(line => {
                 console.log(`${color}│${reset} ${dim}${line}${reset}`);
             });
             console.log(`${color}│${reset}`);
@@ -139,18 +128,20 @@ class LogManager {
         console.log();
     }
 
+    /** @private */
     static #formatContext(context, indent = "") {
         const lines = [];
-        
+
         for (const [key, value] of Object.entries(context)) {
-            if (value === null || value === undefined) continue;
+            if (value === null || value === undefined) {
+                continue;
+            }
 
             if (typeof value === "object" && !Array.isArray(value)) {
                 lines.push(`${indent}${key}:`);
                 lines.push(...this.#formatContext(value, indent + "  "));
             }
             else if (key === "stack" && typeof value === "string") {
-                // Format stack trace nicely
                 lines.push(`${indent}${key}:`);
                 value.split("\n").forEach(line => {
                     lines.push(`${indent}  ${line.trim()}`);
@@ -164,6 +155,7 @@ class LogManager {
         return lines;
     }
 
+    /** @private */
     static #logToFile(level, message, context, timestamp, config) {
         const filePath = path.resolve(process.cwd(), config.file);
         const dir = path.dirname(filePath);
@@ -174,23 +166,19 @@ class LogManager {
 
         const time = this.#formatTimestamp(timestamp);
         const label = this.#levelLabels[level];
-        
-        // Build readable log entry
-        const lines = [];
-        lines.push(`[${time}] [${label}] ${message}`);
-        
+        const lines = [`[${time}] [${label}] ${message}`];
+
         if (Object.keys(context).length > 0) {
-            const contextLines = this.#formatContext(context, "  ");
-            lines.push(...contextLines);
+            lines.push(...this.#formatContext(context, "  "));
         }
-        
-        lines.push(""); // Empty line between entries
-        
+
+        lines.push("");
         const logEntry = lines.join("\n") + "\n";
 
         if (config.sync) {
             fs.appendFileSync(filePath, logEntry);
-        } else {
+        }
+        else {
             fs.appendFile(filePath, logEntry, (err) => {
                 if (err) {
                     console.error("Failed to write log:", err.message);
@@ -200,4 +188,4 @@ class LogManager {
     }
 }
 
-export default LogManager;
+export default Log;

package/lib/Mail/Mail.js

@@ -0,0 +1,187 @@
+import nodemailer from "nodemailer";
+import View from "../View/View.js";
+
+/**
+ * Email sending utility with fluent API.
+ * Supports text, HTML views, attachments, and calendar invites.
+ * 
+ * @example
+ * await Mail.from("noreply@example.com")
+ *     .to("user@example.com")
+ *     .subject("Welcome!")
+ *     .view(res, "emails/welcome", { name: "John" })
+ *     .send();
+ */
+class Mail {
+    #fromAddress = null;
+    #toAddress = null;
+    #subjectText = null;
+    #textContent = null;
+    #htmlContent = null;
+    #attachments = [];
+    #calendarContent = null;
+
+    /**
+     * Creates a new Mail instance with sender address.
+     * @param {string} email - Sender email address
+     * @returns {Mail} New Mail instance
+     */
+    static from(email) {
+        const instance = new Mail();
+        instance.#fromAddress = email;
+
+        return instance;
+    }
+
+    /**
+     * Sets the sender address.
+     * @param {string} email - Sender email address
+     * @returns {Mail} This instance for chaining
+     */
+    from(email) {
+        this.#fromAddress = email;
+
+        return this;
+    }
+
+    /**
+     * Creates a new Mail instance with recipient address.
+     * @param {string} email - Recipient email address
+     * @returns {Mail} New Mail instance
+     */
+    static to(email) {
+        const instance = new Mail();
+        instance.#toAddress = email;
+
+        return instance;
+    }
+
+    /**
+     * Sets the recipient address.
+     * @param {string} email - Recipient email address
+     * @returns {Mail} This instance for chaining
+     */
+    to(email) {
+        this.#toAddress = email;
+
+        return this;
+    }
+
+    /**
+     * Sets the email subject.
+     * @param {string} subject - Email subject line
+     * @returns {Mail} This instance for chaining
+     */
+    subject(subject) {
+        this.#subjectText = subject;
+
+        return this;
+    }
+
+    /**
+     * Adds an attachment to the email.
+     * @param {Object} attachment - Nodemailer attachment object
+     * @returns {Mail} This instance for chaining
+     */
+    attachment(attachment) {
+        this.#attachments.push(attachment);
+
+        return this;
+    }
+
+    /**
+     * Adds a calendar invite (ICS) to the email.
+     * @param {string} icsContent - ICS calendar content
+     * @returns {Mail} This instance for chaining
+     */
+    calendar(icsContent) {
+        this.#calendarContent = icsContent;
+
+        return this;
+    }
+
+    /**
+     * Sets plain text content.
+     * @param {string} message - Plain text message
+     * @returns {Mail} This instance for chaining
+     */
+    text(message) {
+        this.#textContent = message;
+
+        return this;
+    }
+
+    /**
+     * Sets HTML content from a view template.
+     * @param {import("fastify").FastifyReply} res - Fastify response object
+     * @param {string} viewName - View template name
+     * @param {Object|null} data - Data to pass to the view
+     * @returns {Mail} This instance for chaining
+     */
+    view(res, viewName, data = null) {
+        this.#htmlContent = View.renderFile(viewName, data);
+
+        return this;
+    }
+
+    /**
+     * Sends the email.
+     * @param {Function|null} transportCallback - Optional callback to configure custom transport
+     * @returns {Promise<Object>} Nodemailer send result
+     */
+    async send(transportCallback = null) {
+        let transporter;
+
+        if (typeof transportCallback === "function") {
+            const transportData = {
+                MAIL_HOST: null,
+                MAIL_PORT: null,
+                MAIL_USERNAME: null,
+                MAIL_PASSWORD: null,
+                MAIL_SECURE: null
+            };
+            transportCallback(transportData);
+            transporter = this.#createTransport(transportData);
+        }
+        else {
+            transporter = this.#createTransport(process.env);
+        }
+
+        const mailOptions = {
+            from: this.#fromAddress,
+            to: this.#toAddress,
+            subject: this.#subjectText,
+            text: this.#textContent,
+            html: this.#htmlContent,
+            attachments: this.#attachments.length > 0 ? this.#attachments : undefined,
+            alternatives: this.#calendarContent
+                ? [{
+                    contentType: "text/calendar; method=REQUEST; charset=\"UTF-8\"",
+                    content: this.#calendarContent,
+                    component: "VEVENT",
+                    headers: { "Content-Class": "urn:content-classes:calendarmessage" }
+                }]
+                : undefined
+        };
+
+        const response = await transporter.sendMail(mailOptions);
+        transporter.close();
+
+        return response;
+    }
+
+    /** @private */
+    #createTransport(data) {
+        return nodemailer.createTransport({
+            host: data.MAIL_HOST,
+            port: data.MAIL_PORT,
+            secure: data.MAIL_SECURE || false,
+            auth: {
+                user: data.MAIL_USERNAME,
+                pass: data.MAIL_PASSWORD
+            }
+        });
+    }
+}
+
+export default Mail;