@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -1,18 +1,11 @@
 import { ErrorRequestHandler, NextFunction, Request, RequestHandler, RequestParamHandler, Response } from "express";
-import { ErrorHandlerOptions, IMiddleware } from "./middleware-interface";
-import { OptionsJson } from "./interfaces/body-parser.interface";
-import { CompressionOptions } from "./interfaces/compression.interface";
-import { CookieParserOptions } from "./interfaces/cookie-parser.interface";
-import { CookieSessionOptions } from "./interfaces/cookie-session/cookie-session.interface";
-import { CorsOptions } from "./interfaces/cors.interface";
-import { RateLimitOptions } from "./interfaces/express-rate-limit.interface";
-import { SessionOptions } from "./interfaces/express-session.interface";
-import { OptionsHelmet } from "./interfaces/helmet.interface";
-import { FormatFn, OptionsMorgan } from "./interfaces/morgan.interface";
-import { multer } from "./interfaces/multer.interface";
-import { ServeFaviconOptions } from "./interfaces/serve-favicon.interface";
-import { ServeStaticOptions } from "./interfaces/serve-static.interface";
-import { OptionsUrlencoded } from "./interfaces/url-encoded.interface";
+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
  *
@@ -32,8 +25,42 @@ interface IExpressoMiddleware {
 }
 /**
  * Abstract class for creating custom Expresso middleware.
- * Custom middleware classes should extend this class and implement the use method.
  *
+ * @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;
@@ -57,29 +84,197 @@ 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.
- * - timestamp: The date and time at which the middleware was added to the 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 {
-    timestamp: Date;
+    /** 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;
 }
 /**
- * Singleton class that implements the IConfigure interface.
- * Manages the middleware configuration for the application,
- * including adding Body Parser and retrieving all configured middlewares.
+ * 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" }
+ *   }
+ * });
+ * ```
  *
- * @see IConfigure
  * @public API
  */
 export declare class Middleware implements IMiddleware {
+    private middlewareMap;
     private middlewarePipeline;
+    private insertionOrder;
+    private sortedPipelineCache;
     private errorHandler;
-    private logger;
+    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.
      *
@@ -89,157 +284,505 @@ export declare class Middleware implements IMiddleware {
     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;
     /**
-     * Adds a URL Encoded Parser middleware to the middleware collection.
-     * The URL Encoded Parser is responsible for parsing the URL-encoded data in the incoming request bodies.
+     * 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"
+     * });
      *
-     * @param options - Optional configuration options for the URL Encoded Parser.
+     * // Only apply auth for non-public routes
+     * middleware.addConditional({
+     *   middleware: authMiddleware,
+     *   condition: (req) => !req.path.startsWith("/public"),
+     *   name: "conditional-auth"
+     * });
+     * ```
+     *
+     * @public API
      */
-    addUrlEncodedParser(options?: OptionsUrlencoded): void;
-    addRateLimiter(options?: RateLimitOptions): void;
+    addConditional(config: ConditionalMiddlewareConfig): void;
     /**
-     * Adds a Body Parser middleware to the middleware collection using the given options.
+     * Configures the error handling middleware for the application.
      *
-     * @param options - Optional configuration options for the JSON body parser.
+     * @param options - The object containing the configuration options for the error handler middleware.
      */
-    addBodyParser(options?: OptionsJson): void;
+    setErrorHandler(options?: ErrorHandlerOptions): void;
     /**
-     * Adds Cross-Origin Resource Sharing (CORS) middleware to enable or control cross-origin requests.
+     * Gets the configured error handler middleware.
      *
-     * @param options - Optional configuration options for CORS. Defines the behavior of CORS requests like allowed origins, methods, headers, etc.
+     * @returns The error handler middleware.
      */
-    addCors(options?: CorsOptions): void;
+    getErrorHandler(): ExpressHandler;
     /**
-     * Adds Compression middleware to reduce the size of the response body and improve the speed of the client-server communication.
+     * Configures content negotiation middleware for automatic response format selection.
      *
-     * @param options - Optional configuration options for Compression. Allows fine-tuning the compression behavior, such as setting the compression level, threshold, and filter functions to determine which requests should be compressed.
+     * @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
      */
-    addCompression(options?: CompressionOptions): void;
+    getContentNegotiationService(): ContentNegotiationService | undefined;
+    private validationServiceFactory?;
     /**
-     * Adds Morgan middleware to log HTTP requests.
+     * Configures validation for automatic request parameter validation.
      *
-     * @param format - The log format. Can be a string or a function.
-     * @param options - Optional configuration options for Morgan. Defines the behavior of the logger like the output stream, buffer duration, etc.
+     * @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
      */
-    addMorgan(format: string | FormatFn, options?: OptionsMorgan | undefined): void;
+    getValidationService(): unknown;
     /**
-     * Adds Cookie Parser middleware to parse the cookie header and populate req.cookies with an object keyed by the cookie names.
+     * Enable middleware profiling to track execution times.
      *
-     * @param secret - A string or array used for signing cookies. This is optional and if not specified, the cookie-parser will not parse signed cookies.
-     * @param options - Optional configuration options for Cookie Parser.
+     * @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
      */
-    addCookieParser(secret?: string | Array<string> | undefined, options?: CookieParserOptions | undefined): void;
+    getProfiler(): MiddlewareProfiler | null;
     /**
-     * Adds Cookie Session middleware to enable cookie-based sessions.
+     * Get profiling metrics for all middleware.
      *
-     * @param options - Optional configuration options for Cookie Session. Defines the behavior of cookie sessions like the name of the cookie, keys to sign the cookie, etc.
+     * @returns Array of middleware metrics or empty array if profiling is disabled
+     * @public API
      */
-    addCookieSession(options: CookieSessionOptions): void;
+    getProfilingMetrics(): Array<MiddlewareMetrics>;
     /**
-     * Adds a middleware to serve the favicon to the middleware collection.
-     * The favicon is the icon that is displayed in the browser tab for the application.
+     * Get profiling statistics.
      *
-     * @param path - The path to the favicon file.
-     * @param options - Optional configuration options for serving the favicon. Defines the behavior of the favicon middleware like cache control, custom headers, etc.
+     * @returns Profiler statistics or null if profiling is disabled
+     * @public API
      */
-    addServeFavicon(path: string | Buffer, options?: ServeFaviconOptions): void;
-    setupMulter(options?: multer.Options): multer.Multer;
+    getProfilingStats(): ProfilerStats | null;
     /**
-     * Adds a middleware to enhance security by setting various HTTP headers.
+     * Add a health check endpoint that reports middleware status.
+     *
+     * @param options - Health check options
+     *
+     * @example
+     * ```typescript
+     * middleware.addHealthCheck({
+     *   path: "/health/middleware",
+     *   includeMetrics: true
+     * });
+     * ```
      *
-     * @param options - Optional configuration options for Helmet.
+     * @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.
      */
-    addHelmet(options?: OptionsHelmet): void;
+    getMiddlewarePipeline(): Array<MiddlewarePipeline>;
+    /**
+     * View middleware pipeline formatted as a table.
+     */
+    viewMiddlewarePipeline(): void;
     /**
-     * Add a middleware to enable express-session.
+     * Get a visual ASCII representation of the middleware pipeline.
+     *
+     * @returns ASCII art diagram of the pipeline
      *
-     * @param options - Optional configuration options for Session.
+     * @example
+     * ```typescript
+     * console.log(middleware.visualizePipeline());
+     * // ╔══════════════════════════════════════════════════════════════╗
+     * // ║                  MIDDLEWARE PIPELINE                        ║
+     * // ╠══════════════════════════════════════════════════════════════╣
+     * // ║ 📦 jsonParser                              [parser]         ║
+     * // ║     ↓                                                       ║
+     * // ║ 🔒 cors                                    [security]       ║
+     * // ║     ↓                                                       ║
+     * // ║ 🔒 helmet                                  [security]       ║
+     * // ╚══════════════════════════════════════════════════════════════╝
+     * ```
      *
+     * @public API
      */
-    addSession(options: SessionOptions): void;
+    visualizePipeline(): string;
     /**
-     * Configures the error handling middleware for the application.
+     * Get a compact summary of the middleware pipeline.
      *
-     * @param options - The object containing the configuration options for the error handler middleware.
-     * @param errorHandler - The Express error handler function that takes care of processing errors and formulating the response.
-     * @param showStackTrace - A boolean value indicating whether to show the stack trace in the response.
+     * @returns Single-line summary
+     * @public API
      */
-    setErrorHandler(options?: ErrorHandlerOptions): void;
+    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;
+    };
     /**
-     * Adds a middleware to serve static files from the specified root directory.
-     * Allows the application to serve files like images, CSS, JavaScript, etc.
+     * 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 root - The root directory from which the static assets are to be served.
-     * @param options - Optional configuration options for serving static files. Defines behavior like cache control, custom headers, etc.
+     * @param name - The middleware name to remove
+     * @returns True if removed, false if not found
+     * @public API
      */
-    serveStatic(root: string, options?: ServeStaticOptions): void;
+    remove(name: string): boolean;
     /**
-     * Helper method to add middleware configuration objects to the middleware collection.
-     * @param middleware - The middleware configuration object to be added to the middleware collection.
-     * @returns void
+     * Clear all middleware from the pipeline.
+     * @public API
      */
-    private addConfigMiddleware;
+    clear(): void;
     /**
-     * Helper method to add express request handler functions to the middleware collection.
-     * @param middleware - The express request handler function to be added to the middleware collection.
-     * @returns void
+     * Get the total number of middleware in the pipeline.
+     * @returns Number of middleware
+     * @public API
      */
-    private addExpressHandlerMiddleware;
+    count(): number;
     /**
-     * Helper method to add custom Expresso middleware to the middleware collection.
-     * @param middleware - The custom Expresso middleware to be added to the middleware collection.
-     * @returns void
+     * Configure request parsing (unified method).
+     * Replaces: addBodyParser, addUrlEncodedParser, addCookieParser
      */
-    private addIExpressoMiddleware;
+    parse(options?: ParseOptions): void;
     /**
-     * Adds a middleware to the middleware collection.
+     * 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.
      *
-     * @param options - The Express request handler function to be added to the middleware collection, or a middleware configuration object
-     * that is composed by a route and an expressjs handler, or a custom Expresso middleware.
+     * When called, this stores the configuration globally so that
+     * @FileUpload decorators can use these settings as defaults.
      *
-     * @example Express Handler
-     *  const middleware = (req, res, next) => {
-     *    // Your middleware logic here
-     *    next();
-     *  }
+     * @param config - Upload configuration
+     * @returns Upload handler with single, array, fields, any, none methods
      *
-     * @example Middleware Configuration Object
-     *  const middleware = {
-     *    path: "/",
-     *    middlewares: [] // Array of Express Handlers
-     *  }
+     * @example
+     * ```typescript
+     * // In app.ts - configure globally
+     * this.Middleware.upload({
+     *   destination: './uploads',
+     *   limits: { fileSize: 10 * 1024 * 1024 }
+     * });
      *
-     * @example Expresso Middleware
-     *  class CustomMiddleware implements IExpressoMiddleware {
-     *    use(req: Request, res: Response, next: NextFunction): Promise<void> | void {
-     *    // Your middleware logic here
-     *      next();
-     *    }
-     *  }
+     * // In controller - @FileUpload uses global config
+     * @FileUpload({ fieldName: 'avatar' })
+     * uploadAvatar(req: Request) { }
+     * ```
+     *
+     * @public API
      */
-    addMiddleware(options: MiddlewareOptions): void;
+    upload(config?: UploadConfig): UploadHandler;
     /**
-     * Retrieves middleware pipeline in the order they were added.
+     * 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.
      *
-     * @returns An array of Express request handlers representing the middlewares.
+     * 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
      */
-    getMiddlewarePipeline(): Array<MiddlewarePipeline>;
+    private getBuiltInPresets;
     /**
-     * View middleware pipeline formatted.
-     * @returns void
+     * Get preset config by name.
      */
-    viewMiddlewarePipeline(): void;
+    private getPresetConfig;
     /**
-     * Gets the configured error handler middleware.
+     * 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).
      *
-     * @returns The error handler middleware.
+     * @param config - Render configuration or preset name
      */
-    getErrorHandler(): ExpressHandler;
+    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 {};