@expressots/core 3.0.0 → 4.0.0-preview.1

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

@@ -0,0 +1,202 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as fs from "fs";
+import * as path from "path";
+import { Logger } from "../../provider/logger/logger.provider.js";
+/**
+ * Auto Detection
+ *
+ * @description Automatically detects the best template engine based on
+ * installed packages and existing view files.
+ *
+ * @public API
+ */
+export class AutoDetection {
+    logger;
+    constructor() {
+        this.logger = new 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;
+        }
+    }
+}

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

@@ -0,0 +1,153 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Logger } from "../../provider/logger/logger.provider.js";
+/**
+ * Hot Reload
+ *
+ * @description Watches view files for changes and triggers reloads in development.
+ *
+ * @public API
+ */
+export class HotReload {
+    watcher = null;
+    viewsDir;
+    logger;
+    isRunning = false;
+    onChange = null;
+    constructor(viewsDir) {
+        this.viewsDir = viewsDir;
+        this.logger = new 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;
+        }
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Render Engine Features
+ *
+ * @module render/features
+ * @description Advanced features for the render engine system.
+ * @public API
+ */
+export { AutoDetection } from "./auto-detection.js";
+export { HotReload } from "./hot-reload.js";
+export { StreamingRenderer } from "./streaming.js";
+export { TypeGenerator } from "./type-generator.js";
+export { ViewDebugger } from "./view-debugger.js";

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

@@ -0,0 +1,103 @@
+import { Logger } from "../../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
+ */
+export class StreamingRenderer {
+    logger;
+    constructor() {
+        this.logger = new 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();
+    }
+}

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

@@ -0,0 +1,195 @@
+import * as fs from "fs";
+import * as path from "path";
+import { Logger } from "../../provider/logger/logger.provider.js";
+/**
+ * Type Generator
+ *
+ * @description Generates TypeScript type definitions for view files.
+ * Provides type safety for view rendering.
+ *
+ * @public API
+ */
+export class TypeGenerator {
+    logger;
+    constructor() {
+        this.logger = new 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>";
+        }
+    }
+}