@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/interceptor/interceptor-decorators.js

@@ -0,0 +1,151 @@
+import "reflect-metadata";
+import { INTERCEPTOR_METADATA_KEY } from "./interceptor-constants.js";
+/**
+ * Decorator to mark a class as an interceptor (for auto-discovery).
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept interceptor-decorator
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Mark your interceptor class with `@Interceptor()` to enable auto-discovery.
+ *
+ * @example
+ * ```typescript
+ * @Interceptor({ priority: 1 })
+ * @provide(LoggingInterceptor)
+ * export class LoggingInterceptor implements IInterceptor {
+ *   async intercept(context: ExecutionContext, next: CallHandler) {
+ *     const start = Date.now();
+ *     const result = await next.handle();
+ *     console.log(`Execution time: ${Date.now() - start}ms`);
+ *     return result;
+ *   }
+ * }
+ * ```
+ *
+ * @param options - Interceptor options
+ * @param options.priority - Execution priority (lower = earlier, wraps later). Default: 100
+ * @returns ClassDecorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Registers interceptor metadata for auto-discovery
+ * - Stores metadata in global registry via Reflect
+ * - InterceptorRegistry discovers interceptors during initialization
+ *
+ * **Priority System**
+ * - Lower priority = earlier execution (outermost wrapper)
+ * - Logging interceptors typically use priority 1-10
+ * - Caching interceptors typically use priority 20-50
+ * - Transformation interceptors typically use priority 50-100+
+ *
+ * @see {@link InterceptorRegistry} for auto-discovery mechanism
+ * @see {@link UseInterceptors} for applying interceptors to routes
+ *
+ * @public API
+ */
+export function Interceptor(options) {
+    return (target) => {
+        const metadata = {
+            priority: options?.priority ?? 100,
+            interceptor: target,
+        };
+        Reflect.defineMetadata(INTERCEPTOR_METADATA_KEY.interceptor, metadata, target);
+        // Register in global registry for auto-discovery
+        const existingInterceptors = Reflect.getMetadata(INTERCEPTOR_METADATA_KEY.interceptor, Reflect) || [];
+        const newInterceptors = [...existingInterceptors, metadata];
+        Reflect.defineMetadata(INTERCEPTOR_METADATA_KEY.interceptor, newInterceptors, Reflect);
+    };
+}
+/**
+ * Apply interceptors at controller or method level.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept interceptor-application
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Apply interceptors to routes for cross-cutting concerns like logging, caching, transformation.
+ *
+ * @example
+ * ```typescript
+ * // Controller-level interceptors (apply to all methods)
+ * @UseInterceptors(LoggingInterceptor)
+ * @controller("/users")
+ * export class UserController {
+ *   @Get("/")
+ *   getUsers() {
+ *     // LoggingInterceptor applies to all methods
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Method-level interceptors
+ * @controller("/users")
+ * export class UserController {
+ *   @Get("/:id")
+ *   @UseInterceptors(CacheInterceptor, LoggingInterceptor)
+ *   getUser(@param("id") id: string) {
+ *     // Both interceptors apply to this method
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With conditional interceptors
+ * @Get("/data")
+ * @UseInterceptors(
+ *   whenInterceptor(ctx => ctx.getRequest().headers['x-cache'], CacheInterceptor),
+ *   LoggingInterceptor
+ * )
+ * getData() {}
+ * ```
+ *
+ * @param interceptors - Interceptor classes or instances to apply
+ * @returns ClassDecorator & MethodDecorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Stores interceptor metadata on controller/method
+ * - Method-level interceptors are combined with controller-level
+ * - Interceptors are resolved and executed by InterceptorExecutor
+ * - Execution order follows interceptor priority
+ *
+ * **Interceptor Resolution**
+ * - InterceptorRegistry resolves interceptor instances
+ * - Supports both interceptor classes and instances
+ * - Conditional interceptors are evaluated at runtime
+ *
+ * @see {@link Interceptor} for creating interceptors
+ * @see {@link InterceptorExecutor} for execution logic
+ *
+ * @public API
+ */
+export function UseInterceptors(...interceptors) {
+    return (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    target, propertyKey) => {
+        if (propertyKey) {
+            // Method-level interceptors
+            const existingInterceptors = Reflect.getMetadata(INTERCEPTOR_METADATA_KEY.methodInterceptors, target.constructor, propertyKey) || [];
+            const newInterceptors = [...existingInterceptors, ...interceptors];
+            Reflect.defineMetadata(INTERCEPTOR_METADATA_KEY.methodInterceptors, newInterceptors, target.constructor, propertyKey);
+        }
+        else {
+            // Controller-level interceptors
+            const existingInterceptors = Reflect.getMetadata(INTERCEPTOR_METADATA_KEY.controllerInterceptors, target) || [];
+            const newInterceptors = [...existingInterceptors, ...interceptors];
+            Reflect.defineMetadata(INTERCEPTOR_METADATA_KEY.controllerInterceptors, newInterceptors, target);
+        }
+    };
+}

