@nitronjs/framework 0.2.3 → 0.2.5

package/lib/Route/Router.js

@@ -0,0 +1,416 @@
+/**
+ * NitronJS Router
+ * 
+ * Handles route definitions, middleware chains, and Fastify integration.
+ * Includes built-in Hot Module Replacement (HMR) for development.
+ * 
+ * @example
+ * // routes/web.js
+ * import { Route } from "@nitronjs/framework";
+ * import HomeController from "../app/Controllers/HomeController.js";
+ * 
+ * Route.get("/", HomeController.index).name("home");
+ * 
+ * Route.prefix("/admin").middleware("auth").group(() => {
+ *     Route.get("/dashboard", AdminController.dashboard).name("admin.dashboard");
+ * });
+ */
+
+import fs from "fs";
+import path from "path";
+import Paths from "../Core/Paths.js";
+import Config from "../Core/Config.js";
+import Environment from "../Core/Environment.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HMR Handler Registry (Development Only)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class HotReloadRegistry {
+    #handlers = new Map();
+    #initialized = false;
+
+    async initialize() {
+        if (this.#initialized || !Environment.isDev) return;
+
+        const directories = [Paths.controllers, Paths.middlewares];
+
+        for (const dir of directories) {
+            await this.#scanDirectory(dir);
+        }
+
+        this.#initialized = true;
+    }
+
+    /**
+     * Wraps a handler for hot reload support.
+     * In production, returns the handler unchanged.
+     * In development, returns a wrapper that re-imports the file on each request.
+     */
+    wrap(handler) {
+        if (!Environment.isDev) return handler;
+
+        const info = this.#handlers.get(handler);
+        if (!info) return handler;
+
+        const { filePath, methodName } = info;
+
+        return async (request, response, param) => {
+            const module = await import(`file://${filePath}?t=${Date.now()}`);
+
+            return module.default[methodName](request, response, param);
+        };
+    }
+
+    async #scanDirectory(dir) {
+        if (!fs.existsSync(dir)) return;
+
+        for (const filePath of this.#getJsFiles(dir)) {
+            try {
+                const module = await import(`file://${filePath}`);
+                const Class = module.default;
+
+                if (!Class || typeof Class !== "function") continue;
+
+                for (const name of Object.getOwnPropertyNames(Class)) {
+                    if (typeof Class[name] === "function" && !["length", "name", "prototype"].includes(name)) {
+                        this.#handlers.set(Class[name], { filePath, methodName: name });
+                    }
+                }
+            }
+            catch {
+                // Ignore import errors during scanning
+            }
+        }
+    }
+
+    #getJsFiles(dir) {
+        const files = [];
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+
+            if (entry.isDirectory()) {
+                files.push(...this.#getJsFiles(fullPath));
+            }
+            else if (entry.name.endsWith(".js")) {
+                files.push(fullPath);
+            }
+        }
+
+        return files;
+    }
+}
+
+const hotReload = new HotReloadRegistry();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Route Manager
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Router {
+    static #routes = [];
+    static #kernel = null;
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Setup & Initialization
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Initialize router, load routes, and register with Fastify.
+     * @param {FastifyInstance} server - Fastify server instance
+     */
+    static async setup(server) {
+        // Initialize HMR registry (development only)
+        await hotReload.initialize();
+
+        // Load route definitions from routes/web.js
+        await import(Paths.routeUrl("web"));
+
+        // Setup global route() helper
+        globalThis.route = (name, params, query) => this.url(name, params, query);
+
+        const Kernel = await this.#getKernel();
+        const csrf = Config.all("session").csrf;
+
+        for (const route of this.#routes) {
+            // Auto-add CSRF middleware for applicable routes
+            if (csrf.enabled && csrf.methods.includes(route.method)) {
+                const isExcluded = csrf.except.some(pattern => {
+                    if (route.url === pattern) return true;
+                    if (pattern.includes("*")) {
+                        return new RegExp("^" + pattern.replace(/\*/g, ".*") + "$").test(route.url);
+                    }
+                    return false;
+                });
+
+                if (!isExcluded) {
+                    route.middlewares.unshift("verify-csrf");
+                }
+            }
+
+            // Resolve middleware names to handlers
+            const middlewareHandlers = route.middlewares.map(middleware => {
+                const [name, param] = middleware.split(":");
+
+                if (!Kernel.routeMiddlewares[name]) {
+                    throw new Error(`Middleware '${name}' is not defined in Kernel.js`);
+                }
+
+                const handler = hotReload.wrap(Kernel.routeMiddlewares[name].handler);
+
+                return (request, response) => handler(request, response, param);
+            });
+
+            // Wrap controller handler for HMR
+            const handler = hotReload.wrap(route.handler);
+
+            server.route({
+                method: route.method,
+                url: route.url,
+                preHandler: middlewareHandlers,
+                handler
+            });
+        }
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Route Definition Methods
+    // ─────────────────────────────────────────────────────────────────────────
+
+    static get(url, handler) {
+        return this.#addRoute("GET", url, handler);
+    }
+
+    static post(url, handler) {
+        return this.#addRoute("POST", url, handler);
+    }
+
+    static put(url, handler) {
+        return this.#addRoute("PUT", url, handler);
+    }
+
+    static delete(url, handler) {
+        return this.#addRoute("DELETE", url, handler);
+    }
+
+    static patch(url, handler) {
+        return this.#addRoute("PATCH", url, handler);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Route Grouping
+    // ─────────────────────────────────────────────────────────────────────────
+
+    static prefix(url) {
+        return new RouteGroup({ prefix: url }, this.#routes);
+    }
+
+    static middleware(handlers) {
+        const middlewareArray = typeof handlers === "string" ? [handlers] : handlers;
+
+        return new RouteGroup({ middlewares: middlewareArray }, this.#routes);
+    }
+
+    static name(name) {
+        return new RouteGroup({ name }, this.#routes);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // URL Generation
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Generate URL for a named route.
+     * 
+     * @param {string} name - Route name
+     * @param {Object} params - Route parameters
+     * @param {Object} query - Query string parameters
+     * @returns {string} Generated URL
+     */
+    static url(name, params = {}, query = {}) {
+        const route = this.#routes.find(r => r.name === name);
+
+        if (!route) {
+            throw new Error(`Route '${name}' is not defined`);
+        }
+
+        let url = route.url;
+
+        for (const key in params) {
+            url = url.replace(`:${key}`, params[key]);
+        }
+
+        if (query && Object.keys(query).length > 0) {
+            url += "?" + new URLSearchParams(query).toString();
+        }
+
+        return url;
+    }
+
+    /**
+     * Get client-side route manifest for frontend navigation.
+     */
+    static getClientManifest() {
+        const manifest = {};
+        for (const route of this.#routes) {
+            if (route.name) {
+                manifest[route.name] = route.url;
+            }
+        }
+        return manifest;
+    }
+
+    /**
+     * Match a URL path to a route definition.
+     */
+    static match(pathname, method = "GET") {
+        for (const route of this.#routes) {
+            if (route.method !== method) continue;
+
+            const pattern = route.url
+                .replace(/:[^/]+/g, "([^/]+)")
+                .replace(/\//g, "\\/");
+            const regex = new RegExp(`^${pattern}$`);
+            const match = pathname.match(regex);
+
+            if (match) {
+                const paramNames = (route.url.match(/:[^/]+/g) || []).map(p => p.slice(1));
+                const params = {};
+                paramNames.forEach((name, i) => {
+                    params[name] = match[i + 1];
+                });
+                return { handler: route.handler, params, route };
+            }
+        }
+        return null;
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Internal Methods
+    // ─────────────────────────────────────────────────────────────────────────
+
+    static #addRoute(method, url, handler) {
+        const route = {
+            method,
+            url,
+            handler,
+            middlewares: [],
+            name: null
+        };
+
+        this.#routes.push(route);
+
+        return new RouteItem(route);
+    }
+
+    static async #getKernel() {
+        if (!this.#kernel) {
+            this.#kernel = (await import(Paths.kernelUrl())).default;
+        }
+        return this.#kernel;
+    }
+
+    // Legacy compatibility (used by View/Manager.js)
+    static getSessionConfig() {
+        return Config.all("session");
+    }
+
+    static async getKernel() {
+        return this.#getKernel();
+    }
+
+    // Alias for backwards compatibility
+    static route(name, params, query) {
+        return this.url(name, params, query);
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Route Item (Fluent API for single route)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class RouteItem {
+    constructor(route) {
+        this.route = route;
+    }
+
+    middleware(handlers) {
+        if (typeof handlers === "string") {
+            this.route.middlewares.push(handlers);
+        }
+        else if (Array.isArray(handlers)) {
+            this.route.middlewares.push(...handlers);
+        }
+
+        return this;
+    }
+
+    name(name) {
+        this.route.name = name;
+
+        return this;
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Route Group (Fluent API for grouped routes)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class RouteGroup {
+    constructor(options, routes) {
+        this.options = {
+            prefix: options.prefix || "",
+            middlewares: options.middlewares || [],
+            name: options.name || ""
+        };
+        this.routes = routes;
+    }
+
+    prefix(url) {
+        this.options.prefix = url;
+        return this;
+    }
+
+    middleware(handlers) {
+        if (typeof handlers === "string") {
+            this.options.middlewares.push(handlers);
+        }
+        else if (Array.isArray(handlers)) {
+            this.options.middlewares.push(...handlers);
+        }
+        
+        return this;
+    }
+
+    name(name) {
+        this.options.name = name;
+        return this;
+    }
+
+    group(callback) {
+        const beforeCount = this.routes.length;
+        callback();
+        const newRoutes = this.routes.slice(beforeCount);
+
+        for (const route of newRoutes) {
+            // Apply prefix
+            if (this.options.prefix) {
+                route.url = route.url === "/" 
+                    ? this.options.prefix 
+                    : this.options.prefix + route.url;
+            }
+
+            // Apply name prefix
+            if (route.name && this.options.name) {
+                route.name = this.options.name + route.name;
+            }
+
+            // Prepend middlewares
+            route.middlewares.unshift(...this.options.middlewares);
+        }
+    }
+}
+
+export default Router;