@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/types/interceptor/interceptor.interface.d.ts

@@ -0,0 +1,281 @@
+import { Request, Response } from "express";
+import type { Container, interfaces } from "../di/inversify.js";
+/**
+ * Execution context providing comprehensive information for interceptor decisions.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept execution-context
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * ExecutionContext provides access to the request, response, and DI container
+ * for making interception decisions and modifications.
+ *
+ * @example
+ * ```typescript
+ * async intercept(context: ExecutionContext, next: CallHandler) {
+ *   const request = context.getRequest();
+ *   const startTime = Date.now();
+ *   const result = await next.handle();
+ *   console.log(`Request to ${request.path} took ${Date.now() - startTime}ms`);
+ *   return result;
+ * }
+ * ```
+ *
+ * @public API
+ */
+export interface ExecutionContext {
+    /**
+     * Get the Express request object
+     */
+    getRequest(): Request;
+    /**
+     * Get the Express response object
+     */
+    getResponse(): Response;
+    /**
+     * Get the DI container (request-scoped child container)
+     */
+    getContainer(): Container;
+    /**
+     * Get scoped service from container
+     * @param identifier - Service identifier
+     * @param scopeName - Optional scope name (e.g., "tenant")
+     */
+    getScoped<T>(identifier: interfaces.ServiceIdentifier<T>, scopeName?: string): T;
+    /**
+     * Get controller class
+     */
+    getClass(): NewableFunction;
+    /**
+     * Get method/handler name
+     */
+    getHandler(): string;
+    /**
+     * Get route information
+     */
+    getRoute(): {
+        path: string;
+        method: string;
+        params: Record<string, unknown>;
+        query: Record<string, unknown>;
+    };
+    /**
+     * Get/set custom data on context for passing between interceptors
+     */
+    getData<T = unknown>(key: string): T | undefined;
+    setData<T = unknown>(key: string, value: T): void;
+}
+/**
+ * Call handler for executing the next interceptor or the route handler.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept call-handler
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use `next.handle()` to continue to the next interceptor or route handler.
+ *
+ * @example
+ * ```typescript
+ * async intercept(context: ExecutionContext, next: CallHandler) {
+ *   // Before route handler
+ *   console.log('Before...');
+ *
+ *   const result = await next.handle(); // Execute route handler
+ *
+ *   // After route handler
+ *   console.log('After...');
+ *
+ *   return result; // Return (optionally transformed) result
+ * }
+ * ```
+ *
+ * @public API
+ */
+export interface CallHandler<T = unknown> {
+    /**
+     * Execute the next interceptor in the chain or the route handler.
+     * @returns Promise with the result from the handler
+     */
+    handle(): Promise<T>;
+}
+/**
+ * Interceptor interface for AOP (Aspect-Oriented Programming) cross-cutting concerns.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept interceptor-interface
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Implement this interface to create custom interceptors for logging, caching,
+ * transformation, error handling, and other cross-cutting concerns.
+ *
+ * @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;
+ *   }
+ * }
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Interceptors are executed by InterceptorExecutor in priority order:
+ * 1. Resolved from registry or container
+ * 2. Sorted by priority (lower = earlier)
+ * 3. Executed in pipeline (each wraps the next)
+ * 4. Response can be transformed at each step
+ *
+ * **Execution Flow**
+ * ```
+ * Request → Interceptor1.before → Interceptor2.before → Handler
+ *                                                         ↓
+ * Response ← Interceptor1.after ← Interceptor2.after ← Result
+ * ```
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Patterns**
+ *
+ * Caching interceptor:
+ * ```typescript
+ * @Interceptor({ priority: 1 })
+ * export class CacheInterceptor implements IInterceptor {
+ *   private cache = new Map();
+ *   async intercept(context: ExecutionContext, next: CallHandler) {
+ *     const key = context.getRequest().url;
+ *     if (this.cache.has(key)) return this.cache.get(key);
+ *     const result = await next.handle();
+ *     this.cache.set(key, result);
+ *     return result;
+ *   }
+ * }
+ * ```
+ *
+ * @public API
+ */
+export interface IInterceptor<T = unknown> {
+    /**
+     * Intercept the request/response pipeline.
+     *
+     * @layer public
+     * @audience application-developers
+     *
+     * @param context - Execution context with request, response, container info
+     * @param next - Call handler to proceed to next interceptor or route handler
+     * @returns The (optionally transformed) result
+     *
+     * @example
+     * ```typescript
+     * async intercept(context: ExecutionContext, next: CallHandler) {
+     *   // Pre-processing
+     *   console.log('Before handler...');
+     *
+     *   try {
+     *     // Call next interceptor or handler
+     *     const result = await next.handle();
+     *
+     *     // Post-processing - transform response
+     *     return { data: result, timestamp: Date.now() };
+     *   } catch (error) {
+     *     // Error handling
+     *     console.error('Handler error:', error);
+     *     throw error;
+     *   }
+     * }
+     * ```
+     *
+     * @public API
+     */
+    intercept(context: ExecutionContext, next: CallHandler<T>): Promise<T>;
+    /**
+     * Optional: Execution priority (lower = earlier, wraps later interceptors).
+     * Default: 100
+     *
+     * @default 100
+     *
+     * Useful for interceptors that must run before others (e.g., logging before caching).
+     *
+     * **Common Priorities:**
+     * - 1-10: Logging interceptors (wrap everything)
+     * - 20-50: Caching interceptors
+     * - 50-100: Transformation interceptors
+     * - 100+: Response modification interceptors
+     *
+     * @example
+     * ```typescript
+     * @Interceptor({ priority: 1 })  // Runs first (outermost wrapper)
+     * export class LoggingInterceptor implements IInterceptor { }
+     * ```
+     */
+    priority?: number;
+}
+/**
+ * Type for interceptor class constructor
+ */
+export type InterceptorClass = new (...args: Array<any>) => IInterceptor;
+/**
+ * Metadata for interceptor registration
+ */
+export interface InterceptorMetadata {
+    /**
+     * Execution priority
+     */
+    priority: number;
+    /**
+     * The interceptor class
+     */
+    interceptor: NewableFunction;
+}
+/**
+ * Options for conditional interceptor execution
+ */
+export interface ConditionalInterceptorOptions {
+    /**
+     * Condition function to determine if interceptor should run
+     */
+    condition: (context: ExecutionContext) => boolean | Promise<boolean>;
+    /**
+     * The interceptor to conditionally execute
+     */
+    interceptor: IInterceptor | InterceptorClass;
+}
+/**
+ * Marker interface for composed interceptors
+ */
+export interface ComposedInterceptor {
+    __isComposed: true;
+    interceptors: Array<IInterceptor | InterceptorClass>;
+    mode: "pipe" | "combine";
+}
+/**
+ * Marker interface for conditional interceptors
+ */
+export interface ConditionalInterceptor {
+    __isConditional: true;
+    condition: (context: ExecutionContext) => boolean | Promise<boolean>;
+    interceptor: IInterceptor | InterceptorClass;
+    type: "when" | "unless";
+}
+/**
+ * Type guard for conditional interceptor
+ */
+export declare function isConditionalInterceptor(value: unknown): value is ConditionalInterceptor;
+/**
+ * Type guard for composed interceptor
+ */
+export declare function isComposedInterceptor(value: unknown): value is ComposedInterceptor;

