arcanajs 2.5.0 → 2.5.2

package/framework/lib/client/index.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hydrateArcanaJS = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const client_1 = require("react-dom/client");
+const HeadContext_1 = require("../shared/context/HeadContext");
+const ArcanaJSApp_1 = require("../shared/core/ArcanaJSApp");
+const ErrorPage_1 = __importDefault(require("../shared/views/ErrorPage"));
+const NotFoundPage_1 = __importDefault(require("../shared/views/NotFoundPage"));
+// ============================================================================
+// Client Hydration Function
+// ============================================================================
+/**
+ * Hydrate the ArcanaJS application on the client side
+ *
+ * This function initializes the React application on the client,
+ * hydrating the server-rendered HTML with client-side interactivity.
+ *
+ * @param viewsOrContext - Either a views registry object or a webpack require.context
+ * @param layout - Optional layout component to wrap all pages
+ * @param options - Optional navigation configuration options
+ *
+ * @example
+ * ```typescript
+ * // Using webpack require.context (recommended)
+ * import { hydrateArcanaJS } from 'arcanajs/client';
+ *
+ * const views = require.context('./views', false, /\.tsx$/);
+ * hydrateArcanaJS(views);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using manual views registry
+ * import { hydrateArcanaJS } from 'arcanajs/client';
+ * import HomePage from './views/HomePage';
+ * import AboutPage from './views/AboutPage';
+ *
+ * hydrateArcanaJS({
+ *   HomePage,
+ *   AboutPage,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With navigation options
+ * import { hydrateArcanaJS } from 'arcanajs/client';
+ *
+ * const views = require.context('./views', false, /\.tsx$/);
+ * hydrateArcanaJS(views, undefined, {
+ *   onNavigate: (url) => {
+ *     // Track page views
+ *     gtag('event', 'page_view', { page_path: url });
+ *   }
+ * });
+ * ```
+ */
+const hydrateArcanaJS = (viewsOrContext, layout, options) => {
+    let views = {};
+    if (viewsOrContext.keys && typeof viewsOrContext.keys === "function") {
+        viewsOrContext.keys().forEach((key) => {
+            const viewName = key.replace(/^\.\/(.*)\.tsx$/, "$1");
+            views[viewName] = viewsOrContext(key).default;
+        });
+    }
+    else {
+        views = viewsOrContext;
+    }
+    // Add default error views if not present
+    if (!views["NotFoundPage"]) {
+        views["NotFoundPage"] = NotFoundPage_1.default;
+    }
+    if (!views["ErrorPage"]) {
+        views["ErrorPage"] = ErrorPage_1.default;
+    }
+    const container = document.getElementById("root");
+    const dataScript = document.getElementById("__ARCANAJS_DATA__");
+    // Client-side HeadManager (noop for push, as Head handles client updates via useEffect)
+    const headManager = {
+        tags: [],
+        push: () => { },
+    };
+    if (container && dataScript) {
+        try {
+            const { page, data, params, csrfToken } = JSON.parse(dataScript.textContent || "{}");
+            (0, client_1.hydrateRoot)(container, (0, jsx_runtime_1.jsx)(HeadContext_1.HeadContext.Provider, { value: headManager, children: (0, jsx_runtime_1.jsx)(ArcanaJSApp_1.ArcanaJSApp, { initialPage: page, initialData: data, initialParams: params, csrfToken: csrfToken, views: views, layout: layout, onNavigate: options?.onNavigate || (() => { }) }) }));
+        }
+        catch (e) {
+            console.error("Failed to parse initial data", e);
+        }
+    }
+};
+exports.hydrateArcanaJS = hydrateArcanaJS;

