@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/types/render/adapters/pug-adapter.d.ts

@@ -0,0 +1,57 @@
+import type { Application } from "express";
+import { BaseEngineAdapter } from "./base-adapter.js";
+import type { PugConfig } from "../render-config.js";
+/**
+ * Pug Engine Adapter
+ *
+ * @description Adapter for the Pug (formerly Jade) template engine.
+ * Provides clean, whitespace-sensitive template syntax.
+ *
+ * @example
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'pug',
+ *   viewsDir: 'src/views',
+ *   pugOptions: {
+ *     options: { pretty: true }
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export declare class PugAdapter extends BaseEngineAdapter {
+    readonly name = "pug";
+    readonly extensions: string[];
+    readonly packageName = "pug";
+    readonly supportsStreaming = false;
+    readonly supportsSSR = false;
+    private pug;
+    private options;
+    /**
+     * Initialize and configure the Pug engine.
+     *
+     * @param app - Express application instance
+     * @param options - Pug configuration options
+     */
+    setup(app: Application, options?: PugConfig): Promise<void>;
+    /**
+     * Render a view to string.
+     *
+     * @param view - View name or path (without extension)
+     * @param data - Data to pass to the template
+     * @returns Rendered HTML string
+     */
+    render(view: string, data: any): Promise<string>;
+    /**
+     * Resolve the full path to a view file.
+     *
+     * @param view - View name or path
+     * @returns Full path to the view file
+     */
+    private resolveViewPath;
+    /**
+     * Handle hot reload.
+     */
+    onHotReload(): void;
+}

package/lib/cjs/types/render/adapters/react-adapter.d.ts

@@ -0,0 +1,99 @@
+import type { Application } from "express";
+import { BaseEngineAdapter } from "./base-adapter.js";
+import type { ReactConfig, SSRConfig } from "../render-config.js";
+/**
+ * React Engine Adapter
+ *
+ * @description Adapter for React Server-Side Rendering (SSR).
+ * Provides server rendering with client-side hydration support.
+ *
+ * @example
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'react',
+ *   viewsDir: 'src/views',
+ *   reactOptions: {
+ *     ssr: { hydrate: true, streaming: true },
+ *     clientBundleDir: 'public/assets'
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export declare class ReactAdapter extends BaseEngineAdapter {
+    readonly name = "react";
+    readonly extensions: string[];
+    readonly packageName = "react-dom";
+    readonly supportsStreaming = true;
+    readonly supportsSSR = true;
+    private react;
+    private reactDom;
+    private reactDomServer;
+    private options;
+    private app;
+    private componentCache;
+    /**
+     * Initialize and configure the React engine.
+     *
+     * @param app - Express application instance
+     * @param options - React configuration options
+     */
+    setup(app: Application, options?: ReactConfig): Promise<void>;
+    /**
+     * Render a React component to string.
+     *
+     * @param view - Component name or path (without extension)
+     * @param data - Props to pass to the component
+     * @returns Rendered HTML string
+     */
+    render(view: string, data: any): Promise<string>;
+    /**
+     * Render a React component as a stream.
+     *
+     * @param view - Component name or path
+     * @param data - Props to pass to the component
+     * @returns Readable stream of HTML
+     */
+    renderStream(view: string, data: any): NodeJS.ReadableStream;
+    /**
+     * Load a React component asynchronously.
+     *
+     * @param view - Component name or path
+     * @returns React component
+     */
+    private loadComponent;
+    /**
+     * Load a React component synchronously.
+     *
+     * @param view - Component name or path
+     * @returns React component
+     */
+    private loadComponentSync;
+    /**
+     * Resolve the full path to a React component.
+     *
+     * @param view - Component name or path
+     * @returns Full path to the component file
+     */
+    private resolveComponentPath;
+    /**
+     * Wrap rendered HTML with hydration script.
+     *
+     * @param html - Rendered HTML
+     * @param view - Component name
+     * @param data - Props data
+     * @returns Complete HTML document with hydration
+     */
+    private wrapWithHydration;
+    /**
+     * Handle hot reload.
+     */
+    onHotReload(): void;
+    /**
+     * Get SSR configuration.
+     *
+     * @returns SSR configuration
+     */
+    getSSRConfig(): SSRConfig | undefined;
+}

package/lib/cjs/types/render/features/auto-detection.d.ts

@@ -0,0 +1,58 @@
+import type { EngineType } from "../render-config.js";
+/**
+ * Auto Detection
+ *
+ * @description Automatically detects the best template engine based on
+ * installed packages and existing view files.
+ *
+ * @public API
+ */
+export declare class AutoDetection {
+    private logger;
+    constructor();
+    /**
+     * Detect the best engine to use.
+     *
+     * @returns Detected engine type
+     */
+    detectEngine(): Promise<EngineType>;
+    /**
+     * Get list of installed template engine packages.
+     *
+     * @returns Array of installed engine types
+     */
+    getInstalledEngines(): Promise<Array<EngineType>>;
+    /**
+     * Scan common view directories for template files.
+     *
+     * @returns Array of found file extensions
+     */
+    scanViewFiles(): Promise<Array<string>>;
+    /**
+     * Read and parse package.json.
+     *
+     * @returns Parsed package.json content
+     */
+    private readPackageJson;
+    /**
+     * Check if an extension is a view file extension.
+     *
+     * @param extension - File extension
+     * @returns Whether it's a view extension
+     */
+    private isViewExtension;
+    /**
+     * Map a file extension to an engine type.
+     *
+     * @param extension - File extension
+     * @returns Engine type
+     */
+    mapExtensionToEngine(extension: string): EngineType;
+    /**
+     * Check if a specific engine is available.
+     *
+     * @param engine - Engine type to check
+     * @returns Whether the engine is available
+     */
+    isEngineAvailable(engine: EngineType): boolean;
+}