package/lib/esm/types/interceptor/interceptors/index.d.ts

@@ -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/types/interceptor/interceptors/logging.interceptor.d.ts

@@ -0,0 +1,28 @@
+import { Logger } from "../../provider/logger/logger.provider.js";
+import type { IInterceptor, ExecutionContext, CallHandler } from "../interceptor.interface.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
+ */
+export declare class LoggingInterceptor implements IInterceptor {
+    private logger;
+    readonly priority = 5;
+    constructor(logger: Logger);
+    intercept<T>(context: ExecutionContext, next: CallHandler<T>): Promise<T>;
+}

package/lib/esm/types/interceptor/interceptors/performance.interceptor.d.ts

@@ -0,0 +1,197 @@
+import { Logger } from "../../provider/logger/logger.provider.js";
+import type { IInterceptor, ExecutionContext, CallHandler } from "../interceptor.interface.js";
+/**
+ * Performance metrics for a single endpoint
+ */
+export interface EndpointMetrics {
+    /**
+     * Average response time in milliseconds
+     */
+    avgTime: number;
+    /**
+     * Maximum response time in milliseconds
+     */
+    maxTime: number;
+    /**
+     * Minimum response time in milliseconds
+     */
+    minTime: number;
+    /**
+     * Total number of calls
+     */
+    callCount: number;
+    /**
+     * Number of calls that exceeded slow threshold
+     */
+    slowCalls: number;
+    /**
+     * Last response time in milliseconds
+     */
+    lastTime: number;
+    /**
+     * Last call timestamp
+     */
+    lastCall: Date;
+}
+/**
+ * All performance metrics keyed by endpoint
+ */
+export type PerformanceMetrics = Record<string, EndpointMetrics>;
+/**
+ * Configuration options for PerformanceInterceptor
+ */
+export interface PerformanceInterceptorOptions {
+    /**
+     * Threshold in milliseconds above which a call is considered slow
+     * @default 1000
+     */
+    slowThreshold?: number;
+    /**
+     * Whether to log slow calls automatically
+     * @default true
+     */
+    logSlowCalls?: boolean;
+    /**
+     * Whether to log all calls (verbose mode)
+     * @default false
+     */
+    logAllCalls?: boolean;
+}
+/**
+ * Service for managing performance metrics.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept performance-service
+ *
+ * @summary Quick Start
+ * Inject PerformanceInterceptorService to access performance metrics.
+ *
+ * @example
+ * ```typescript
+ * @controller("/admin")
+ * export class AdminController {
+ *   constructor(private perfService: PerformanceInterceptorService) {}
+ *
+ *   @Get("/metrics")
+ *   getMetrics() {
+ *     return this.perfService.getMetrics();
+ *   }
+ *
+ *   @Get("/slow-endpoints")
+ *   getSlowEndpoints() {
+ *     return this.perfService.getSlowEndpoints();
+ *   }
+ * }
+ * ```
+ *
+ * @public API
+ */
+export declare class PerformanceInterceptorService {
+    private metrics;
+    private slowThreshold;
+    private logSlowCalls;
+    private logAllCalls;
+    constructor();
+    /**
+     * Configure performance interceptor options
+     */
+    configure(options: PerformanceInterceptorOptions): void;
+    /**
+     * Record a call for an endpoint
+     */
+    recordCall(key: string, duration: number, _isError: boolean): void;
+    /**
+     * Check if a duration is considered slow
+     */
+    isSlowCall(duration: number): boolean;
+    /**
+     * Get slow threshold
+     */
+    getSlowThreshold(): number;
+    /**
+     * Get all performance metrics
+     */
+    getMetrics(): PerformanceMetrics;
+    /**
+     * Get metrics for a specific endpoint
+     */
+    getEndpointMetrics(key: string): EndpointMetrics | undefined;
+    /**
+     * Get all endpoints that have had slow calls
+     */
+    getSlowEndpoints(): Array<{
+        endpoint: string;
+        metrics: EndpointMetrics;
+    }>;
+    /**
+     * Get endpoints sorted by average response time (slowest first)
+     */
+    getSlowestEndpoints(limit?: number): Array<{
+        endpoint: string;
+        avgTime: number;
+    }>;
+    /**
+     * Clear all metrics
+     */
+    clearMetrics(): void;
+    /**
+     * Get summary statistics
+     */
+    getSummary(): {
+        totalEndpoints: number;
+        totalCalls: number;
+        avgResponseTime: number;
+        slowEndpoints: number;
+    };
+}
+/**
+ * Built-in performance interceptor with automatic profiling.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept performance-interceptor
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use PerformanceInterceptor to automatically track execution time and
+ * identify slow endpoints.
+ *
+ * @example
+ * ```typescript
+ * // Apply to individual endpoints
+ * @Get("/slow-endpoint")
+ * @UseInterceptors(PerformanceInterceptor)
+ * getSlowData() {
+ *   // Automatically tracked
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Apply to entire controller
+ * @UseInterceptors(PerformanceInterceptor)
+ * @controller("/api")
+ * export class ApiController {
+ *   // All methods tracked
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Access metrics
+ * const perfService = container.get(PerformanceInterceptorService);
+ * const metrics = perfService.getMetrics();
+ * console.log(metrics["/api/users"]);
+ * // { avgTime: 123, maxTime: 456, minTime: 45, callCount: 100, slowCalls: 5 }
+ * ```
+ *
+ * @public API
+ */
+export declare class PerformanceInterceptor implements IInterceptor {
+    private logger;
+    private metricsService;
+    readonly priority = 1;
+    constructor(logger: Logger, metricsService: PerformanceInterceptorService);
+    intercept<T>(context: ExecutionContext, next: CallHandler<T>): Promise<T>;
+}

