@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/middleware/middleware-service.d.ts

@@ -0,0 +1,788 @@
+import { ErrorRequestHandler, NextFunction, Request, RequestHandler, RequestParamHandler, Response } from "express";
+import { ErrorHandlerOptions, IMiddleware } from "./middleware-interface.js";
+import { MiddlewareEntry as RegistryEntry } from "./middleware-registry.js";
+import type { ParseOptions, MiddlewareLoggerConfig, SecurityConfig, SecurityPreset, CompressConfig, SessionConfig as V4SessionConfig, UploadConfig, UploadHandler, StaticConfig, MiddlewareConfig as V4MiddlewareConfig, OptimizationConfig, PipelineAnalysis, Recommendation } from "./middleware-config.js";
+import { ContentNegotiationService } from "./content-negotiation/content-negotiation-service.js";
+import { ContentNegotiationOptions } from "./interfaces/content-negotiation.interface.js";
+import type { ValidationConfig } from "../provider/validation/validation.interface.js";
+import { MiddlewareProfiler, MiddlewareMetrics, ProfilerStats } from "./middleware-profiler.js";
+/**
+ * ExpressHandler Type
+ *
+ * The ExpressHandler type is a union type that represents various types of Express middleware functions.
+ * It can be one of the following types:
+ * - express.ErrorRequestHandler: Handles errors in the middleware pipeline.
+ * - express.RequestParamHandler: Handles parameters in the middleware pipeline.
+ * - express.RequestHandler: General request handler.
+ * - undefined: Represents the absence of a handler.
+ */
+export type ExpressHandler = ErrorRequestHandler | RequestParamHandler | RequestHandler | undefined;
+/**
+ * Expresso middleware interface.
+ */
+interface IExpressoMiddleware {
+    use(req: Request, res: Response, next: NextFunction): Promise<void> | void;
+}
+/**
+ * Abstract class for creating custom Expresso middleware.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept custom-middleware
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Create custom middleware classes by extending this abstract class.
+ *
+ * @example
+ * ```typescript
+ * class AuthMiddleware extends ExpressoMiddleware {
+ *   use(req: Request, res: Response, next: NextFunction): void {
+ *     const token = req.headers.authorization;
+ *     if (!token) {
+ *       return res.status(401).json({ error: "Unauthorized" });
+ *     }
+ *     next();
+ *   }
+ * }
+ *
+ * // Use in application
+ * services.Middleware.addMiddleware(new AuthMiddleware());
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Provides `name` getter (returns constructor name)
+ * - Abstract `use()` method must be implemented
+ * - Compatible with Express middleware signature
+ *
+ * @see {@link IMiddleware.addMiddleware} for adding middleware
+ *
+ * @public API
+ */
+export declare abstract class ExpressoMiddleware implements IExpressoMiddleware {
+    get name(): string;
+    abstract use(req: Request, res: Response, next: NextFunction): Promise<void> | void;
+}
+/**
+ * MiddlewareOptions Type
+ *
+ * The MiddlewareOptions type represents arguments that can be passed to a middleware function.
+ * It can either be a expressjs request handler function, a middleware configuration object that is composed by a route and an expressjs handler or
+ */
+export type MiddlewareOptions = ExpressHandler | MiddlewareConfig | IExpressoMiddleware;
+/**
+ * MiddlewareConfig Interface
+ *
+ * The MiddlewareConfig interface specifies the structure for middleware configuration objects.
+ * - path: Optional. The route path for which the middleware is configured.
+ * - middlewares: An array of ExpressHandler types that make up the middleware pipeline for the route specified by 'path'.
+ */
+type MiddlewareConfig = {
+    path?: string;
+    middlewares: Array<ExpressHandler | IExpressoMiddleware>;
+};
+/**
+ * Middleware category for banner display and organization.
+ * @public API
+ */
+export type MiddlewareCategory = "parser" | "security" | "logging" | "validation" | "error" | "session" | "static" | "other";
+/**
+ * Enhanced middleware entry with metadata for introspection.
+ * @public API
+ */
+export interface MiddlewareEntry {
+    /** Display name of the middleware */
+    name: string;
+    /** Whether this is a built-in or custom middleware */
+    type: "built-in" | "custom";
+    /** Category for organization */
+    category: MiddlewareCategory;
+    /** Order in the pipeline (0-based) */
+    order: number;
+    /** Route path (or "Global" for global middleware) */
+    path: string;
+    /** The actual middleware */
+    middleware: ExpressHandler | MiddlewareConfig | IExpressoMiddleware;
+}
+/**
+ * MiddlewarePipeline Interface
+ *
+ * The MiddlewarePipeline interface represents the metadata and actual middleware to be executed in a middleware pipeline.
+ * - order: The insertion order of the middleware (for stable sorting).
+ * - middleware: Can be either an ExpressHandler function or a MiddlewareConfig object defining a more complex middleware setup.
+ */
+interface MiddlewarePipeline {
+    /** Insertion order for stable sorting */
+    order: number;
+    /** The middleware handler or config */
+    middleware: ExpressHandler | MiddlewareConfig | IExpressoMiddleware;
+    /** Middleware name for lookup */
+    name?: string;
+    /** Middleware category */
+    category?: MiddlewareCategory;
+    /** Whether this is built-in */
+    isBuiltIn?: boolean;
+    /** Condition function for conditional middleware */
+    condition?: (req: Request) => boolean;
+}
+/**
+ * Middleware pipeline info for banner display.
+ * @public API
+ */
+export interface MiddlewarePipelineInfo {
+    /** Total middleware count */
+    total: number;
+    /** Middleware entries */
+    entries: Array<MiddlewareEntry>;
+    /** Middleware count by category */
+    byCategory: Record<MiddlewareCategory, number>;
+}
+/**
+ * Conditional middleware configuration.
+ * @public API
+ */
+export interface ConditionalMiddlewareConfig {
+    /** The middleware handler */
+    middleware: ExpressHandler;
+    /** Condition function - middleware runs only if this returns true */
+    condition: (req: Request) => boolean;
+    /** Optional name for the middleware */
+    name?: string;
+    /** Optional category */
+    category?: MiddlewareCategory;
+}
+/**
+ * Middleware service for managing Express middleware pipeline.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept middleware-management
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Configure and manage middleware for your ExpressoTS application.
+ *
+ * @example
+ * ```typescript
+ * @provide(App)
+ * export class App extends AppFactory {
+ *   configureServices(services: IService): void {
+ *     // Add built-in middleware
+ *     services.Middleware.addCors();
+ *     services.Middleware.addBodyParser();
+ *     services.Middleware.addHelmet();
+ *
+ *     // Add custom middleware
+ *     services.Middleware.addMiddleware((req, res, next) => {
+ *       // Custom logic
+ *       next();
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * **Features:**
+ * - Built-in middleware helpers (CORS, Helmet, Body Parser, etc.)
+ * - Custom middleware support
+ * - Middleware presets for common configurations
+ * - Conditional middleware execution
+ * - Content negotiation
+ * - Request validation
+ * - Performance profiling
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Middleware service:
+ * - Maintains ordered pipeline array
+ * - Uses Map for O(1) middleware lookup
+ * - Caches sorted pipeline for performance
+ * - Supports conditional middleware execution
+ * - Integrates with middleware resolver for auto-discovery
+ *
+ * **Design Decisions**
+ * - Singleton pattern (one instance per app)
+ * - Ordered pipeline (insertion order preserved)
+ * - Cached sorting (invalidated on changes)
+ * - Built-in middleware auto-discovery
+ *
+ * @see {@link IMiddleware} for interface definition
+ * @see {@link middlewareResolver} for middleware resolution
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * Conditional middleware:
+ * ```typescript
+ * services.Middleware.addConditional({
+ *   middleware: rateLimiter,
+ *   condition: (req) => !req.headers["x-internal-service"],
+ *   name: "conditional-rate-limit"
+ * });
+ * ```
+ *
+ * Middleware presets:
+ * ```typescript
+ * services.Middleware.usePreset("api", {
+ *   overrides: {
+ *     Cors: { origin: "https://myapp.com" }
+ *   }
+ * });
+ * ```
+ *
+ * @public API
+ */
+export declare class Middleware implements IMiddleware {
+    private middlewareMap;
+    private middlewarePipeline;
+    private insertionOrder;
+    private sortedPipelineCache;
+    private errorHandler;
+    private _logger;
+    private contentNegotiationService;
+    private profiler;
+    private profilingEnabled;
+    private customPresets;
+    private _lastPreset;
+    private registry;
+    private startupLogs;
+    private registeredMiddlewareNames;
+    constructor();
+    /**
+     * Buffer a startup log message to be displayed after the banner.
+     * Only buffers in development mode.
+     * @param message - The message to buffer
+     * @param type - Log type: "info" or "warn"
+     */
+    private bufferStartupLog;
+    /**
+     * Get all buffered startup logs for display after the banner.
+     * Includes warnings from the middleware resolver (e.g., missing packages).
+     * @returns Array of startup log entries
+     */
+    getStartupLogs(): Array<{
+        message: string;
+        type: "info" | "warn";
+    }>;
+    /**
+     * Clear all buffered startup logs.
+     */
+    clearStartupLogs(): void;
+    /**
+     * Retrieves the type of the middleware.
+     *
+     * @param middleware - The middleware to be checked.
+     * @returns The type of the middleware.
+     */
+    private getMiddlewareType;
+    /**
+     * Checks if a middleware with the given name exists in the middleware collection.
+     * Uses O(1) Map lookup instead of O(n) array scan.
+     *
+     * @param middlewareName - The name of the middleware to be checked.
+     * @returns A boolean value indicating whether the middleware exists or not.
+     */
+    private middlewareExists;
+    /**
+     * Invalidate the sorted pipeline cache.
+     */
+    private invalidateCache;
+    /**
+     * Generic method to add built-in middleware with consistent pattern.
+     *
+     * @param name - Middleware name for lookup
+     * @param category - Middleware category
+     * @param middlewareFactory - Factory function that creates the middleware
+     * @returns True if middleware was added, false if skipped
+     */
+    private addBuiltInMiddleware;
+    /**
+     * Get middleware name from a pipeline entry.
+     */
+    private getMiddlewareName;
+    /**
+     * Get the category of a middleware.
+     */
+    private getMiddlewareCategory;
+    /**
+     * Get the path for a middleware.
+     */
+    private getMiddlewarePath;
+    /**
+     * Internal: Sets up Multer middleware for handling multipart/form-data.
+     * Used by upload() method.
+     * @internal
+     */
+    private setupMulter;
+    /**
+     * Internal: Adds a middleware to serve static files.
+     * Used by static() method.
+     * @internal
+     */
+    private serveStatic;
+    /**
+     * Helper method to add middleware configuration objects.
+     */
+    private addConfigMiddleware;
+    /**
+     * Helper method to add express request handler functions.
+     */
+    private addExpressHandlerMiddleware;
+    /**
+     * Helper method to add custom Expresso middleware.
+     */
+    private addIExpressoMiddleware;
+    /**
+     * Adds a middleware to the middleware collection.
+     *
+     * @param options - The Express request handler function, middleware configuration object,
+     * or a custom Expresso middleware.
+     *
+     * @example Express Handler
+     * ```typescript
+     * const middleware = (req, res, next) => {
+     *   // Your middleware logic here
+     *   next();
+     * }
+     * ```
+     *
+     * @example Middleware Configuration Object
+     * ```typescript
+     * const middleware = {
+     *   path: "/",
+     *   middlewares: [] // Array of Express Handlers
+     * }
+     * ```
+     *
+     * @example Expresso Middleware
+     * ```typescript
+     * class CustomMiddleware implements IExpressoMiddleware {
+     *   use(req: Request, res: Response, next: NextFunction): Promise<void> | void {
+     *     // Your middleware logic here
+     *     next();
+     *   }
+     * }
+     * ```
+     */
+    addMiddleware(options: MiddlewareOptions): void;
+    /**
+     * Add middleware that only executes when a condition is met.
+     *
+     * @param config - Conditional middleware configuration
+     *
+     * @example
+     * ```typescript
+     * // Only apply rate limiting for non-internal requests
+     * middleware.addConditional({
+     *   middleware: rateLimiter,
+     *   condition: (req) => !req.headers["x-internal-service"],
+     *   name: "conditional-rate-limit"
+     * });
+     *
+     * // Only apply auth for non-public routes
+     * middleware.addConditional({
+     *   middleware: authMiddleware,
+     *   condition: (req) => !req.path.startsWith("/public"),
+     *   name: "conditional-auth"
+     * });
+     * ```
+     *
+     * @public API
+     */
+    addConditional(config: ConditionalMiddlewareConfig): void;
+    /**
+     * Configures the error handling middleware for the application.
+     *
+     * @param options - The object containing the configuration options for the error handler middleware.
+     */
+    setErrorHandler(options?: ErrorHandlerOptions): void;
+    /**
+     * Gets the configured error handler middleware.
+     *
+     * @returns The error handler middleware.
+     */
+    getErrorHandler(): ExpressHandler;
+    /**
+     * Configures content negotiation middleware for automatic response format selection.
+     *
+     * @param options - Configuration options for content negotiation
+     * @public API
+     */
+    addContentNegotiation(options?: ContentNegotiationOptions): void;
+    /**
+     * Gets the content negotiation service instance.
+     * @returns Content negotiation service or undefined if not configured
+     * @internal
+     */
+    getContentNegotiationService(): ContentNegotiationService | undefined;
+    private validationServiceFactory?;
+    /**
+     * Configures validation for automatic request parameter validation.
+     *
+     * @param options - Configuration options for validation
+     * @public API
+     */
+    addValidation(options?: ValidationConfig): void;
+    /**
+     * Gets the validation configuration.
+     * @internal
+     */
+    getValidationConfig(): ValidationConfig | undefined;
+    /**
+     * Sets the validation service factory (called by adapter-express).
+     * @internal
+     */
+    setValidationServiceFactory(factory: () => unknown): void;
+    /**
+     * Gets the validation service instance.
+     * @internal
+     */
+    getValidationService(): unknown;
+    /**
+     * Enable middleware profiling to track execution times.
+     *
+     * @param options - Profiler options
+     * @returns The profiler instance
+     *
+     * @example
+     * ```typescript
+     * const profiler = middleware.enableProfiling();
+     *
+     * // Later, get metrics
+     * const stats = profiler.getStats();
+     * console.log(stats.metrics);
+     * ```
+     *
+     * @public API
+     */
+    enableProfiling(options?: {
+        maxSamples?: number;
+    }): MiddlewareProfiler;
+    /**
+     * Disable middleware profiling.
+     * @public API
+     */
+    disableProfiling(): void;
+    /**
+     * Get the profiler instance.
+     * @returns The profiler or null if not enabled
+     * @public API
+     */
+    getProfiler(): MiddlewareProfiler | null;
+    /**
+     * Get profiling metrics for all middleware.
+     *
+     * @returns Array of middleware metrics or empty array if profiling is disabled
+     * @public API
+     */
+    getProfilingMetrics(): Array<MiddlewareMetrics>;
+    /**
+     * Get profiling statistics.
+     *
+     * @returns Profiler statistics or null if profiling is disabled
+     * @public API
+     */
+    getProfilingStats(): ProfilerStats | null;
+    /**
+     * Add a health check endpoint that reports middleware status.
+     *
+     * @param options - Health check options
+     *
+     * @example
+     * ```typescript
+     * middleware.addHealthCheck({
+     *   path: "/health/middleware",
+     *   includeMetrics: true
+     * });
+     * ```
+     *
+     * @public API
+     */
+    addHealthCheck(options?: {
+        path?: string;
+        includeMetrics?: boolean;
+        detailed?: boolean;
+    }): void;
+    /**
+     * Retrieves middleware pipeline in the order they were added.
+     * Uses cached sorting for performance.
+     *
+     * @returns An array of middleware pipeline entries.
+     */
+    getMiddlewarePipeline(): Array<MiddlewarePipeline>;
+    /**
+     * View middleware pipeline formatted as a table.
+     */
+    viewMiddlewarePipeline(): void;
+    /**
+     * Get a visual ASCII representation of the middleware pipeline.
+     *
+     * @returns ASCII art diagram of the pipeline
+     *
+     * @example
+     * ```typescript
+     * console.log(middleware.visualizePipeline());
+     * // ╔══════════════════════════════════════════════════════════════╗
+     * // ║                  MIDDLEWARE PIPELINE                        ║
+     * // ╠══════════════════════════════════════════════════════════════╣
+     * // ║ 📦 jsonParser                              [parser]         ║
+     * // ║     ↓                                                       ║
+     * // ║ 🔒 cors                                    [security]       ║
+     * // ║     ↓                                                       ║
+     * // ║ 🔒 helmet                                  [security]       ║
+     * // ╚══════════════════════════════════════════════════════════════╝
+     * ```
+     *
+     * @public API
+     */
+    visualizePipeline(): string;
+    /**
+     * Get a compact summary of the middleware pipeline.
+     *
+     * @returns Single-line summary
+     * @public API
+     */
+    getPipelineSummary(): string;
+    /**
+     * Get structured pipeline info for banner display and introspection.
+     * @returns Middleware pipeline information
+     * @public API
+     */
+    getPipelineInfo(): MiddlewarePipelineInfo;
+    /**
+     * Get a formatted view for banner display.
+     * @param maxDisplay - Maximum number of middleware to show
+     * @returns Formatted middleware view
+     * @public API
+     */
+    getFormattedView(maxDisplay?: number): {
+        entries: Array<{
+            name: string;
+            category: MiddlewareCategory;
+            type: "built-in" | "custom";
+        }>;
+        total: number;
+        remaining: number;
+    };
+    /**
+     * Get middleware count by category.
+     * @returns Record of category to count
+     * @public API
+     */
+    getCountByCategory(): Record<MiddlewareCategory, number>;
+    /**
+     * Get middleware by name.
+     * @param name - The middleware name
+     * @returns The middleware entry or undefined
+     * @public API
+     */
+    getByName(name: string): MiddlewareEntry | undefined;
+    /**
+     * Remove a middleware from the pipeline by name.
+     *
+     * @param name - The middleware name to remove
+     * @returns True if removed, false if not found
+     * @public API
+     */
+    remove(name: string): boolean;
+    /**
+     * Clear all middleware from the pipeline.
+     * @public API
+     */
+    clear(): void;
+    /**
+     * Get the total number of middleware in the pipeline.
+     * @returns Number of middleware
+     * @public API
+     */
+    count(): number;
+    /**
+     * Configure request parsing (unified method).
+     * Replaces: addBodyParser, addUrlEncodedParser, addCookieParser
+     */
+    parse(options?: ParseOptions): void;
+    /**
+     * Configure logging with any implementation.
+     * Replaces: addMorgan
+     */
+    logger(config?: MiddlewareLoggerConfig): void;
+    private get loggerInstance();
+    /**
+     * Detect the best available logger.
+     */
+    private detectBestLogger;
+    /**
+     * Resolve logger implementation.
+     */
+    private resolveLoggerImplementation;
+    /**
+     * Unified security configuration.
+     * Replaces: addHelmet, addCors, addRateLimiter
+     */
+    security(config?: SecurityConfig | SecurityPreset): void;
+    /**
+     * Get security preset configuration.
+     */
+    private getSecurityPreset;
+    /**
+     * Configure compression.
+     * Replaces: addCompression
+     */
+    compress(config?: CompressConfig): void;
+    /**
+     * Unified session management.
+     * Replaces: addSession, addCookieSession
+     */
+    session(config: V4SessionConfig): void;
+    /**
+     * Enhanced file upload handling.
+     * Configures global upload settings and returns upload handlers.
+     *
+     * When called, this stores the configuration globally so that
+     * @FileUpload decorators can use these settings as defaults.
+     *
+     * @param config - Upload configuration
+     * @returns Upload handler with single, array, fields, any, none methods
+     *
+     * @example
+     * ```typescript
+     * // In app.ts - configure globally
+     * this.Middleware.upload({
+     *   destination: './uploads',
+     *   limits: { fileSize: 10 * 1024 * 1024 }
+     * });
+     *
+     * // In controller - @FileUpload uses global config
+     * @FileUpload({ fieldName: 'avatar' })
+     * uploadAvatar(req: Request) { }
+     * ```
+     *
+     * @public API
+     */
+    upload(config?: UploadConfig): UploadHandler;
+    /**
+     * Enhanced static file serving.
+     * Replaces: serveStatic, addServeFavicon
+     */
+    static(config: StaticConfig | string | Array<StaticConfig | string>): void;
+    /**
+     * Register a named middleware for use in routes.
+     */
+    register(name: string, handler: RequestHandler | Array<RequestHandler> | RegistryEntry): void;
+    /**
+     * Get a registered middleware by name.
+     */
+    get(name: string): RequestHandler | Array<RequestHandler> | undefined;
+    /**
+     * Check if a middleware is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered middleware names.
+     */
+    getRegisteredNames(): Array<string>;
+    /**
+     * Define a custom reusable preset.
+     */
+    definePreset(name: string, config: V4MiddlewareConfig): void;
+    /**
+     * Apply a preset configuration.
+     */
+    applyPreset(preset: string, overrides?: Partial<V4MiddlewareConfig>): void;
+    /**
+     * Get all available presets.
+     */
+    getAllPresets(): Record<string, V4MiddlewareConfig>;
+    /**
+     * Returns info about the last applied preset (name, whether overrides
+     * were used, and the effective merged config). Used by the adapter to
+     * forward preset metadata to Studio.
+     */
+    getLastAppliedPreset(): {
+        name: string;
+        hasOverrides: boolean;
+        config: V4MiddlewareConfig;
+    } | null;
+    /**
+     * Get built-in presets.
+     *
+     * Each preset is tuned for a specific workload:
+     * - api: REST APIs (large payloads, rate-limited, strict CORS)
+     * - web: traditional server-rendered apps (cookies, sessions, relaxed CORS)
+     * - spa: single-page apps served with static fallback
+     * - microservice: internal service-to-service (minimal surface, no security)
+     * - graphql: single endpoint with large JSON payloads
+     * - minimal: parsing only, no security or compression
+     * - development: relaxed for local iteration, verbose logging
+     * - production: hardened defaults for shipped deployments
+     */
+    private getBuiltInPresets;
+    /**
+     * Get preset config by name.
+     */
+    private getPresetConfig;
+    /**
+     * Get available preset names.
+     */
+    private getAvailablePresetNames;
+    /**
+     * Merge two configs.
+     */
+    private mergeConfigs;
+    /**
+     * Conditional middleware application.
+     */
+    when(condition: boolean | (() => boolean), handler: RequestHandler | (() => void)): void;
+    /**
+     * Auto-optimize middleware pipeline.
+     */
+    optimize(config?: OptimizationConfig): void;
+    /**
+     * Reorder middleware for optimal performance.
+     */
+    private reorderForPerformance;
+    /**
+     * Analyze middleware pipeline.
+     */
+    analyze(): PipelineAnalysis;
+    /**
+     * Get recommendations for improvement.
+     */
+    getRecommendations(): Array<Recommendation>;
+    /**
+     * Add custom middleware to global pipeline.
+     * Alias for addMiddleware() with shorter name.
+     */
+    add(middleware: MiddlewareOptions): void;
+    /** Render service instance (lazy initialized) */
+    private renderService;
+    /** Express app reference for render service */
+    private expressApp;
+    /**
+     * Set the Express app reference for render service initialization.
+     * Called internally by AppExpress.
+     * @internal
+     */
+    setExpressApp(app: import("express").Application): void;
+    /**
+     * Configure view rendering with unified API.
+     * Supports traditional engines (EJS, Pug, Handlebars) and modern frameworks (React, Vue, Svelte).
+     *
+     * @param config - Render configuration or preset name
+     */
+    render(config?: import("../render/render-config.js").RenderConfig | import("../render/render-config.js").PresetName): Promise<void>;
+    /**
+     * Get the render service instance.
+     *
+     * @returns Render service or null if not configured
+     */
+    getRenderService(): import("../render/render-service.js").RenderService | null;
+}
+export {};