@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/types/render/render-config.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Render Engine Configuration Types
+ *
+ * @module render/config
+ * @description Configuration types for the unified render engine system.
+ * @public API
+ */
+/**
+ * Supported template engine types.
+ * @public API
+ */
+export type EngineType = "ejs" | "pug" | "hbs" | "react" | "vue" | "svelte";
+/**
+ * Preset names for common configurations.
+ * @public API
+ */
+export type PresetName = "development" | "production" | "ssr" | "edge";
+/**
+ * Cache configuration options.
+ * @public API
+ */
+export interface CacheConfig {
+    /** Enable/disable caching */
+    enabled: boolean;
+    /** Cache strategy: memory, file, or redis */
+    strategy?: "memory" | "file" | "redis";
+    /** Time-to-live in seconds */
+    ttl?: number;
+    /** Maximum cache size */
+    maxSize?: number;
+}
+/**
+ * SSR (Server-Side Rendering) configuration.
+ * @public API
+ */
+export interface SSRConfig {
+    /** Enable client-side hydration */
+    hydrate?: boolean;
+    /** Enable streaming render */
+    streaming?: boolean;
+    /** Preload data before render */
+    preload?: boolean;
+    /** Enable progressive rendering */
+    progressive?: boolean;
+}
+/**
+ * Engine-specific configuration.
+ * @public API
+ */
+export interface EngineConfig {
+    /** Views directory for this engine */
+    viewsDir?: string | Array<string>;
+    /** Additional engine-specific options */
+    options?: Record<string, any>;
+    /** Routes this engine handles (for multi-engine setup) */
+    routes?: Array<string>;
+}
+/**
+ * Main render configuration interface.
+ * @public API
+ */
+export interface RenderConfig {
+    /** Template engine to use, or 'auto' for auto-detection */
+    engine?: EngineType | "auto";
+    /** Multiple engine configurations for hybrid setups */
+    engines?: Record<string, EngineConfig>;
+    /** Path(s) to view templates */
+    viewsDir?: string | Array<string>;
+    /** Path to layout templates */
+    layoutsDir?: string;
+    /** Path to partial templates */
+    partialsDir?: string;
+    /** Enable view caching */
+    cache?: boolean | "auto" | CacheConfig;
+    /** Enable streaming render */
+    streaming?: boolean;
+    /** Enable hot reload for views */
+    watch?: boolean | "auto";
+    /** Enable debug mode and /__views endpoint */
+    debug?: boolean;
+    /** Server-side rendering options */
+    ssr?: SSRConfig;
+    /** Directory for client-side bundles (React/Vue/Svelte) */
+    clientBundleDir?: string;
+    /** Apply a preset configuration */
+    preset?: PresetName;
+    /** EJS-specific options */
+    ejsOptions?: EjsConfig;
+    /** Pug-specific options */
+    pugOptions?: PugConfig;
+    /** Handlebars-specific options */
+    hbsOptions?: HandlebarsConfig;
+    /** React-specific options */
+    reactOptions?: ReactConfig;
+}
+/**
+ * EJS engine configuration.
+ * @public API
+ */
+export interface EjsConfig {
+    /** View engine name */
+    viewEngine?: string;
+    /** Views directory */
+    viewsDir?: string | Array<string>;
+    /** EJS server options */
+    serverOptions?: {
+        cache?: boolean;
+        compileDebug?: boolean;
+        debug?: boolean;
+        delimiter?: string;
+        strict?: boolean;
+    };
+}
+/**
+ * Pug engine configuration.
+ * @public API
+ */
+export interface PugConfig {
+    /** View engine name */
+    viewEngine?: string;
+    /** Views directory */
+    viewsDir?: string;
+    /** Pug-specific options */
+    options?: {
+        pretty?: boolean;
+        compileDebug?: boolean;
+        debug?: boolean;
+    };
+}
+/**
+ * Handlebars engine configuration.
+ * @public API
+ */
+export interface HandlebarsConfig {
+    /** View engine name */
+    viewEngine?: string;
+    /** Views directory */
+    viewsDir?: string;
+    /** Partials directory */
+    partialsDir?: string;
+    /** Helpers to register */
+    helpers?: Record<string, (...args: Array<any>) => any>;
+}
+/**
+ * React SSR configuration.
+ * @public API
+ */
+export interface ReactConfig {
+    /** Views directory containing React components */
+    viewsDir?: string;
+    /** Directory for client-side bundles */
+    clientBundleDir?: string;
+    /** SSR configuration */
+    ssr?: SSRConfig;
+    /** Enable streaming render */
+    streaming?: boolean;
+}
+/**
+ * Render options for individual render calls.
+ * @public API
+ */
+export interface RenderOptions {
+    /** Override default layout */
+    layout?: string | false;
+    /** Additional locals to pass to template */
+    locals?: Record<string, any>;
+    /** Enable streaming for this render */
+    streaming?: boolean;
+}
+/**
+ * Stream options for streaming render.
+ * @public API
+ */
+export interface StreamOptions extends RenderOptions {
+    /** Callback when shell is ready (React) */
+    onShellReady?: () => void;
+    /** Callback when all content is ready */
+    onAllReady?: () => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+/**
+ * Render metrics for monitoring.
+ * @public API
+ */
+export interface RenderMetrics {
+    /** Total renders performed */
+    totalRenders: number;
+    /** Cache hit count */
+    cacheHits: number;
+    /** Cache miss count */
+    cacheMisses: number;
+    /** Average render time in ms */
+    avgRenderTime: number;
+    /** Renders by engine */
+    rendersByEngine: Record<string, number>;
+}
+/**
+ * View information for introspection.
+ * @public API
+ */
+export interface ViewInfo {
+    /** View name/path */
+    name: string;
+    /** Full file path */
+    path: string;
+    /** File extension */
+    extension: string;
+    /** Associated engine */
+    engine: EngineType;
+    /** Props type (for type generation) */
+    propsType?: string;
+}

package/lib/cjs/types/render/render-interface.d.ts

@@ -0,0 +1,126 @@
+import type { Application } from "express";
+import type { RenderConfig, RenderOptions, StreamOptions, RenderMetrics, EngineType } from "./render-config.js";
+/**
+ * Engine Adapter Interface
+ *
+ * @description Defines the contract for template engine adapters.
+ * Each supported engine (EJS, Pug, Handlebars, React, etc.) must implement this interface.
+ *
+ * @public API
+ */
+export interface EngineAdapter {
+    /** Unique engine identifier */
+    readonly name: string;
+    /** File extensions this engine handles */
+    readonly extensions: Array<string>;
+    /** NPM package name for this engine */
+    readonly packageName: string;
+    /** Whether this engine supports streaming render */
+    readonly supportsStreaming: boolean;
+    /** Whether this engine supports SSR with hydration */
+    readonly supportsSSR: boolean;
+    /**
+     * Initialize and configure the engine with the Express app.
+     * @param app - Express application instance
+     * @param options - Engine-specific configuration
+     */
+    setup(app: Application, options: any): Promise<void>;
+    /**
+     * Render a view to string.
+     * @param view - View name or path
+     * @param data - Data to pass to the template
+     * @returns Rendered HTML string
+     */
+    render(view: string, data: any): Promise<string>;
+    /**
+     * Render a view as a stream (optional).
+     * Only available if supportsStreaming is true.
+     * @param view - View name or path
+     * @param data - Data to pass to the template
+     * @returns Readable stream of HTML
+     */
+    renderStream?(view: string, data: any): NodeJS.ReadableStream;
+    /** Called when hot reload is triggered */
+    onHotReload?(): void;
+    /** Called when cache should be invalidated */
+    onCacheInvalidate?(): void;
+}
+/**
+ * Render Service Interface
+ *
+ * @description Main service for managing view rendering across different engines.
+ * Provides a unified API for configuration, rendering, and introspection.
+ *
+ * @public API
+ */
+export interface IRenderService {
+    /**
+     * Configure the render service with the given options.
+     * @param config - Render configuration
+     */
+    configure(config: RenderConfig): Promise<void>;
+    /**
+     * Register a new engine adapter.
+     * @param adapter - Engine adapter to register
+     */
+    registerEngine(adapter: EngineAdapter): void;
+    /**
+     * Get a registered engine by name.
+     * @param name - Engine name
+     * @returns Engine adapter or undefined
+     */
+    getEngine(name: string): EngineAdapter | undefined;
+    /**
+     * Get the currently active engine.
+     * @returns Active engine adapter
+     */
+    getActiveEngine(): EngineAdapter;
+    /**
+     * 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
+     */
+    render(view: string, data: any, options?: RenderOptions): Promise<string>;
+    /**
+     * 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: string, data: any, options?: StreamOptions): NodeJS.ReadableStream;
+    /** Enable hot reload for views in development */
+    enableHotReload(): void;
+    /** Enable TypeScript type generation for views */
+    enableTypeGeneration(): void;
+    /** Enable debug endpoint at /__views */
+    enableViewDebugger(): void;
+    /**
+     * Get list of registered engine names.
+     * @returns Array of engine names
+     */
+    getRegisteredEngines(): Array<string>;
+    /**
+     * Get list of discovered view files.
+     * @returns Array of view file paths
+     */
+    getViewFiles(): Array<string>;
+    /**
+     * Get current configuration.
+     * @returns Render configuration
+     */
+    getConfig(): RenderConfig;
+    /**
+     * Get render metrics.
+     * @returns Render metrics
+     */
+    getMetrics(): RenderMetrics;
+    /**
+     * Check if an engine is available (installed).
+     * @param engine - Engine type to check
+     * @returns Whether the engine is available
+     */
+    isEngineAvailable(engine: EngineType): boolean;
+}

package/lib/cjs/types/render/render-registry.d.ts

@@ -0,0 +1,86 @@
+import type { EngineAdapter } from "./render-interface.js";
+import type { EngineType } from "./render-config.js";
+/**
+ * Engine Registry
+ *
+ * @description Manages registration and lookup of template engine adapters.
+ * Provides O(1) lookup by engine name and by file extension.
+ *
+ * @public API
+ */
+export declare class EngineRegistry {
+    /** Map of engine name to adapter */
+    private engines;
+    /** Map of file extension to adapter for quick lookup */
+    private extensionMap;
+    /**
+     * Register an engine adapter.
+     *
+     * @param adapter - Engine adapter to register
+     */
+    register(adapter: EngineAdapter): void;
+    /**
+     * Get an engine adapter by name.
+     *
+     * @param name - Engine name
+     * @returns Engine adapter or undefined
+     */
+    get(name: string): EngineAdapter | undefined;
+    /**
+     * Get an engine adapter by file extension.
+     *
+     * @param extension - File extension (with or without dot)
+     * @returns Engine adapter or undefined
+     */
+    getByExtension(extension: string): EngineAdapter | undefined;
+    /**
+     * Get all registered engine adapters.
+     *
+     * @returns Array of all engine adapters
+     */
+    getAll(): Array<EngineAdapter>;
+    /**
+     * Get all registered engine names.
+     *
+     * @returns Array of engine names
+     */
+    getNames(): Array<string>;
+    /**
+     * Check if an engine is registered.
+     *
+     * @param name - Engine name
+     * @returns Whether the engine is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Check if an extension is supported.
+     *
+     * @param extension - File extension
+     * @returns Whether the extension is supported
+     */
+    hasExtension(extension: string): boolean;
+    /**
+     * Unregister an engine adapter.
+     *
+     * @param name - Engine name to unregister
+     * @returns Whether the engine was unregistered
+     */
+    unregister(name: string): boolean;
+    /**
+     * Clear all registered engines.
+     */
+    clear(): void;
+    /**
+     * Get the number of registered engines.
+     *
+     * @returns Number of engines
+     */
+    get size(): number;
+    /**
+     * Map extension to engine type.
+     *
+     * @param extension - File extension
+     * @returns Engine type or undefined
+     */
+    mapExtensionToEngineType(extension: string): EngineType | undefined;
+}

package/lib/cjs/types/render/render-service.d.ts

@@ -0,0 +1,157 @@
+import type { Application } from "express";
+import type { EngineAdapter, IRenderService } from "./render-interface.js";
+import type { RenderConfig, RenderOptions, StreamOptions, RenderMetrics, EngineType, PresetName } from "./render-config.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 declare class RenderService implements IRenderService {
+    private registry;
+    private config;
+    private app;
+    private logger;
+    private activeEngine;
+    private metrics;
+    private renderTimes;
+    private isConfigured;
+    private hotReloader;
+    private viewDebugger;
+    private typeGenerator;
+    constructor(app: Application);
+    /**
+     * Configure the render service.
+     *
+     * @param config - Render configuration or preset name
+     */
+    configure(config?: RenderConfig | PresetName): Promise<void>;
+    /**
+     * Register a custom engine adapter.
+     *
+     * @param adapter - Engine adapter to register
+     */
+    registerEngine(adapter: EngineAdapter): void;
+    /**
+     * Get an engine by name.
+     *
+     * @param name - Engine name
+     * @returns Engine adapter or undefined
+     */
+    getEngine(name: string): EngineAdapter | undefined;
+    /**
+     * Get the currently active engine.
+     *
+     * @returns Active engine adapter
+     */
+    getActiveEngine(): EngineAdapter;
+    /**
+     * 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
+     */
+    render(view: string, data?: any, options?: RenderOptions): Promise<string>;
+    /**
+     * 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: string, data?: any, options?: StreamOptions): NodeJS.ReadableStream;
+    /**
+     * Enable hot reload for views.
+     */
+    enableHotReload(): Promise<void>;
+    /**
+     * Enable view type generation.
+     */
+    enableTypeGeneration(): Promise<void>;
+    /**
+     * Enable the view debugger endpoint.
+     */
+    enableViewDebugger(): Promise<void>;
+    /**
+     * Get list of registered engine names.
+     *
+     * @returns Array of engine names
+     */
+    getRegisteredEngines(): Array<string>;
+    /**
+     * Get list of discovered view files.
+     *
+     * @returns Array of view file paths
+     */
+    getViewFiles(): Array<string>;
+    /**
+     * Get current configuration.
+     *
+     * @returns Render configuration
+     */
+    getConfig(): RenderConfig;
+    /**
+     * Get render metrics.
+     *
+     * @returns Render metrics
+     */
+    getMetrics(): RenderMetrics;
+    /**
+     * Check if an engine is available (installed).
+     *
+     * @param engine - Engine type to check
+     * @returns Whether the engine is available
+     */
+    isEngineAvailable(engine: EngineType): boolean;
+    /**
+     * Register built-in engine adapters.
+     */
+    private registerBuiltInAdapters;
+    /**
+     * Apply default configuration values.
+     *
+     * @param config - User configuration
+     * @returns Configuration with defaults applied
+     */
+    private applyDefaults;
+    /**
+     * Build engine-specific options from config.
+     *
+     * @param config - Render configuration
+     * @returns Engine options
+     */
+    private buildEngineOptions;
+    /**
+     * Update render metrics.
+     *
+     * @param engineName - Engine that performed the render
+     * @param renderTime - Time taken to render in ms
+     */
+    private updateMetrics;
+    /**
+     * Check if running in development mode.
+     *
+     * @returns Whether in development mode
+     */
+    private isDevelopment;
+    /**
+     * Log the current configuration.
+     */
+    private logConfiguration;
+}

