arcanajs 2.5.0 → 2.5.1

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

@@ -0,0 +1,94 @@
+import express, { Router as ExpressRouter, RequestHandler } from "express";
+/**
+ * Provides Routing syntax for defining routes with prefixes, middlewares, and groups
+ */
+export declare class Router {
+    private router;
+    private middlewareStack;
+    private prefixStack;
+    constructor();
+    /**
+     * Create a new router instance
+     */
+    static create(): Router;
+    /**
+     * Add middleware to the current stack
+     */
+    middleware(...middleware: RequestHandler[]): Router;
+    /**
+     * Add prefix to the current stack
+     */
+    prefix(prefix: string): Router;
+    /**
+     * Create a route group
+     */
+    group(callback: (router: Router) => void): Router;
+    /**
+     * Define a GET route
+     */
+    get(path: string, ...args: any[]): Router;
+    /**
+     * Define a POST route
+     */
+    post(path: string, ...args: any[]): Router;
+    /**
+     * Define a PUT route
+     */
+    put(path: string, ...args: any[]): Router;
+    /**
+     * Define a DELETE route
+     */
+    delete(path: string, ...args: any[]): Router;
+    /**
+     * Define a PATCH route
+     */
+    patch(path: string, ...args: any[]): Router;
+    /**
+     * Define an OPTIONS route
+     */
+    options(path: string, ...args: any[]): Router;
+    /**
+     * Get the underlying Express router
+     */
+    getRouter(): ExpressRouter;
+    /**
+     * Mount this router to an Express app or router
+     */
+    mount(app: express.Application | ExpressRouter, basePath?: string): void;
+    /**
+     * Clone the current router instance
+     */
+    private _clone;
+    /**
+     * Add a route to the router
+     */
+    private _addRoute;
+    /**
+     * Build the full path with prefixes
+     */
+    private _buildPath;
+    /**
+     * Build the route handler
+     */
+    private _buildHandler;
+}
+/**
+ * Static Route class for ArcanaJS Routing
+ */
+export declare class Route {
+    private static _router;
+    static create(): Router;
+    static middleware(...middleware: RequestHandler[]): Router;
+    static prefix(prefix: string): Router;
+    static group(callback: (router: Router) => void): Router;
+    static get(path: string, ...args: any[]): Router;
+    static post(path: string, ...args: any[]): Router;
+    static put(path: string, ...args: any[]): Router;
+    static delete(path: string, ...args: any[]): Router;
+    static patch(path: string, ...args: any[]): Router;
+    static options(path: string, ...args: any[]): Router;
+    static getRouter(): ExpressRouter;
+    static mount(app: express.Application, basePath?: string): void;
+    static reset(): void;
+}
+export default Route;

package/framework/lib/server/Router.js