package/lib/esm/types/interceptor/interceptors/timeout.interceptor.d.ts

@@ -0,0 +1,42 @@
+import type { IInterceptor, ExecutionContext, CallHandler } from "../interceptor.interface.js";
+/**
+ * Configuration for timeout interceptor
+ */
+export interface TimeoutOptions {
+    /**
+     * Timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Custom error message
+     */
+    message?: string;
+}
+/**
+ * Built-in timeout interceptor to prevent long-running requests.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept timeout-interceptor
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use TimeoutInterceptor to automatically timeout slow requests.
+ *
+ * @example
+ * ```typescript
+ * @Get("/slow-operation")
+ * @UseInterceptors(new TimeoutInterceptor({ timeout: 5000 }))
+ * slowOperation() {}
+ * ```
+ *
+ * @public API
+ */
+export declare class TimeoutInterceptor implements IInterceptor {
+    readonly priority = 2;
+    private timeout;
+    private message;
+    constructor(options?: TimeoutOptions);
+    intercept<T>(_context: ExecutionContext, next: CallHandler<T>): Promise<T>;
+}

package/lib/esm/types/lazy-loading/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Lazy-Loading Module
+ *
+ * @module lazy-loading
+ *
+ * Intelligent lazy-loading of modules for improved startup time and memory efficiency.
+ *
+ * Features:
+ * - On-demand module loading
+ * - Preload hints (high, medium, low, never)
+ * - Usage analytics and recommendations
+ * - Progressive loading with phases
+ * - Runtime module status queries
+ * - Background warmup during idle time
+ *
+ * @example
+ * ```typescript
+ * // Create a lazy module
+ * export const AdminModule = CreateLazyModule([
+ *   AdminController,
+ *   AdminDashboardController
+ * ]).withPreloadHint("low");
+ *
+ * // Load on-demand
+ * const loader = container.get(LazyModuleLoader);
+ * await loader.load("AdminModule");
+ *
+ * // Get recommendations
+ * const metrics = container.get(LazyLoadMetrics);
+ * console.log(metrics.getRecommendations());
+ *
+ * // Warm up in background
+ * const warmup = container.get(LazyModuleWarmup);
+ * await warmup.start({ strategy: "idle" });
+ * ```
+ */
+export type { PreloadHint, ModuleLoadStatus, LazyModuleConfig, LazyModuleFactory, ILazyModule, ILazyModuleLoader, ModuleLoadStatistics, ILazyModuleManager, ModuleRecommendation, ApplyRecommendationsOptions, ILazyLoadMetrics, WarmupStrategy, WarmupConfig, ILazyModuleWarmup, LoadingPhase, ProgressiveLoadingConfig, LazyLoadingOptions, LazyLoadingSetupResult, } from "./lazy.interfaces.js";
+export { LazyModule, CreateLazyModule, createLazyModule, isLazyModule, getModuleName, LAZY_MODULE_METADATA_KEY, } from "./lazy-module.js";
+export { LazyModuleLoader, createLazyModuleLoader, } from "./lazy-module-loader.js";
+export { LazyModuleManager, createLazyModuleManager, } from "./lazy-module-manager.js";
+export { LazyLoadMetrics, createLazyLoadMetrics } from "./lazy-load-metrics.js";
+export { LazyModuleWarmup, createLazyModuleWarmup, } from "./lazy-module-warmup.js";