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

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

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

package/lib/cjs/types/adapter-express/express-utils/setup-event-system.d.ts

@@ -0,0 +1,118 @@
+import { interfaces, EventRegistry, EventEmitter, EventRecorder, EventFlowTracker } from "@expressots/core";
+/**
+ * Configuration options for the event system setup.
+ *
+ * @public API
+ */
+export interface EventSystemOptions {
+    /**
+     * Enable event recording for debugging.
+     * When true, all emitted events are recorded for later inspection or replay.
+     * @default true in development, false in production
+     */
+    enableRecording?: boolean;
+    /**
+     * Enable flow tracking for event visualization.
+     * When true, tracks the flow of events through handlers.
+     * @default true in development, false in production
+     */
+    enableFlowTracking?: boolean;
+    /**
+     * Maximum number of events to keep in the recording buffer.
+     * @default 1000
+     */
+    maxRecordedEvents?: number;
+    /**
+     * Default timeout for handler execution in milliseconds.
+     * @default 30000
+     */
+    defaultTimeout?: number;
+    /**
+     * Auto-discover event handlers from the container.
+     * When true, scans the container for @OnEvent decorated handlers.
+     * @default true
+     */
+    autoDiscover?: boolean;
+    /**
+     * Callback when an event is emitted.
+     */
+    onEmit?: (event: unknown) => void;
+    /**
+     * Callback when a handler completes execution.
+     */
+    onHandlerComplete?: (result: {
+        handler: string;
+        success: boolean;
+        duration: number;
+    }) => void;
+    /**
+     * Custom error handler for handler failures.
+     */
+    onError?: (error: Error, event: unknown, handlerName: string) => void;
+}
+/**
+ * Result of event system setup.
+ *
+ * @public API
+ */
+export interface EventSystemSetupResult {
+    /**
+     * The event registry instance.
+     */
+    registry: EventRegistry;
+    /**
+     * The event emitter instance.
+     */
+    emitter: EventEmitter;
+    /**
+     * The event recorder instance (if recording is enabled).
+     */
+    recorder: EventRecorder;
+    /**
+     * The flow tracker instance (if flow tracking is enabled).
+     */
+    flowTracker: EventFlowTracker;
+    /**
+     * Number of event handlers discovered.
+     */
+    handlersDiscovered: number;
+}
+/**
+ * Set up the ExpressoTS Event System with zero boilerplate.
+ *
+ * This function:
+ * 1. Registers all event system services (EventRegistry, EventEmitter, EventRecorder, EventFlowTracker)
+ * 2. Auto-discovers and registers all @OnEvent decorated handlers
+ * 3. Configures recording and flow tracking based on environment
+ * 4. Sets up replay emitter for development debugging
+ *
+ * @param container - The DI container
+ * @param options - Configuration options for the event system
+ * @returns Setup result with references to all event system services
+ *
+ * @example
+ * ```typescript
+ * export class App extends AppExpress {
+ *   async configureServices(): Promise<void> {
+ *     // Simple setup with defaults (recommended)
+ *     const { handlersDiscovered } = setupEventSystemForExpress(
+ *       this.config.Container
+ *     );
+ *     console.log(`Discovered ${handlersDiscovered} event handlers`);
+ *
+ *     // Or with custom options
+ *     setupEventSystemForExpress(this.config.Container, {
+ *       enableRecording: true,
+ *       maxRecordedEvents: 500,
+ *       defaultTimeout: 10000,
+ *       onError: (error, event, handler) => {
+ *         console.error(`Handler ${handler} failed:`, error);
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @public API
+ */
+export declare function setupEventSystemForExpress(container: interfaces.Container, options?: EventSystemOptions): EventSystemSetupResult;

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