@@ -0,0 +1,203 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = exports.Router = void 0;
+const express_1 = __importDefault(require("express"));
+const ControllerBinder_1 = __importDefault(require("./ControllerBinder"));
+/**
+ * Provides Routing syntax for defining routes with prefixes, middlewares, and groups
+ */
+class Router {
+    constructor() {
+        this.router = express_1.default.Router();
+        this.middlewareStack = [];
+        this.prefixStack = [];
+    }
+    /**
+     * Create a new router instance
+     */
+    static create() {
+        return new Router();
+    }
+    /**
+     * Add middleware to the current stack
+     */
+    middleware(...middleware) {
+        const newRouter = this._clone();
+        newRouter.middlewareStack = [...this.middlewareStack, ...middleware];
+        return newRouter;
+    }
+    /**
+     * Add prefix to the current stack
+     */
+    prefix(prefix) {
+        const newRouter = this._clone();
+        newRouter.prefixStack = [
+            ...this.prefixStack,
+            prefix.replace(/^\/|\/$/g, ""),
+        ];
+        return newRouter;
+    }
+    /**
+     * Create a route group
+     */
+    group(callback) {
+        callback(this);
+        return this;
+    }
+    /**
+     * Define a GET route
+     */
+    get(path, ...args) {
+        const action = args.pop();
+        const middlewares = args;
+        return this._addRoute("get", path, action, middlewares);
+    }
+    /**
+     * Define a POST route
+     */
+    post(path, ...args) {
+        const action = args.pop();
+        const middlewares = args;
+        return this._addRoute("post", path, action, middlewares);
+    }
+    /**
+     * Define a PUT route
+     */
+    put(path, ...args) {
+        const action = args.pop();
+        const middlewares = args;
+        return this._addRoute("put", path, action, middlewares);
+    }
+    /**
+     * Define a DELETE route
+     */
+    delete(path, ...args) {
+        const action = args.pop();
+        const middlewares = args;
+        return this._addRoute("delete", path, action, middlewares);
+    }
+    /**
+     * Define a PATCH route
+     */
+    patch(path, ...args) {
+        const action = args.pop();
+        const middlewares = args;
+        return this._addRoute("patch", path, action, middlewares);
+    }
+    /**
+     * Define an OPTIONS route
+     */
+    options(path, ...args) {
+        const action = args.pop();
+        const middlewares = args;
+        return this._addRoute("options", path, action, middlewares);
+    }
+    /**
+     * Get the underlying Express router
+     */
+    getRouter() {
+        return this.router;
+    }
+    /**
+     * Mount this router to an Express app or router
+     */
+    mount(app, basePath = "/") {
+        app.use(basePath, this.router);
+    }
+    /**
+     * Clone the current router instance
+     */
+    _clone() {
+        const newRouter = new Router();
+        newRouter.router = this.router;
+        newRouter.middlewareStack = [...this.middlewareStack];
+        newRouter.prefixStack = [...this.prefixStack];
+        return newRouter;
+    }
+    /**
+     * Add a route to the router
+     */
+    _addRoute(method, path, action, routeMiddlewares = []) {
+        const fullPath = this._buildPath(path);
+        const handler = this._buildHandler(action);
+        const flatMiddlewares = routeMiddlewares.flat(Infinity);
+        const middlewares = [...this.middlewareStack, ...flatMiddlewares, handler];
+        this.router[method](fullPath, ...middlewares);
+        return this;
+    }
+    /**
+     * Build the full path with prefixes
+     */
+    _buildPath(path) {
+        const cleanPath = path.replace(/^\//, "");
+        const prefixes = this.prefixStack.filter((p) => p !== "");
+        if (prefixes.length === 0) {
+            return `/${cleanPath}`;
+        }
+        return `/${prefixes.join("/")}/${cleanPath}`.replace(/\/+/g, "/");
+    }
+    /**
+     * Build the route handler
+     */
+    _buildHandler(action) {
+        if (typeof action === "function") {
+            return action;
+        }
+        if (Array.isArray(action) && action.length === 2) {
+            const [controller, method] = action;
+            return ControllerBinder_1.default.handle(controller, method);
+        }
+        throw new Error('Action must be a function or array [Controller, "method"]');
+    }
+}
+exports.Router = Router;
+/**
+ * Static Route class for ArcanaJS Routing
+ */
+class Route {
+    static create() {
+        return Router.create();
+    }
+    static middleware(...middleware) {
+        return this._router.middleware(...middleware);
+    }
+    static prefix(prefix) {
+        return this._router.prefix(prefix);
+    }
+    static group(callback) {
+        return this._router.group(callback);
+    }
+    static get(path, ...args) {
+        return this._router.get(path, ...args);
+    }
+    static post(path, ...args) {
+        return this._router.post(path, ...args);
+    }
+    static put(path, ...args) {
+        return this._router.put(path, ...args);
+    }
+    static delete(path, ...args) {
+        return this._router.delete(path, ...args);
+    }
+    static patch(path, ...args) {
+        return this._router.patch(path, ...args);
+    }
+    static options(path, ...args) {
+        return this._router.options(path, ...args);
+    }
+    static getRouter() {
+        return this._router.getRouter();
+    }
+    static mount(app, basePath = "/") {
+        return this._router.mount(app, basePath);
+    }
+    static reset() {
+        this._router = new Router();
+    }
+}
+exports.Route = Route;
+Route._router = new Router();
+exports.default = Route;

package/framework/lib/server/default-index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!--HEAD_CONTENT-->
+  </head>
+  <body>
+    <div id="root"><!--APP_CONTENT--></div>
+    <!--ARCANAJS_DATA_SCRIPT-->
+  </body>
+</html>

package/framework/lib/server.d.ts

@@ -0,0 +1,32 @@
+import { Express } from "express";
+import { ArcanaJSConfig, ArcanaJSServer } from "./server/ArcanaJSServer";
+export * from "./server/ArcanaJSMiddleware";
+export * from "./server/ArcanaJSServer";
+export { default as ControllerBinder } from "./server/ControllerBinder";
+export * from "./server/DynamicRouter";
+export * from "./server/Router";
+export { default as Route } from "./server/Router";
+export * from "./server/CsrfMiddleware";
+export * from "./server/ResponseHandlerMiddleware";
+/**
+ * Create an ArcanaJS server with the given Express app
+ *
+ * @param app - Express application instance
+ * @param config - Optional ArcanaJS configuration
+ * @returns ArcanaJSServer instance
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createArcanaServer } from 'arcanajs/server';
+ *
+ * const app = express();
+ * const server = createArcanaServer(app, {
+ *   port: 3000,
+ *   viewsDir: 'src/views',
+ * });
+ *
+ * server.start();
+ * ```
+ */
+export declare function createArcanaServer(app: Express, config?: Partial<ArcanaJSConfig>): ArcanaJSServer;

package/framework/lib/server.js

@@ -0,0 +1,69 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = exports.ControllerBinder = void 0;
+exports.createArcanaServer = createArcanaServer;
+const ArcanaJSServer_1 = require("./server/ArcanaJSServer");
+// ============================================================================
+// Server Core Exports
+// ============================================================================
+__exportStar(require("./server/ArcanaJSMiddleware"), exports);
+__exportStar(require("./server/ArcanaJSServer"), exports);
+var ControllerBinder_1 = require("./server/ControllerBinder");
+Object.defineProperty(exports, "ControllerBinder", { enumerable: true, get: function () { return __importDefault(ControllerBinder_1).default; } });
+// ============================================================================
+// Routing Exports
+// ============================================================================
+__exportStar(require("./server/DynamicRouter"), exports);
+__exportStar(require("./server/Router"), exports);
+var Router_1 = require("./server/Router");
+Object.defineProperty(exports, "Route", { enumerable: true, get: function () { return __importDefault(Router_1).default; } });
+// ============================================================================
+// Middleware Exports
+// ============================================================================
+__exportStar(require("./server/CsrfMiddleware"), exports);
+__exportStar(require("./server/ResponseHandlerMiddleware"), exports);
+// ============================================================================
+// Server Factory Function
+// ============================================================================
+/**
+ * Create an ArcanaJS server with the given Express app
+ *
+ * @param app - Express application instance
+ * @param config - Optional ArcanaJS configuration
+ * @returns ArcanaJSServer instance
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createArcanaServer } from 'arcanajs/server';
+ *
+ * const app = express();
+ * const server = createArcanaServer(app, {
+ *   port: 3000,
+ *   viewsDir: 'src/views',
+ * });
+ *
+ * server.start();
+ * ```
+ */
+function createArcanaServer(app, config) {
+    const server = new ArcanaJSServer_1.ArcanaJSServer({ ...config });
+    return server;
+}

package/framework/lib/shared/components/Body.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+interface BodyProps {
+    children: React.ReactNode;
+}
+export declare const Body: React.FC<BodyProps>;
+export {};

package/framework/lib/shared/components/Body.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Body = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const Body = ({ children }) => {
+    return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children });
+};
+exports.Body = Body;