package/lib/cjs/types/render/features/hot-reload.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Hot Reload
+ *
+ * @description Watches view files for changes and triggers reloads in development.
+ *
+ * @public API
+ */
+export declare class HotReload {
+    private watcher;
+    private viewsDir;
+    private logger;
+    private isRunning;
+    private onChange;
+    constructor(viewsDir: string | Array<string>);
+    /**
+     * Set the change handler.
+     *
+     * @param handler - Function to call when files change
+     */
+    setOnChange(handler: () => void): void;
+    /**
+     * Start watching for file changes.
+     */
+    start(): void;
+    /**
+     * Stop watching for file changes.
+     */
+    stop(): void;
+    /**
+     * Check if hot reload is running.
+     *
+     * @returns Whether hot reload is active
+     */
+    isActive(): boolean;
+    /**
+     * Handle file change event.
+     *
+     * @param filePath - Path to changed file
+     */
+    private onFileChange;
+    /**
+     * Handle file add event.
+     *
+     * @param filePath - Path to added file
+     */
+    private onFileAdd;
+    /**
+     * Handle file delete event.
+     *
+     * @param filePath - Path to deleted file
+     */
+    private onFileDelete;
+    /**
+     * Clear a file from Node's require cache.
+     *
+     * @param filePath - Path to clear
+     */
+    private clearRequireCache;
+    /**
+     * Try to resolve chokidar package.
+     *
+     * @returns Chokidar module or null
+     */
+    private resolveChokidar;
+}

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

@@ -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/cjs/types/render/features/streaming.d.ts

@@ -0,0 +1,39 @@
+import type { Response } from "express";
+import type { EngineAdapter } from "../render-interface.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 declare class StreamingRenderer {
+    private logger;
+    constructor();
+    /**
+     * 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
+     */
+    renderWithStreaming(view: string, data: any, res: Response, adapter: EngineAdapter): Promise<void>;
+    /**
+     * Check if an adapter supports streaming.
+     *
+     * @param adapter - Engine adapter
+     * @returns Whether streaming is supported
+     */
+    supportsStreaming(adapter: EngineAdapter): boolean;
+    /**
+     * 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
+     */
+    renderProgressive(sections: Record<string, () => Promise<string>>, res: Response, priority: Array<string>): Promise<void>;
+}

package/lib/cjs/types/render/features/type-generator.d.ts

@@ -0,0 +1,64 @@
+import type { ViewInfo } from "../render-config.js";
+/**
+ * Type Generator
+ *
+ * @description Generates TypeScript type definitions for view files.
+ * Provides type safety for view rendering.
+ *
+ * @public API
+ */
+export declare class TypeGenerator {
+    private logger;
+    constructor();
+    /**
+     * 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)
+     */
+    generateViewTypes(viewsDir: string, outputFile?: string): Promise<void>;
+    /**
+     * Scan a directory for view files.
+     *
+     * @param viewsDir - Directory to scan
+     * @returns Array of view information
+     */
+    scanViews(viewsDir: string): Promise<Array<ViewInfo>>;
+    /**
+     * Recursively scan a directory.
+     *
+     * @param dir - Current directory
+     * @param baseDir - Base directory for relative paths
+     * @param views - Array to populate with view info
+     */
+    private scanDirectory;
+    /**
+     * Generate TypeScript type definitions.
+     *
+     * @param views - Array of view information
+     * @returns TypeScript type definition string
+     */
+    private generateTypes;
+    /**
+     * Check if a file is a view file.
+     *
+     * @param filename - File name
+     * @returns Whether it's a view file
+     */
+    private isViewFile;
+    /**
+     * Map file extension to engine type.
+     *
+     * @param extension - File extension
+     * @returns Engine type string
+     */
+    private mapExtensionToEngine;
+    /**
+     * Extract props type from a React component.
+     *
+     * @param filePath - Path to the component file
+     * @param extension - File extension
+     * @returns Props type string or undefined
+     */
+    private extractPropsType;
+}

package/lib/cjs/types/render/features/view-debugger.d.ts

@@ -0,0 +1,52 @@
+import type { Application } from "express";
+import type { IRenderService } from "../render-interface.js";
+/**
+ * View Debugger
+ *
+ * @description Provides debug endpoints for inspecting the render system.
+ * Only available in development mode.
+ *
+ * @public API
+ */
+export declare class ViewDebugger {
+    private renderService;
+    private logger;
+    private isRegistered;
+    constructor(renderService: IRenderService);
+    /**
+     * Register debug routes on the Express app.
+     *
+     * @param app - Express application
+     */
+    registerRoutes(app: Application): void;
+    /**
+     * Handle the main views endpoint.
+     */
+    private handleViewsEndpoint;
+    /**
+     * Handle the view preview endpoint.
+     */
+    private handlePreviewEndpoint;
+    /**
+     * Normalise the `view` route param across Express 4 and 5.
+     *
+     * Express 4 / path-to-regexp v6 captured `/__views/preview/:view(*)`
+     * as a single string. Express 5 / path-to-regexp v8 changed the
+     * named-splat capture to `string[]` (one entry per slash-separated
+     * segment). The view engine needs the slash-joined form, so we always
+     * collapse the array shape back to that.
+     */
+    private resolveViewParam;
+    /**
+     * Handle the view info endpoint.
+     */
+    private handleInfoEndpoint;
+    /**
+     * Handle the metrics endpoint.
+     */
+    private handleMetricsEndpoint;
+    /**
+     * Wrap preview HTML with debug info.
+     */
+    private wrapPreview;
+}

package/lib/cjs/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/cjs/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;