@@ -0,0 +1,115 @@
+import { interfaces } from "@expressots/core";
+import { InterceptorRegistry, InterceptorExecutor, IInterceptor } from "@expressots/core";
+/**
+ * Type for interceptor classes that can be registered.
+ * Accepts any class constructor, including those with DI-injected dependencies.
+ * The DI container resolves constructor parameters at runtime.
+ */
+export type InterceptorClass = new (...args: Array<any>) => IInterceptor;
+/**
+ * Built-in interceptor types that can be enabled via configuration.
+ *
+ * @public API
+ */
+export type BuiltInInterceptor = "performance" | "logging" | "timeout";
+/**
+ * Configuration options for the interceptor system setup.
+ *
+ * @public API
+ */
+export interface InterceptorSystemOptions {
+    /**
+     * Enable and configure built-in interceptors.
+     * Set to true to enable with defaults, or provide configuration object.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   performance: true,  // Enable with defaults
+     *   logging: { logResponse: true },  // Enable with custom config
+     *   timeout: { defaultTimeout: 5000 }
+     * }
+     * ```
+     */
+    builtIn?: {
+        performance?: boolean;
+        logging?: boolean;
+        timeout?: boolean | {
+            defaultTimeout?: number;
+        };
+    };
+    /**
+     * Custom interceptor classes to register.
+     * These will be bound as singletons and auto-discovered.
+     * Supports classes with DI-injected constructor dependencies.
+     *
+     * @example
+     * ```typescript
+     * customInterceptors: [CacheInterceptor, AuditInterceptor]
+     * ```
+     */
+    customInterceptors?: Array<InterceptorClass>;
+    /**
+     * Auto-discover interceptors from the container.
+     * When true, scans the container for @UseInterceptor decorated controllers/methods.
+     * @default true
+     */
+    autoDiscover?: boolean;
+}
+/**
+ * Result of interceptor system setup.
+ *
+ * @public API
+ */
+export interface InterceptorSystemSetupResult {
+    /**
+     * The interceptor registry instance.
+     */
+    registry: InterceptorRegistry;
+    /**
+     * The interceptor executor instance.
+     */
+    executor: InterceptorExecutor;
+    /**
+     * Number of interceptors registered.
+     */
+    interceptorsRegistered: number;
+}
+/**
+ * Set up the ExpressoTS Interceptor System with zero boilerplate.
+ *
+ * This function:
+ * 1. Registers all interceptor infrastructure (InterceptorRegistry, InterceptorExecutor)
+ * 2. Optionally enables built-in interceptors (Performance, Logging, Timeout)
+ * 3. Registers custom interceptor classes
+ * 4. Initializes the interceptor registry
+ *
+ * @param container - The DI container
+ * @param options - Configuration options for the interceptor system
+ * @returns Setup result with references to interceptor services
+ *
+ * @example
+ * ```typescript
+ * export class App extends AppExpress {
+ *   async configureServices(): Promise<void> {
+ *     // Simple setup with performance interceptor
+ *     setupInterceptorsForExpress(this.config.Container, {
+ *       builtIn: { performance: true }
+ *     });
+ *
+ *     // Full setup with custom interceptors
+ *     setupInterceptorsForExpress(this.config.Container, {
+ *       builtIn: {
+ *         performance: true,
+ *         logging: true,
+ *         timeout: { defaultTimeout: 5000 }
+ *       },
+ *       customInterceptors: [CacheInterceptor, AuditInterceptor]
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @public API
+ */
+export declare function setupInterceptorsForExpress(container: interfaces.Container, options?: InterceptorSystemOptions): InterceptorSystemSetupResult;