package/lib/esm/interceptor/interceptor-executor.js

@@ -0,0 +1,139 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from "../di/inversify.js";
+import { Logger } from "../provider/logger/logger.provider.js";
+import { isConditionalInterceptor, isComposedInterceptor, } from "./interceptor.interface.js";
+import { InterceptorRegistry } from "./interceptor-registry.js";
+/**
+ * Executor for running interceptors in pipeline order
+ *
+ * @layer internal
+ * @audience framework-developers
+ * @concept interceptor-executor
+ *
+ * @summary Quick Start
+ * InterceptorExecutor runs interceptors in a pipeline pattern where each
+ * interceptor wraps the next. Lower priority interceptors run first (outermost).
+ *
+ * **Execution Flow**
+ * ```
+ * Request → Interceptor1.before → Interceptor2.before → Handler
+ *                                                         ↓
+ * Response ← Interceptor1.after ← Interceptor2.after ← Result
+ * ```
+ *
+ * @internal
+ */
+let InterceptorExecutor = class InterceptorExecutor {
+    registry;
+    logger;
+    constructor(registry, logger) {
+        this.registry = registry;
+        this.logger = logger;
+    }
+    /**
+     * Execute interceptors in pipeline order
+     * @param interceptors - Array of interceptor classes, instances, or conditional/composed
+     * @param context - Execution context with request, response, container info
+     * @param handler - The actual route handler to execute at the end
+     * @returns The (optionally transformed) result
+     */
+    async execute(interceptors, context, handler) {
+        if (interceptors.length === 0) {
+            return handler();
+        }
+        // 1. Flatten and resolve all interceptors (including conditional and composed)
+        const resolvedInterceptors = await this.resolveInterceptors(interceptors, context);
+        if (resolvedInterceptors.length === 0) {
+            return handler();
+        }
+        // 2. Sort by priority (lower = earlier = outermost)
+        resolvedInterceptors.sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+        // 3. Build pipeline (reverse order so first interceptor wraps outermost)
+        let pipeline = {
+            handle: handler,
+        };
+        // Build from last to first (so first interceptor is outermost)
+        for (let i = resolvedInterceptors.length - 1; i >= 0; i--) {
+            const interceptor = resolvedInterceptors[i];
+            const next = pipeline;
+            pipeline = {
+                handle: async () => {
+                    try {
+                        return (await interceptor.intercept(context, next));
+                    }
+                    catch (error) {
+                        this.logger.error(`Interceptor ${interceptor.constructor.name} threw an error: ${error}`, "interceptor-executor");
+                        throw error;
+                    }
+                },
+            };
+        }
+        // 4. Execute pipeline
+        return pipeline.handle();
+    }
+    /**
+     * Resolve all interceptors including conditional and composed
+     * @private
+     */
+    async resolveInterceptors(interceptors, context) {
+        const resolved = [];
+        for (const interceptor of interceptors) {
+            // Handle conditional interceptors
+            if (isConditionalInterceptor(interceptor)) {
+                const shouldRun = await this.evaluateCondition(interceptor, context);
+                if (shouldRun) {
+                    const resolvedInterceptor = this.registry.get(interceptor.interceptor);
+                    resolved.push(resolvedInterceptor);
+                }
+                continue;
+            }
+            // Handle composed interceptors
+            if (isComposedInterceptor(interceptor)) {
+                for (const composedInterceptor of interceptor.interceptors) {
+                    const resolvedInterceptor = this.registry.get(composedInterceptor);
+                    resolved.push(resolvedInterceptor);
+                }
+                continue;
+            }
+            // Handle regular interceptors (class or instance)
+            const resolvedInterceptor = this.registry.get(interceptor);
+            resolved.push(resolvedInterceptor);
+        }
+        return resolved;
+    }
+    /**
+     * Evaluate conditional interceptor condition
+     * @private
+     */
+    async evaluateCondition(conditional, context) {
+        try {
+            const result = await conditional.condition(context);
+            // "when" = run if true, "unless" = run if false
+            return conditional.type === "when" ? result : !result;
+        }
+        catch (error) {
+            this.logger.error(`Conditional interceptor evaluation failed: ${error}`, "interceptor-executor");
+            // On error, don't run the interceptor (safe default)
+            return false;
+        }
+    }
+};
+InterceptorExecutor = __decorate([
+    injectable(),
+    __param(0, inject(InterceptorRegistry)),
+    __param(1, inject(Logger)),
+    __metadata("design:paramtypes", [InterceptorRegistry,
+        Logger])
+], InterceptorExecutor);
+export { InterceptorExecutor };

