@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/render/adapters/handlebars-adapter.js

@@ -0,0 +1,161 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as path from "path";
+import * as fs from "fs";
+import { BaseEngineAdapter } from "./base-adapter.js";
+/**
+ * Default Handlebars configuration.
+ */
+const HBS_DEFAULTS = {
+    viewEngine: "hbs",
+    viewsDir: path.join(process.cwd(), "views"),
+    partialsDir: path.join(process.cwd(), "views", "partials"),
+};
+/**
+ * Handlebars Engine Adapter
+ *
+ * @description Adapter for the Handlebars template engine.
+ * Provides logic-less templates with partials and helpers support.
+ *
+ * @example
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'hbs',
+ *   viewsDir: 'src/views',
+ *   hbsOptions: {
+ *     partialsDir: 'src/views/partials',
+ *     helpers: {
+ *       formatDate: (date) => date.toLocaleDateString()
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export class HandlebarsAdapter extends BaseEngineAdapter {
+    name = "hbs";
+    extensions = [".hbs", ".handlebars"];
+    packageName = "hbs";
+    supportsStreaming = false;
+    supportsSSR = false;
+    hbs = null;
+    options = HBS_DEFAULTS;
+    /**
+     * Initialize and configure the Handlebars engine.
+     *
+     * @param app - Express application instance
+     * @param options - Handlebars configuration options
+     */
+    async setup(app, options = {}) {
+        // Merge with defaults
+        this.options = {
+            ...HBS_DEFAULTS,
+            ...options,
+        };
+        // Resolve HBS package
+        this.hbs = this.resolvePackage("hbs");
+        // Register partials directory
+        const partialsDir = this.options.partialsDir || HBS_DEFAULTS.partialsDir;
+        if (partialsDir && fs.existsSync(partialsDir)) {
+            this.hbs.registerPartials(partialsDir);
+        }
+        // Register custom helpers
+        if (this.options.helpers) {
+            for (const [name, fn] of Object.entries(this.options.helpers)) {
+                this.hbs.registerHelper(name, fn);
+            }
+        }
+        // Configure Express
+        app.set("view engine", this.options.viewEngine || "hbs");
+        const viewsDir = this.options.viewsDir || HBS_DEFAULTS.viewsDir;
+        this.setViewsDir(viewsDir);
+        app.set("views", viewsDir);
+        this.isInitialized = true;
+        this.logger.info("Handlebars engine initialized", "render-engine");
+    }
+    /**
+     * Render a view to string.
+     *
+     * @param view - View name or path (without extension)
+     * @param data - Data to pass to the template
+     * @returns Rendered HTML string
+     */
+    async render(view, data) {
+        if (!this.hbs) {
+            throw new Error("Handlebars engine not initialized. Call setup() first.");
+        }
+        const viewPath = this.resolveViewPath(view);
+        // Check cache
+        const cacheKey = viewPath;
+        const shouldCache = process.env.NODE_ENV === "production";
+        if (shouldCache && this.hasCachedView(cacheKey)) {
+            const compiled = this.getCachedView(cacheKey);
+            return compiled(data);
+        }
+        // Read template
+        const template = await fs.promises.readFile(viewPath, "utf-8");
+        // Compile template using handlebars
+        const handlebars = this.hbs.handlebars || this.hbs;
+        const compiled = handlebars.compile(template);
+        // Cache if in production
+        if (shouldCache) {
+            this.cacheView(cacheKey, compiled);
+        }
+        return compiled(data);
+    }
+    /**
+     * Register a helper function.
+     *
+     * @param name - Helper name
+     * @param fn - Helper function
+     */
+    registerHelper(name, fn) {
+        if (this.hbs) {
+            this.hbs.registerHelper(name, fn);
+        }
+    }
+    /**
+     * Register a partial template.
+     *
+     * @param name - Partial name
+     * @param template - Partial template string
+     */
+    registerPartial(name, template) {
+        if (this.hbs) {
+            const handlebars = this.hbs.handlebars || this.hbs;
+            handlebars.registerPartial(name, template);
+        }
+    }
+    /**
+     * Resolve the full path to a view file.
+     *
+     * @param view - View name or path
+     * @returns Full path to the view file
+     */
+    resolveViewPath(view) {
+        const viewsDir = this.getViewsDir();
+        const dir = Array.isArray(viewsDir) ? viewsDir[0] : viewsDir;
+        // Try .hbs extension first, then .handlebars
+        for (const ext of [".hbs", ".handlebars"]) {
+            const viewWithExt = view.endsWith(ext) ? view : `${view}${ext}`;
+            const fullPath = path.join(dir, viewWithExt);
+            if (fs.existsSync(fullPath)) {
+                return fullPath;
+            }
+        }
+        // Return .hbs path if not found (for error handling)
+        return path.join(dir, `${view}.hbs`);
+    }
+    /**
+     * Handle hot reload.
+     */
+    onHotReload() {
+        super.onHotReload();
+        // Re-register partials
+        const partialsDir = this.options.partialsDir;
+        if (partialsDir && fs.existsSync(partialsDir) && this.hbs) {
+            this.hbs.registerPartials(partialsDir);
+        }
+        this.logger.info("Handlebars templates reloaded", "render-engine");
+    }
+}

package/lib/esm/render/adapters/index.js

