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

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

@@ -0,0 +1,172 @@
+import express, { Application, Router } from "express";
+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;
+    private _app;
+    private _configFn;
+    private _errorConfigFn;
+    private _routingConfig;
+    private _AuthProvider;
+    private _forceControllers;
+    private _contentNegotiationService?;
+    private _validationService?;
+    /**
+     * Wrapper for the express server.
+     *
+     * @param container Container loaded with all controllers and their dependencies.
+     * @param customRouter optional express.Router custom router
+     * @param routingConfig optional interfaces.RoutingConfig routing config
+     * @param customApp optional express.Application custom app
+     * @param authProvider optional interfaces.AuthProvider auth provider
+     * @param forceControllers optional boolean setting to force controllers (defaults do true)
+     */
+    constructor(container: interfaces.Container, customRouter?: Router | null, routingConfig?: RoutingConfig | null, customApp?: Application | null, authProvider?: (new () => AuthProvider) | null, forceControllers?: boolean);
+    /**
+     * Sets the configuration function to be applied to the application.
+     * Note that the config function is not actually executed until a call to
+     * InversifyExpresServer.build().
+     *
+     * This method is chainable.
+     *
+     * @param fn Function in which app-level middleware can be registered.
+     */
+    setConfig(fn: ConfigFunction): InversifyExpressServer;
+    /**
+     * Sets the error handler configuration function to be applied to the application.
+     * Note that the error config function is not actually executed until a call to
+     * InversifyExpressServer.build().
+     *
+     * This method is chainable.
+     *
+     * @param fn Function in which app-level error handlers can be registered.
+     */
+    setErrorConfig(fn: ConfigFunction): 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;
+    private getParam;
+    private _getPrincipal;
+}

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

