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

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