@expressots/adapter-express 3.0.0-beta.4.2 → 4.0.0-preview.1

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

@@ -0,0 +1,30 @@
+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/esm/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/esm/types/adapter-express/express-utils/interfaces.d.ts

@@ -0,0 +1,115 @@
+import type { Application, NextFunction, Request, RequestHandler, Response } from "express";
+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;
+} & {
+    constructor: NewableFunction;
+};
+interface ConstructorFunction<T = Record<string, unknown>> {
+    new (...args: Array<unknown>): T;
+    prototype: Prototype<T>;
+}
+export type DecoratorTarget<T = unknown> = ConstructorFunction<T> | Prototype<T>;
+export interface IExpressoMiddleware {
+    use(req: Request, res: Response, next: NextFunction): Promise<void> | void;
+}
+/**
+ * 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 {
+}
+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>;
+}
+export interface ParameterMetadata {
+    index: number;
+    injectRoot: boolean;
+    parameterName?: string | undefined;
+    type: PARAMETER_TYPE;
+}
+export type ExtractedParameters = Array<ParameterMetadata> | [Request, Response, NextFunction] | Array<unknown>;
+export type HandlerDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+export type ConfigFunction = (app: Application) => void;
+export interface RoutingConfig {
+    rootPath: string;
+}
+export interface Principal<T = unknown> {
+    details: T;
+    isAuthenticated(): Promise<boolean>;
+    isInRole(role: string): Promise<boolean>;
+    isResourceOwner(resourceId: unknown): Promise<boolean>;
+}
+export interface AuthProvider {
+    getUser(req: Request, res: Response, next: NextFunction): Promise<Principal>;
+}
+export interface HttpContext<T = unknown> {
+    container: inversifyInterfaces.Container;
+    request: Request;
+    response: Response;
+    user: Principal<T>;
+}
+export interface IHttpActionResult {
+    executeAsync(): Promise<HttpResponseMessage>;
+}
+export interface RouteDetails {
+    args?: Array<string>;
+    route: string;
+}
+export interface RouteInfo {
+    controller: string;
+    endpoints: Array<RouteDetails>;
+}
+export interface RawMetadata {
+    controllerMetadata: ControllerMetadata;
+    methodMetadata: Array<ControllerMethodMetadata>;
+    parameterMetadata: ControllerParameterMetadata;
+}
+export {};

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/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,89 @@
+/**
+ * Route parameter patterns for common use cases.
+ * These are Express regex patterns that can be used in route paths.
+ *
+ * @example
+ * ```typescript
+ * import { Patterns, pattern } from "@expressots/adapter-express";
+ *
+ * @Get(`/users/${pattern("id", Patterns.NUMERIC_ID)}`)
+ * getUserById(@param("id") id: number) {
+ *   // Only matches numeric IDs like /users/123
+ * }
+ *
+ * @Get(`/documents/${pattern("uuid", Patterns.UUID)}`)
+ * getDocument(@param("uuid") uuid: string) {
+ *   // Only matches 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;