@@ -0,0 +1,12 @@
+/**
+ * Engine Adapters
+ *
+ * @module render/adapters
+ * @description Template engine adapters for the unified render system.
+ * @public API
+ */
+export { BaseEngineAdapter } from "./base-adapter.js";
+export { EjsAdapter } from "./ejs-adapter.js";
+export { PugAdapter } from "./pug-adapter.js";
+export { HandlebarsAdapter } from "./handlebars-adapter.js";
+export { ReactAdapter } from "./react-adapter.js";

package/lib/esm/render/adapters/pug-adapter.js

@@ -0,0 +1,134 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as path from "path";
+import * as fs from "fs";
+import { BaseEngineAdapter } from "./base-adapter.js";
+/**
+ * Default Pug configuration.
+ */
+const PUG_DEFAULTS = {
+    viewEngine: "pug",
+    viewsDir: path.join(process.cwd(), "views"),
+    options: {
+        pretty: process.env.NODE_ENV !== "production",
+        compileDebug: process.env.NODE_ENV !== "production",
+        debug: false,
+    },
+};
+/**
+ * Pug Engine Adapter
+ *
+ * @description Adapter for the Pug (formerly Jade) template engine.
+ * Provides clean, whitespace-sensitive template syntax.
+ *
+ * @example
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'pug',
+ *   viewsDir: 'src/views',
+ *   pugOptions: {
+ *     options: { pretty: true }
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export class PugAdapter extends BaseEngineAdapter {
+    name = "pug";
+    extensions = [".pug", ".jade"];
+    packageName = "pug";
+    supportsStreaming = false;
+    supportsSSR = false;
+    pug = null;
+    options = PUG_DEFAULTS;
+    /**
+     * Initialize and configure the Pug engine.
+     *
+     * @param app - Express application instance
+     * @param options - Pug configuration options
+     */
+    async setup(app, options = {}) {
+        // Merge with defaults
+        this.options = {
+            ...PUG_DEFAULTS,
+            ...options,
+            options: {
+                ...PUG_DEFAULTS.options,
+                ...options.options,
+            },
+        };
+        // Resolve Pug package
+        this.pug = this.resolvePackage("pug");
+        // Configure Express
+        app.set("view engine", this.options.viewEngine || "pug");
+        const viewsDir = this.options.viewsDir || PUG_DEFAULTS.viewsDir;
+        this.setViewsDir(viewsDir);
+        app.set("views", viewsDir);
+        this.isInitialized = true;
+        this.logger.info("Pug engine initialized", "render-engine");
+    }
+    /**
+     * Render a view to string.
+     *
+     * @param view - View name or path (without extension)
+     * @param data - Data to pass to the template
+     * @returns Rendered HTML string
+     */
+    async render(view, data) {
+        if (!this.pug) {
+            throw new Error("Pug engine not initialized. Call setup() first.");
+        }
+        const viewPath = this.resolveViewPath(view);
+        // Check cache
+        const cacheKey = viewPath;
+        const shouldCache = process.env.NODE_ENV === "production";
+        if (shouldCache && this.hasCachedView(cacheKey)) {
+            const compiled = this.getCachedView(cacheKey);
+            return compiled(data);
+        }
+        // Compile template
+        const compiled = this.pug.compileFile(viewPath, {
+            filename: viewPath,
+            cache: shouldCache,
+            ...this.options.options,
+        });
+        // Cache if in production
+        if (shouldCache) {
+            this.cacheView(cacheKey, compiled);
+        }
+        return compiled(data);
+    }
+    /**
+     * Resolve the full path to a view file.
+     *
+     * @param view - View name or path
+     * @returns Full path to the view file
+     */
+    resolveViewPath(view) {
+        const viewsDir = this.getViewsDir();
+        const dir = Array.isArray(viewsDir) ? viewsDir[0] : viewsDir;
+        // Try .pug extension first, then .jade
+        for (const ext of [".pug", ".jade"]) {
+            const viewWithExt = view.endsWith(ext) ? view : `${view}${ext}`;
+            const fullPath = path.join(dir, viewWithExt);
+            if (fs.existsSync(fullPath)) {
+                return fullPath;
+            }
+        }
+        // Return .pug path if not found (for error handling)
+        return path.join(dir, `${view}.pug`);
+    }
+    /**
+     * Handle hot reload.
+     */
+    onHotReload() {
+        super.onHotReload();
+        // Clear Pug's internal cache
+        if (this.pug && this.pug.cache) {
+            Object.keys(this.pug.cache).forEach((key) => {
+                delete this.pug.cache[key];
+            });
+        }
+        this.logger.info("Pug templates reloaded", "render-engine");
+    }
+}

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

@@ -0,0 +1,303 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as path from "path";
+import * as fs from "fs";
+import { Readable, Writable } from "stream";
+import express from "express";
+import { BaseEngineAdapter } from "./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
+ */
+export class ReactAdapter extends BaseEngineAdapter {
+    name = "react";
+    extensions = [".tsx", ".jsx"];
+    packageName = "react-dom";
+    supportsStreaming = true;
+    supportsSSR = true;
+    react = null;
+    reactDom = null;
+    reactDomServer = null;
+    options = REACT_DEFAULTS;
+    app = null;
+    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.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 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 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 import(componentPath);
+            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;
+    }
+}