@expressots/adapter-express 3.0.0 → 4.0.0-preview.3

package/lib/cjs/types/adapter-express/express-utils/decorators.d.ts

@@ -1,8 +1,8 @@
 import "reflect-metadata";
-import { PARAMETER_TYPE, HTTP_VERBS_ENUM } from "./constants";
-import type { HandlerDecorator, Middleware } from "./interfaces";
+import { PARAMETER_TYPE, HTTP_VERBS_ENUM } from "./constants.js";
+import type { HandlerDecorator, Middleware, NewableFunction } from "./interfaces.js";
 import { Request } from "express";
-export declare const injectHttpContext: (target: import("@expressots/core/lib/cjs/types/di/annotation/decorator_utils").DecoratorTarget, targetKey?: string | symbol, indexOrPropertyDescriptor?: number | TypedPropertyDescriptor<unknown>) => void;
+export declare const injectHttpContext: ParameterDecorator & PropertyDecorator;
 /**
  * Controller decorator to define a new controller
  * @param path route path
@@ -24,6 +24,25 @@ export declare function controller(path: string, ...middleware: Array<Middleware
  * @public API
  */
 export declare function Http(code: number): (target: object, key: string | symbol, descriptor: TypedPropertyDescriptor<any>) => void;
+/**
+ * Version decorator to define the API version for a controller or route method
+ * @param version API version (e.g., "1", "1.0", "v1", or 1)
+ * @returns ClassDecorator | MethodDecorator
+ * @example ```typescript
+ * @Version("1")
+ * @controller("/users")
+ * class UserController {}
+ *
+ * // Or at method level:
+ * @Version("2")
+ * @Get("/")
+ * getUsers() {
+ *   return "v2 users";
+ * }
+ * ```
+ * @public API
+ */
+export declare function Version(version: string | number): (target: any, key?: string | symbol, descriptor?: any) => void;
 /**
  * Decorator to allow accept all HTTP methods
  * @param path route path, wildcard
@@ -195,11 +214,40 @@ type FieldOptions = {
     maxCount?: number;
 };
 /**
- * File upload decorator to handle file uploads
- * @param options
- * @param multerOptions
+ * File upload decorator to handle file uploads.
+ *
+ * This decorator integrates with the global upload configuration
+ * set via `Middleware.upload()` in app.ts. If global config exists,
+ * it will be used as defaults, with local options taking precedence.
+ *
+ * @param options - Field configuration (fieldName, maxCount, none, any)
+ * @param multerOptions - Optional multer options (overrides global config)
  * @default { none: true }
  * @returns MethodDecorator
+ *
+ * @example
+ * ```typescript
+ * // In app.ts - configure globally (optional)
+ * this.Middleware.upload({
+ *   destination: './uploads',
+ *   limits: { fileSize: 10 * 1024 * 1024 }
+ * });
+ *
+ * // In controller - uses global config automatically
+ * @Post('avatar')
+ * @FileUpload({ fieldName: 'avatar' })
+ * uploadAvatar(req: Request) {
+ *   return req.file;
+ * }
+ *
+ * // Override global config for specific endpoint
+ * @Post('document')
+ * @FileUpload({ fieldName: 'doc' }, { limits: { fileSize: 50 * 1024 * 1024 } })
+ * uploadDocument(req: Request) {
+ *   return req.file;
+ * }
+ * ```
+ *
  * @public API
  */
 export declare function FileUpload(options?: FieldOptions | Array<FieldOptions> | {

package/lib/cjs/types/adapter-express/express-utils/exception-filter-decorators.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-export exception filter decorators from core for backward compatibility
+ * These decorators are now part of @expressots/core to avoid circular dependencies
+ * @public API
+ */
+export { Catch, UseFilters } from "@expressots/core";

package/lib/cjs/types/adapter-express/express-utils/guard-context-factory.d.ts

@@ -0,0 +1,17 @@
+import "reflect-metadata";
+import { Request, Response } from "express";
+import { interfaces } from "@expressots/core";
+import type { GuardContext } from "@expressots/core";
+import type { IScopeExtractor } from "./scope-extractor.interface.js";
+/**
+ * Factory for creating GuardContext from Express request/response
+ */
+export declare class GuardContextFactory {
+    private container;
+    private scopeExtractor;
+    constructor(container: interfaces.Container, scopeExtractor: IScopeExtractor);
+    /**
+     * Create GuardContext from Express request/response
+     */
+    create(req: Request, res: Response): Promise<GuardContext>;
+}

package/lib/cjs/types/adapter-express/express-utils/guard-middleware.d.ts

@@ -0,0 +1,22 @@
+import { Request, Response, NextFunction } from "express";
+import { Container } from "@expressots/core";
+import { GuardExecutor } from "@expressots/core";
+import { GuardContextFactory } from "./guard-context-factory.js";
+/**
+ * Express middleware that executes guards before route handler
+ */
+export declare class GuardMiddleware {
+    private executor;
+    private contextFactory;
+    private container;
+    constructor(executor: GuardExecutor, contextFactory: GuardContextFactory, container: Container);
+    /**
+     * Express middleware function
+     */
+    execute: (req: Request, res: Response, next: NextFunction) => Promise<void>;
+    /**
+     * Extract guards from request metadata
+     * @private
+     */
+    private extractGuards;
+}

package/lib/cjs/types/adapter-express/express-utils/guard-utils.d.ts

@@ -0,0 +1,11 @@
+import "reflect-metadata";
+import type { GuardClass, IGuard } from "@expressots/core";
+import type { NewableFunction } from "./interfaces.js";
+/**
+ * Extract guards from controller metadata
+ */
+export declare function getControllerGuards(constructor: NewableFunction): Array<GuardClass | IGuard>;
+/**
+ * Extract guards from method metadata
+ */
+export declare function getMethodGuards(constructor: NewableFunction, methodName: string | symbol): Array<GuardClass | IGuard>;

package/lib/cjs/types/adapter-express/express-utils/http-context-store.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Per-request HttpContext storage.
+ *
+ * Replaces the previous `Reflect.defineMetadata(METADATA_KEY.httpContext, ctx, req)`
+ * call in `InversifyExpressServer.build()`, which paid the cost of
+ * `reflect-metadata` map allocation and key lookup on every single request.
+ *
+ * A `WeakMap<Request, HttpContext>` is functionally identical (lookup keyed
+ * by request reference, GC'd when the request goes out of scope) and is
+ * substantially cheaper on the hot path because it bypasses
+ * `reflect-metadata`'s string-keyed metadata store.
+ *
+ * Both `InversifyExpressServer` and `GuardContextFactory` use this module
+ * so they observe the same per-request value.
+ */
+import type { Request } from "express";
+import type { HttpContext } from "./interfaces.js";
+export declare function setHttpContext(req: Request, ctx: HttpContext): void;
+export declare function getHttpContext(req: Request): HttpContext | undefined;
+export declare function hasHttpContext(req: Request): boolean;

package/lib/cjs/types/adapter-express/express-utils/httpResponseMessage.d.ts

@@ -1,5 +1,5 @@
 import type { OutgoingHttpHeaders } from "node:http";
-import { HttpContent } from "./content/httpContent";
+import { HttpContent } from "./content/httpContent.js";
 export declare class HttpResponseMessage {
     private _content;
     private _headers;

package/lib/cjs/types/adapter-express/express-utils/index.d.ts

@@ -1,2 +1,30 @@
-export * from "./decorators";
-export { Controller } from "./interfaces";
+export * from "./decorators.js";
+export { Accept, Consumes, Produces, CsvOptions, XmlOptions, YamlOptions, StreamResponse, } from "./content-negotiation-decorators.js";
+export { Controller } from "./interfaces.js";
+export { Patterns, pattern } from "./route-constraints.js";
+export { when, unless, isConditionalMiddleware } from "./conditional-middleware.js";
+export type { ConditionalMiddlewareConfig, MiddlewareCondition } from "./conditional-middleware.js";
+export { combine, sequence, isComposedMiddleware } from "./middleware-composition.js";
+export type { ComposedMiddlewareConfig } from "./middleware-composition.js";
+export { Catch, UseFilters } from "./exception-filter-decorators.js";
+export { getControllerGuards, getMethodGuards } from "./guard-utils.js";
+export { GuardContextFactory } from "./guard-context-factory.js";
+export { GuardMiddleware } from "./guard-middleware.js";
+export { InterceptorMiddleware, createInterceptorMiddleware } from "./interceptor-middleware.js";
+export { ScopeExtractor } from "./scope-extractor.js";
+export type { IScopeExtractor } from "./scope-extractor.interface.js";
+export { PermissionPreloaderMiddleware } from "./permission-preloader.middleware.js";
+export { TYPE } from "./constants.js";
+export type { AuthProvider, Principal } from "./interfaces.js";
+export { setupAuthorizationForExpress } from "./setup-authorization.js";
+export { setupEventSystemForExpress } from "./setup-event-system.js";
+export type { EventSystemOptions, EventSystemSetupResult } from "./setup-event-system.js";
+export { setupInterceptorsForExpress } from "./setup-interceptors.js";
+export type { InterceptorSystemOptions, InterceptorSystemSetupResult, BuiltInInterceptor, InterceptorClass, } from "./setup-interceptors.js";
+export { setupLazyLoadingForExpress } from "./setup-lazy-loading.js";
+export type { LazyLoadingOptions, LazyLoadingSetupResult, LazyLoadingExpressOptions, LazyLoadingExpressResult, LazyRouteMapping, } from "./setup-lazy-loading.js";
+export { createLazyModuleMiddleware, createRouteMappings } from "./lazy-module-middleware.js";
+export { validatedBody, validatedQuery, validatedParam, validatedHeaders, Validate, getValidationMetadata, hasValidationMetadata, } from "./validation-decorators.js";
+export type { ValidationSchemaMetadata, SchemaType, ValidatedDecoratorOptions, } from "./validation-decorators.js";
+export { ValidationService } from "./validation-service.js";
+export { getHttpContext, hasHttpContext } from "./http-context-store.js";

package/lib/cjs/types/adapter-express/express-utils/interceptor-middleware.d.ts

@@ -0,0 +1,40 @@
+import { Request, Response, NextFunction } from "express";
+import { Container, interfaces, InterceptorExecutor } from "@expressots/core";
+import "reflect-metadata";
+/**
+ * Express middleware that executes interceptors around route handler
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * @summary Quick Start
+ * InterceptorMiddleware integrates the interceptor system with Express.
+ * It wraps the route handler with interceptors defined via @UseInterceptors().
+ *
+ * @internal
+ */
+export declare class InterceptorMiddleware {
+    private executor;
+    private container;
+    constructor(executor: InterceptorExecutor, container: Container);
+    /**
+     * Create middleware for a specific controller and method
+     * @param controllerClass - Controller class
+     * @param methodName - Method name
+     * @param handler - Original route handler
+     */
+    createMiddleware(controllerClass: NewableFunction, methodName: string | symbol, handler: (req: Request, res: Response, next: NextFunction) => Promise<unknown>): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+    /**
+     * Extract interceptors from controller and method metadata
+     * @private
+     */
+    private extractInterceptors;
+}
+/**
+ * Factory function to create interceptor middleware
+ * @param container - DI container
+ * @param controllerClass - Controller class
+ * @param methodName - Method name
+ * @param handler - Original handler
+ */
+export declare function createInterceptorMiddleware(container: interfaces.Container | Container, controllerClass: NewableFunction, methodName: string | symbol, handler: (req: Request, res: Response, next: NextFunction) => Promise<unknown>): (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/lib/cjs/types/adapter-express/express-utils/interfaces.d.ts

@@ -1,7 +1,11 @@
 import type { Application, NextFunction, Request, RequestHandler, Response } from "express";
-import { interfaces as inversifyInterfaces } from "../../di/di.interfaces";
-import { HTTP_VERBS_ENUM, PARAMETER_TYPE } from "./constants";
-import { HttpResponseMessage } from "./httpResponseMessage";
+import { interfaces as inversifyInterfaces } from "@expressots/core";
+import { HTTP_VERBS_ENUM, PARAMETER_TYPE } from "./constants.js";
+import { HttpResponseMessage } from "./httpResponseMessage.js";
+/**
+ * Type for a constructor function (class)
+ */
+export type NewableFunction = abstract new (...args: Array<any>) => any;
 type Prototype<T> = {
     [P in keyof T]: T[P] extends NewableFunction ? T[P] : T[P] | undefined;
 } & {
@@ -15,7 +19,38 @@ export type DecoratorTarget<T = unknown> = ConstructorFunction<T> | Prototype<T>
 export interface IExpressoMiddleware {
     use(req: Request, res: Response, next: NextFunction): Promise<void> | void;
 }
-export type Middleware = string | symbol | RequestHandler | IExpressoMiddleware;
+/**
+ * Conditional middleware configuration type.
+ * Import from conditional-middleware.ts for the full ConditionalMiddlewareConfig interface.
+ */
+export interface ConditionalMiddlewareConfig {
+    condition: (req: Request) => boolean | Promise<boolean>;
+    middleware: Middleware;
+    skipOnFalse?: boolean;
+}
+/**
+ * Composed middleware configuration type.
+ * Import from middleware-composition.ts for the full ComposedMiddlewareConfig interface.
+ */
+export interface ComposedMiddlewareConfig {
+    middleware: Array<Middleware>;
+    type: "combine" | "sequence";
+}
+/**
+ * Middleware class constructor type.
+ * Supports classes that extend ExpressoMiddleware or implement IExpressoMiddleware.
+ * Accepts both concrete and abstract class constructors.
+ * Phase 2: Supports class references without 'new' keyword.
+ */
+export type MiddlewareClass = (new (...args: Array<unknown>) => IExpressoMiddleware) | (abstract new (...args: Array<unknown>) => IExpressoMiddleware);
+/**
+ * Union type for all supported middleware types.
+ * Phase 2: Includes class constructors (class references) for cleaner API.
+ * Note: Uses 'any' for class constructors to support typeof class types (e.g., typeof AdminMiddleware).
+ */
+export type Middleware = string | symbol | RequestHandler | IExpressoMiddleware | ConditionalMiddlewareConfig | MiddlewareClass | {
+    prototype: IExpressoMiddleware;
+} | any;
 export type ControllerHandler = (...params: Array<unknown>) => unknown;
 export type BaseController = Record<string, ControllerHandler>;
 export interface Controller {
@@ -24,10 +59,12 @@ export interface ControllerMetadata {
     middleware: Array<Middleware>;
     path: string;
     target: DecoratorTarget;
+    version?: string | number;
 }
 export interface ControllerMethodMetadata extends ControllerMetadata {
     key: string;
     method: keyof typeof HTTP_VERBS_ENUM;
+    version?: string | number;
 }
 export interface ControllerParameterMetadata {
     [methodName: string]: Array<ParameterMetadata>;
@@ -39,7 +76,7 @@ export interface ParameterMetadata {
     type: PARAMETER_TYPE;
 }
 export type ExtractedParameters = Array<ParameterMetadata> | [Request, Response, NextFunction] | Array<unknown>;
-export type HandlerDecorator = (target: DecoratorTarget, key: string, value: unknown) => void;
+export type HandlerDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
 export type ConfigFunction = (app: Application) => void;
 export interface RoutingConfig {
     rootPath: string;

package/lib/cjs/types/adapter-express/express-utils/inversify-express-server.d.ts

@@ -1,6 +1,7 @@
 import express, { Application, Router } from "express";
-import { interfaces } from "../../di/di.interfaces";
-import type { AuthProvider, ConfigFunction, RoutingConfig } from "./interfaces";
+import { interfaces, ContentNegotiationService } from "@expressots/core";
+import type { AuthProvider, ConfigFunction, RoutingConfig } from "./interfaces.js";
+import { ValidationService } from "./validation-service.js";
 export declare class InversifyExpressServer {
     private _router;
     private _container;
@@ -10,6 +11,8 @@ export declare class InversifyExpressServer {
     private _routingConfig;
     private _AuthProvider;
     private _forceControllers;
+    private _contentNegotiationService?;
+    private _validationService?;
     /**
      * Wrapper for the express server.
      *
@@ -45,13 +48,122 @@ export declare class InversifyExpressServer {
      * Applies all routes and configuration to the server, returning the express application.
      */
     build(): express.Application;
+    /**
+     * Install a catch-all 404 handler that runs after every registered route.
+     *
+     * When the user has the suggestions feature enabled (default in development),
+     * this consults the route registry, computes "Did you mean ...?" suggestions
+     * via `getErrorHints` from `@expressots/core`, logs them through the framework
+     * Logger, and returns a structured RFC-7807-style JSON 404 instead of the
+     * default Express HTML.
+     *
+     * Users who want the legacy Express HTML 404 can opt out by configuring the
+     * Logger with `suggestions.enabled = false` (this also disables the JSON
+     * envelope so they can install their own 404 handler in the error-config fn).
+     *
+     * @private
+     */
+    private registerNotFoundHandler;
+    /**
+     * Resolve the user-configured suggestions config, falling back to the
+     * env-aware default when the Logger is not bound or has no overrides.
+     *
+     * @private
+     */
+    private resolveSuggestionsConfig;
+    /**
+     * Resolve the framework Logger from DI when available.
+     *
+     * @private
+     */
+    private resolveLogger;
     private registerControllers;
+    /**
+     * Initialize the interceptor system by binding required components
+     * @private
+     */
+    private initializeInterceptorSystem;
+    /**
+     * Check if the interceptor system is properly initialized
+     * @private
+     */
+    private isInterceptorSystemReady;
+    /**
+     * Extract interceptors from controller and method metadata
+     * @private
+     */
+    private extractInterceptors;
+    /**
+     * Wrap a handler with interceptor middleware
+     * @private
+     */
+    private wrapWithInterceptors;
+    /**
+     * Checks if a middleware item is a class constructor (not an instance).
+     * Handles classes that extend ExpressoMiddleware (which has abstract use method).
+     * Note: Abstract methods don't exist at runtime, so we check for concrete implementations.
+     */
+    private isMiddlewareClass;
     private isExpressoMiddleware;
     private resolveMiddleware;
+    /**
+     * Creates a lazy middleware handler for class constructors.
+     * Supports both container-bound middleware (via @provide()) and direct instantiation.
+     *
+     * Performance: Instances are created per-request to support request-scoped state.
+     * For better performance with stateless middleware, use container-bound middleware
+     * with proper scoping (singleton/request scope) via @provide().
+     *
+     * Note: If container resolution fails (e.g., base class missing @injectable()),
+     * falls back to direct instantiation for backward compatibility.
+     */
+    private createLazyMiddlewareHandler;
+    /**
+     * Creates a request handler for conditional middleware.
+     * Evaluates the condition and executes the wrapped middleware if condition is true.
+     */
+    private createConditionalMiddlewareHandler;
+    /**
+     * Creates a request handler for composed middleware (Phase 3: Middleware Composition).
+     * Executes all middleware in the composition sequentially.
+     * Both 'combine' and 'sequence' types behave the same way - they execute middleware
+     * sequentially and propagate errors normally (Express handles errors via next(error)).
+     *
+     * @param config - ComposedMiddlewareConfig containing the middleware array and type
+     * @returns Express RequestHandler
+     */
+    private createComposedMiddlewareHandler;
+    /**
+     * Executes a chain of middleware handlers sequentially.
+     * Each middleware calls next() to proceed to the next one.
+     * Handles both synchronous and asynchronous middleware.
+     */
+    private executeMiddlewareChain;
     private copyHeadersTo;
     private handleHttpResponseMessage;
     private handlerFactory;
+    private executeRouteHandler;
     private _getHttpContext;
+    /**
+     * Sets the content negotiation service instance.
+     * @param service - Content negotiation service instance
+     */
+    setContentNegotiationService(service: ContentNegotiationService): void;
+    /**
+     * Gets the content negotiation service if available.
+     * @returns Content negotiation service or undefined
+     */
+    private getContentNegotiationService;
+    /**
+     * Sets the validation service instance.
+     * @param service - Validation service instance
+     */
+    setValidationService(service: ValidationService): void;
+    /**
+     * Gets the validation service if available.
+     * @returns Validation service or undefined
+     */
+    private getValidationService;
     private _createHttpContext;
     private _getCurrentUser;
     private extractParameters;

package/lib/cjs/types/adapter-express/express-utils/lazy-module-middleware.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Lazy Module Auto-Load Middleware
+ *
+ * Automatically loads lazy modules when their routes are accessed.
+ * This provides seamless lazy loading without 404 errors.
+ *
+ * @module adapter-express
+ */
+import { RequestHandler, Router, Express } from "express";
+import { LazyModuleLoader, ILazyModule } from "@expressots/core";
+/**
+ * Route prefix mapping for lazy modules.
+ * Maps route prefixes to module names for auto-loading.
+ */
+export interface LazyRouteMapping {
+    /** Route prefix (e.g., "/admin", "/reports") */
+    prefix: string;
+    /** Module name to load when this prefix is accessed */
+    moduleName: string;
+    /** Whether the module is currently loaded */
+    loaded: boolean;
+}
+/**
+ * Configuration for the lazy module middleware.
+ */
+export interface LazyModuleMiddlewareConfig {
+    /** Route mappings */
+    routes: Array<LazyRouteMapping>;
+    /** The lazy module loader instance */
+    loader: LazyModuleLoader;
+    /** Global route prefix (e.g., "/api") */
+    globalPrefix?: string;
+    /** Callback when a module starts loading */
+    onLoadStart?: (moduleName: string, path: string) => void;
+    /** Callback when a module finishes loading */
+    onLoadComplete?: (moduleName: string, loadTimeMs: number) => void;
+    /** Callback when module loading fails */
+    onLoadError?: (moduleName: string, error: Error) => void;
+    /**
+     * Express app or router for dynamic route registration.
+     * When provided, routes are registered dynamically after module load,
+     * eliminating the need for 307 redirects.
+     */
+    expressApp?: Express | Router;
+    /**
+     * Callback to register lazy module routes after loading.
+     * When provided, this is called to register the module's routes dynamically.
+     * If not provided and expressApp is set, default registration is attempted.
+     */
+    onRegisterRoutes?: (moduleName: string, router: Router) => void;
+}
+/**
+ * Create middleware that auto-loads lazy modules when their routes are accessed.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * UNIQUE: Seamless lazy loading - no 404s! Modules load automatically
+ * when their routes are accessed for the first time.
+ *
+ * @example
+ * ```typescript
+ * const middleware = createLazyModuleMiddleware({
+ *   routes: [
+ *     { prefix: "/admin", moduleName: "AdminModule", loaded: false },
+ *     { prefix: "/reports", moduleName: "ReportsModule", loaded: false }
+ *   ],
+ *   loader: lazyModuleLoader,
+ *   globalPrefix: "/api"
+ * });
+ *
+ * app.use(middleware);
+ * ```
+ *
+ * @param config - Middleware configuration
+ * @returns Express middleware function
+ *
+ * @public API
+ */
+export declare function createLazyModuleMiddleware(config: LazyModuleMiddlewareConfig): RequestHandler;
+/**
+ * Extract route prefixes from a lazy module.
+ *
+ * Uses auto-detected routes from CreateLazyModule (which analyzes @controller decorators),
+ * falls back to prefetchOn config, and finally infers from module name.
+ *
+ * @param lazyModule - The lazy module to analyze
+ * @returns Detected route prefixes
+ *
+ * @public API
+ */
+export declare function extractRoutePrefixes(lazyModule: ILazyModule): Array<string>;
+/**
+ * Create route mappings from lazy modules.
+ *
+ * Route detection priority:
+ * 1. Manual routePrefixMap (if provided)
+ * 2. Auto-detected from @controller() decorators (via CreateLazyModule)
+ * 3. prefetchOn config
+ * 4. Inferred from module name
+ *
+ * @param lazyModules - Array of lazy modules
+ * @param routePrefixMap - Optional manual prefix mappings { moduleName: prefix }
+ * @returns Array of route mappings
+ *
+ * @example
+ * ```typescript
+ * // Zero-config: routes auto-detected from controllers!
+ * const mappings = createRouteMappings([AdminModule, ReportsModule]);
+ * // Automatically maps @controller("/admin") -> /admin
+ *
+ * // Or with manual overrides
+ * const mappings = createRouteMappings(
+ *   [AdminModule, ReportsModule],
+ *   { "AdminModule": "/admin-panel" }  // Override auto-detection
+ * );
+ * ```
+ *
+ * @public API
+ */
+export declare function createRouteMappings(lazyModules: Array<ILazyModule>, routePrefixMap?: Record<string, string>): Array<LazyRouteMapping>;

package/lib/cjs/types/adapter-express/express-utils/middleware-composition.d.ts

@@ -0,0 +1,85 @@
+import type { Middleware } from "./interfaces.js";
+/**
+ * Configuration object for composed middleware.
+ * Represents a group of middleware that should be executed together.
+ */
+export interface ComposedMiddlewareConfig {
+    /**
+     * Array of middleware to execute.
+     * Can be any valid ExpressoTS middleware type (function, class instance, class reference, or container-bound).
+     */
+    middleware: Array<Middleware>;
+    /**
+     * Composition type: 'combine' or 'sequence'.
+     * - 'combine': All middleware execute sequentially, errors propagate normally
+     * - 'sequence': Middleware execute sequentially, execution stops on error
+     */
+    type: "combine" | "sequence";
+    /**
+     * Symbol to identify composed middleware configuration objects.
+     * Used internally for type checking.
+     */
+    [COMPOSED_MIDDLEWARE_SYMBOL]: true;
+}
+/**
+ * Symbol to identify composed middleware configuration objects.
+ * Used internally for type checking.
+ */
+export declare const COMPOSED_MIDDLEWARE_SYMBOL: unique symbol;
+/**
+ * Type guard to check if an object is a ComposedMiddlewareConfig.
+ */
+export declare function isComposedMiddleware(item: unknown): item is ComposedMiddlewareConfig;
+/**
+ * Combines multiple middleware into a single middleware that executes all of them sequentially.
+ * All middleware will execute in order. If any middleware calls `next(error)`, the error
+ * is propagated to Express's error handling system.
+ *
+ * @param middleware - Array of middleware to combine
+ * @returns ComposedMiddlewareConfig object
+ *
+ * @example
+ * ```typescript
+ * // Combine multiple middleware into a reusable group
+ * @Get("/api", combine(AuthMiddleware, LoggingMiddleware, RateLimitMiddleware))
+ * async apiHandler() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Combine with conditional middleware (Phase 3)
+ * @Get("/admin",
+ *   when(req => req.method === "POST", combine(BodyParser, ValidationMiddleware)),
+ *   combine(AuthMiddleware, LoggingMiddleware)
+ * )
+ * async adminHandler() {}
+ * ```
+ */
+export declare function combine(...middleware: Array<Middleware>): ComposedMiddlewareConfig;
+/**
+ * Sequences multiple middleware that execute one after another.
+ * Similar to `combine()`, but semantically indicates sequential execution
+ * where each middleware depends on the previous one completing successfully.
+ * If any middleware calls `next(error)`, execution stops and the error is propagated.
+ *
+ * @param middleware - Array of middleware to sequence
+ * @returns ComposedMiddlewareConfig object
+ *
+ * @example
+ * ```typescript
+ * // Sequence middleware where each depends on the previous
+ * @Get("/api", sequence(ValidateMiddleware, TransformMiddleware, ProcessMiddleware))
+ * async apiHandler() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Sequence with conditional middleware
+ * @Get("/data",
+ *   when(req => req.method === "POST", sequence(BodyParser, ValidateMiddleware)),
+ *   sequence(AuthMiddleware, ProcessMiddleware)
+ * )
+ * async dataHandler() {}
+ * ```
+ */
+export declare function sequence(...middleware: Array<Middleware>): ComposedMiddlewareConfig;