package/lib/cjs/types/render/utils/cache-manager.d.ts

@@ -0,0 +1,106 @@
+import type { CacheConfig } from "../render-config.js";
+/**
+ * Cache Manager
+ *
+ * @description Manages view caching with configurable strategies.
+ * Supports memory caching with TTL and LRU eviction.
+ *
+ * @public API
+ */
+export declare class CacheManager {
+    private cache;
+    private config;
+    private maxSize;
+    constructor(config?: CacheConfig);
+    /**
+     * Get a cached value.
+     *
+     * @param key - Cache key
+     * @returns Cached value or undefined if not found/expired
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * 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<T>(key: string, value: T, ttl?: number): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * Delete a cached value.
+     *
+     * @param key - Cache key
+     * @returns Whether the key was deleted
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cached values.
+     */
+    clear(): void;
+    /**
+     * Get the number of cached items.
+     *
+     * @returns Cache size
+     */
+    get size(): number;
+    /**
+     * Get cache statistics.
+     *
+     * @returns Cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Remove expired entries.
+     *
+     * @returns Number of entries removed
+     */
+    cleanup(): number;
+    /**
+     * Update the cache configuration.
+     *
+     * @param config - New configuration
+     */
+    updateConfig(config: Partial<CacheConfig>): void;
+    /**
+     * Check if an entry is expired.
+     *
+     * @param entry - Cache entry
+     * @returns Whether the entry is expired
+     */
+    private isExpired;
+    /**
+     * Evict the least recently used entry.
+     */
+    private evictLRU;
+}
+/**
+ * Cache statistics.
+ * @public API
+ */
+export interface CacheStats {
+    /** Current cache size */
+    size: number;
+    /** Maximum cache size */
+    maxSize: number;
+    /** Total cache hits */
+    totalHits: number;
+    /** Number of expired entries */
+    expiredCount: number;
+    /** Whether caching is enabled */
+    enabled: boolean;
+}
+/**
+ * Get the cache manager singleton.
+ *
+ * @param config - Optional configuration
+ * @returns Cache manager instance
+ */
+export declare function getCacheManager(config?: CacheConfig): CacheManager;

package/lib/cjs/types/render/utils/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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";
+export type { CacheStats } from "./cache-manager.js";