package/lib/cjs/types/adapter-express/express-utils/setup-lazy-loading.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Setup Lazy Loading for Express
+ *
+ * One-liner helper function to configure the lazy loading system.
+ *
+ * @module adapter-express
+ */
+import { RequestHandler } from "express";
+import { Container } from "@expressots/core";
+import { ILazyModule, LazyLoadingOptions, LazyLoadingSetupResult } from "@expressots/core";
+import { LazyRouteMapping } from "./lazy-module-middleware.js";
+/**
+ * Set up the lazy loading system with one function call.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept lazy-loading
+ *
+ * UNIQUE: Zero-configuration lazy loading!
+ * - Auto-detects routes from @controller() decorators
+ * - Creates middleware for automatic module loading
+ * - Optional metrics and background warmup
+ *
+ * @example
+ * ```typescript
+ * // 1. Define lazy modules (routes auto-detected from @controller)
+ * // lazy-modules.ts
+ * export const AdminModule = CreateLazyModule([AdminController]);
+ * // Routes auto-detected: ["/admin"] from @controller("/admin")
+ *
+ * export const ReportsModule = CreateLazyModule([ReportsController]);
+ * // Routes auto-detected: ["/reports"] from @controller("/reports")
+ *
+ * // 2. Setup in app.ts (just pass the modules!)
+ * export class App extends AppExpress {
+ *   async configureServices(): Promise<void> {
+ *     const { middleware } = setupLazyLoadingForExpress(
+ *       this.config.Container,
+ *       {
+ *         lazyModules: [AdminModule, ReportsModule],
+ *         globalPrefix: "/api"  // Optional
+ *       }
+ *     );
+ *
+ *     // Add middleware - that's it!
+ *     if (middleware) {
+ *       this.Middleware.addMiddleware(middleware);
+ *     }
+ *   }
+ * }
+ *
+ * // Now:
+ * // - GET /api/admin/* → AdminModule auto-loads
+ * // - GET /api/reports/* → ReportsModule auto-loads
+ * // - No manual route mapping needed!
+ * ```
+ *
+ * @param container - The DI container
+ * @param options - Configuration options
+ * @returns Setup result with loader, manager, and middleware
+ *
+ * @public API
+ */
+export declare function setupLazyLoadingForExpress(container: Container, options?: LazyLoadingExpressOptions): LazyLoadingExpressResult;
+/**
+ * Extended lazy loading options for Express.
+ *
+ * @public API
+ */
+export interface LazyLoadingExpressOptions extends LazyLoadingOptions {
+    /** Lazy modules to register */
+    lazyModules?: Array<ILazyModule>;
+    /**
+     * Manual route prefix mappings.
+     * Maps module names to route prefixes for auto-loading.
+     *
+     * @example
+     * ```typescript
+     * routePrefixes: {
+     *   "AdminModule": "/admin",
+     *   "ReportsModule": "/reports"
+     * }
+     * ```
+     */
+    routePrefixes?: Record<string, string>;
+    /**
+     * Global route prefix (e.g., "/api").
+     * Used when determining if a request matches a lazy module route.
+     */
+    globalPrefix?: string;
+    /**
+     * Enable automatic module loading when routes are accessed.
+     * When enabled, accessing a lazy module's route will trigger loading.
+     * @default true
+     */
+    enableAutoLoad?: boolean;
+}
+/**
+ * Extended result of lazy loading setup for Express.
+ *
+ * @public API
+ */
+export interface LazyLoadingExpressResult extends LazyLoadingSetupResult {
+    /**
+     * Middleware for auto-loading lazy modules.
+     * Add this to your Express app to enable auto-loading.
+     *
+     * @example
+     * ```typescript
+     * const { middleware } = setupLazyLoadingForExpress(container, options);
+     * if (middleware) {
+     *   this.Middleware.addMiddleware(middleware);
+     * }
+     * ```
+     */
+    middleware?: RequestHandler;
+    /**
+     * Route mappings used by the middleware.
+     */
+    routeMappings: Array<LazyRouteMapping>;
+}
+export type { LazyLoadingOptions, LazyLoadingSetupResult } from "@expressots/core";
+export type { LazyRouteMapping } from "./lazy-module-middleware.js";

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

@@ -1,5 +1,5 @@
-import { interfaces } from "../../di/di.interfaces";
-import type { BaseController, ControllerMetadata, ControllerMethodMetadata, ControllerParameterMetadata, DecoratorTarget, IHttpActionResult } from "./interfaces";
+import { interfaces } from "@expressots/core";
+import type { BaseController, ControllerMetadata, ControllerMethodMetadata, ControllerParameterMetadata, DecoratorTarget, IHttpActionResult } from "./interfaces.js";
 export declare function getControllersFromContainer(container: interfaces.Container, forceControllers: boolean): Array<BaseController>;
 export declare function getControllersFromMetadata(): Array<DecoratorTarget>;
 export declare function getControllerMetadata(constructor: NewableFunction): ControllerMetadata;
