@nitronjs/framework 0.3.0 → 0.3.2

package/lib/Date/DateTime.js

@@ -22,12 +22,14 @@ class DateTime {
         const lang = locale[Config.get('app.locale', 'en')] || locale.en;
         const pad = (n) => String(n).padStart(2, '0');
 
-        // Replace multi-character tokens first to avoid per-character replacement
+        // Replace multi-character tokens first using non-alpha placeholders so the
+        // single-character replacement pass below cannot accidentally corrupt them.
+        // \x10-\x13 are control characters not present in the format token regex.
         let result = formatString;
-        result = result.replace(/MMMM/g, '\x01MONTH\x01');
-        result = result.replace(/MMM/g, '\x01MONTHSHORT\x01');
-        result = result.replace(/DDDD/g, '\x01DAY\x01');
-        result = result.replace(/DDD/g, '\x01DAYSHORT\x01');
+        result = result.replace(/MMMM/g, '\x10');
+        result = result.replace(/MMM/g, '\x11');
+        result = result.replace(/DDDD/g, '\x12');
+        result = result.replace(/DDD/g, '\x13');
 
         const map = {
             'Y': date.getFullYear(),
@@ -47,11 +49,11 @@ class DateTime {
 
         result = result.replace(/[YynmdjHislDMF]/g, match => map[match]);
 
-        // Restore multi-character tokens
-        result = result.replace(/\x01MONTH\x01/g, lang.months[date.getMonth()]);
-        result = result.replace(/\x01MONTHSHORT\x01/g, lang.monthsShort[date.getMonth()]);
-        result = result.replace(/\x01DAY\x01/g, lang.days[date.getDay()]);
-        result = result.replace(/\x01DAYSHORT\x01/g, lang.daysShort[date.getDay()]);
+        // Restore multi-character tokens from their safe placeholders
+        result = result.replace(/\x10/g, lang.months[date.getMonth()]);
+        result = result.replace(/\x11/g, lang.monthsShort[date.getMonth()]);
+        result = result.replace(/\x12/g, lang.days[date.getDay()]);
+        result = result.replace(/\x13/g, lang.daysShort[date.getDay()]);
 
         return result;
     }

package/lib/Http/Server.js

@@ -60,7 +60,8 @@ class Server {
 
         if (!process.env.APP_KEY || process.env.APP_KEY.trim() === "") {
             console.error("\x1b[31m✕ APP_KEY is not set. Please set APP_KEY in your .env file before starting the server.\x1b[0m");
-            process.exit(1);
+            process.exitCode = 1;
+            return;
         }
 
         this.#config = Config.all("server");
@@ -484,7 +485,7 @@ class Server {
             const banner = this.#renderBanner({ success: false, error: err });
             if (banner) console.log(banner);
             Log.fatal("Server startup failed", { error: err.message, code: err.code, stack: err.stack });
-            process.exit(1);
+            process.exitCode = 1;
         }
     }
 

package/lib/Mail/Mail.js

@@ -1,6 +1,9 @@
 import nodemailer from "nodemailer";
 import fs from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
 import Paths from "../Core/Paths.js";
 
 /**
@@ -22,6 +25,7 @@ class Mail {
     #htmlContent = null;
     #attachments = [];
     #calendarContent = null;
+    #viewTemplate = null;
 
     /**
      * Creates a new Mail instance with sender address.
@@ -125,23 +129,21 @@ class Mail {
     }
 
     /**
-     * Sets HTML content from a template file with placeholder replacement.
-     * Template files are loaded from resources/views/ directory.
-     * Placeholders use {{ key }} syntax.
+     * Sets HTML content from a React component template (.tsx/.jsx).
+     * Uses the built version from .nitron/build/views/ and renders to static HTML.
      *
-     * @param {string} templateName - Template path relative to views dir (e.g. "emails/welcome")
-     * @param {Object} data - Data to replace placeholders with
+     * @param {string} templateName - Template path relative to views dir (e.g. "Mail/Welcome")
+     * @param {Object} data - Data to pass as props to the React component
      * @returns {Mail} This instance for chaining
      */
     view(templateName, data = {}) {
-        const filePath = path.join(Paths.views, `${templateName}.html`);
-        let content = fs.readFileSync(filePath, "utf-8");
+        const buildPath = path.join(Paths.buildViews, `${templateName}.js`);
 
-        for (const [key, value] of Object.entries(data)) {
-            content = content.replaceAll(`{{ ${key} }}`, escapeHtml(String(value ?? "")));
+        if (!fs.existsSync(buildPath)) {
+            throw new Error(`Mail template not found: ${templateName}`);
         }
 
-        this.#htmlContent = content;
+        this.#viewTemplate = { buildPath, data };
 
         return this;
     }
@@ -152,6 +154,16 @@ class Mail {
      * @returns {Promise<Object>} Nodemailer send result
      */
     async send(transportCallback = null) {
+        if (this.#viewTemplate) {
+            const { buildPath, data } = this.#viewTemplate;
+            const mod = await import(pathToFileURL(buildPath).href + "?t=" + Date.now());
+            const factory = mod.default;
+            const exports = typeof factory === "function" && mod.__factory ? await factory() : mod;
+            const Component = exports.default || exports;
+            const element = createElement(Component, data);
+            this.#htmlContent = renderToStaticMarkup(element);
+        }
+
         let transporter;
 
         if (typeof transportCallback === "function") {
@@ -206,13 +218,4 @@ class Mail {
     }
 }
 
-function escapeHtml(str) {
-    return str
-        .replace(/&/g, "&amp;")
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;")
-        .replace(/"/g, "&quot;")
-        .replace(/'/g, "&#39;");
-}
-
 export default Mail;

package/lib/Runtime/Entry.js

@@ -36,6 +36,6 @@ const isMain = process.argv[1]?.endsWith("Entry.js");
 if (isMain) {
   start().catch(e => {
     console.error(e);
-    process.exit(1);
+    process.exitCode = 1;
   });
 }

package/lib/View/Client/spa.js

@@ -5,35 +5,34 @@
  * fetches a fresh RSC Flight payload from /__nitron/rsc, and lets
  * React reconcile the DOM without a full page reload.
  *
- * Wire format from /__nitron/rsc:
- *   "<flightLength>\n<flightPayload><jsonMetadata>"
- *   - First line: byte length of the Flight payload
- *   - Then the Flight payload itself (React serialization format)
- *   - Then a JSON object with { meta, css, translations }
+ * RSC wire format: "<payloadLength>\n<flightPayload><jsonMetadata>"
+ * Redirect format: { "redirect": "/target/path" }
  */
 (function() {
     "use strict";
 
-    var RSC_ENDPOINT = "/__nitron/rsc";
+    const RSC_ENDPOINT = "/__nitron/rsc";
+    const NAVIGATION_TIMEOUT = 10000;
+    const SKIP_PATTERN = /^(\/storage|\/api|\/__|#|javascript:|mailto:|tel:)/;
 
-    // URLs that should never be intercepted by SPA navigation
-    var SKIP = /^(\/storage|\/api|\/__|#|javascript:|mailto:|tel:)/;
+    let navigating = false;
 
-    var navigating = false;
+    // ============================================================
+    // Client-side route() helper
+    // ============================================================
 
-    // --- Client-side route() helper ---
-
-    // Mirrors the server-side route() global — resolves named routes to URL paths.
-    // Route definitions are injected by the server into window.__NITRON_RUNTIME__.routes.
+    // Mirrors the server-side route() global.
+    // Resolves named routes to URL paths using route definitions
+    // injected by the server into window.__NITRON_RUNTIME__.routes.
     globalThis.route = function(name, params) {
-        var runtime = window.__NITRON_RUNTIME__;
+        const runtime = window.__NITRON_RUNTIME__;
 
         if (!runtime || !runtime.routes) {
             console.error("Route runtime not initialized");
             return "";
         }
 
-        var pattern = runtime.routes[name];
+        const pattern = runtime.routes[name];
 
         if (!pattern) {
             console.error('Route "' + name + '" not found');
@@ -42,92 +41,119 @@
 
         if (!params) return pattern;
 
-        // Replace :param tokens with actual values
+        // Replace :param tokens with actual values (e.g. :id -> 5)
         return pattern.replace(/:(\w+)/g, function(match, key) {
             return params[key] !== undefined ? params[key] : match;
         });
     };
 
-    // --- Link Interception ---
+    // ============================================================
+    // Initialization & Event Listeners
+    // ============================================================
 
     function init() {
         // Capture phase (true) so we intercept before any stopPropagation
-        document.addEventListener("click", onClick, true);
-        window.addEventListener("popstate", onPopState);
+        document.addEventListener("click", handleLinkClick, true);
+        window.addEventListener("popstate", handleBackForward);
     }
 
-    // Intercepts <a> clicks — if the link is local, navigates via RSC instead of full reload
-    function onClick(e) {
+    // When user clicks an <a> link, intercept it and navigate via RSC
+    // instead of doing a full page reload
+    function handleLinkClick(e) {
         if (navigating) return;
-        var link = e.target.closest("a");
+
+        const link = e.target.closest("a");
 
         if (!link) return;
 
-        var href = link.getAttribute("href");
+        const href = link.getAttribute("href");
 
+        // Skip: no href, external tab, download links, modifier keys
         if (!href || link.target === "_blank" || link.download) return;
         if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
-        if (!isLocal(href)) return;
+        if (!isLocalUrl(href)) return;
 
         e.preventDefault();
         navigate(href, true);
     }
 
-    // Browser back/forward — re-fetch RSC payload for the new URL
-    function onPopState() {
+    // When browser back/forward buttons are pressed,
+    // re-fetch the RSC payload for the current URL
+    function handleBackForward() {
         navigate(location.pathname + location.search, false);
     }
 
-    // Returns true if the href points to the same origin and is not in the SKIP list
-    function isLocal(href) {
-        if (!href || SKIP.test(href)) return false;
+    // Check if the URL belongs to this site (same origin) and is not
+    // a path we should skip (storage files, API routes, internal routes)
+    function isLocalUrl(href) {
+        if (!href || SKIP_PATTERN.test(href)) return false;
 
-        // Absolute URLs — check if same origin
+        // Absolute URLs — compare origins
         if (/^https?:\/\/|^\/\//.test(href)) {
-            try { return new URL(href, location.origin).origin === location.origin; }
-            catch (e) { return false; }
+            try {
+                return new URL(href, location.origin).origin === location.origin;
+            }
+            catch (e) {
+                return false;
+            }
         }
 
+        // Relative URLs are always local
         return true;
     }
 
-    // --- RSC Wire Format Parser ---
+    // ============================================================
+    // RSC Response Parser
+    // ============================================================
 
-    // Parses the length-prefixed response from /__nitron/rsc.
+    // Parses the length-prefixed RSC response from the server.
     // Format: "<length>\n<flight payload><json metadata>"
-    // Returns { payload, meta, css, translations } or null on malformed input.
-    function parseLengthPrefixed(text) {
-        var nl = text.indexOf("\n");
-        if (nl === -1) return null;
+    // Returns { payload, meta, css, layouts, translations } or null if malformed.
+    function parseRscResponse(text) {
+        const newlineIndex = text.indexOf("\n");
+
+        if (newlineIndex === -1) return null;
 
-        var len = parseInt(text.substring(0, nl), 10);
-        if (isNaN(len) || len < 0) return null;
+        const payloadLength = parseInt(text.substring(0, newlineIndex), 10);
 
-        var flight = text.substring(nl + 1, nl + 1 + len);
-        var jsonStr = text.substring(nl + 1 + len);
-        var data;
+        if (isNaN(payloadLength) || payloadLength < 0) return null;
 
-        try { data = JSON.parse(jsonStr); }
-        catch (e) { return null; }
+        const payloadStart = newlineIndex + 1;
+        const payload = text.substring(payloadStart, payloadStart + payloadLength);
+        const metadataStr = text.substring(payloadStart + payloadLength);
+
+        let metadata;
+
+        try {
+            metadata = JSON.parse(metadataStr);
+        }
+        catch (e) {
+            return null;
+        }
 
         return {
-            payload: flight,
-            meta: data.meta || null,
-            css: data.css || null,
-            translations: data.translations || null
+            payload: payload,
+            meta: metadata.meta || null,
+            css: metadata.css || null,
+            layouts: metadata.layouts || null,
+            translations: metadata.translations || null
         };
     }
 
-    // --- SPA Navigation ---
+    // ============================================================
+    // SPA Navigation
+    // ============================================================
 
-    // Core navigation: fetches RSC payload and lets React reconcile.
-    // Falls back to full page load on error or timeout (10s).
-    function navigate(url, push) {
+    // Main navigation function.
+    // Fetches the RSC payload from the server, then lets React update the DOM.
+    // If server returns a redirect, follows it via SPA (no full page reload).
+    // Falls back to full page load if anything goes wrong or takes too long.
+    async function navigate(url, push) {
         if (navigating) return;
 
-        var rsc = window.__NITRON_RSC__;
+        const rsc = window.__NITRON_RSC__;
 
-        // RSC root not available (e.g. initial page was server-rendered without hydration)
+        // If RSC is not set up, do a normal page load
         if (!rsc || !rsc.root) {
             location.href = url;
             return;
@@ -135,76 +161,126 @@
 
         navigating = true;
 
-        // Abort + fallback after 10 seconds to prevent hanging navigations
-        var ctrl = typeof AbortController !== "undefined" ? new AbortController() : null;
-        var timer = setTimeout(function() { if (ctrl) ctrl.abort(); fallback(); }, 10000);
-
-        fetch(RSC_ENDPOINT + "?url=" + encodeURIComponent(url), {
-            headers: { "X-Nitron-SPA": "1" },
-            credentials: "same-origin",
-            signal: ctrl ? ctrl.signal : undefined
-        })
-        .then(function(r) {
-            clearTimeout(timer);
+        const abortController = new AbortController();
 
-            if (!r.ok) throw new Error("HTTP " + r.status);
+        // Safety timeout: if navigation takes more than 10 seconds,
+        // abort the fetch and fall back to a normal page load
+        const timeout = setTimeout(function() {
+            abortController.abort();
+            navigating = false;
+            location.href = url;
+        }, NAVIGATION_TIMEOUT);
 
-            return r.text().then(function(text) {
-                return parseLengthPrefixed(text);
+        try {
+            const response = await fetch(RSC_ENDPOINT + "?url=" + encodeURIComponent(url), {
+                headers: { "X-Nitron-SPA": "1" },
+                credentials: "same-origin",
+                signal: abortController.signal
             });
-        })
-        .then(function(d) {
-            if (!d || !d.payload) { fallback(); return; }
 
-            // Merge translations BEFORE rsc.navigate — persistent components (layouts) keep their keys
-            if (d.translations) {
-                var prev = window.__NITRON_TRANSLATIONS__;
+            clearTimeout(timeout);
+
+            if (!response.ok) {
+                throw new Error("HTTP " + response.status);
+            }
+
+            const contentType = response.headers.get("content-type") || "";
+
+            // Server returned a redirect (JSON response like { redirect: "/path" })
+            // Navigate to the redirect target via SPA instead of full page reload
+            if (contentType.indexOf("application/json") !== -1) {
+                const json = await response.json();
+
+                if (json.redirect) {
+                    navigating = false;
+                    navigate(json.redirect, true);
+                }
+
+                return;
+            }
+
+            // Normal RSC payload — parse it and render
+            const text = await response.text();
+            const data = parseRscResponse(text);
 
-                window.__NITRON_TRANSLATIONS__ = prev
-                    ? Object.assign({}, prev, d.translations)
-                    : d.translations;
+            if (!data || !data.payload) {
+                throw new Error("Invalid RSC response");
             }
 
-            // Use RSC consumer to render new payload via React reconciliation
-            rsc.navigate(d.payload);
+            if (!layoutsMatch(data.layouts)) {
+                navigating = false;
+                location.href = url;
+                return;
+            }
+
+            // Merge new translations with existing ones.
+            // This keeps translation keys alive for persistent layout components.
+            if (data.translations) {
+                const existing = window.__NITRON_TRANSLATIONS__;
+
+                window.__NITRON_TRANSLATIONS__ = existing
+                    ? Object.assign({}, existing, data.translations)
+                    : data.translations;
+            }
+
+            // Let React reconcile the new payload into the DOM
+            rsc.navigate(data.payload);
 
+            // Update browser URL and page title
             if (push) history.pushState({ nitron: 1 }, "", url);
+            if (data.meta && data.meta.title) document.title = data.meta.title;
 
-            if (d.meta && d.meta.title) document.title = d.meta.title;
-            setMeta("description", d.meta ? d.meta.description : null);
+            updateMetaTag("description", data.meta ? data.meta.description : null);
 
-            // Load new CSS stylesheets if needed
-            if (d.css) loadNewCss(d.css);
+            // Load any new CSS files this page needs
+            if (data.css) loadNewCss(data.css);
 
+            // Scroll to top and fire a custom event for any listeners
             scrollTo(0, 0);
             dispatchEvent(new CustomEvent("nitron:navigate", { detail: { url: url } }));
             navigating = false;
-        })
-        .catch(function() {
-            // RSC fetch failed or aborted — full page load as last resort
-            clearTimeout(timer);
-            fallback();
-        });
-
-        function fallback() {
+        }
+        catch (e) {
+            // Something went wrong — fall back to a normal full page load
+            clearTimeout(timeout);
             navigating = false;
             location.href = url;
         }
     }
 
-    // --- CSS & Meta Helpers ---
+    // ============================================================
+    // Helper Functions
+    // ============================================================
+
+    function layoutsMatch(targetLayouts) {
+        const currentLayouts = window.__NITRON_RUNTIME__?.layouts || [];
+        const newLayouts = targetLayouts || [];
+
+        if (currentLayouts.length !== newLayouts.length) {
+            return false;
+        }
+
+        for (let i = 0; i < currentLayouts.length; i++) {
+            if (currentLayouts[i] !== newLayouts[i]) {
+                return false;
+            }
+        }
+
+        return true;
+    }
 
-    // Loads CSS files that the new page needs but the current page doesn't have
+    // Checks if any new CSS files need to be loaded for the new page.
+    // Skips files that are already loaded.
     function loadNewCss(cssFiles) {
-        var existing = new Set();
+        const existing = new Set();
 
-        document.querySelectorAll('link[rel="stylesheet"]').forEach(function(link) {
-            existing.add(link.getAttribute("href"));
+        document.querySelectorAll('link[rel="stylesheet"]').forEach(function(el) {
+            existing.add(el.getAttribute("href"));
         });
 
-        for (var i = 0; i < cssFiles.length; i++) {
+        for (let i = 0; i < cssFiles.length; i++) {
             if (!existing.has(cssFiles[i])) {
-                var link = document.createElement("link");
+                const link = document.createElement("link");
                 link.rel = "stylesheet";
                 link.href = cssFiles[i];
                 document.head.appendChild(link);
@@ -212,24 +288,32 @@
         }
     }
 
-    // Creates or updates a <meta> tag (e.g. description)
-    function setMeta(name, val) {
-        if (!val) return;
+    // Creates or updates a <meta> tag in the document head.
+    // Used to update SEO meta tags when navigating between pages.
+    function updateMetaTag(name, value) {
+        if (!value) return;
 
-        var m = document.querySelector('meta[name="' + name + '"]');
+        let tag = document.querySelector('meta[name="' + name + '"]');
 
-        if (m) m.content = val;
+        if (tag) {
+            tag.content = value;
+        }
         else {
-            m = document.createElement("meta");
-            m.name = name;
-            m.content = val;
-            document.head.appendChild(m);
+            tag = document.createElement("meta");
+            tag.name = name;
+            tag.content = value;
+            document.head.appendChild(tag);
         }
     }
 
-    // --- Initialize ---
+    // ============================================================
+    // Start
+    // ============================================================
 
-    document.readyState === "loading"
-        ? document.addEventListener("DOMContentLoaded", init)
-        : init();
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", init);
+    }
+    else {
+        init();
+    }
 })();

package/lib/View/FlightRenderer.js

@@ -69,7 +69,10 @@ class FlightRenderer {
             }, timeout);
 
             stream.on("data", chunk => chunks.push(chunk));
-            stream.on("end", () => finish(Buffer.concat(chunks).toString("utf-8")));
+            stream.on("end", () => {
+                const payload = Buffer.concat(chunks).toString("utf-8");
+                finish(payload);
+            });
             stream.on("error", (error) => {
                 renderError = error;
                 finish(null);
@@ -89,6 +92,7 @@ class FlightRenderer {
                 pipe(stream);
             }
             catch (error) {
+                console.error("[FlightRenderer] renderToPipeableStream threw:", error?.message);
                 renderError = error;
                 finish(null);
             }