@expressots/core 3.0.0 → 4.0.0-preview.1

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

@@ -0,0 +1,418 @@
+"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.RenderService = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const logger_provider_js_1 = require("../provider/logger/logger.provider.js");
+const render_registry_js_1 = require("./render-registry.js");
+const ejs_adapter_js_1 = require("./adapters/ejs-adapter.js");
+const pug_adapter_js_1 = require("./adapters/pug-adapter.js");
+const handlebars_adapter_js_1 = require("./adapters/handlebars-adapter.js");
+const react_adapter_js_1 = require("./adapters/react-adapter.js");
+const package_resolver_js_1 = require("./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
+ */
+class RenderService {
+    constructor(app) {
+        this.config = {};
+        this.activeEngine = null;
+        this.metrics = {
+            totalRenders: 0,
+            cacheHits: 0,
+            cacheMisses: 0,
+            avgRenderTime: 0,
+            rendersByEngine: {},
+        };
+        this.renderTimes = [];
+        this.isConfigured = false;
+        // Features (lazy initialized)
+        this.hotReloader = null;
+        this.viewDebugger = null;
+        this.typeGenerator = null;
+        this.app = app;
+        this.logger = new logger_provider_js_1.Logger();
+        this.registry = new render_registry_js_1.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 Promise.resolve().then(() => __importStar(require("./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 Promise.resolve().then(() => __importStar(require("./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 Promise.resolve().then(() => __importStar(require("./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 Promise.resolve().then(() => __importStar(require("./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 Promise.resolve().then(() => __importStar(require("./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 = (0, package_resolver_js_1.getPackageResolver)();
+        return resolver.isInstalled(adapter.packageName);
+    }
+    /**
+     * Register built-in engine adapters.
+     */
+    registerBuiltInAdapters() {
+        this.registry.register(new ejs_adapter_js_1.EjsAdapter());
+        this.registry.register(new pug_adapter_js_1.PugAdapter());
+        this.registry.register(new handlebars_adapter_js_1.HandlebarsAdapter());
+        this.registry.register(new react_adapter_js_1.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");
+    }
+}
+exports.RenderService = RenderService;

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

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CacheManager = void 0;
+exports.getCacheManager = getCacheManager;
+/**
+ * Cache Manager
+ *
+ * @description Manages view caching with configurable strategies.
+ * Supports memory caching with TTL and LRU eviction.
+ *
+ * @public API
+ */
+class CacheManager {
+    constructor(config) {
+        this.cache = new Map();
+        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);
+        }
+    }
+}
+exports.CacheManager = CacheManager;
+/** Singleton instance */
+let cacheInstance = null;
+/**
+ * Get the cache manager singleton.
+ *
+ * @param config - Optional configuration
+ * @returns Cache manager instance
+ */
+function getCacheManager(config) {
+    if (!cacheInstance) {
+        cacheInstance = new CacheManager(config);
+    }
+    return cacheInstance;
+}

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

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Render Utilities
+ *
+ * @module render/utils
+ * @description Utility classes for the render engine system.
+ * @public API
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCacheManager = exports.CacheManager = exports.getViewScanner = exports.ViewScanner = exports.getPackageResolver = exports.PackageNotInstalledError = exports.PackageResolver = void 0;
+var package_resolver_js_1 = require("./package-resolver.js");
+Object.defineProperty(exports, "PackageResolver", { enumerable: true, get: function () { return package_resolver_js_1.PackageResolver; } });
+Object.defineProperty(exports, "PackageNotInstalledError", { enumerable: true, get: function () { return package_resolver_js_1.PackageNotInstalledError; } });
+Object.defineProperty(exports, "getPackageResolver", { enumerable: true, get: function () { return package_resolver_js_1.getPackageResolver; } });
+var view_scanner_js_1 = require("./view-scanner.js");
+Object.defineProperty(exports, "ViewScanner", { enumerable: true, get: function () { return view_scanner_js_1.ViewScanner; } });
+Object.defineProperty(exports, "getViewScanner", { enumerable: true, get: function () { return view_scanner_js_1.getViewScanner; } });
+var cache_manager_js_1 = require("./cache-manager.js");
+Object.defineProperty(exports, "CacheManager", { enumerable: true, get: function () { return cache_manager_js_1.CacheManager; } });
+Object.defineProperty(exports, "getCacheManager", { enumerable: true, get: function () { return cache_manager_js_1.getCacheManager; } });