@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/render/features/hot-reload.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HotReload = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const logger_provider_js_1 = require("../../provider/logger/logger.provider.js");
+/**
+ * Hot Reload
+ *
+ * @description Watches view files for changes and triggers reloads in development.
+ *
+ * @public API
+ */
+class HotReload {
+    constructor(viewsDir) {
+        this.watcher = null;
+        this.isRunning = false;
+        this.onChange = null;
+        this.viewsDir = viewsDir;
+        this.logger = new logger_provider_js_1.Logger();
+    }
+    /**
+     * Set the change handler.
+     *
+     * @param handler - Function to call when files change
+     */
+    setOnChange(handler) {
+        this.onChange = handler;
+    }
+    /**
+     * Start watching for file changes.
+     */
+    start() {
+        if (this.isRunning) {
+            return;
+        }
+        try {
+            // Try to use chokidar if available
+            const chokidar = this.resolveChokidar();
+            if (!chokidar) {
+                this.logger.warn("Hot reload disabled: chokidar not installed. Run: npm install -D chokidar", "hot-reload");
+                return;
+            }
+            this.watcher = chokidar.watch(this.viewsDir, {
+                ignored: /(^|[/\\])\../, // Ignore dotfiles
+                persistent: true,
+                ignoreInitial: true,
+            });
+            this.watcher.on("change", (filePath) => {
+                this.onFileChange(filePath);
+            });
+            this.watcher.on("add", (filePath) => {
+                this.onFileAdd(filePath);
+            });
+            this.watcher.on("unlink", (filePath) => {
+                this.onFileDelete(filePath);
+            });
+            this.watcher.on("error", (error) => {
+                this.logger.error(`Watcher error: ${error.message}`, "hot-reload");
+            });
+            this.isRunning = true;
+            this.logger.info("Hot reload enabled for views", "hot-reload");
+        }
+        catch (error) {
+            this.logger.warn(`Failed to start hot reload: ${error.message}`, "hot-reload");
+        }
+    }
+    /**
+     * Stop watching for file changes.
+     */
+    stop() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+            this.isRunning = false;
+            this.logger.info("Hot reload stopped", "hot-reload");
+        }
+    }
+    /**
+     * Check if hot reload is running.
+     *
+     * @returns Whether hot reload is active
+     */
+    isActive() {
+        return this.isRunning;
+    }
+    /**
+     * Handle file change event.
+     *
+     * @param filePath - Path to changed file
+     */
+    onFileChange(filePath) {
+        this.logger.info(`View updated: ${filePath}`, "hot-reload");
+        // Clear Node's require cache for the file
+        this.clearRequireCache(filePath);
+        // Notify listeners
+        if (this.onChange) {
+            this.onChange();
+        }
+    }
+    /**
+     * Handle file add event.
+     *
+     * @param filePath - Path to added file
+     */
+    onFileAdd(filePath) {
+        this.logger.info(`View added: ${filePath}`, "hot-reload");
+        if (this.onChange) {
+            this.onChange();
+        }
+    }
+    /**
+     * Handle file delete event.
+     *
+     * @param filePath - Path to deleted file
+     */
+    onFileDelete(filePath) {
+        this.logger.info(`View deleted: ${filePath}`, "hot-reload");
+        // Clear from require cache
+        this.clearRequireCache(filePath);
+        if (this.onChange) {
+            this.onChange();
+        }
+    }
+    /**
+     * Clear a file from Node's require cache.
+     *
+     * @param filePath - Path to clear
+     */
+    clearRequireCache(filePath) {
+        try {
+            const resolved = require.resolve(filePath);
+            delete require.cache[resolved];
+        }
+        catch {
+            // File might not be in cache
+        }
+    }
+    /**
+     * Try to resolve chokidar package.
+     *
+     * @returns Chokidar module or null
+     */
+    resolveChokidar() {
+        try {
+            const chokidarPath = require.resolve("chokidar", {
+                paths: [process.cwd()],
+            });
+            return require(chokidarPath);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.HotReload = HotReload;

package/lib/cjs/render/features/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Render Engine Features
+ *
+ * @module render/features
+ * @description Advanced features for the render engine system.
+ * @public API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewDebugger = exports.TypeGenerator = exports.StreamingRenderer = exports.HotReload = exports.AutoDetection = void 0;
+var auto_detection_js_1 = require("./auto-detection.js");
+Object.defineProperty(exports, "AutoDetection", { enumerable: true, get: function () { return auto_detection_js_1.AutoDetection; } });
+var hot_reload_js_1 = require("./hot-reload.js");
+Object.defineProperty(exports, "HotReload", { enumerable: true, get: function () { return hot_reload_js_1.HotReload; } });
+var streaming_js_1 = require("./streaming.js");
+Object.defineProperty(exports, "StreamingRenderer", { enumerable: true, get: function () { return streaming_js_1.StreamingRenderer; } });
+var type_generator_js_1 = require("./type-generator.js");
+Object.defineProperty(exports, "TypeGenerator", { enumerable: true, get: function () { return type_generator_js_1.TypeGenerator; } });
+var view_debugger_js_1 = require("./view-debugger.js");
+Object.defineProperty(exports, "ViewDebugger", { enumerable: true, get: function () { return view_debugger_js_1.ViewDebugger; } });

package/lib/cjs/render/features/streaming.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamingRenderer = void 0;
+const logger_provider_js_1 = require("../../provider/logger/logger.provider.js");
+/**
+ * Streaming Renderer
+ *
+ * @description Handles streaming render for engines that support it.
+ * Falls back to regular rendering for engines that don't.
+ *
+ * @public API
+ */
+class StreamingRenderer {
+    constructor() {
+        this.logger = new logger_provider_js_1.Logger();
+    }
+    /**
+     * Render with streaming support.
+     *
+     * @param view - View name or path
+     * @param data - Data to pass to the template
+     * @param res - Express response object
+     * @param adapter - Engine adapter to use
+     */
+    async renderWithStreaming(view, data, res, adapter) {
+        if (!adapter.supportsStreaming || !adapter.renderStream) {
+            // Fallback to regular render
+            this.logger.info(`Engine '${adapter.name}' does not support streaming, using regular render`, "streaming");
+            const html = await adapter.render(view, data);
+            res.send(html);
+            return;
+        }
+        try {
+            const stream = adapter.renderStream(view, data);
+            // Set streaming headers
+            res.setHeader("Content-Type", "text/html; charset=utf-8");
+            res.setHeader("Transfer-Encoding", "chunked");
+            // Handle stream events
+            stream.on("error", (error) => {
+                this.logger.error(`Streaming error: ${error.message}`, "streaming");
+                if (!res.headersSent) {
+                    res.status(500).send("Render error");
+                }
+            });
+            // Pipe the stream to response
+            stream.pipe(res);
+        }
+        catch (error) {
+            this.logger.error(`Failed to start streaming: ${error.message}`, "streaming");
+            // Fallback to regular render
+            const html = await adapter.render(view, data);
+            res.send(html);
+        }
+    }
+    /**
+     * Check if an adapter supports streaming.
+     *
+     * @param adapter - Engine adapter
+     * @returns Whether streaming is supported
+     */
+    supportsStreaming(adapter) {
+        return (adapter.supportsStreaming && typeof adapter.renderStream === "function");
+    }
+    /**
+     * Create a progressive render stream.
+     * Renders critical content first, then streams the rest.
+     *
+     * @param sections - Object mapping section names to render functions
+     * @param res - Express response
+     * @param priority - Order of sections to render
+     */
+    async renderProgressive(sections, res, priority) {
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        res.setHeader("Transfer-Encoding", "chunked");
+        // Start HTML
+        res.write("<!DOCTYPE html><html><head></head><body>");
+        // Render sections in priority order
+        for (const section of priority) {
+            if (sections[section]) {
+                try {
+                    const html = await sections[section]();
+                    res.write(html);
+                }
+                catch (error) {
+                    this.logger.error(`Error rendering section '${section}': ${error.message}`, "streaming");
+                }
+            }
+        }
+        // Render remaining sections
+        for (const [name, renderFn] of Object.entries(sections)) {
+            if (!priority.includes(name)) {
+                try {
+                    const html = await renderFn();
+                    res.write(html);
+                }
+                catch (error) {
+                    this.logger.error(`Error rendering section '${name}': ${error.message}`, "streaming");
+                }
+            }
+        }
+        // End HTML
+        res.write("</body></html>");
+        res.end();
+    }
+}
+exports.StreamingRenderer = StreamingRenderer;

package/lib/cjs/render/features/type-generator.js

@@ -0,0 +1,221 @@
+"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.TypeGenerator = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_provider_js_1 = require("../../provider/logger/logger.provider.js");
+/**
+ * Type Generator
+ *
+ * @description Generates TypeScript type definitions for view files.
+ * Provides type safety for view rendering.
+ *
+ * @public API
+ */
+class TypeGenerator {
+    constructor() {
+        this.logger = new logger_provider_js_1.Logger();
+    }
+    /**
+     * Generate TypeScript types for all views in a directory.
+     *
+     * @param viewsDir - Directory containing views
+     * @param outputFile - Output file path (defaults to views.generated.d.ts)
+     */
+    async generateViewTypes(viewsDir, outputFile) {
+        try {
+            const views = await this.scanViews(viewsDir);
+            if (views.length === 0) {
+                this.logger.info("No views found, skipping type generation", "type-generator");
+                return;
+            }
+            const typeDefinitions = this.generateTypes(views);
+            const outputPath = outputFile || path.join(viewsDir, "views.generated.d.ts");
+            await fs.promises.writeFile(outputPath, typeDefinitions);
+            this.logger.info(`Generated view types: ${outputPath}`, "type-generator");
+        }
+        catch (error) {
+            this.logger.error(`Failed to generate view types: ${error.message}`, "type-generator");
+        }
+    }
+    /**
+     * Scan a directory for view files.
+     *
+     * @param viewsDir - Directory to scan
+     * @returns Array of view information
+     */
+    async scanViews(viewsDir) {
+        const views = [];
+        if (!fs.existsSync(viewsDir)) {
+            return views;
+        }
+        await this.scanDirectory(viewsDir, viewsDir, views);
+        return views;
+    }
+    /**
+     * Recursively scan a directory.
+     *
+     * @param dir - Current directory
+     * @param baseDir - Base directory for relative paths
+     * @param views - Array to populate with view info
+     */
+    async scanDirectory(dir, baseDir, views) {
+        const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await this.scanDirectory(fullPath, baseDir, views);
+            }
+            else if (entry.isFile() && this.isViewFile(entry.name)) {
+                const ext = path.extname(entry.name);
+                const relativePath = path.relative(baseDir, fullPath);
+                const name = relativePath.replace(ext, "").replace(/\\/g, "/");
+                views.push({
+                    name,
+                    path: fullPath,
+                    extension: ext,
+                    engine: this.mapExtensionToEngine(ext),
+                    propsType: await this.extractPropsType(fullPath, ext),
+                });
+            }
+        }
+    }
+    /**
+     * Generate TypeScript type definitions.
+     *
+     * @param views - Array of view information
+     * @returns TypeScript type definition string
+     */
+    generateTypes(views) {
+        const viewTypes = views.map((v) => {
+            const propsType = v.propsType || "Record<string, unknown>";
+            return `  "${v.name}": ${propsType};`;
+        });
+        return `/**
+ * Auto-generated view types
+ * Generated by ExpressoTS Render Engine
+ * Do not edit this file manually
+ */
+
+/**
+ * View name to props type mapping
+ */
+export interface Views {
+${viewTypes.join("\n")}
+}
+
+/**
+ * All view names
+ */
+export type ViewName = keyof Views;
+
+/**
+ * Get props type for a specific view
+ */
+export type ViewProps<T extends ViewName> = Views[T];
+
+/**
+ * Type-safe render function signature
+ */
+export type RenderFunction = <T extends ViewName>(
+  view: T,
+  data: Views[T],
+) => Promise<string>;
+`;
+    }
+    /**
+     * Check if a file is a view file.
+     *
+     * @param filename - File name
+     * @returns Whether it's a view file
+     */
+    isViewFile(filename) {
+        const viewExtensions = [
+            ".ejs",
+            ".pug",
+            ".jade",
+            ".hbs",
+            ".handlebars",
+            ".tsx",
+            ".jsx",
+        ];
+        const ext = path.extname(filename).toLowerCase();
+        return viewExtensions.includes(ext);
+    }
+    /**
+     * Map file extension to engine type.
+     *
+     * @param extension - File extension
+     * @returns Engine type string
+     */
+    mapExtensionToEngine(extension) {
+        const map = {
+            ".ejs": "ejs",
+            ".pug": "pug",
+            ".jade": "pug",
+            ".hbs": "hbs",
+            ".handlebars": "hbs",
+            ".tsx": "react",
+            ".jsx": "react",
+        };
+        return map[extension.toLowerCase()] || "ejs";
+    }
+    /**
+     * Extract props type from a React component.
+     *
+     * @param filePath - Path to the component file
+     * @param extension - File extension
+     * @returns Props type string or undefined
+     */
+    async extractPropsType(filePath, extension) {
+        // Only extract from React components
+        if (extension !== ".tsx" && extension !== ".jsx") {
+            return undefined;
+        }
+        try {
+            const content = await fs.promises.readFile(filePath, "utf-8");
+            // Simple regex to find interface/type Props
+            const propsMatch = content.match(/(?:interface|type)\s+(\w*Props)\s*(?:=\s*)?{([^}]+)}/);
+            if (propsMatch) {
+                // Return inline type
+                return `{ ${propsMatch[2].trim()} }`;
+            }
+            // Check for function component with typed props
+            const funcMatch = content.match(/(?:function|const)\s+\w+\s*\(\s*(?:{\s*([^}]+)\s*}\s*:\s*(\w+)|props\s*:\s*(\w+))/);
+            if (funcMatch) {
+                const typeName = funcMatch[2] || funcMatch[3];
+                if (typeName && typeName !== "any") {
+                    return typeName;
+                }
+            }
+            return "Record<string, unknown>";
+        }
+        catch {
+            return "Record<string, unknown>";
+        }
+    }
+}
+exports.TypeGenerator = TypeGenerator;

