@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/cjs/types/interceptor/conditional-interceptor.d.ts

@@ -0,0 +1,91 @@
+import type { IInterceptor, InterceptorClass, ExecutionContext, ConditionalInterceptor } from "./interceptor.interface.js";
+/**
+ * Create a conditional interceptor that only runs when condition is true.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept conditional-interceptor
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use `whenInterceptor()` to conditionally execute an interceptor based on request context.
+ *
+ * @example
+ * ```typescript
+ * // Only cache when x-cache header is present
+ * @Get("/data")
+ * @UseInterceptors(
+ *   whenInterceptor(ctx => ctx.getRequest().headers['x-cache'] === 'true', CacheInterceptor),
+ *   LoggingInterceptor
+ * )
+ * getData() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async condition support
+ * @Get("/premium")
+ * @UseInterceptors(
+ *   whenInterceptor(async ctx => {
+ *     const user = await getUser(ctx.getRequest());
+ *     return user.isPremium;
+ *   }, PremiumFeaturesInterceptor)
+ * )
+ * getPremiumData() {}
+ * ```
+ *
+ * @param condition - Function returning true if interceptor should run
+ * @param interceptor - Interceptor class or instance to conditionally execute
+ * @returns ConditionalInterceptor that can be used with @UseInterceptors()
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Returns a marker object identified by `__isConditional: true`
+ * - InterceptorExecutor evaluates condition at runtime
+ * - If condition returns true, interceptor is executed
+ * - If condition returns false, interceptor is skipped
+ *
+ * @public API
+ */
+export declare function whenInterceptor(condition: (context: ExecutionContext) => boolean | Promise<boolean>, interceptor: IInterceptor | InterceptorClass): ConditionalInterceptor;
+/**
+ * Create a conditional interceptor that runs unless condition is true.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept conditional-interceptor
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use `unlessInterceptor()` to skip an interceptor when condition is true.
+ *
+ * @example
+ * ```typescript
+ * // Skip caching for authenticated requests
+ * @Get("/data")
+ * @UseInterceptors(
+ *   unlessInterceptor(ctx => ctx.getRequest().headers['authorization'], CacheInterceptor),
+ *   LoggingInterceptor
+ * )
+ * getData() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Skip rate limiting for internal requests
+ * @Post("/api")
+ * @UseInterceptors(
+ *   unlessInterceptor(ctx => ctx.getRequest().headers['x-internal'] === 'true', RateLimitInterceptor)
+ * )
+ * handleApi() {}
+ * ```
+ *
+ * @param condition - Function returning true if interceptor should be SKIPPED
+ * @param interceptor - Interceptor class or instance to conditionally skip
+ * @returns ConditionalInterceptor that can be used with @UseInterceptors()
+ *
+ * @public API
+ */
+export declare function unlessInterceptor(condition: (context: ExecutionContext) => boolean | Promise<boolean>, interceptor: IInterceptor | InterceptorClass): ConditionalInterceptor;

package/lib/cjs/types/interceptor/execution-context.d.ts

@@ -0,0 +1,41 @@
+import { Request, Response } from "express";
+import type { Container, interfaces } from "../di/inversify.js";
+import type { ExecutionContext } from "./interceptor.interface.js";
+/**
+ * Implementation of ExecutionContext for Express adapter
+ *
+ * @layer internal
+ * @audience framework-developers
+ * @internal
+ */
+export declare class ExpressExecutionContext implements ExecutionContext {
+    private request;
+    private response;
+    private container;
+    private controllerClass;
+    private handlerName;
+    private data;
+    constructor(request: Request, response: Response, container: Container, controllerClass: NewableFunction, handlerName: string);
+    getRequest(): Request;
+    getResponse(): Response;
+    getContainer(): Container;
+    getScoped<T>(identifier: interfaces.ServiceIdentifier<T>, _scopeName?: string): T;
+    getClass(): NewableFunction;
+    getHandler(): string;
+    getRoute(): {
+        path: string;
+        method: string;
+        params: Record<string, unknown>;
+        query: Record<string, unknown>;
+    };
+    getData<T = unknown>(key: string): T | undefined;
+    setData<T = unknown>(key: string, value: T): void;
+}
+/**
+ * Factory for creating ExecutionContext instances
+ *
+ * @layer internal
+ * @audience framework-developers
+ * @internal
+ */
+export declare function createExecutionContext(request: Request, response: Response, container: Container, controllerClass: NewableFunction, handlerName: string): ExecutionContext;