package/framework/lib/config/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ArcanaJS Configuration System
+ *
+ * Provides utilities for loading and validating ArcanaJS configuration files.
+ */
+import type { ArcanaJSUserConfig, ResolvedArcanaJSConfig } from "../types";
+/**
+ * Define a configuration object with type safety
+ *
+ * @example
+ * ```typescript
+ * export default defineConfig({
+ *   server: {
+ *     port: 3000,
+ *   },
+ * });
+ * ```
+ */
+export declare function defineConfig(config: ArcanaJSUserConfig): ArcanaJSUserConfig;
+/**
+ * Load ArcanaJS configuration from project root
+ *
+ * Searches for:
+ * - arcanajs.config.js
+ * - arcanajs.config.ts
+ * - arcanajs.config.mjs
+ *
+ * @param root - Project root directory (defaults to process.cwd())
+ * @returns User configuration object or empty object if not found
+ */
+export declare function loadConfig(root?: string): Promise<ArcanaJSUserConfig>;
+/**
+ * Resolve user configuration with defaults
+ *
+ * @param userConfig - User-provided configuration
+ * @param root - Project root directory
+ * @returns Fully resolved configuration with all defaults applied
+ */
+export declare function resolveConfig(userConfig: ArcanaJSUserConfig, root?: string): ResolvedArcanaJSConfig;
+/**
+ * Load and resolve configuration in one step
+ *
+ * @param root - Project root directory
+ * @returns Fully resolved configuration
+ */
+export declare function loadAndResolveConfig(root?: string): Promise<ResolvedArcanaJSConfig>;

package/framework/lib/config/index.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * ArcanaJS Configuration System
+ *
+ * Provides utilities for loading and validating ArcanaJS configuration files.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineConfig = defineConfig;
+exports.loadConfig = loadConfig;
+exports.resolveConfig = resolveConfig;
+exports.loadAndResolveConfig = loadAndResolveConfig;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Define a configuration object with type safety
+ *
+ * @example
+ * ```typescript
+ * export default defineConfig({
+ *   server: {
+ *     port: 3000,
+ *   },
+ * });
+ * ```
+ */
+function defineConfig(config) {
+    return config;
+}
+/**
+ * Load ArcanaJS configuration from project root
+ *
+ * Searches for:
+ * - arcanajs.config.js
+ * - arcanajs.config.ts
+ * - arcanajs.config.mjs
+ *
+ * @param root - Project root directory (defaults to process.cwd())
+ * @returns User configuration object or empty object if not found
+ */
+async function loadConfig(root = process.cwd()) {
+    const configFiles = [
+        "arcanajs.config.js",
+        "arcanajs.config.ts",
+        "arcanajs.config.mjs",
+    ];
+    for (const configFile of configFiles) {
+        const configPath = path_1.default.resolve(root, configFile);
+        if (fs_1.default.existsSync(configPath)) {
+            try {
+                // For TypeScript files, we need ts-node or tsx
+                if (configFile.endsWith(".ts")) {
+                    try {
+                        require("tsx/cjs");
+                    }
+                    catch {
+                        try {
+                            require("ts-node/register");
+                        }
+                        catch {
+                            console.warn(`Found ${configFile} but ts-node/tsx is not available. Skipping.`);
+                            continue;
+                        }
+                    }
+                }
+                const config = require(configPath);
+                return config.default || config;
+            }
+            catch (error) {
+                console.error(`Error loading config from ${configPath}:`, error);
+            }
+        }
+    }
+    return {};
+}
+/**
+ * Resolve user configuration with defaults
+ *
+ * @param userConfig - User-provided configuration
+ * @param root - Project root directory
+ * @returns Fully resolved configuration with all defaults applied
+ */
+function resolveConfig(userConfig, root = process.cwd()) {
+    const mode = process.env.NODE_ENV || "development";
+    return {
+        root,
+        mode,
+        server: {
+            port: userConfig.server?.port || process.env.PORT || 3000,
+            staticDir: userConfig.server?.staticDir || "public",
+            distDir: userConfig.server?.distDir || "dist/public",
+        },
+        build: {
+            outDir: userConfig.build?.outDir || "dist",
+            sourcemap: userConfig.build?.sourcemap ?? mode === "development",
+            minify: userConfig.build?.minify ?? mode === "production",
+        },
+        views: {
+            dir: userConfig.views?.dir || "src/views",
+            layout: userConfig.views?.layout,
+        },
+    };
+}
+/**
+ * Load and resolve configuration in one step
+ *
+ * @param root - Project root directory
+ * @returns Fully resolved configuration
+ */
+async function loadAndResolveConfig(root = process.cwd()) {
+    const userConfig = await loadConfig(root);
+    return resolveConfig(userConfig, root);
+}

