@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/render/adapters/base-adapter.d.ts

@@ -0,0 +1,95 @@
+import { Logger } from "../../provider/logger/logger.provider.js";
+import type { EngineAdapter } from "../render-interface.js";
+import type { Application } from "express";
+/**
+ * Base Engine Adapter
+ *
+ * @description Abstract base class for template engine adapters.
+ * Provides common functionality like logging, caching, and package resolution.
+ *
+ * @public API
+ */
+export declare abstract class BaseEngineAdapter implements EngineAdapter {
+    abstract readonly name: string;
+    abstract readonly extensions: Array<string>;
+    abstract readonly packageName: string;
+    readonly supportsStreaming: boolean;
+    readonly supportsSSR: boolean;
+    protected logger: Logger;
+    protected cache: Map<string, any>;
+    protected viewsDir: string | Array<string>;
+    protected isInitialized: boolean;
+    constructor();
+    /**
+     * Initialize and configure the engine.
+     * Must be implemented by subclasses.
+     */
+    abstract setup(app: Application, options: any): Promise<void>;
+    /**
+     * Render a view to string.
+     * Must be implemented by subclasses.
+     */
+    abstract render(view: string, data: any): Promise<string>;
+    /**
+     * Resolve and require a package from the user's project.
+     * Provides helpful error messages if the package is not installed.
+     *
+     * @param packageName - Package name to resolve
+     * @param options - Options to pass to the package if it's a function
+     * @returns The resolved package module
+     */
+    protected resolvePackage(packageName: string, ...options: Array<any>): any;
+    /**
+     * Check if a package is installed without throwing.
+     *
+     * @param packageName - Package name to check
+     * @returns Whether the package is installed
+     */
+    protected isPackageInstalled(packageName: string): boolean;
+    /**
+     * Cache a compiled template.
+     *
+     * @param key - Cache key (usually view path)
+     * @param compiled - Compiled template
+     */
+    protected cacheView(key: string, compiled: any): void;
+    /**
+     * Get a cached template.
+     *
+     * @param key - Cache key
+     * @returns Cached template or undefined
+     */
+    protected getCachedView(key: string): any;
+    /**
+     * Check if a template is cached.
+     *
+     * @param key - Cache key
+     * @returns Whether the template is cached
+     */
+    protected hasCachedView(key: string): boolean;
+    /**
+     * Clear the template cache.
+     */
+    protected clearCache(): void;
+    /**
+     * Called when hot reload is triggered.
+     * Clears the cache by default.
+     */
+    onHotReload(): void;
+    /**
+     * Called when cache should be invalidated.
+     */
+    onCacheInvalidate(): void;
+    /**
+     * Set the views directory.
+     *
+     * @param viewsDir - Views directory path(s)
+     */
+    protected setViewsDir(viewsDir: string | Array<string>): void;
+    /**
+     * Get the views directory.
+     *
+     * @returns Views directory path(s)
+     */
+    protected getViewsDir(): string | Array<string>;
+}

package/lib/esm/types/render/adapters/ejs-adapter.d.ts

@@ -0,0 +1,57 @@
+import type { Application } from "express";
+import { BaseEngineAdapter } from "./base-adapter.js";
+import type { EjsConfig } from "../render-config.js";
+/**
+ * EJS Engine Adapter
+ *
+ * @description Adapter for the EJS (Embedded JavaScript) template engine.
+ * Provides server-side rendering with JavaScript embedded in HTML.
+ *
+ * @example
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'ejs',
+ *   viewsDir: 'src/views',
+ *   ejsOptions: {
+ *     serverOptions: { cache: true }
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export declare class EjsAdapter extends BaseEngineAdapter {
+    readonly name = "ejs";
+    readonly extensions: string[];
+    readonly packageName = "ejs";
+    readonly supportsStreaming = false;
+    readonly supportsSSR = false;
+    private ejs;
+    private options;
+    /**
+     * Initialize and configure the EJS engine.
+     *
+     * @param app - Express application instance
+     * @param options - EJS configuration options
+     */
+    setup(app: Application, options?: EjsConfig): 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/esm/types/render/adapters/handlebars-adapter.d.ts

@@ -0,0 +1,74 @@
+import type { Application } from "express";
+import { BaseEngineAdapter } from "./base-adapter.js";
+import type { HandlebarsConfig } from "../render-config.js";
+/**
+ * Handlebars Engine Adapter
+ *
+ * @description Adapter for the Handlebars template engine.
+ * Provides logic-less templates with partials and helpers support.
+ *
+ * @example
+ * ```typescript
+ * this.Middleware.render({
+ *   engine: 'hbs',
+ *   viewsDir: 'src/views',
+ *   hbsOptions: {
+ *     partialsDir: 'src/views/partials',
+ *     helpers: {
+ *       formatDate: (date) => date.toLocaleDateString()
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export declare class HandlebarsAdapter extends BaseEngineAdapter {
+    readonly name = "hbs";
+    readonly extensions: string[];
+    readonly packageName = "hbs";
+    readonly supportsStreaming = false;
+    readonly supportsSSR = false;
+    private hbs;
+    private options;
+    /**
+     * Initialize and configure the Handlebars engine.
+     *
+     * @param app - Express application instance
+     * @param options - Handlebars configuration options
+     */
+    setup(app: Application, options?: HandlebarsConfig): 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>;
+    /**
+     * Register a helper function.
+     *
+     * @param name - Helper name
+     * @param fn - Helper function
+     */
+    registerHelper(name: string, fn: (...args: Array<any>) => any): void;
+    /**
+     * Register a partial template.
+     *
+     * @param name - Partial name
+     * @param template - Partial template string
+     */
+    registerPartial(name: string, template: string): void;
+    /**
+     * 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/esm/types/render/adapters/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Engine Adapters
+ *
+ * @module render/adapters
+ * @description Template engine adapters for the unified render system.
+ * @public API
+ */
+export { BaseEngineAdapter } from "./base-adapter.js";
+export { EjsAdapter } from "./ejs-adapter.js";
+export { PugAdapter } from "./pug-adapter.js";
+export { HandlebarsAdapter } from "./handlebars-adapter.js";
+export { ReactAdapter } from "./react-adapter.js";

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