arcanajs 2.5.0 → 2.5.1

package/framework/lib/server/ArcanaJSServer.js

@@ -0,0 +1,441 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArcanaJSServer = void 0;
+const compression_1 = __importDefault(require("compression"));
+const cookie_parser_1 = __importDefault(require("cookie-parser"));
+const express_1 = __importDefault(require("express"));
+const fs_1 = __importDefault(require("fs"));
+const helmet_1 = __importDefault(require("helmet"));
+const path_1 = __importDefault(require("path"));
+const ErrorPage_1 = __importDefault(require("../shared/views/ErrorPage"));
+const NotFoundPage_1 = __importDefault(require("../shared/views/NotFoundPage"));
+const ArcanaJSMiddleware_1 = require("./ArcanaJSMiddleware");
+const CsrfMiddleware_1 = require("./CsrfMiddleware");
+const DynamicRouter_1 = require("./DynamicRouter");
+const ResponseHandlerMiddleware_1 = require("./ResponseHandlerMiddleware");
+class ArcanaJSServer {
+    constructor(config) {
+        this.config = config;
+        this.app = (0, express_1.default)();
+        this.initialize();
+    }
+    /**
+     * Normalize different DB client shapes into a single object exposing:
+     * { client?: any, db?: any, close: async () => void }
+     */
+    normalizeDb(obj) {
+        if (!obj)
+            return obj;
+        // If already normalized (has close function), return as-is
+        if (typeof obj.close === "function") {
+            return obj;
+        }
+        // Mongoose instance
+        if (typeof obj.disconnect === "function") {
+            return {
+                client: obj,
+                close: async () => {
+                    await obj.disconnect();
+                },
+            };
+        }
+        // If object contains { client, db }
+        if (obj.client && obj.db) {
+            const client = obj.client;
+            return {
+                client,
+                db: obj.db,
+                close: async () => {
+                    if (client && typeof client.close === "function") {
+                        await client.close();
+                    }
+                    else if (client && typeof client.disconnect === "function") {
+                        await client.disconnect();
+                    }
+                    else {
+                        throw new Error("No close method on client");
+                    }
+                },
+            };
+        }
+        // Native MongoClient instance
+        if (obj && typeof obj.close === "function" && obj.connect) {
+            return {
+                client: obj,
+                close: async () => {
+                    await obj.close();
+                },
+            };
+        }
+        // Pg/mysql client with end()/query()
+        if (typeof obj.end === "function" || typeof obj.query === "function") {
+            return {
+                client: obj,
+                close: async () => {
+                    if (typeof obj.end === "function") {
+                        await obj.end();
+                    }
+                    else if (typeof obj.close === "function") {
+                        await obj.close();
+                    }
+                    else {
+                        throw new Error("No close/end method on SQL client");
+                    }
+                },
+            };
+        }
+        // Try internal mongo client path { s: { client } }
+        if (obj.s && obj.s.client && typeof obj.s.client.close === "function") {
+            return {
+                client: obj.s.client,
+                db: obj,
+                close: async () => {
+                    await obj.s.client.close();
+                },
+            };
+        }
+        // Fallback: wrap with a close that throws to surface the issue
+        return {
+            client: obj,
+            close: async () => {
+                throw new Error("No known close method on DB client");
+            },
+        };
+    }
+    initialize() {
+        const { staticDir = "public", distDir = "dist/public", indexFile = "dist/public/index.html", views, viewsContext, routes, layout, apiRoutes, apiBase = "/api", } = this.config;
+        const root = process.cwd();
+        // 1. Resolve views once and in priority order
+        let resolvedViews = views;
+        if (!resolvedViews && viewsContext)
+            resolvedViews = this.loadViewsFromContext(viewsContext);
+        if (!resolvedViews)
+            resolvedViews = this.loadViewsFromAlias();
+        if (!resolvedViews)
+            resolvedViews = this.discoverViews();
+        if (!resolvedViews || Object.keys(resolvedViews).length === 0) {
+            console.warn("No views found. Please check your views directory.");
+            resolvedViews = {};
+        }
+        resolvedViews.NotFoundPage = resolvedViews.NotFoundPage || NotFoundPage_1.default;
+        resolvedViews.ErrorPage = resolvedViews.ErrorPage || ErrorPage_1.default;
+        // Security headers
+        this.app.use((0, helmet_1.default)({ contentSecurityPolicy: false }));
+        this.app.use((0, cookie_parser_1.default)());
+        this.app.use((0, CsrfMiddleware_1.createCsrfMiddleware)());
+        this.app.use(ResponseHandlerMiddleware_1.responseHandler);
+        // Expose `req.db` for convenience
+        this.app.use((req, _res, next) => {
+            req.db = this.app.locals.db;
+            next();
+        });
+        // Static files: resolve and dedupe paths, serve before compression to avoid recompressing static files
+        const isProduction = process.env.NODE_ENV === "production";
+        const staticOptions = { index: false, maxAge: isProduction ? "1y" : "0" };
+        const staticPaths = [
+            path_1.default.resolve(root, distDir),
+            path_1.default.resolve(root, staticDir),
+        ].filter((p, i, a) => a.indexOf(p) === i);
+        for (const p of staticPaths) {
+            this.app.use(express_1.default.static(p, staticOptions));
+        }
+        // Compression for dynamic responses (after static middleware)
+        this.app.use((0, compression_1.default)());
+        // ArcanaJS Middleware
+        this.app.use((0, ArcanaJSMiddleware_1.createArcanaJSMiddleware)({
+            views: resolvedViews,
+            indexFile: path_1.default.resolve(root, indexFile),
+            layout,
+        }));
+        // Establish DB connection if provided (normalize eagerly where possible)
+        if (this.config.dbConnect) {
+            try {
+                const maybe = this.config.dbConnect();
+                const handleDb = (db) => {
+                    try {
+                        this.app.locals.db = this.normalizeDb(db) || db;
+                        console.log("Database connection attached to app.locals.db");
+                    }
+                    catch (e) {
+                        this.app.locals.db = db;
+                        console.warn("DB connection attached without full normalization", e);
+                    }
+                };
+                if (maybe &&
+                    maybe.then &&
+                    typeof maybe.then === "function") {
+                    maybe
+                        .then(handleDb)
+                        .catch((err) => console.error("Error establishing DB connection:", err));
+                }
+                else {
+                    handleDb(maybe);
+                }
+            }
+            catch (err) {
+                console.error("Error calling dbConnect:", err);
+            }
+        }
+        // Helper to mount arrays or single route objects
+        const mount = (target, base) => {
+            if (!target)
+                return;
+            const items = Array.isArray(target) ? target : [target];
+            for (const r of items) {
+                if (!r)
+                    continue;
+                if (typeof r.getRouter === "function") {
+                    this.app.use(base || "/", r.getRouter());
+                }
+                else {
+                    this.app.use(base || "/", r);
+                }
+            }
+        };
+        try {
+            mount(apiRoutes, apiBase);
+            if (apiRoutes)
+                console.log(`API routes mounted at ${apiBase}`);
+        }
+        catch (err) {
+            console.error("Error mounting apiRoutes:", err);
+        }
+        try {
+            mount(routes);
+        }
+        catch (err) {
+            console.error("Error mounting routes:", err);
+        }
+        // Dynamic Router
+        this.app.use((0, DynamicRouter_1.createDynamicRouter)(resolvedViews));
+        // 404 and error handlers
+        this.app.use((req, res) => {
+            if (req.get("X-ArcanaJS-Request") || req.query.format === "json") {
+                res.status(404).json({
+                    page: "NotFoundPage",
+                    data: {},
+                    params: {},
+                    csrfToken: res.locals.csrfToken,
+                });
+            }
+            else {
+                res.status(404).renderPage("NotFoundPage");
+            }
+        });
+        this.app.use((err, req, res, next) => {
+            console.error(err);
+            const message = process.env.NODE_ENV === "production"
+                ? "Internal Server Error"
+                : err.message;
+            if (req.get("X-ArcanaJS-Request") || req.query.format === "json") {
+                res.status(500).json({
+                    page: "ErrorPage",
+                    data: { message },
+                    params: {},
+                    csrfToken: res.locals.csrfToken,
+                });
+            }
+            else {
+                res.status(500).renderPage("ErrorPage", { message });
+            }
+        });
+    }
+    loadViewsFromContext(context) {
+        const views = {};
+        context.keys().forEach((key) => {
+            const viewName = key.replace(/^\.\/(.*)\.tsx$/, "$1");
+            views[viewName] = context(key).default;
+        });
+        return views;
+    }
+    loadViewsFromAlias() {
+        try {
+            // @ts-ignore - This alias is injected by Webpack
+            const injectedViews = require("arcana-views");
+            if (injectedViews) {
+                return this.loadViewsFromContext(injectedViews);
+            }
+        }
+        catch (e) {
+            // Ignore
+        }
+        return undefined;
+    }
+    discoverViews() {
+        const views = {};
+        const viewsDir = this.config.viewsDir
+            ? path_1.default.resolve(process.cwd(), this.config.viewsDir)
+            : path_1.default.resolve(process.cwd(), "src/views");
+        if (!fs_1.default.existsSync(viewsDir))
+            return views;
+        const traverse = (dir) => {
+            const files = fs_1.default.readdirSync(dir);
+            files.forEach((file) => {
+                const fullPath = path_1.default.join(dir, file);
+                const stat = fs_1.default.statSync(fullPath);
+                if (stat.isDirectory()) {
+                    traverse(fullPath);
+                }
+                else if (file.endsWith(".tsx") || file.endsWith(".jsx")) {
+                    const relativePath = path_1.default.relative(viewsDir, fullPath);
+                    const viewName = relativePath.replace(/\.(tsx|jsx)$/, "");
+                    try {
+                        // Use __non_webpack_require__ if available to avoid Webpack bundling issues
+                        // or standard require if running in Node directly
+                        const requireFunc = typeof __non_webpack_require__ !== "undefined"
+                            ? __non_webpack_require__
+                            : eval("require");
+                        // Register ts-node if needed
+                        if (file.endsWith(".tsx") || file.endsWith(".ts")) {
+                            try {
+                                requireFunc("ts-node/register");
+                            }
+                            catch (e) {
+                                // Ignore
+                            }
+                        }
+                        const pageModule = requireFunc(fullPath);
+                        views[viewName] = pageModule.default || pageModule;
+                    }
+                    catch (error) {
+                        console.error(`Failed to load view ${viewName}:`, error);
+                    }
+                }
+            });
+        };
+        traverse(viewsDir);
+        return views;
+    }
+    start() {
+        const PORT = this.config.port || process.env.PORT || 3000;
+        this.serverInstance = this.app.listen(PORT, () => {
+            console.log(`Server is running on http://localhost:${PORT}`);
+        });
+        // Optionally register process signal handlers per-instance to gracefully shutdown
+        const autoHandle = this.config.autoHandleSignals !== false;
+        if (autoHandle) {
+            const shutdown = async () => {
+                try {
+                    await this.stop();
+                    process.exit(0);
+                }
+                catch (err) {
+                    console.error("Error during shutdown:", err);
+                    process.exit(1);
+                }
+            };
+            this._sigintHandler = shutdown;
+            this._sigtermHandler = shutdown;
+            process.on("SIGINT", this._sigintHandler);
+            process.on("SIGTERM", this._sigtermHandler);
+        }
+    }
+    /**
+     * Stop the HTTP server and close DB connection if present.
+     */
+    async stop() {
+        // Close HTTP server
+        if (this.serverInstance) {
+            await new Promise((resolve, reject) => {
+                this.serverInstance.close((err) => {
+                    if (err)
+                        return reject(err);
+                    resolve();
+                });
+            });
+            this.serverInstance = undefined;
+            console.log("HTTP server stopped");
+        }
+        // Close DB connection if attached to app.locals.db
+        const db = this.app.locals.db;
+        if (db) {
+            let closed = false;
+            // Try mongoose.disconnect()
+            try {
+                if (typeof db.disconnect === "function") {
+                    await db.disconnect();
+                    closed = true;
+                    console.log("Database connection closed via disconnect().");
+                }
+            }
+            catch (err) {
+                console.error("Error calling disconnect() on DB client:", err);
+            }
+            // Try db.close()
+            if (!closed) {
+                try {
+                    if (typeof db.close === "function") {
+                        await db.close();
+                        closed = true;
+                        console.log("Database connection closed via close().");
+                    }
+                }
+                catch (err) {
+                    console.error("Error calling close() on DB client:", err);
+                }
+            }
+            // Try db.end()
+            if (!closed) {
+                try {
+                    if (typeof db.end === "function") {
+                        await db.end();
+                        closed = true;
+                        console.log("Database connection closed via end().");
+                    }
+                }
+                catch (err) {
+                    console.error("Error calling end() on DB client:", err);
+                }
+            }
+            // Try db.client?.close()
+            if (!closed) {
+                try {
+                    const clientClose = db.client && db.client.close;
+                    if (clientClose && typeof clientClose === "function") {
+                        await db.client.close();
+                        closed = true;
+                        console.log("Database connection closed via db.client.close().");
+                    }
+                }
+                catch (err) {
+                    console.error("Error calling db.client.close() on DB client:", err);
+                }
+            }
+            // Try db.s?.client?.close() (internal Mongo client path)
+            if (!closed) {
+                try {
+                    const maybeInternal = db.s && db.s.client && db.s.client.close;
+                    if (maybeInternal && typeof maybeInternal === "function") {
+                        await db.s.client.close();
+                        closed = true;
+                        console.log("Database connection closed via db.s.client.close().");
+                    }
+                }
+                catch (err) {
+                    console.error("Error calling db.s.client.close() on DB client:", err);
+                }
+            }
+            if (!closed) {
+                console.warn("Could not find a supported close method on the DB client; connection may remain open.");
+            }
+        }
+        // Remove signal handlers registered by this instance
+        try {
+            if (this._sigintHandler) {
+                process.removeListener("SIGINT", this._sigintHandler);
+                this._sigintHandler = undefined;
+            }
+            if (this._sigtermHandler) {
+                process.removeListener("SIGTERM", this._sigtermHandler);
+                this._sigtermHandler = undefined;
+            }
+        }
+        catch (err) {
+            // ignore errors while removing listeners
+        }
+    }
+}
+exports.ArcanaJSServer = ArcanaJSServer;