package/framework/lib/global.d.ts

@@ -0,0 +1,65 @@
+// ============================================================================
+// CSS Module Declarations
+// ============================================================================
+
+// Global CSS files
+declare module "*.css";
+
+// CSS Modules
+declare module "*.module.css" {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}
+
+// ============================================================================
+// Express Augmentation
+// ============================================================================
+
+declare global {
+  var __non_webpack_require__: NodeJS.Require;
+  namespace Express {
+    interface Request {
+      /**
+       * Normalized DB object optionally attached to the request by ArcanaJSServer.
+       * It may be either the raw client, or an object like `{ client, db, close }`.
+       */
+      db?: any;
+    }
+    interface Response {
+      /**
+       * Render a page component with data
+       * @param page - Name of the page component to render
+       * @param data - Data to pass to the page component
+       */
+      renderPage(page: string, data?: any): void;
+
+      /**
+       * Send a success JSON response
+       * @param data - Data to send in the response
+       * @param message - Optional success message
+       * @param status - HTTP status code (default: 200)
+       */
+      success(
+        data?: string | object | null,
+        message?: string,
+        status?: number
+      ): Response;
+
+      /**
+       * Send an error JSON response
+       * @param message - Error message
+       * @param status - HTTP status code (default: 500)
+       * @param error - Error details
+       * @param data - Additional error data
+       */
+      error(
+        message?: string,
+        status?: number,
+        error?: string | object | null,
+        data?: string | object | null
+      ): Response;
+    }
+  }
+}
+
+export {};

package/framework/lib/index.d.ts

@@ -0,0 +1,19 @@
+/// <reference path="./global.d.ts" />
+export * from "./shared/components/Body";
+export * from "./shared/components/Head";
+export * from "./shared/components/Link";
+export * from "./shared/components/NavLink";
+export * from "./shared/components/Page";
+export * from "./shared/context/HeadContext";
+export * from "./shared/context/PageContext";
+export * from "./shared/context/RouterContext";
+export * from "./shared/core/ArcanaJSApp";
+export * from "./shared/hooks/useHead";
+export * from "./shared/hooks/useLocation";
+export * from "./shared/hooks/usePage";
+export * from "./shared/hooks/useParams";
+export * from "./shared/hooks/useQuery";
+export * from "./shared/hooks/useRouter";
+export { default as ErrorPage } from "./shared/views/ErrorPage";
+export { default as NotFoundPage } from "./shared/views/NotFoundPage";
+export * from "./types";

package/framework/lib/index.js