package/lib/esm/types/adapter-express/express-utils/path-pattern-compat.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Express 5 / path-to-regexp v8 compatibility for the `:name(regex)`
+ * inline-constraint syntax.
+ *
+ * `path-to-regexp` v8 (the parser Express 5 ships with) removed the
+ * inline regex form entirely — `/users/:id(\\d+)` now throws
+ *
+ *   Unexpected ( at index 10: /users/:id(\\d+)
+ *
+ * That breaks two things we ship as public API:
+ *
+ *   1. The {@link Patterns} / {@link pattern} helpers in
+ *      `route-constraints.ts`, which were introduced specifically to
+ *      encourage that pattern.
+ *   2. Hand-written controller routes upgraded from v3, where users
+ *      relied on Express 4 inline regex.
+ *
+ * Rather than break those at the surface of preview-3, we keep the
+ * authoring-time syntax and translate it at decorator time:
+ *
+ *   - {@link splitPathConstraints} parses the path into a
+ *     plain-`:name`-only form plus a list of `(name, regex)` pairs.
+ *   - {@link createPathConstraintMiddleware} returns a middleware that
+ *     runs at request time and 404s when any captured `req.params[name]`
+ *     fails to match its constraint.
+ *
+ * The middleware emits an HTTP 404 (not 400) so the behaviour matches
+ * Express 4's "no route matched" semantics — under v6 of path-to-regexp,
+ * a non-matching `:id(\\d+)` simply meant the route wasn't selected and
+ * the request fell through to the framework's NotFound handler.
+ */
+import type { RequestHandler } from "express";
+export interface PathConstraint {
+    /** The `:name` placeholder, without the leading colon. */
+    paramName: string;
+    /** Compiled regex. Anchored with `^...$` to match the whole segment. */
+    regex: RegExp;
+    /** The original raw regex text, for diagnostics. */
+    rawPattern: string;
+}
+export interface SplitPath {
+    /** Path string ready to hand to Express 5 / path-to-regexp v8. */
+    path: string;
+    /** Param-level regex constraints, in path declaration order. */
+    constraints: Array<PathConstraint>;
+}
+/**
+ * Split `:name(regex)` segments out of an Express-style route path.
+ *
+ * The walker honours balanced parens inside the regex (e.g.
+ * `(\\d{4})` or `((a|b)+)`), which is more forgiving than a naive
+ * single-pass regex match would be. Returns the original path and an
+ * empty constraints list when no inline patterns are found, so this is
+ * a no-op for the common case.
+ */
+export declare function splitPathConstraints(path: string): SplitPath;
+/**
+ * Build a middleware that enforces the given param-level regex
+ * constraints on `req.params`. Returns `null` when the list is empty
+ * (so callers can avoid wiring an unnecessary middleware).
+ *
+ * When a constraint fails, the middleware delegates to `next()` without
+ * a value; the framework's NotFound handler then converts that into a
+ * 404 — same observable behaviour as Express 4's "no route matched".
+ */
+export declare function createPathConstraintMiddleware(constraints: Array<PathConstraint>): RequestHandler | null;

package/lib/esm/types/adapter-express/express-utils/permission-preloader.middleware.d.ts

@@ -0,0 +1,10 @@
+import { Request, Response, NextFunction } from "express";
+import { BaseMiddleware } from "./base-middleware.js";
+/**
+ * Middleware that preloads permissions for authenticated users
+ * Caches permissions in request-scoped SecurityContext
+ */
+export declare class PermissionPreloaderMiddleware extends BaseMiddleware {
+    private securityContext?;
+    handler(req: Request, res: Response, next: NextFunction): Promise<void>;
+}

package/lib/esm/types/adapter-express/express-utils/resolver-multer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve package from the current working directory.
+ * @param packageName
+ * @param options
+ * @returns
+ */
+export declare function packageResolver(packageName: string): any;

package/lib/esm/types/adapter-express/express-utils/route-constraints.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Route parameter patterns for common use cases.
+ *
+ * Express 5 / path-to-regexp v8 dropped the inline-regex form
+ * (`:id(\\d+)`), so the framework no longer hands these patterns to
+ * the underlying matcher verbatim. Instead, the HTTP-method decorators
+ * (`@Get`, `@Post`, …) parse the constraint out of the path at decorator
+ * time, register the route under a plain `:id` placeholder, and inject
+ * a small validator middleware that 404s when the captured value
+ * doesn't match. The user-facing semantics are unchanged: a path that
+ * uses `Patterns.NUMERIC_ID` still rejects `/users/abc` and only
+ * dispatches the handler for matches like `/users/123`.
+ *
+ * @example
+ * ```typescript
+ * import { Patterns, pattern } from "@expressots/adapter-express";
+ *
+ * @Get(`/users/${pattern("id", Patterns.NUMERIC_ID)}`)
+ * getUserById(@param("id") id: number) {
+ *   // Only dispatches for numeric IDs like /users/123
+ * }
+ *
+ * @Get(`/documents/${pattern("uuid", Patterns.UUID)}`)
+ * getDocument(@param("uuid") uuid: string) {
+ *   // Only dispatches for valid UUIDs
+ * }
+ * ```
+ *
+ * @public API
+ */
+export declare const Patterns: {
+    /**
+     * Matches one or more digits (numeric ID)
+     * Example: /users/123 ✅, /users/abc ❌
+     */
+    readonly NUMERIC_ID: "(\\d+)";
+    /**
+     * Matches a valid UUID v4 format
+     * Example: /documents/550e8400-e29b-41d4-a716-446655440000 ✅
+     */
+    readonly UUID: "([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})";
+    /**
+     * Matches lowercase letters, numbers, and hyphens (URL-friendly slug)
+     * Example: /posts/my-awesome-post ✅, /posts/My_Post ❌
+     */
+    readonly SLUG: "([a-z0-9-]+)";
+    /**
+     * Matches alphanumeric characters (letters and numbers only)
+     * Example: /codes/ABC123 ✅, /codes/ABC-123 ❌
+     */
+    readonly ALPHANUMERIC: "([a-zA-Z0-9]+)";
+    /**
+     * Matches lowercase letters only
+     * Example: /tags/javascript ✅, /tags/JavaScript ❌
+     */
+    readonly LOWERCASE: "([a-z]+)";
+    /**
+     * Matches uppercase letters only
+     * Example: /codes/USD ✅, /codes/usd ❌
+     */
+    readonly UPPERCASE: "([A-Z]+)";
+    /**
+     * Matches email format (basic validation)
+     * Example: /users/user@example.com ✅
+     */
+    readonly EMAIL: "([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})";
+    /**
+     * Matches hexadecimal string (e.g., color codes, hash)
+     * Example: /colors/ff5733 ✅, /colors/xyz ❌
+     */
+    readonly HEXADECIMAL: "([0-9a-fA-F]+)";
+    /**
+     * Matches MongoDB ObjectId format (24 hex characters)
+     * Example: /documents/507f1f77bcf86cd799439011 ✅
+     */
+    readonly MONGO_ID: "([0-9a-fA-F]{24})";
+};
+/**
+ * Helper function to build route parameter patterns.
+ * This is optional - you can also use Patterns directly in template strings.
+ *
+ * @param paramName - The parameter name (e.g., "id", "uuid")
+ * @param pattern - The pattern from Patterns
+ * @returns The formatted route parameter with pattern
+ *
+ * @example
+ * ```typescript
+ * import { pattern, Patterns } from "@expressots/adapter-express";
+ *
+ * @Get(`/users/${pattern("id", Patterns.NUMERIC_ID)}`)
+ * getUserById(@param("id") id: number) {
+ *   // Route: /users/:id(\\d+)
+ * }
+ * ```
+ *
+ * @public API
+ */
+export declare function pattern(paramName: string, patternValue: string): string;

package/lib/esm/types/adapter-express/express-utils/scope-extractor.d.ts

@@ -0,0 +1,21 @@
+import { Request } from "express";
+import type { GuardScope } from "@expressots/core";
+import type { IScopeExtractor } from "./scope-extractor.interface.js";
+/**
+ * Extracts scope information from requests
+ * Supports tenant extraction from subdomain, header, or param
+ * Note: This is bound manually in setupAuthorizationForExpress() to allow user overrides
+ */
+export declare class ScopeExtractor implements IScopeExtractor {
+    extract(req: Request): Promise<GuardScope>;
+    /**
+     * Extract tenant ID from multiple sources
+     * @private
+     */
+    private extractTenant;
+    /**
+     * Generate or retrieve request ID
+     * @private
+     */
+    private generateRequestId;
+}

package/lib/esm/types/adapter-express/express-utils/scope-extractor.interface.d.ts

@@ -0,0 +1,12 @@
+import { Request } from "express";
+import type { GuardScope } from "@expressots/core";
+/**
+ * Interface for extracting scope information from requests
+ */
+export interface IScopeExtractor {
+    /**
+     * Extract scope information from request
+     * @param req - Express request
+     */
+    extract(req: Request): Promise<GuardScope>;
+}

package/lib/esm/types/adapter-express/express-utils/setup-authorization.d.ts

@@ -0,0 +1,34 @@
+import { interfaces } from "@expressots/core";
+import { type AuthorizationConfig } from "@expressots/core";
+import type { AuthProvider } from "./interfaces.js";
+import type { IMiddleware } from "@expressots/core";
+/**
+ * Express-specific authorization setup
+ * Automatically registers all adapter-specific services and middleware
+ *
+ * @param container - DI container
+ * @param config - Authorization configuration
+ * @param middleware - Optional middleware manager to add PermissionPreloaderMiddleware
+ * @param authProvider - Optional AuthProvider class (if not already bound)
+ *
+ * @example
+ * ```typescript
+ * export class App extends AppExpress {
+ *   async configureServices(): Promise<void> {
+ *     setupAuthorizationForExpress(
+ *       this.config.Container,
+ *       {
+ *         enablePreloading: true,
+ *         enableCaching: true,
+ *         permissionHierarchy: {
+ *           admin: ["moderator", "user"],
+ *           moderator: ["user"],
+ *         },
+ *       },
+ *       this.Middleware,
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare function setupAuthorizationForExpress(container: interfaces.Container, config?: AuthorizationConfig, middleware?: IMiddleware, authProvider?: new () => AuthProvider): void;