package/lib/cjs/types/interceptor/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Interceptor module - AOP (Aspect-Oriented Programming) for ExpressoTS
+ *
+ * @module interceptor
+ *
+ * Interceptors provide a powerful way to handle cross-cutting concerns like:
+ * - Logging
+ * - Caching
+ * - Response transformation
+ * - Performance tracking
+ * - Error handling
+ *
+ * @example
+ * ```typescript
+ * // Create a custom interceptor
+ * @Interceptor({ priority: 10 })
+ * @provide(MyInterceptor)
+ * export class MyInterceptor implements IInterceptor {
+ *   async intercept(context: ExecutionContext, next: CallHandler) {
+ *     console.log('Before...');
+ *     const result = await next.handle();
+ *     console.log('After...');
+ *     return result;
+ *   }
+ * }
+ *
+ * // Apply to a route
+ * @Get("/data")
+ * @UseInterceptors(MyInterceptor)
+ * getData() {}
+ * ```
+ */
+export * from "./interceptor.interface.js";
+export * from "./interceptor-constants.js";
+export * from "./interceptor-decorators.js";
+export * from "./interceptor-registry.js";
+export * from "./interceptor-executor.js";
+export * from "./conditional-interceptor.js";
+export * from "./interceptor-composition.js";
+export * from "./execution-context.js";
+export * from "./interceptors/index.js";

package/lib/cjs/types/interceptor/interceptor-composition.d.ts

@@ -0,0 +1,115 @@
+import type { IInterceptor, InterceptorClass, ComposedInterceptor } from "./interceptor.interface.js";
+/**
+ * Compose multiple interceptors into a pipeline.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept interceptor-composition
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use `pipeInterceptors()` to group interceptors that should run in sequence.
+ * Each interceptor wraps the next in the pipeline.
+ *
+ * @example
+ * ```typescript
+ * // All interceptors run in sequence
+ * @Get("/api/data")
+ * @UseInterceptors(
+ *   pipeInterceptors(
+ *     ValidationInterceptor,
+ *     TransformInterceptor,
+ *     CacheInterceptor,
+ *     LoggingInterceptor
+ *   )
+ * )
+ * getData() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Reusable interceptor pipeline
+ * const apiPipeline = pipeInterceptors(
+ *   ValidationInterceptor,
+ *   TransformInterceptor,
+ *   LoggingInterceptor
+ * );
+ *
+ * @Get("/users")
+ * @UseInterceptors(apiPipeline)
+ * getUsers() {}
+ * ```
+ *
+ * @param interceptors - Interceptor classes or instances to compose
+ * @returns ComposedInterceptor that can be used with @UseInterceptors()
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Returns a marker object identified by `__isComposed: true`
+ * - InterceptorExecutor flattens composed interceptors
+ * - All interceptors are executed in pipeline order
+ * - `mode: "pipe"` indicates sequential pipeline execution
+ *
+ * @public API
+ */
+export declare function pipeInterceptors(...interceptors: Array<IInterceptor | InterceptorClass>): ComposedInterceptor;
+/**
+ * Combine multiple interceptors with all-must-pass semantics.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept interceptor-composition
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use `combineInterceptors()` to group interceptors that all must complete successfully.
+ * Semantically indicates that all interceptors are required.
+ *
+ * @example
+ * ```typescript
+ * // All interceptors must pass
+ * @Post("/secure")
+ * @UseInterceptors(
+ *   combineInterceptors(
+ *     AuthInterceptor,
+ *     RateLimitInterceptor,
+ *     ValidationInterceptor
+ *   )
+ * )
+ * secureEndpoint() {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Reusable security interceptor group
+ * const securityInterceptors = combineInterceptors(
+ *   AuthInterceptor,
+ *   RateLimitInterceptor,
+ *   CSRFInterceptor
+ * );
+ *
+ * @Post("/api")
+ * @UseInterceptors(securityInterceptors)
+ * handleApi() {}
+ * ```
+ *
+ * @param interceptors - Interceptor classes or instances to combine
+ * @returns ComposedInterceptor that can be used with @UseInterceptors()
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Returns a marker object identified by `__isComposed: true`
+ * - InterceptorExecutor flattens composed interceptors
+ * - All interceptors are executed in pipeline order
+ * - `mode: "combine"` indicates all-must-pass semantics
+ *
+ * **Note**: Functionally identical to `pipeInterceptors()` but semantically
+ * indicates that ALL interceptors are required (similar to AND logic).
+ *
+ * @public API
+ */
+export declare function combineInterceptors(...interceptors: Array<IInterceptor | InterceptorClass>): ComposedInterceptor;