package/lib/cjs/render/features/view-debugger.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViewDebugger = void 0;
+const logger_provider_js_1 = require("../../provider/logger/logger.provider.js");
+/**
+ * View Debugger
+ *
+ * @description Provides debug endpoints for inspecting the render system.
+ * Only available in development mode.
+ *
+ * @public API
+ */
+class ViewDebugger {
+    constructor(renderService) {
+        this.isRegistered = false;
+        this.renderService = renderService;
+        this.logger = new logger_provider_js_1.Logger();
+    }
+    /**
+     * Register debug routes on the Express app.
+     *
+     * @param app - Express application
+     */
+    registerRoutes(app) {
+        if (this.isRegistered) {
+            return;
+        }
+        // Main debug endpoint
+        app.get("/__views", (req, res) => {
+            this.handleViewsEndpoint(req, res);
+        });
+        // Preview a view. The view name can contain slashes (e.g.
+        // `users/profile`), so we use a named splat (`*view`) — the
+        // path-to-regexp v6 form `:view(*)` shipped by Express 4 is not
+        // valid in path-to-regexp v8 (Express 5) and now throws
+        // `Missing parameter name`. Path-to-regexp v8 captures the splat
+        // segments as `req.params.view: string[]`; the helpers below
+        // normalise that to a slash-joined string for backward compat.
+        app.get("/__views/preview/*view", (req, res) => {
+            this.handlePreviewEndpoint(req, res);
+        });
+        // Get view info — same shape as preview.
+        app.get("/__views/info/*view", (req, res) => {
+            this.handleInfoEndpoint(req, res);
+        });
+        // Get metrics
+        app.get("/__views/metrics", (req, res) => {
+            this.handleMetricsEndpoint(req, res);
+        });
+        this.isRegistered = true;
+        this.logger.info("View debugger enabled at /__views", "view-debugger");
+    }
+    /**
+     * Handle the main views endpoint.
+     */
+    handleViewsEndpoint(req, res) {
+        try {
+            const data = {
+                engines: this.renderService.getRegisteredEngines(),
+                activeEngine: this.renderService.getActiveEngine().name,
+                views: this.renderService.getViewFiles(),
+                config: this.renderService.getConfig(),
+                metrics: this.renderService.getMetrics(),
+                endpoints: {
+                    list: "GET /__views",
+                    preview: "GET /__views/preview/:view",
+                    info: "GET /__views/info/:view",
+                    metrics: "GET /__views/metrics",
+                },
+            };
+            res.json(data);
+        }
+        catch (error) {
+            res.status(500).json({ error: error.message });
+        }
+    }
+    /**
+     * Handle the view preview endpoint.
+     */
+    async handlePreviewEndpoint(req, res) {
+        try {
+            const view = this.resolveViewParam(req.params.view);
+            const data = req.query.data ? JSON.parse(req.query.data) : {};
+            const html = await this.renderService.render(view, data);
+            res.setHeader("Content-Type", "text/html");
+            res.send(this.wrapPreview(view, html));
+        }
+        catch (error) {
+            res.status(500).json({
+                error: error.message,
+                view: this.resolveViewParam(req.params.view),
+            });
+        }
+    }
+    /**
+     * Normalise the `view` route param across Express 4 and 5.
+     *
+     * Express 4 / path-to-regexp v6 captured `/__views/preview/:view(*)`
+     * as a single string. Express 5 / path-to-regexp v8 changed the
+     * named-splat capture to `string[]` (one entry per slash-separated
+     * segment). The view engine needs the slash-joined form, so we always
+     * collapse the array shape back to that.
+     */
+    resolveViewParam(value) {
+        if (Array.isArray(value))
+            return value.join("/");
+        return typeof value === "string" ? value : "";
+    }
+    /**
+     * Handle the view info endpoint.
+     */
+    handleInfoEndpoint(req, res) {
+        try {
+            const view = this.resolveViewParam(req.params.view);
+            const viewFiles = this.renderService.getViewFiles();
+            // Find matching view
+            const matchingFiles = viewFiles.filter((file) => file.includes(view));
+            res.json({
+                view,
+                files: matchingFiles,
+                engine: this.renderService.getActiveEngine().name,
+            });
+        }
+        catch (error) {
+            res.status(500).json({ error: error.message });
+        }
+    }
+    /**
+     * Handle the metrics endpoint.
+     */
+    handleMetricsEndpoint(req, res) {
+        try {
+            res.json(this.renderService.getMetrics());
+        }
+        catch (error) {
+            res.status(500).json({ error: error.message });
+        }
+    }
+    /**
+     * Wrap preview HTML with debug info.
+     */
+    wrapPreview(view, html) {
+        return `<!DOCTYPE html>
+<html>
+<head>
+  <title>View Preview: ${view}</title>
+  <style>
+    .debug-bar {
+      position: fixed;
+      top: 0;
+      left: 0;
+      right: 0;
+      background: #1a1a2e;
+      color: #eee;
+      padding: 8px 16px;
+      font-family: system-ui, -apple-system, sans-serif;
+      font-size: 13px;
+      z-index: 99999;
+      display: flex;
+      align-items: center;
+      gap: 16px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+    }
+    .debug-bar strong {
+      color: #00d9ff;
+    }
+    .debug-bar a {
+      color: #ff6b6b;
+      text-decoration: none;
+    }
+    .debug-bar a:hover {
+      text-decoration: underline;
+    }
+    .content-wrapper {
+      padding-top: 50px;
+    }
+  </style>
+</head>
+<body>
+  <div class="debug-bar">
+    <span>📁 <strong>${view}</strong></span>
+    <span>|</span>
+    <span>Engine: <strong>${this.renderService.getActiveEngine().name}</strong></span>
+    <span>|</span>
+    <a href="/__views">← Back to Views</a>
+  </div>
+  <div class="content-wrapper">
+    ${html}
+  </div>
+</body>
+</html>`;
+    }
+}
+exports.ViewDebugger = ViewDebugger;