@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/render/adapters/react-adapter.js

@@ -0,0 +1,336 @@
+"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 (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReactAdapter = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const stream_1 = require("stream");
+const express_1 = __importDefault(require("express"));
+const base_adapter_js_1 = require("./base-adapter.js");
+/**
+ * Default React configuration.
+ */
+const REACT_DEFAULTS = {
+    viewsDir: path.join(process.cwd(), "views"),
+    clientBundleDir: path.join(process.cwd(), "public", "assets"),
+    streaming: true,
+    ssr: {
+        hydrate: true,
+        streaming: true,
+        preload: false,
+    },
+};
+/**
+ * React Engine Adapter
+ *
+ * @description Adapter for React Server-Side Rendering (SSR).
+ * Provides server rendering with client-side hydration support.
+ *
+ * @example
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'react',
+ *   viewsDir: 'src/views',
+ *   reactOptions: {
+ *     ssr: { hydrate: true, streaming: true },
+ *     clientBundleDir: 'public/assets'
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+class ReactAdapter extends base_adapter_js_1.BaseEngineAdapter {
+    constructor() {
+        super(...arguments);
+        this.name = "react";
+        this.extensions = [".tsx", ".jsx"];
+        this.packageName = "react-dom";
+        this.supportsStreaming = true;
+        this.supportsSSR = true;
+        this.react = null;
+        this.reactDom = null;
+        this.reactDomServer = null;
+        this.options = REACT_DEFAULTS;
+        this.app = null;
+        this.componentCache = new Map();
+    }
+    /**
+     * Initialize and configure the React engine.
+     *
+     * @param app - Express application instance
+     * @param options - React configuration options
+     */
+    async setup(app, options = {}) {
+        // Merge with defaults
+        this.options = {
+            ...REACT_DEFAULTS,
+            ...options,
+            ssr: {
+                ...REACT_DEFAULTS.ssr,
+                ...options.ssr,
+            },
+        };
+        this.app = app;
+        // Resolve React packages
+        try {
+            this.react = this.resolvePackage("react");
+            this.reactDom = this.resolvePackage("react-dom");
+            this.reactDomServer = this.resolvePackage("react-dom/server");
+        }
+        catch (error) {
+            this.logger.error("React packages not found. Install: npm install react react-dom", "render-engine");
+            throw error;
+        }
+        // Set views directory
+        const viewsDir = this.options.viewsDir || REACT_DEFAULTS.viewsDir;
+        this.setViewsDir(viewsDir);
+        // Serve client bundles if directory exists
+        if (this.options.clientBundleDir &&
+            fs.existsSync(this.options.clientBundleDir)) {
+            app.use("/assets", express_1.default.static(this.options.clientBundleDir));
+        }
+        this.isInitialized = true;
+        this.logger.info("React SSR engine initialized", "render-engine");
+    }
+    /**
+     * Render a React component to string.
+     *
+     * @param view - Component name or path (without extension)
+     * @param data - Props to pass to the component
+     * @returns Rendered HTML string
+     */
+    async render(view, data) {
+        if (!this.reactDomServer) {
+            throw new Error("React engine not initialized. Call setup() first.");
+        }
+        try {
+            // Load the component
+            const Component = await this.loadComponent(view);
+            // Create React element
+            const element = this.react.createElement(Component, data);
+            // Render to string
+            const html = this.reactDomServer.renderToString(element);
+            // Wrap with hydration script if enabled
+            if (this.options.ssr?.hydrate) {
+                return this.wrapWithHydration(html, view, data);
+            }
+            return html;
+        }
+        catch (error) {
+            this.logger.error(`Failed to render React component '${view}': ${error.message}`, "render-engine");
+            throw error;
+        }
+    }
+    /**
+     * Render a React component as a stream.
+     *
+     * @param view - Component name or path
+     * @param data - Props to pass to the component
+     * @returns Readable stream of HTML
+     */
+    renderStream(view, data) {
+        if (!this.reactDomServer) {
+            throw new Error("React engine not initialized. Call setup() first.");
+        }
+        // Note: renderToPipeableStream is available in React 18+
+        const renderMethod = this.reactDomServer.renderToPipeableStream ||
+            this.reactDomServer.renderToNodeStream;
+        if (!renderMethod) {
+            throw new Error("Streaming render not available. Upgrade to React 18 or use render() instead.");
+        }
+        // Load component synchronously for streaming
+        const Component = this.loadComponentSync(view);
+        const element = this.react.createElement(Component, data);
+        if (this.reactDomServer.renderToPipeableStream) {
+            // React 18+ with Suspense support
+            const readable = new stream_1.Readable({ read() { } });
+            const { pipe } = this.reactDomServer.renderToPipeableStream(element, {
+                onShellReady() {
+                    // Start streaming when shell is ready
+                },
+                onAllReady() {
+                    readable.push(null);
+                },
+                onError(error) {
+                    readable.destroy(error);
+                },
+            });
+            // Create a writable that pushes to readable
+            const writable = new stream_1.Writable({
+                write(chunk, _encoding, callback) {
+                    readable.push(chunk);
+                    callback();
+                },
+            });
+            pipe(writable);
+            return readable;
+        }
+        else {
+            // React 17 and below
+            return this.reactDomServer.renderToNodeStream(element);
+        }
+    }
+    /**
+     * Load a React component asynchronously.
+     *
+     * @param view - Component name or path
+     * @returns React component
+     */
+    async loadComponent(view) {
+        const componentPath = this.resolveComponentPath(view);
+        // Check cache in production
+        if (process.env.NODE_ENV === "production" &&
+            this.componentCache.has(componentPath)) {
+            return this.componentCache.get(componentPath);
+        }
+        // Clear require cache in development for hot reload
+        if (process.env.NODE_ENV !== "production") {
+            delete require.cache[require.resolve(componentPath)];
+        }
+        try {
+            // Dynamic import for ESM support
+            const module = await Promise.resolve(`${componentPath}`).then(s => __importStar(require(s)));
+            const Component = module.default || module;
+            // Cache in production
+            if (process.env.NODE_ENV === "production") {
+                this.componentCache.set(componentPath, Component);
+            }
+            return Component;
+        }
+        catch (error) {
+            // Try require for CJS
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const module = require(componentPath);
+                const Component = module.default || module;
+                if (process.env.NODE_ENV === "production") {
+                    this.componentCache.set(componentPath, Component);
+                }
+                return Component;
+            }
+            catch {
+                throw new Error(`Failed to load React component '${view}': ${error.message}`);
+            }
+        }
+    }
+    /**
+     * Load a React component synchronously.
+     *
+     * @param view - Component name or path
+     * @returns React component
+     */
+    loadComponentSync(view) {
+        const componentPath = this.resolveComponentPath(view);
+        if (this.componentCache.has(componentPath)) {
+            return this.componentCache.get(componentPath);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const module = require(componentPath);
+        const Component = module.default || module;
+        if (process.env.NODE_ENV === "production") {
+            this.componentCache.set(componentPath, Component);
+        }
+        return Component;
+    }
+    /**
+     * Resolve the full path to a React component.
+     *
+     * @param view - Component name or path
+     * @returns Full path to the component file
+     */
+    resolveComponentPath(view) {
+        const viewsDir = this.getViewsDir();
+        const dir = Array.isArray(viewsDir) ? viewsDir[0] : viewsDir;
+        // Try .tsx first, then .jsx
+        for (const ext of [".tsx", ".jsx", ".ts", ".js"]) {
+            const viewWithExt = view.endsWith(ext) ? view : `${view}${ext}`;
+            const fullPath = path.join(dir, viewWithExt);
+            if (fs.existsSync(fullPath)) {
+                return fullPath;
+            }
+        }
+        // Also try without pages/ prefix
+        for (const ext of [".tsx", ".jsx", ".ts", ".js"]) {
+            const fullPath = path.join(dir, "pages", `${view}${ext}`);
+            if (fs.existsSync(fullPath)) {
+                return fullPath;
+            }
+        }
+        // Return .tsx path if not found (for error handling)
+        return path.join(dir, `${view}.tsx`);
+    }
+    /**
+     * Wrap rendered HTML with hydration script.
+     *
+     * @param html - Rendered HTML
+     * @param view - Component name
+     * @param data - Props data
+     * @returns Complete HTML document with hydration
+     */
+    wrapWithHydration(html, view, data) {
+        // Escape data for safe embedding in script tag
+        const safeData = JSON.stringify(data)
+            .replace(/</g, "\\u003c")
+            .replace(/>/g, "\\u003e")
+            .replace(/&/g, "\\u0026");
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <script>
+    window.__INITIAL_DATA__ = ${safeData};
+    window.__COMPONENT__ = "${view}";
+  </script>
+</head>
+<body>
+  <div id="root">${html}</div>
+  <script src="/assets/client.js" defer></script>
+</body>
+</html>`;
+    }
+    /**
+     * Handle hot reload.
+     */
+    onHotReload() {
+        super.onHotReload();
+        this.componentCache.clear();
+        this.logger.info("React components cache cleared", "render-engine");
+    }
+    /**
+     * Get SSR configuration.
+     *
+     * @returns SSR configuration
+     */
+    getSSRConfig() {
+        return this.options.ssr;
+    }
+}
+exports.ReactAdapter = ReactAdapter;

package/lib/cjs/render/features/auto-detection.js

@@ -0,0 +1,228 @@
+"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 (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoDetection = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_provider_js_1 = require("../../provider/logger/logger.provider.js");
+/**
+ * Auto Detection
+ *
+ * @description Automatically detects the best template engine based on
+ * installed packages and existing view files.
+ *
+ * @public API
+ */
+class AutoDetection {
+    constructor() {
+        this.logger = new logger_provider_js_1.Logger();
+    }
+    /**
+     * Detect the best engine to use.
+     *
+     * @returns Detected engine type
+     */
+    async detectEngine() {
+        // 1. Check package.json dependencies
+        const installedEngines = await this.getInstalledEngines();
+        // 2. Priority: react > vue > svelte > ejs > pug > hbs
+        const priority = [
+            "react",
+            "vue",
+            "svelte",
+            "ejs",
+            "pug",
+            "hbs",
+        ];
+        for (const engine of priority) {
+            if (installedEngines.includes(engine)) {
+                this.logger.info(`Detected engine '${engine}' from installed packages`, "auto-detection");
+                return engine;
+            }
+        }
+        // 3. Check for view files
+        const viewExtensions = await this.scanViewFiles();
+        if (viewExtensions.length > 0) {
+            const engine = this.mapExtensionToEngine(viewExtensions[0]);
+            this.logger.info(`Detected engine '${engine}' from view files`, "auto-detection");
+            return engine;
+        }
+        // Default to EJS
+        this.logger.info("No engine detected, defaulting to 'ejs'", "auto-detection");
+        return "ejs";
+    }
+    /**
+     * Get list of installed template engine packages.
+     *
+     * @returns Array of installed engine types
+     */
+    async getInstalledEngines() {
+        const engines = [];
+        try {
+            const packageJson = await this.readPackageJson();
+            const deps = {
+                ...packageJson.dependencies,
+                ...packageJson.devDependencies,
+            };
+            // Check for each engine
+            if (deps["ejs"])
+                engines.push("ejs");
+            if (deps["pug"])
+                engines.push("pug");
+            if (deps["hbs"] || deps["handlebars"])
+                engines.push("hbs");
+            if (deps["react"] && deps["react-dom"])
+                engines.push("react");
+            if (deps["vue"])
+                engines.push("vue");
+            if (deps["svelte"])
+                engines.push("svelte");
+        }
+        catch {
+            // If package.json can't be read, return empty
+        }
+        return engines;
+    }
+    /**
+     * Scan common view directories for template files.
+     *
+     * @returns Array of found file extensions
+     */
+    async scanViewFiles() {
+        const viewDirs = [
+            "views",
+            "src/views",
+            "templates",
+            "src/templates",
+            "app/views",
+        ];
+        const extensions = [];
+        for (const dir of viewDirs) {
+            const fullPath = path.join(process.cwd(), dir);
+            if (fs.existsSync(fullPath)) {
+                try {
+                    const files = await fs.promises.readdir(fullPath);
+                    files.forEach((file) => {
+                        const ext = path.extname(file).toLowerCase();
+                        if (this.isViewExtension(ext) && !extensions.includes(ext)) {
+                            extensions.push(ext);
+                        }
+                    });
+                }
+                catch {
+                    // Skip if directory can't be read
+                }
+            }
+        }
+        return extensions;
+    }
+    /**
+     * Read and parse package.json.
+     *
+     * @returns Parsed package.json content
+     */
+    async readPackageJson() {
+        const packagePath = path.join(process.cwd(), "package.json");
+        if (!fs.existsSync(packagePath)) {
+            return {};
+        }
+        const content = await fs.promises.readFile(packagePath, "utf-8");
+        return JSON.parse(content);
+    }
+    /**
+     * Check if an extension is a view file extension.
+     *
+     * @param extension - File extension
+     * @returns Whether it's a view extension
+     */
+    isViewExtension(extension) {
+        const viewExtensions = [
+            ".ejs",
+            ".pug",
+            ".jade",
+            ".hbs",
+            ".handlebars",
+            ".tsx",
+            ".jsx",
+            ".vue",
+            ".svelte",
+        ];
+        return viewExtensions.includes(extension);
+    }
+    /**
+     * Map a file extension to an engine type.
+     *
+     * @param extension - File extension
+     * @returns Engine type
+     */
+    mapExtensionToEngine(extension) {
+        const extensionMap = {
+            ".ejs": "ejs",
+            ".pug": "pug",
+            ".jade": "pug",
+            ".hbs": "hbs",
+            ".handlebars": "hbs",
+            ".tsx": "react",
+            ".jsx": "react",
+            ".vue": "vue",
+            ".svelte": "svelte",
+        };
+        return extensionMap[extension.toLowerCase()] || "ejs";
+    }
+    /**
+     * Check if a specific engine is available.
+     *
+     * @param engine - Engine type to check
+     * @returns Whether the engine is available
+     */
+    isEngineAvailable(engine) {
+        try {
+            const packageMap = {
+                ejs: "ejs",
+                pug: "pug",
+                hbs: "hbs",
+                react: ["react", "react-dom"],
+                vue: "vue",
+                svelte: "svelte",
+            };
+            const packages = packageMap[engine];
+            const packagesToCheck = Array.isArray(packages) ? packages : [packages];
+            return packagesToCheck.every((pkg) => {
+                try {
+                    require.resolve(pkg, { paths: [process.cwd()] });
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+}
+exports.AutoDetection = AutoDetection;