@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/render/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * ExpressoTS Render Engine
+ *
+ * @module render
+ * @description Unified render engine system supporting traditional template engines
+ * (EJS, Pug, Handlebars) and modern frameworks (React, Vue, Svelte).
+ *
+ * @example Simple usage
+ * ```typescript
+ * // In app.ts
+ * this.Middleware.render(); // Auto-detects installed engine
+ * ```
+ *
+ * @example With preset
+ * ```typescript
+ * this.Middleware.render('production');
+ * ```
+ *
+ * @example Full configuration
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'react',
+ *   viewsDir: 'src/views',
+ *   cache: 'auto',
+ *   ssr: { hydrate: true, streaming: true },
+ *   watch: 'auto'
+ * });
+ * ```
+ *
+ * @public API
+ */
+export type { RenderConfig, RenderOptions, StreamOptions, RenderMetrics, ViewInfo, EngineType, PresetName as RenderPresetName, CacheConfig, SSRConfig, EngineConfig, EjsConfig, PugConfig, HandlebarsConfig, ReactConfig, } from "./render-config.js";
+export type { EngineAdapter, IRenderService } from "./render-interface.js";
+export { EngineRegistry } from "./render-registry.js";
+export { BaseEngineAdapter } from "./adapters/base-adapter.js";
+export { EjsAdapter } from "./adapters/ejs-adapter.js";
+export { PugAdapter } from "./adapters/pug-adapter.js";
+export { HandlebarsAdapter } from "./adapters/handlebars-adapter.js";
+export { ReactAdapter } from "./adapters/react-adapter.js";
+export { PackageResolver, PackageNotInstalledError, getPackageResolver, } from "./utils/package-resolver.js";
+export { ViewScanner, getViewScanner } from "./utils/view-scanner.js";
+export { CacheManager, getCacheManager } from "./utils/cache-manager.js";
+export type { CacheStats } from "./utils/cache-manager.js";
+export { RenderService } from "./render-service.js";
+export { AutoDetection } from "./features/auto-detection.js";
+export { HotReload } from "./features/hot-reload.js";
+export { ViewDebugger } from "./features/view-debugger.js";
+export { StreamingRenderer } from "./features/streaming.js";
+export { TypeGenerator } from "./features/type-generator.js";
+export { developmentPreset as renderDevelopmentPreset, productionPreset as renderProductionPreset, ssrPreset as renderSsrPreset, getPreset as getRenderPreset, } from "./presets/index.js";

package/lib/esm/types/render/presets/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Render Engine Presets
+ *
+ * @module render/presets
+ * @description Pre-configured render configurations for common scenarios.
+ * @public API
+ */
+import type { RenderConfig, PresetName } from "../render-config.js";
+/**
+ * Development Preset
+ *
+ * Optimized for development with:
+ * - No caching (see changes immediately)
+ * - Hot reload enabled
+ * - Debug mode with /__views endpoint
+ * - Streaming disabled for easier debugging
+ *
+ * @public API
+ */
+export declare const developmentPreset: RenderConfig;
+/**
+ * Production Preset
+ *
+ * Optimized for production with:
+ * - View caching enabled
+ * - No hot reload
+ * - Debug mode disabled
+ * - Streaming enabled for performance
+ *
+ * @public API
+ */
+export declare const productionPreset: RenderConfig;
+/**
+ * SSR Preset
+ *
+ * Optimized for server-side rendering with:
+ * - Caching enabled
+ * - Streaming enabled
+ * - Full hydration support
+ * - Progressive rendering
+ *
+ * @public API
+ */
+export declare const ssrPreset: RenderConfig;
+/**
+ * Edge Preset
+ *
+ * Optimized for edge computing environments with:
+ * - Memory-only caching
+ * - Streaming enabled
+ * - Minimal runtime overhead
+ *
+ * @public API
+ */
+export declare const edgePreset: RenderConfig;
+/**
+ * API Preset
+ *
+ * Optimized for API-first applications with:
+ * - Minimal view configuration
+ * - Caching based on environment
+ *
+ * @public API
+ */
+export declare const apiPreset: RenderConfig;
+/**
+ * Get a preset by name.
+ *
+ * @param name - Preset name
+ * @returns Preset configuration
+ * @throws Error if preset not found
+ *
+ * @public API
+ */
+export declare function getPreset(name: PresetName | string): RenderConfig;
+/**
+ * Get all available preset names.
+ *
+ * @returns Array of preset names
+ *
+ * @public API
+ */
+export declare function getPresetNames(): Array<string>;
+/**
+ * Check if a preset exists.
+ *
+ * @param name - Preset name
+ * @returns Whether the preset exists
+ *
+ * @public API
+ */
+export declare function hasPreset(name: string): boolean;
+/**
+ * Register a custom preset.
+ *
+ * @param name - Preset name
+ * @param config - Preset configuration
+ *
+ * @public API
+ */
+export declare function registerPreset(name: string, config: RenderConfig): void;
+/**
+ * Merge multiple presets.
+ *
+ * @param basePreset - Base preset name
+ * @param overrides - Configuration overrides
+ * @returns Merged configuration
+ *
+ * @public API
+ */
+export declare function mergePreset(basePreset: PresetName | string, overrides: Partial<RenderConfig>): RenderConfig;
+/**
+ * Auto-select preset based on environment.
+ *
+ * @returns Appropriate preset for current environment
+ *
+ * @public API
+ */
+export declare function autoSelectPreset(): RenderConfig;

package/lib/esm/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/esm/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/esm/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;
+}