@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/render/render-service.js

@@ -0,0 +1,394 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import * as path from "path";
+import * as fs from "fs";
+import { Logger } from "../provider/logger/logger.provider.js";
+import { EngineRegistry } from "./render-registry.js";
+import { EjsAdapter } from "./adapters/ejs-adapter.js";
+import { PugAdapter } from "./adapters/pug-adapter.js";
+import { HandlebarsAdapter } from "./adapters/handlebars-adapter.js";
+import { ReactAdapter } from "./adapters/react-adapter.js";
+import { getPackageResolver } from "./utils/package-resolver.js";
+/**
+ * Render Service
+ *
+ * @description Main service for managing view rendering across different engines.
+ * Provides a unified API for configuration, rendering, and introspection.
+ *
+ * @example
+ * ```typescript
+ * const renderService = new RenderService(app);
+ * await renderService.configure({
+ *   engine: 'react',
+ *   viewsDir: 'src/views',
+ *   ssr: { hydrate: true }
+ * });
+ * const html = await renderService.render('Home', { title: 'Welcome' });
+ * ```
+ *
+ * @public API
+ */
+export class RenderService {
+    registry;
+    config = {};
+    app;
+    logger;
+    activeEngine = null;
+    metrics = {
+        totalRenders: 0,
+        cacheHits: 0,
+        cacheMisses: 0,
+        avgRenderTime: 0,
+        rendersByEngine: {},
+    };
+    renderTimes = [];
+    isConfigured = false;
+    // Features (lazy initialized)
+    hotReloader = null;
+    viewDebugger = null;
+    typeGenerator = null;
+    constructor(app) {
+        this.app = app;
+        this.logger = new Logger();
+        this.registry = new EngineRegistry();
+        // Register built-in adapters
+        this.registerBuiltInAdapters();
+    }
+    /**
+     * Configure the render service.
+     *
+     * @param config - Render configuration or preset name
+     */
+    async configure(config = {}) {
+        // Resolve preset names to a concrete RenderConfig object first, so the
+        // rest of the function deals with a single, well-typed shape (TS does
+        // not carry parameter narrowing across reassignments reliably).
+        let resolved;
+        if (typeof config === "string") {
+            const { getPreset } = await import("./presets/index.js");
+            resolved = getPreset(config);
+        }
+        else {
+            resolved = config;
+        }
+        // Apply smart defaults
+        resolved = this.applyDefaults(resolved);
+        // Auto-detect engine if needed
+        if (resolved.engine === "auto" || !resolved.engine) {
+            const { AutoDetection } = await import("./features/auto-detection.js");
+            const autoDetector = new AutoDetection();
+            resolved.engine = await autoDetector.detectEngine();
+            this.logger.info(`Auto-detected render engine: ${resolved.engine}`, "render-service");
+        }
+        this.config = resolved;
+        // Get and configure the engine adapter
+        const adapter = this.registry.get(resolved.engine);
+        if (!adapter) {
+            throw new Error(`Render engine '${resolved.engine}' not found or not registered`);
+        }
+        // Build engine-specific options
+        const engineOptions = this.buildEngineOptions(resolved);
+        await adapter.setup(this.app, engineOptions);
+        this.activeEngine = adapter;
+        // Enable features based on config
+        if (resolved.watch === true ||
+            (resolved.watch === "auto" && this.isDevelopment())) {
+            await this.enableHotReload();
+        }
+        if (resolved.debug === true ||
+            (resolved.debug === undefined && this.isDevelopment())) {
+            await this.enableViewDebugger();
+        }
+        this.isConfigured = true;
+        this.logConfiguration();
+    }
+    /**
+     * Register a custom engine adapter.
+     *
+     * @param adapter - Engine adapter to register
+     */
+    registerEngine(adapter) {
+        this.registry.register(adapter);
+    }
+    /**
+     * Get an engine by name.
+     *
+     * @param name - Engine name
+     * @returns Engine adapter or undefined
+     */
+    getEngine(name) {
+        return this.registry.get(name);
+    }
+    /**
+     * Get the currently active engine.
+     *
+     * @returns Active engine adapter
+     */
+    getActiveEngine() {
+        if (!this.activeEngine) {
+            throw new Error("No render engine configured. Call configure() first.");
+        }
+        return this.activeEngine;
+    }
+    /**
+     * Render a view to string.
+     *
+     * @param view - View name or path
+     * @param data - Data to pass to the template
+     * @param options - Additional render options
+     * @returns Rendered HTML string
+     */
+    async render(view, data = {}, options) {
+        const adapter = this.getActiveEngine();
+        const startTime = Date.now();
+        try {
+            const html = await adapter.render(view, { ...data, ...options?.locals });
+            // Update metrics
+            this.updateMetrics(adapter.name, Date.now() - startTime);
+            return html;
+        }
+        catch (error) {
+            this.logger.error(`Render failed for view '${view}': ${error.message}`, "render-service");
+            throw error;
+        }
+    }
+    /**
+     * Render a view as a stream.
+     *
+     * @param view - View name or path
+     * @param data - Data to pass to the template
+     * @param options - Stream options
+     * @returns Readable stream of HTML
+     */
+    renderStream(view, data = {}, options) {
+        const adapter = this.getActiveEngine();
+        if (!adapter.supportsStreaming || !adapter.renderStream) {
+            throw new Error(`Engine '${adapter.name}' does not support streaming. Use render() instead.`);
+        }
+        return adapter.renderStream(view, { ...data, ...options?.locals });
+    }
+    /**
+     * Enable hot reload for views.
+     */
+    async enableHotReload() {
+        if (this.hotReloader)
+            return;
+        const { HotReload } = await import("./features/hot-reload.js");
+        this.hotReloader = new HotReload(this.config.viewsDir || "views");
+        this.hotReloader.setOnChange(() => {
+            // Notify active engine
+            this.activeEngine?.onHotReload?.();
+        });
+        this.hotReloader.start();
+    }
+    /**
+     * Enable view type generation.
+     */
+    async enableTypeGeneration() {
+        if (this.typeGenerator)
+            return;
+        const { TypeGenerator } = await import("./features/type-generator.js");
+        this.typeGenerator = new TypeGenerator();
+        const viewsDir = this.config.viewsDir;
+        if (viewsDir) {
+            const dir = Array.isArray(viewsDir) ? viewsDir[0] : viewsDir;
+            await this.typeGenerator.generateViewTypes(dir);
+        }
+    }
+    /**
+     * Enable the view debugger endpoint.
+     */
+    async enableViewDebugger() {
+        if (this.viewDebugger)
+            return;
+        const { ViewDebugger } = await import("./features/view-debugger.js");
+        this.viewDebugger = new ViewDebugger(this);
+        this.viewDebugger.registerRoutes(this.app);
+    }
+    /**
+     * Get list of registered engine names.
+     *
+     * @returns Array of engine names
+     */
+    getRegisteredEngines() {
+        return this.registry.getNames();
+    }
+    /**
+     * Get list of discovered view files.
+     *
+     * @returns Array of view file paths
+     */
+    getViewFiles() {
+        const viewsDir = this.config.viewsDir || "views";
+        const dir = Array.isArray(viewsDir) ? viewsDir[0] : viewsDir;
+        // Return synchronously cached result or empty array
+        // Full scan is sync for immediate return
+        try {
+            const files = [];
+            const scanDir = (dirPath) => {
+                if (!fs.existsSync(dirPath))
+                    return;
+                const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+                for (const entry of entries) {
+                    const fullPath = path.join(dirPath, entry.name);
+                    if (entry.isDirectory()) {
+                        scanDir(fullPath);
+                    }
+                    else if (entry.isFile()) {
+                        files.push(fullPath);
+                    }
+                }
+            };
+            scanDir(dir);
+            return files;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Get current configuration.
+     *
+     * @returns Render configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Get render metrics.
+     *
+     * @returns Render metrics
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Check if an engine is available (installed).
+     *
+     * @param engine - Engine type to check
+     * @returns Whether the engine is available
+     */
+    isEngineAvailable(engine) {
+        const adapter = this.registry.get(engine);
+        if (!adapter)
+            return false;
+        const resolver = getPackageResolver();
+        return resolver.isInstalled(adapter.packageName);
+    }
+    /**
+     * Register built-in engine adapters.
+     */
+    registerBuiltInAdapters() {
+        this.registry.register(new EjsAdapter());
+        this.registry.register(new PugAdapter());
+        this.registry.register(new HandlebarsAdapter());
+        this.registry.register(new ReactAdapter());
+    }
+    /**
+     * Apply default configuration values.
+     *
+     * @param config - User configuration
+     * @returns Configuration with defaults applied
+     */
+    applyDefaults(config) {
+        const isDev = this.isDevelopment();
+        return {
+            engine: "auto",
+            viewsDir: config.viewsDir || path.join(process.cwd(), "views"),
+            cache: config.cache === "auto" ? !isDev : (config.cache ?? !isDev),
+            watch: config.watch === "auto" ? isDev : (config.watch ?? isDev),
+            debug: config.debug ?? isDev,
+            streaming: config.streaming ?? true,
+            ...config,
+        };
+    }
+    /**
+     * Build engine-specific options from config.
+     *
+     * @param config - Render configuration
+     * @returns Engine options
+     */
+    buildEngineOptions(config) {
+        const engine = config.engine;
+        const baseOptions = {
+            viewsDir: config.viewsDir,
+            cache: config.cache === true,
+        };
+        switch (engine) {
+            case "ejs":
+                return {
+                    ...baseOptions,
+                    ...config.ejsOptions,
+                    serverOptions: {
+                        cache: config.cache === true,
+                        ...config.ejsOptions?.serverOptions,
+                    },
+                };
+            case "pug":
+                return {
+                    ...baseOptions,
+                    ...config.pugOptions,
+                };
+            case "hbs":
+                return {
+                    ...baseOptions,
+                    partialsDir: config.partialsDir,
+                    ...config.hbsOptions,
+                };
+            case "react":
+                return {
+                    ...baseOptions,
+                    clientBundleDir: config.clientBundleDir,
+                    ssr: config.ssr,
+                    streaming: config.streaming,
+                    ...config.reactOptions,
+                };
+            default:
+                return baseOptions;
+        }
+    }
+    /**
+     * Update render metrics.
+     *
+     * @param engineName - Engine that performed the render
+     * @param renderTime - Time taken to render in ms
+     */
+    updateMetrics(engineName, renderTime) {
+        this.metrics.totalRenders++;
+        this.renderTimes.push(renderTime);
+        // Keep only last 100 render times for average
+        if (this.renderTimes.length > 100) {
+            this.renderTimes.shift();
+        }
+        // Calculate average
+        this.metrics.avgRenderTime =
+            this.renderTimes.reduce((a, b) => a + b, 0) / this.renderTimes.length;
+        // Track by engine
+        this.metrics.rendersByEngine[engineName] =
+            (this.metrics.rendersByEngine[engineName] || 0) + 1;
+    }
+    /**
+     * Check if running in development mode.
+     *
+     * @returns Whether in development mode
+     */
+    isDevelopment() {
+        return process.env.NODE_ENV !== "production";
+    }
+    /**
+     * Log the current configuration.
+     */
+    logConfiguration() {
+        const engine = this.activeEngine?.name || "unknown";
+        const viewsDir = this.config.viewsDir || "views";
+        const features = [];
+        if (this.config.watch)
+            features.push("hot-reload");
+        if (this.config.debug)
+            features.push("debug");
+        if (this.config.streaming)
+            features.push("streaming");
+        if (this.config.ssr?.hydrate)
+            features.push("ssr");
+        this.logger.info(`Render engine: ${engine} | Views: ${viewsDir} | Features: ${features.join(", ") || "none"}`, "render-service");
+    }
+}

package/lib/esm/render/utils/cache-manager.js

@@ -0,0 +1,196 @@
+/**
+ * Cache Manager
+ *
+ * @description Manages view caching with configurable strategies.
+ * Supports memory caching with TTL and LRU eviction.
+ *
+ * @public API
+ */
+export class CacheManager {
+    cache = new Map();
+    config;
+    maxSize;
+    constructor(config) {
+        this.config = config || { enabled: true };
+        this.maxSize = config?.maxSize || 1000;
+    }
+    /**
+     * Get a cached value.
+     *
+     * @param key - Cache key
+     * @returns Cached value or undefined if not found/expired
+     */
+    get(key) {
+        if (!this.config.enabled) {
+            return undefined;
+        }
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        // Check if expired
+        if (this.isExpired(entry)) {
+            this.cache.delete(key);
+            return undefined;
+        }
+        // Update hits
+        entry.hits++;
+        return entry.value;
+    }
+    /**
+     * Set a cached value.
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Time-to-live in seconds (optional, uses config default)
+     */
+    set(key, value, ttl) {
+        if (!this.config.enabled) {
+            return;
+        }
+        // Evict if at max size
+        if (this.cache.size >= this.maxSize) {
+            this.evictLRU();
+        }
+        const ttlMs = (ttl || this.config.ttl || 3600) * 1000;
+        this.cache.set(key, {
+            value,
+            cachedAt: Date.now(),
+            ttl: ttlMs,
+            hits: 0,
+        });
+    }
+    /**
+     * Check if a key exists in cache (and is not expired).
+     *
+     * @param key - Cache key
+     * @returns Whether the key exists and is valid
+     */
+    has(key) {
+        if (!this.config.enabled) {
+            return false;
+        }
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return false;
+        }
+        if (this.isExpired(entry)) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delete a cached value.
+     *
+     * @param key - Cache key
+     * @returns Whether the key was deleted
+     */
+    delete(key) {
+        return this.cache.delete(key);
+    }
+    /**
+     * Clear all cached values.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get the number of cached items.
+     *
+     * @returns Cache size
+     */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * Get cache statistics.
+     *
+     * @returns Cache statistics
+     */
+    getStats() {
+        let totalHits = 0;
+        let expiredCount = 0;
+        for (const [, entry] of this.cache.entries()) {
+            totalHits += entry.hits;
+            if (this.isExpired(entry)) {
+                expiredCount++;
+            }
+        }
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            totalHits,
+            expiredCount,
+            enabled: this.config.enabled,
+        };
+    }
+    /**
+     * Remove expired entries.
+     *
+     * @returns Number of entries removed
+     */
+    cleanup() {
+        let removed = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (this.isExpired(entry)) {
+                this.cache.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Update the cache configuration.
+     *
+     * @param config - New configuration
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+        if (config.maxSize !== undefined) {
+            this.maxSize = config.maxSize;
+        }
+    }
+    /**
+     * Check if an entry is expired.
+     *
+     * @param entry - Cache entry
+     * @returns Whether the entry is expired
+     */
+    isExpired(entry) {
+        if (entry.ttl <= 0) {
+            return false; // No expiration
+        }
+        return Date.now() - entry.cachedAt > entry.ttl;
+    }
+    /**
+     * Evict the least recently used entry.
+     */
+    evictLRU() {
+        let lruKey = null;
+        let lruHits = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.hits < lruHits) {
+                lruHits = entry.hits;
+                lruKey = key;
+            }
+        }
+        if (lruKey) {
+            this.cache.delete(lruKey);
+        }
+    }
+}
+/** Singleton instance */
+let cacheInstance = null;
+/**
+ * Get the cache manager singleton.
+ *
+ * @param config - Optional configuration
+ * @returns Cache manager instance
+ */
+export function getCacheManager(config) {
+    if (!cacheInstance) {
+        cacheInstance = new CacheManager(config);
+    }
+    return cacheInstance;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Render Utilities
+ *
+ * @module render/utils
+ * @description Utility classes for the render engine system.
+ * @public API
+ */
+export { PackageResolver, PackageNotInstalledError, getPackageResolver, } from "./package-resolver.js";
+export { ViewScanner, getViewScanner } from "./view-scanner.js";
+export { CacheManager, getCacheManager } from "./cache-manager.js";