@@ -0,0 +1,59 @@
+"use strict";
+/// <reference path="./global.d.ts" />
+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.NotFoundPage = exports.ErrorPage = void 0;
+// ============================================================================
+// Component Exports
+// ============================================================================
+__exportStar(require("./shared/components/Body"), exports);
+__exportStar(require("./shared/components/Head"), exports);
+__exportStar(require("./shared/components/Link"), exports);
+__exportStar(require("./shared/components/NavLink"), exports);
+__exportStar(require("./shared/components/Page"), exports);
+// ============================================================================
+// Context Exports
+// ============================================================================
+__exportStar(require("./shared/context/HeadContext"), exports);
+__exportStar(require("./shared/context/PageContext"), exports);
+__exportStar(require("./shared/context/RouterContext"), exports);
+// ============================================================================
+// Core Exports
+// ============================================================================
+__exportStar(require("./shared/core/ArcanaJSApp"), exports);
+// ============================================================================
+// Hook Exports
+// ============================================================================
+__exportStar(require("./shared/hooks/useHead"), exports);
+__exportStar(require("./shared/hooks/useLocation"), exports);
+__exportStar(require("./shared/hooks/usePage"), exports);
+__exportStar(require("./shared/hooks/useParams"), exports);
+__exportStar(require("./shared/hooks/useQuery"), exports);
+__exportStar(require("./shared/hooks/useRouter"), exports);
+// ============================================================================
+// Default Error Views
+// ============================================================================
+var ErrorPage_1 = require("./shared/views/ErrorPage");
+Object.defineProperty(exports, "ErrorPage", { enumerable: true, get: function () { return __importDefault(ErrorPage_1).default; } });
+var NotFoundPage_1 = require("./shared/views/NotFoundPage");
+Object.defineProperty(exports, "NotFoundPage", { enumerable: true, get: function () { return __importDefault(NotFoundPage_1).default; } });
+// ============================================================================
+// Type Exports
+// ============================================================================
+__exportStar(require("./types"), exports);

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

@@ -0,0 +1,24 @@
+import { NextFunction, Request, Response } from "express";
+import React from "react";
+declare global {
+    namespace Express {
+        interface Response {
+            /**
+             * Renders a React page using ArcanaJS SSR.
+             *
+             * @param page - The name of the page component to render.
+             * @param data - Initial data to pass to the page component (default: {}).
+             * @param params - Route parameters (default: {}).
+             * @returns The Express Response object.
+             */
+            renderPage(page: string, data?: any, params?: Record<string, string>): Response;
+        }
+    }
+}
+interface ArcanaJSOptions {
+    views: Record<string, React.FC<any>>;
+    indexFile?: string;
+    layout?: React.FC<any>;
+}
+export declare const createArcanaJSMiddleware: (options: ArcanaJSOptions) => (req: Request, res: Response, next: NextFunction) => void;
+export {};

package/framework/lib/server/ArcanaJSMiddleware.js

@@ -0,0 +1,114 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createArcanaJSMiddleware = void 0;
+const fs_1 = __importDefault(require("fs"));
+const react_1 = __importDefault(require("react"));
+const server_1 = require("react-dom/server");
+const HeadContext_1 = require("../shared/context/HeadContext");
+const ArcanaJSApp_1 = require("../shared/core/ArcanaJSApp");
+const DEFAULT_HTML_TEMPLATE = `<!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>`;
+// Helper to prevent XSS in initial data
+const safeStringify = (obj) => {
+    return JSON.stringify(obj).replace(/</g, "\\u003c");
+};
+const createArcanaJSMiddleware = (options) => {
+    const { views, indexFile, layout } = options;
+    let cachedIndexHtml = null;
+    const getIndexHtml = (callback) => {
+        if (process.env.NODE_ENV === "production" && cachedIndexHtml) {
+            return callback(null, cachedIndexHtml);
+        }
+        if (indexFile && fs_1.default.existsSync(indexFile)) {
+            fs_1.default.readFile(indexFile, "utf8", (err, htmlData) => {
+                if (!err && process.env.NODE_ENV === "production") {
+                    cachedIndexHtml = htmlData;
+                }
+                callback(err, htmlData);
+            });
+        }
+        else {
+            if (process.env.NODE_ENV === "production") {
+                cachedIndexHtml = DEFAULT_HTML_TEMPLATE;
+            }
+            callback(null, DEFAULT_HTML_TEMPLATE);
+        }
+    };
+    return (req, res, next) => {
+        res.renderPage = (page, data = {}, params = {}) => {
+            const csrfToken = res.locals.csrfToken;
+            if (req.get("X-ArcanaJS-Request") || req.query.format === "json") {
+                return res.json({ page, data, params, csrfToken });
+            }
+            try {
+                const headTags = [];
+                const headManager = {
+                    tags: headTags,
+                    push: (nodes) => headTags.push(nodes),
+                };
+                const appHtml = (0, server_1.renderToString)(react_1.default.createElement(HeadContext_1.HeadContext.Provider, { value: headManager }, react_1.default.createElement(ArcanaJSApp_1.ArcanaJSApp, {
+                    initialPage: page,
+                    initialData: data,
+                    initialParams: params,
+                    initialUrl: req.path,
+                    csrfToken: csrfToken,
+                    views: views,
+                    layout: layout,
+                })));
+                const headHtml = (0, server_1.renderToString)(react_1.default.createElement(react_1.default.Fragment, null, ...headTags));
+                getIndexHtml((err, htmlData) => {
+                    if (err) {
+                        console.error("Error reading index.html", err);
+                        return res.status(500).send("Server Error");
+                    }
+                    const scriptContent = safeStringify({
+                        page,
+                        data,
+                        params,
+                        csrfToken,
+                    });
+                    const scriptTag = `<script id="__ARCANAJS_DATA__" type="application/json">${scriptContent}</script>`;
+                    const hmrScript = process.env.ARCANA_HMR_PORT
+                        ? `
+            <script>
+              (function() {
+                const socket = new WebSocket("ws://localhost:${process.env.ARCANA_HMR_PORT}");
+                socket.onmessage = function(event) {
+                  const data = JSON.parse(event.data);
+                  if (data.type === "reload") {
+                    window.location.reload();
+                  }
+                };
+              })();
+            </script>`
+                        : "";
+                    const html = htmlData
+                        .replace("<!--HEAD_CONTENT-->", headHtml)
+                        .replace("<!--APP_CONTENT-->", appHtml)
+                        .replace("<!--ARCANAJS_DATA_SCRIPT-->", scriptTag + hmrScript);
+                    res.send(html);
+                });
+            }
+            catch (error) {
+                console.error("SSR Error:", error);
+                return res.status(500).send("Internal Server Error");
+            }
+            return res;
+        };
+        next();
+    };
+};
+exports.createArcanaJSMiddleware = createArcanaJSMiddleware;

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