package/framework/lib/shared/components/Head.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+export declare const Head: React.FC<{
+    children: React.ReactNode;
+}>;

package/framework/lib/shared/components/Head.js

@@ -0,0 +1,125 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Head = void 0;
+const react_1 = __importStar(require("react"));
+const useHead_1 = require("../hooks/useHead");
+const Head = ({ children }) => {
+    const headManager = (0, useHead_1.useHead)();
+    // Server-side: Push tags to context
+    if (typeof window === "undefined" && headManager) {
+        react_1.default.Children.forEach(children, (child) => {
+            if (react_1.default.isValidElement(child)) {
+                headManager.push(react_1.default.cloneElement(child, {
+                    "data-arcanajs-head": "true",
+                }));
+            }
+        });
+    }
+    // Client-side: Update DOM
+    (0, react_1.useEffect)(() => {
+        const managedElements = [];
+        react_1.default.Children.forEach(children, (child) => {
+            if (react_1.default.isValidElement(child)) {
+                const reactElement = child;
+                if (reactElement.type === "title") {
+                    document.title = reactElement.props.children;
+                }
+                else if (reactElement.type === "meta") {
+                    const props = reactElement.props;
+                    // Try to find existing meta tag
+                    let selector = "meta";
+                    if (props.name)
+                        selector += `[name="${props.name}"]`;
+                    if (props.property)
+                        selector += `[property="${props.property}"]`;
+                    // Only select if we have a specific identifier
+                    if (props.name || props.property) {
+                        let element = document.querySelector(selector + '[data-arcanajs-head="true"]') || document.querySelector(selector);
+                        if (element) {
+                            // Update existing
+                            element.setAttribute("content", props.content);
+                            element.setAttribute("data-arcanajs-head", "true");
+                            managedElements.push(element);
+                        }
+                        else {
+                            // Create new
+                            const newMeta = document.createElement("meta");
+                            Object.keys(props).forEach((key) => {
+                                newMeta.setAttribute(key, props[key]);
+                            });
+                            newMeta.setAttribute("data-arcanajs-head", "true");
+                            document.head.appendChild(newMeta);
+                            managedElements.push(newMeta);
+                        }
+                    }
+                }
+                else if (reactElement.type === "link") {
+                    const props = reactElement.props;
+                    let selector = "link";
+                    if (props.rel)
+                        selector += `[rel="${props.rel}"]`;
+                    if (props.href)
+                        selector += `[href="${props.href}"]`;
+                    let element = document.querySelector(selector + '[data-arcanajs-head="true"]') ||
+                        document.querySelector(selector);
+                    if (element) {
+                        element.setAttribute("data-arcanajs-head", "true");
+                        managedElements.push(element);
+                    }
+                    else {
+                        const newLink = document.createElement("link");
+                        Object.keys(props).forEach((key) => {
+                            newLink.setAttribute(key, props[key]);
+                        });
+                        newLink.setAttribute("data-arcanajs-head", "true");
+                        document.head.appendChild(newLink);
+                        managedElements.push(newLink);
+                    }
+                }
+            }
+        });
+        return () => {
+            // Cleanup managed elements
+            managedElements.forEach((el) => {
+                // We remove the element to ensure clean state for the next page
+                // Note: This might cause a momentary flicker if the next page re-adds it immediately
+                el.remove();
+            });
+        };
+    }, [children]);
+    return null;
+};
+exports.Head = Head;