package/lib/esm/interceptor/interceptor-registry.js

@@ -0,0 +1,158 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import "reflect-metadata";
+import { inject, injectable, Container } from "../di/inversify.js";
+import { Logger } from "../provider/logger/logger.provider.js";
+import { INTERCEPTOR_METADATA_KEY } from "./interceptor-constants.js";
+/**
+ * Registry for auto-discovering and resolving interceptors
+ *
+ * @layer public
+ * @audience framework-developers
+ * @concept interceptor-registry
+ *
+ * @summary Quick Start
+ * InterceptorRegistry manages interceptor discovery, registration, and resolution.
+ * It automatically discovers interceptors decorated with @Interceptor() and
+ * resolves them from the DI container.
+ *
+ * @example
+ * ```typescript
+ * // Get interceptor instance
+ * const interceptor = registry.get(LoggingInterceptor);
+ *
+ * // Get all registered interceptors
+ * const allInterceptors = registry.getAll();
+ * ```
+ *
+ * @internal
+ */
+let InterceptorRegistry = class InterceptorRegistry {
+    container;
+    logger;
+    interceptors = new Map();
+    initialized = false;
+    constructor(container, logger) {
+        this.container = container;
+        this.logger = logger;
+    }
+    /**
+     * Initialize registry by discovering all @Interceptor() decorated classes
+     */
+    initialize() {
+        if (this.initialized) {
+            return;
+        }
+        // Get all registered interceptors from metadata
+        const registeredInterceptors = Reflect.getMetadata(INTERCEPTOR_METADATA_KEY.interceptor, Reflect) || [];
+        for (const metadata of registeredInterceptors) {
+            try {
+                // Try to resolve from container
+                const serviceId = metadata.interceptor;
+                if (this.container.isBound(serviceId)) {
+                    const instance = this.container.get(serviceId);
+                    // Set priority from metadata if not defined on instance
+                    if (instance.priority === undefined) {
+                        instance.priority = metadata.priority;
+                    }
+                    this.interceptors.set(metadata.interceptor, instance);
+                    this.logger.debug(`Registered interceptor: ${metadata.interceptor.name} (priority: ${instance.priority})`, "interceptor-registry");
+                }
+            }
+            catch (error) {
+                this.logger.warn(`Failed to resolve interceptor ${metadata.interceptor.name}: ${error}`, "interceptor-registry");
+            }
+        }
+        this.initialized = true;
+        this.logger.debug(`InterceptorRegistry initialized with ${this.interceptors.size} interceptors`, "interceptor-registry");
+    }
+    /**
+     * Get an interceptor instance from registry or container
+     * @param interceptor - Interceptor class or instance
+     * @returns Resolved interceptor instance
+     */
+    get(interceptor) {
+        // If already an instance, return it
+        if (typeof interceptor !== "function") {
+            return interceptor;
+        }
+        // Check if already in registry
+        if (this.interceptors.has(interceptor)) {
+            return this.interceptors.get(interceptor);
+        }
+        // Try to resolve from container
+        try {
+            const serviceId = interceptor;
+            if (this.container.isBound(serviceId)) {
+                const instance = this.container.get(serviceId);
+                this.interceptors.set(interceptor, instance);
+                return instance;
+            }
+        }
+        catch (error) {
+            this.logger.debug(`Interceptor ${interceptor.name} not bound, creating new instance`, "interceptor-registry");
+        }
+        // Create new instance (for interceptors not in container)
+        try {
+            const instance = new interceptor();
+            this.interceptors.set(interceptor, instance);
+            return instance;
+        }
+        catch (error) {
+            this.logger.error(`Failed to create interceptor instance ${interceptor.name}: ${error}`, "interceptor-registry");
+            throw new Error(`Cannot resolve interceptor: ${interceptor.name}`);
+        }
+    }
+    /**
+     * Get all registered interceptors sorted by priority
+     * @returns Array of interceptors sorted by priority
+     */
+    getAll() {
+        return Array.from(this.interceptors.values()).sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+    }
+    /**
+     * Register an interceptor instance manually
+     * @param key - Interceptor class or identifier
+     * @param instance - Interceptor instance
+     */
+    register(key, instance) {
+        this.interceptors.set(key, instance);
+    }
+    /**
+     * Check if an interceptor is registered
+     * @param interceptor - Interceptor class or instance
+     * @returns True if registered
+     */
+    has(interceptor) {
+        if (typeof interceptor !== "function") {
+            return true; // Instances are always "available"
+        }
+        return (this.interceptors.has(interceptor) ||
+            this.container.isBound(interceptor));
+    }
+    /**
+     * Clear all registered interceptors (for testing)
+     */
+    clear() {
+        this.interceptors.clear();
+        this.initialized = false;
+    }
+};
+InterceptorRegistry = __decorate([
+    injectable(),
+    __param(0, inject(Container)),
+    __param(1, inject(Logger)),
+    __metadata("design:paramtypes", [Container,
+        Logger])
+], InterceptorRegistry);
+export { InterceptorRegistry };