@@ -0,0 +1,55 @@
+import { Express, RequestHandler } from "express";
+import React from "react";
+import { Router as ArcanaRouter } from "./Router";
+export interface ArcanaJSConfig<TDb = any> {
+    port?: number | string;
+    views?: Record<string, React.FC<any>>;
+    viewsDir?: string;
+    viewsContext?: any;
+    routes?: RequestHandler | RequestHandler[] | ArcanaRouter | ArcanaRouter[];
+    /** API routes can be provided separately from web routes */
+    apiRoutes?: RequestHandler | RequestHandler[] | ArcanaRouter | ArcanaRouter[];
+    /** Base path under which API routes will be mounted (default: '/api') */
+    apiBase?: string;
+    staticDir?: string;
+    distDir?: string;
+    indexFile?: string;
+    layout?: React.FC<any>;
+    /** Optional function to establish a DB connection. Should return a Promise resolving to the DB client/connection. */
+    dbConnect?: () => Promise<TDb> | TDb;
+    /** Automatically register SIGINT/SIGTERM handlers to call stop(). Default: true */
+    autoHandleSignals?: boolean;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            /**
+             * Normalized DB object optionally attached to the request by ArcanaJSServer.
+             * It may be either the raw client, or an object like `{ client, db, close }`.
+             */
+            db?: any;
+        }
+    }
+}
+export declare class ArcanaJSServer<TDb = any> {
+    app: Express;
+    private config;
+    private serverInstance?;
+    private _sigintHandler?;
+    private _sigtermHandler?;
+    constructor(config: ArcanaJSConfig<TDb>);
+    /**
+     * Normalize different DB client shapes into a single object exposing:
+     * { client?: any, db?: any, close: async () => void }
+     */
+    private normalizeDb;
+    private initialize;
+    private loadViewsFromContext;
+    private loadViewsFromAlias;
+    private discoverViews;
+    start(): void;
+    /**
+     * Stop the HTTP server and close DB connection if present.
+     */
+    stop(): Promise<void>;
+}