package/framework/lib/server/ControllerBinder.d.ts

@@ -0,0 +1,4 @@
+import { NextFunction, Request, Response } from "express";
+export default class ControllerBinder {
+    static handle(controller: any, method: string): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+}

package/framework/lib/server/ControllerBinder.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+class ControllerBinder {
+    static handle(controller, method) {
+        // Instantiate the controller once (Singleton pattern) for performance
+        // This assumes controllers are stateless, which is best practice.
+        let instance;
+        try {
+            instance = new controller();
+        }
+        catch (e) {
+            // Fallback if controller is not a class or fails to instantiate
+            console.warn(`Failed to instantiate controller ${controller.name}`, e);
+            instance = controller;
+        }
+        return async (req, res, next) => {
+            try {
+                // Call the method
+                if (typeof instance[method] === "function") {
+                    await instance[method](req, res, next);
+                }
+                else {
+                    throw new Error(`Method ${method} not found on controller ${controller.name}`);
+                }
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+    }
+}
+exports.default = ControllerBinder;

package/framework/lib/server/CsrfMiddleware.d.ts

@@ -0,0 +1,2 @@
+import { NextFunction, Request, Response } from "express";
+export declare const createCsrfMiddleware: () => (req: Request, res: Response, next: NextFunction) => Response<any, Record<string, any>> | undefined;

package/framework/lib/server/CsrfMiddleware.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCsrfMiddleware = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const CSRF_COOKIE_NAME = "_csrf";
+const createCsrfMiddleware = () => {
+    return (req, res, next) => {
+        // 1. Generate or retrieve token
+        let token = req.cookies[CSRF_COOKIE_NAME];
+        if (!token) {
+            token = crypto_1.default.randomBytes(32).toString("hex");
+            res.cookie(CSRF_COOKIE_NAME, token, {
+                httpOnly: true,
+                secure: process.env.NODE_ENV === "production",
+                sameSite: "strict",
+            });
+        }
+        // 2. Expose token to the response locals (for injection into the view)
+        res.locals.csrfToken = token;
+        // 3. Verify token on state-changing methods
+        const method = req.method.toUpperCase();
+        if (["POST", "PUT", "DELETE", "PATCH"].includes(method)) {
+            const headerToken = req.headers["x-csrf-token"];
+            if (!headerToken || headerToken !== token) {
+                return res.status(403).json({ error: "Invalid CSRF Token" });
+            }
+        }
+        next();
+    };
+};
+exports.createCsrfMiddleware = createCsrfMiddleware;

package/framework/lib/server/DynamicRouter.d.ts

@@ -0,0 +1,2 @@
+import { NextFunction, Request, Response } from "express";
+export declare const createDynamicRouter: (views: Record<string, any>) => (req: Request, res: Response, next: NextFunction) => Express.Response | undefined;

package/framework/lib/server/DynamicRouter.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDynamicRouter = void 0;
+const createDynamicRouter = (views) => {
+    return (req, res, next) => {
+        // Remove leading slash
+        let path = req.path.substring(1);
+        // Handle root path mapping to "index" if not handled elsewhere
+        if (path === "") {
+            path = "index";
+        }
+        // 1. Exact match
+        if (views[path]) {
+            return res.renderPage(path, {});
+        }
+        // 2. Dynamic match
+        for (const viewName of Object.keys(views)) {
+            if (!viewName.includes("["))
+                continue;
+            // Convert view path to regex
+            // e.g., "users/[id]" -> "^users/([^/]+)$"
+            // We need to escape special regex characters first, but keep [ and ] for our logic
+            // Actually, simpler: split by '/' and match segments
+            const pageParts = viewName.split("/");
+            const pathParts = path.split("/");
+            if (pageParts.length !== pathParts.length)
+                continue;
+            let match = true;
+            const params = {};
+            for (let i = 0; i < pageParts.length; i++) {
+                const pagePart = pageParts[i];
+                const pathPart = pathParts[i];
+                if (pagePart.startsWith("[") && pagePart.endsWith("]")) {
+                    const paramName = pagePart.slice(1, -1);
+                    params[paramName] = pathPart;
+                }
+                else if (pagePart !== pathPart) {
+                    match = false;
+                    break;
+                }
+            }
+            if (match) {
+                return res.renderPage(viewName, {}, params);
+            }
+        }
+        // If not found, pass to the next middleware (usually 404 handler)
+        next();
+    };
+};
+exports.createDynamicRouter = createDynamicRouter;

package/framework/lib/server/ResponseHandlerMiddleware.d.ts

@@ -0,0 +1,27 @@
+import type { NextFunction, Request, Response } from "express";
+declare global {
+    namespace Express {
+        interface Response {
+            /**
+             * Sends a success response with a standard format.
+             *
+             * @param data - The data payload to include in the response (default: {}).
+             * @param message - A descriptive message for the success (default: "Success").
+             * @param status - The HTTP status code to return (default: 200).
+             * @returns The Express Response object.
+             */
+            success: (data?: string | object | null, message?: string, status?: number) => Response;
+            /**
+             * Sends an error response with a standard format.
+             *
+             * @param message - A descriptive message for the error (default: "Error").
+             * @param status - The HTTP status code to return (default: 500).
+             * @param error - Additional error details or object (default: null).
+             * @param data - Optional data payload to include in the error response (default: null).
+             * @returns The Express Response object.
+             */
+            error: (message?: string, status?: number, error?: string | object | null, data?: string | object | null) => Response;
+        }
+    }
+}
+export declare const responseHandler: (req: Request, res: Response, next: NextFunction) => void;

package/framework/lib/server/ResponseHandlerMiddleware.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.responseHandler = void 0;
+const responseHandler = (req, res, next) => {
+    res.success = (data = {}, message = "Success", status = 200) => {
+        return res.status(status).json({
+            success: true,
+            message,
+            data,
+            error: null,
+        });
+    };
+    res.error = (message = "Error", status = 500, error = null, data = null) => {
+        const errorResponse = error
+            ? typeof error === "object" && error !== null
+                ? error instanceof Error
+                    ? error.toString()
+                    : error
+                : error.toString()
+            : null;
+        return res.status(status).json({
+            success: false,
+            message,
+            data,
+            error: errorResponse,
+        });
+    };
+    next();
+};
+exports.responseHandler = responseHandler;