package/lib/cjs/types/interceptor/interceptor-constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Metadata keys for interceptor decorators
+ */
+export declare const INTERCEPTOR_METADATA_KEY: {
+    /**
+     * Key for @Interceptor() decorator metadata
+     */
+    readonly interceptor: "expressots:interceptor";
+    /**
+     * Key for controller-level interceptors via @UseInterceptors()
+     */
+    readonly controllerInterceptors: "expressots:controller_interceptors";
+    /**
+     * Key for method-level interceptors via @UseInterceptors()
+     */
+    readonly methodInterceptors: "expressots:method_interceptors";
+};

package/lib/cjs/types/interceptor/interceptor-decorators.d.ts

@@ -0,0 +1,124 @@
+import "reflect-metadata";
+import type { IInterceptor, InterceptorClass } from "./interceptor.interface.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 declare function Interceptor(options?: {
+    priority?: number;
+}): ClassDecorator;
+/**
+ * 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 declare function UseInterceptors(...interceptors: Array<IInterceptor | InterceptorClass | unknown>): ClassDecorator & MethodDecorator;

package/lib/cjs/types/interceptor/interceptor-executor.d.ts

@@ -0,0 +1,46 @@
+import { Logger } from "../provider/logger/logger.provider.js";
+import type { IInterceptor, InterceptorClass, ExecutionContext } 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
+ */
+export declare class InterceptorExecutor {
+    private registry;
+    private logger;
+    constructor(registry: InterceptorRegistry, 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
+     */
+    execute<T>(interceptors: Array<InterceptorClass | IInterceptor | unknown>, context: ExecutionContext, handler: () => Promise<T>): Promise<T>;
+    /**
+     * Resolve all interceptors including conditional and composed
+     * @private
+     */
+    private resolveInterceptors;
+    /**
+     * Evaluate conditional interceptor condition
+     * @private
+     */
+    private evaluateCondition;
+}

package/lib/cjs/types/interceptor/interceptor-registry.d.ts

@@ -0,0 +1,65 @@
+import "reflect-metadata";
+import { Container } from "../di/inversify.js";
+import { Logger } from "../provider/logger/logger.provider.js";
+import type { IInterceptor, InterceptorClass } from "./interceptor.interface.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
+ */
+export declare class InterceptorRegistry {
+    private container;
+    private logger;
+    private interceptors;
+    private initialized;
+    constructor(container: Container, logger: Logger);
+    /**
+     * Initialize registry by discovering all @Interceptor() decorated classes
+     */
+    initialize(): void;
+    /**
+     * Get an interceptor instance from registry or container
+     * @param interceptor - Interceptor class or instance
+     * @returns Resolved interceptor instance
+     */
+    get(interceptor: InterceptorClass | IInterceptor): IInterceptor;
+    /**
+     * Get all registered interceptors sorted by priority
+     * @returns Array of interceptors sorted by priority
+     */
+    getAll(): Array<IInterceptor>;
+    /**
+     * Register an interceptor instance manually
+     * @param key - Interceptor class or identifier
+     * @param instance - Interceptor instance
+     */
+    register(key: NewableFunction | IInterceptor, instance: IInterceptor): void;
+    /**
+     * Check if an interceptor is registered
+     * @param interceptor - Interceptor class or instance
+     * @returns True if registered
+     */
+    has(interceptor: InterceptorClass | IInterceptor): boolean;
+    /**
+     * Clear all registered interceptors (for testing)
+     */
+    clear(): void;
+}