@@ -7,3 +7,18 @@ export declare function getControllerMethodMetadata(constructor: NewableFunction
 export declare function getControllerParameterMetadata(constructor: NewableFunction): ControllerParameterMetadata;
 export declare function cleanUpMetadata(): void;
 export declare function instanceOfIHttpActionResult(value: unknown): value is IHttpActionResult;
+/**
+ * Gets content negotiation metadata from a controller method.
+ * @param target - Controller instance
+ * @param propertyKey - Method name
+ * @returns Content negotiation metadata
+ */
+export declare function getContentNegotiationMetadata(target: object, propertyKey: string | symbol): {
+    accept?: Array<string>;
+    consumes?: Array<string>;
+    produces?: Array<string>;
+    csvOptions?: import("@expressots/core").CsvFormatOptions;
+    xmlOptions?: import("@expressots/core").XmlFormatOptions;
+    yamlOptions?: import("@expressots/core").YamlFormatOptions;
+    streamResponse?: boolean;
+};

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

@@ -0,0 +1,145 @@
+/**
+ * Validation Decorators
+ * @module @expressots/adapter-express
+ *
+ * Enhanced parameter decorators with validation support.
+ * These decorators extend the standard @body, @query, @param, @headers
+ * to accept optional schema for automatic validation.
+ */
+import "reflect-metadata";
+import type { ValidationOptions } from "@expressots/core";
+/**
+ * Metadata stored for validation
+ */
+export interface ValidationSchemaMetadata {
+    /** Parameter index */
+    index: number;
+    /** Parameter source (body, query, params, headers) */
+    source: "body" | "query" | "params" | "headers";
+    /** Schema to validate against */
+    schema?: unknown;
+    /** Validation options */
+    options?: ValidationOptions;
+    /** Whether this metadata was auto-inferred from TypeScript types */
+    inferred?: boolean;
+}
+/**
+ * Schema type - can be a class constructor, Zod schema, or any other schema type
+ */
+export type SchemaType = (new (...args: Array<unknown>) => unknown) | object;
+/**
+ * Options for validated decorators
+ */
+export interface ValidatedDecoratorOptions extends ValidationOptions {
+    /** Force specific adapter by name */
+    adapter?: string;
+}
+/**
+ * Enhanced body decorator with validation support
+ *
+ * @example
+ * ```typescript
+ * // Without validation (backward compatible)
+ * @Post("/users")
+ * createUser(@body() user: CreateUserDTO) {}
+ *
+ * // With class-validator schema
+ * @Post("/users")
+ * createUser(@body(CreateUserDTO) user: CreateUserDTO) {}
+ *
+ * // With Zod schema
+ * const UserSchema = z.object({ email: z.string().email() });
+ * @Post("/users")
+ * createUser(@body(UserSchema) user: z.infer<typeof UserSchema>) {}
+ *
+ * // With validation options
+ * @Post("/users")
+ * createUser(@body({ group: "create", partial: false }) user: CreateUserDTO) {}
+ * ```
+ */
+export declare const validatedBody: {
+    (schema?: SchemaType | ValidatedDecoratorOptions): ParameterDecorator;
+    (nameOrSchema?: string | SchemaType | ValidatedDecoratorOptions): ParameterDecorator;
+};
+/**
+ * Enhanced query decorator with validation support
+ *
+ * @example
+ * ```typescript
+ * // Extract single query param (backward compatible)
+ * @Get("/search")
+ * search(@query("page") page: number) {}
+ *
+ * // Extract all query params with validation
+ * @Get("/search")
+ * search(@query(SearchQueryDTO) query: SearchQueryDTO) {}
+ * ```
+ */
+export declare const validatedQuery: {
+    (schema?: SchemaType | ValidatedDecoratorOptions): ParameterDecorator;
+    (nameOrSchema?: string | SchemaType | ValidatedDecoratorOptions): ParameterDecorator;
+};
+/**
+ * Enhanced param decorator with validation support
+ *
+ * @example
+ * ```typescript
+ * // Extract single route param (backward compatible)
+ * @Get("/:id")
+ * getUser(@param("id") id: string) {}
+ *
+ * // Extract all route params with validation
+ * @Get("/:userId/posts/:postId")
+ * getPost(@param(RouteParamsDTO) params: RouteParamsDTO) {}
+ * ```
+ */
+export declare const validatedParam: {
+    (schema?: SchemaType | ValidatedDecoratorOptions): ParameterDecorator;
+    (nameOrSchema?: string | SchemaType | ValidatedDecoratorOptions): ParameterDecorator;
+};
+/**
+ * Enhanced headers decorator with validation support
+ *
+ * @example
+ * ```typescript
+ * // Extract single header (backward compatible)
+ * @Get("/")
+ * handle(@headers("authorization") auth: string) {}
+ *
+ * // Extract all headers with validation
+ * @Get("/")
+ * handle(@headers(RequiredHeadersDTO) headers: RequiredHeadersDTO) {}
+ * ```
+ */
+export declare const validatedHeaders: {
+    (schema?: SchemaType | ValidatedDecoratorOptions): ParameterDecorator;
+    (nameOrSchema?: string | SchemaType | ValidatedDecoratorOptions): ParameterDecorator;
+};
+/**
+ * Get validation schema metadata for a method
+ * @param target - Controller constructor
+ * @param methodName - Method name
+ * @returns Array of validation metadata
+ */
+export declare function getValidationMetadata(target: object, methodName: string): Array<ValidationSchemaMetadata>;
+/**
+ * Check if a method has validation metadata
+ * @param target - Controller constructor
+ * @param methodName - Method name
+ * @returns true if validation is configured
+ */
+export declare function hasValidationMetadata(target: object, methodName: string): boolean;
+/**
+ * @Validate decorator - marks a parameter for auto-validation
+ * Can be used with any parameter decorator
+ *
+ * @example
+ * ```typescript
+ * @Post("/users")
+ * createUser(
+ *   @Validate(CreateUserDTO)
+ *   @body() user: CreateUserDTO
+ * ) {}
+ * ```
+ */
+export declare function Validate<T = unknown>(schema: (new (...args: Array<unknown>) => T) | object, options?: ValidatedDecoratorOptions): ParameterDecorator;