package/framework/lib/shared/components/Link.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+    href: string;
+    prefetch?: boolean;
+}
+export declare const Link: React.FC<LinkProps>;
+export {};

package/framework/lib/shared/components/Link.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Link = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const useRouter_1 = require("../hooks/useRouter");
+const Link = ({ href, children, prefetch = false, ...props }) => {
+    const { navigateTo } = (0, useRouter_1.useRouter)();
+    const isExternal = /^https?:\/\//.test(href);
+    const handleClick = (e) => {
+        e.preventDefault();
+        if (!isExternal) {
+            navigateTo(href);
+        }
+        else {
+            // Open external links in a new tab
+            window.open(href, "_blank", "noopener,noreferrer");
+        }
+    };
+    const handleMouseEnter = () => {
+        if (prefetch && !isExternal) {
+            // Prefetch using HEAD request to warm cache
+            fetch(href, { method: "HEAD" }).catch(() => { });
+        }
+    };
+    return ((0, jsx_runtime_1.jsx)("a", { href: href, onClick: handleClick, onMouseEnter: handleMouseEnter, target: isExternal ? "_blank" : undefined, rel: isExternal ? "noopener noreferrer" : undefined, ...props, children: children }));
+};
+exports.Link = Link;

package/framework/lib/shared/components/NavLink.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+interface NavLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+    href: string;
+    activeClassName?: string;
+    exact?: boolean;
+    prefetch?: boolean;
+}
+export declare const NavLink: React.FC<NavLinkProps>;
+export {};

package/framework/lib/shared/components/NavLink.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NavLink = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const useRouter_1 = require("../hooks/useRouter");
+const Link_1 = require("./Link");
+const NavLink = ({ href, activeClassName = "active", className = "", exact = false, prefetch = false, children, ...props }) => {
+    const { currentUrl } = (0, useRouter_1.useRouter)();
+    const isActive = exact ? currentUrl === href : currentUrl.startsWith(href);
+    const combinedClassName = `${className} ${isActive ? activeClassName : ""}`.trim();
+    return ((0, jsx_runtime_1.jsx)(Link_1.Link, { href: href, className: combinedClassName, prefetch: prefetch, ...props, children: children }));
+};
+exports.NavLink = NavLink;

package/framework/lib/shared/components/Page.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+export declare const Page: React.FC<{
+    data?: any;
+    title?: string;
+    children: React.ReactNode;
+}>;

package/framework/lib/shared/components/Page.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Page = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const PageContext_1 = require("../context/PageContext");
+const Head_1 = require("./Head");
+const Page = ({ data, title, children }) => {
+    return ((0, jsx_runtime_1.jsxs)(PageContext_1.PageContext.Provider, { value: data, children: [title && ((0, jsx_runtime_1.jsx)(Head_1.Head, { children: (0, jsx_runtime_1.jsx)("title", { children: title }) })), children] }));
+};
+exports.Page = Page;

package/framework/lib/shared/context/HeadContext.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+export interface HeadManager {
+    tags: React.ReactNode[];
+    push: (tags: React.ReactNode) => void;
+}
+export declare const HeadContext: React.Context<HeadManager | null>;

package/framework/lib/shared/context/HeadContext.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HeadContext = void 0;
+const createSingletonContext_1 = require("../utils/createSingletonContext");
+exports.HeadContext = (0, createSingletonContext_1.createSingletonContext)("HeadContext", null);

package/framework/lib/shared/context/PageContext.d.ts

@@ -0,0 +1 @@
+export declare const PageContext: import("react").Context<any>;

package/framework/lib/shared/context/PageContext.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageContext = void 0;
+const createSingletonContext_1 = require("../utils/createSingletonContext");
+exports.PageContext = (0, createSingletonContext_1.createSingletonContext)("PageContext", null);