package/lib/esm/interceptor/interceptor.interface.js

@@ -0,0 +1,16 @@
+/**
+ * Type guard for conditional interceptor
+ */
+export function isConditionalInterceptor(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.__isConditional === true);
+}
+/**
+ * Type guard for composed interceptor
+ */
+export function isComposedInterceptor(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.__isComposed === true);
+}

package/lib/esm/interceptor/interceptors/index.js

@@ -0,0 +1,6 @@
+/**
+ * Built-in interceptors for common use cases
+ */
+export * from "./performance.interceptor.js";
+export * from "./logging.interceptor.js";
+export * from "./timeout.interceptor.js";

package/lib/esm/interceptor/interceptors/logging.interceptor.js

@@ -0,0 +1,68 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from "../../di/inversify.js";
+import { Logger } from "../../provider/logger/logger.provider.js";
+import { Interceptor } from "../interceptor-decorators.js";
+/**
+ * Built-in logging interceptor with request/response logging.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept logging-interceptor
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use LoggingInterceptor to automatically log requests and responses.
+ *
+ * @example
+ * ```typescript
+ * @Get("/users")
+ * @UseInterceptors(LoggingInterceptor)
+ * getUsers() {}
+ * ```
+ *
+ * @public API
+ */
+let LoggingInterceptor = class LoggingInterceptor {
+    logger;
+    priority = 5;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    async intercept(context, next) {
+        const request = context.getRequest();
+        const method = request.method;
+        const path = request.path;
+        const timestamp = new Date().toISOString();
+        this.logger.debug(`[${timestamp}] → ${method} ${path}`, "logging-interceptor");
+        const startTime = Date.now();
+        try {
+            const result = await next.handle();
+            const duration = Date.now() - startTime;
+            this.logger.debug(`[${timestamp}] ← ${method} ${path} (${duration}ms)`, "logging-interceptor");
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            this.logger.error(`[${timestamp}] ✗ ${method} ${path} (${duration}ms) - ${error}`, "logging-interceptor");
+            throw error;
+        }
+    }
+};
+LoggingInterceptor = __decorate([
+    Interceptor({ priority: 5 }),
+    injectable(),
+    __param(0, inject(Logger)),
+    __metadata("design:paramtypes", [Logger])
+], LoggingInterceptor);
+export { LoggingInterceptor };