@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,70 @@
+"use strict";
+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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoggingInterceptor = void 0;
+const inversify_js_1 = require("../../di/inversify.js");
+const logger_provider_js_1 = require("../../provider/logger/logger.provider.js");
+const interceptor_decorators_js_1 = require("../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 {
+    constructor(logger) {
+        this.logger = logger;
+        this.priority = 5;
+    }
+    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;
+        }
+    }
+};
+exports.LoggingInterceptor = LoggingInterceptor;
+exports.LoggingInterceptor = LoggingInterceptor = __decorate([
+    (0, interceptor_decorators_js_1.Interceptor)({ priority: 5 }),
+    (0, inversify_js_1.injectable)(),
+    __param(0, (0, inversify_js_1.inject)(logger_provider_js_1.Logger)),
+    __metadata("design:paramtypes", [logger_provider_js_1.Logger])
+], LoggingInterceptor);

package/lib/cjs/interceptor/interceptors/performance.interceptor.js

@@ -0,0 +1,251 @@
+"use strict";
+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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerformanceInterceptor = exports.PerformanceInterceptorService = void 0;
+const inversify_js_1 = require("../../di/inversify.js");
+const logger_provider_js_1 = require("../../provider/logger/logger.provider.js");
+const interceptor_decorators_js_1 = require("../interceptor-decorators.js");
+/**
+ * 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
+ */
+let PerformanceInterceptorService = class PerformanceInterceptorService {
+    constructor() {
+        this.metrics = {};
+        this.slowThreshold = 1000; // Default 1 second
+        this.logSlowCalls = true;
+        this.logAllCalls = false;
+    }
+    /**
+     * Configure performance interceptor options
+     */
+    configure(options) {
+        if (options.slowThreshold !== undefined) {
+            this.slowThreshold = options.slowThreshold;
+        }
+        if (options.logSlowCalls !== undefined) {
+            this.logSlowCalls = options.logSlowCalls;
+        }
+        if (options.logAllCalls !== undefined) {
+            this.logAllCalls = options.logAllCalls;
+        }
+    }
+    /**
+     * Record a call for an endpoint
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    recordCall(key, duration, _isError) {
+        if (!this.metrics[key]) {
+            this.metrics[key] = {
+                avgTime: duration,
+                maxTime: duration,
+                minTime: duration,
+                callCount: 1,
+                slowCalls: duration > this.slowThreshold ? 1 : 0,
+                lastTime: duration,
+                lastCall: new Date(),
+            };
+        }
+        else {
+            const m = this.metrics[key];
+            const totalTime = m.avgTime * m.callCount + duration;
+            m.callCount++;
+            m.avgTime = totalTime / m.callCount;
+            m.maxTime = Math.max(m.maxTime, duration);
+            m.minTime = Math.min(m.minTime, duration);
+            m.lastTime = duration;
+            m.lastCall = new Date();
+            if (duration > this.slowThreshold) {
+                m.slowCalls++;
+            }
+        }
+    }
+    /**
+     * Check if a duration is considered slow
+     */
+    isSlowCall(duration) {
+        return duration > this.slowThreshold;
+    }
+    /**
+     * Get slow threshold
+     */
+    getSlowThreshold() {
+        return this.slowThreshold;
+    }
+    /**
+     * Get all performance metrics
+     */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /**
+     * Get metrics for a specific endpoint
+     */
+    getEndpointMetrics(key) {
+        return this.metrics[key];
+    }
+    /**
+     * Get all endpoints that have had slow calls
+     */
+    getSlowEndpoints() {
+        return Object.entries(this.metrics)
+            .filter(([, m]) => m.slowCalls > 0)
+            .map(([endpoint, metrics]) => ({ endpoint, metrics }))
+            .sort((a, b) => b.metrics.slowCalls - a.metrics.slowCalls);
+    }
+    /**
+     * Get endpoints sorted by average response time (slowest first)
+     */
+    getSlowestEndpoints(limit = 10) {
+        return Object.entries(this.metrics)
+            .map(([endpoint, m]) => ({ endpoint, avgTime: m.avgTime }))
+            .sort((a, b) => b.avgTime - a.avgTime)
+            .slice(0, limit);
+    }
+    /**
+     * Clear all metrics
+     */
+    clearMetrics() {
+        this.metrics = {};
+    }
+    /**
+     * Get summary statistics
+     */
+    getSummary() {
+        const endpoints = Object.values(this.metrics);
+        const totalCalls = endpoints.reduce((sum, m) => sum + m.callCount, 0);
+        const totalTime = endpoints.reduce((sum, m) => sum + m.avgTime * m.callCount, 0);
+        const slowEndpoints = endpoints.filter((m) => m.slowCalls > 0).length;
+        return {
+            totalEndpoints: endpoints.length,
+            totalCalls,
+            avgResponseTime: totalCalls > 0 ? totalTime / totalCalls : 0,
+            slowEndpoints,
+        };
+    }
+};
+exports.PerformanceInterceptorService = PerformanceInterceptorService;
+exports.PerformanceInterceptorService = PerformanceInterceptorService = __decorate([
+    (0, inversify_js_1.injectable)(),
+    __metadata("design:paramtypes", [])
+], PerformanceInterceptorService);
+/**
+ * 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
+ */
+let PerformanceInterceptor = class PerformanceInterceptor {
+    constructor(logger, metricsService) {
+        this.logger = logger;
+        this.metricsService = metricsService;
+        this.priority = 1;
+    }
+    async intercept(context, next) {
+        const request = context.getRequest();
+        const method = request.method;
+        const path = request.path;
+        const key = `${method} ${path}`;
+        const startTime = Date.now();
+        try {
+            const result = await next.handle();
+            const duration = Date.now() - startTime;
+            // Record metrics
+            this.metricsService.recordCall(key, duration, false);
+            // Log slow calls
+            if (this.metricsService.isSlowCall(duration)) {
+                this.logger.warn(`⚠️ Slow endpoint: ${key} took ${duration}ms (threshold: ${this.metricsService.getSlowThreshold()}ms)`, "performance-interceptor");
+            }
+            return result;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            this.metricsService.recordCall(key, duration, true);
+            throw error;
+        }
+    }
+};
+exports.PerformanceInterceptor = PerformanceInterceptor;
+exports.PerformanceInterceptor = PerformanceInterceptor = __decorate([
+    (0, interceptor_decorators_js_1.Interceptor)({ priority: 1 }) // Run first (outermost) to capture total time
+    ,
+    (0, inversify_js_1.injectable)(),
+    __param(0, (0, inversify_js_1.inject)(logger_provider_js_1.Logger)),
+    __param(1, (0, inversify_js_1.inject)(PerformanceInterceptorService)),
+    __metadata("design:paramtypes", [logger_provider_js_1.Logger,
+        PerformanceInterceptorService])
+], PerformanceInterceptor);

package/lib/cjs/interceptor/interceptors/timeout.interceptor.js

@@ -0,0 +1,66 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutInterceptor = void 0;
+const inversify_js_1 = require("../../di/inversify.js");
+const interceptor_decorators_js_1 = require("../interceptor-decorators.js");
+const app_error_js_1 = require("../../error/app-error.js");
+const status_code_js_1 = require("../../error/status-code.js");
+/**
+ * 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
+ */
+let TimeoutInterceptor = class TimeoutInterceptor {
+    constructor(options) {
+        this.priority = 2;
+        this.timeout = options?.timeout ?? 30000;
+        this.message = options?.message ?? "Request timed out";
+    }
+    async intercept(_context, next) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new app_error_js_1.AppError(this.message, status_code_js_1.StatusCode.RequestTimeout));
+            }, this.timeout);
+            next
+                .handle()
+                .then((result) => {
+                clearTimeout(timer);
+                resolve(result);
+            })
+                .catch((error) => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    }
+};
+exports.TimeoutInterceptor = TimeoutInterceptor;
+exports.TimeoutInterceptor = TimeoutInterceptor = __decorate([
+    (0, interceptor_decorators_js_1.Interceptor)({ priority: 2 }),
+    (0, inversify_js_1.injectable)(),
+    __metadata("design:paramtypes", [Object])
+], TimeoutInterceptor);

package/lib/cjs/lazy-loading/index.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * 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" });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLazyModuleWarmup = exports.LazyModuleWarmup = exports.createLazyLoadMetrics = exports.LazyLoadMetrics = exports.createLazyModuleManager = exports.LazyModuleManager = exports.createLazyModuleLoader = exports.LazyModuleLoader = exports.withLazyConfig = exports.withPreloadHint = exports.LAZY_MODULE_METADATA_KEY = exports.getModuleName = exports.isLazyModule = exports.createLazyModule = exports.CreateLazyModule = exports.LazyModule = void 0;
+// ============================================================================
+// Lazy Module
+// ============================================================================
+var lazy_module_js_1 = require("./lazy-module.js");
+Object.defineProperty(exports, "LazyModule", { enumerable: true, get: function () { return lazy_module_js_1.LazyModule; } });
+Object.defineProperty(exports, "CreateLazyModule", { enumerable: true, get: function () { return lazy_module_js_1.CreateLazyModule; } });
+Object.defineProperty(exports, "createLazyModule", { enumerable: true, get: function () { return lazy_module_js_1.createLazyModule; } });
+Object.defineProperty(exports, "isLazyModule", { enumerable: true, get: function () { return lazy_module_js_1.isLazyModule; } });
+Object.defineProperty(exports, "getModuleName", { enumerable: true, get: function () { return lazy_module_js_1.getModuleName; } });
+Object.defineProperty(exports, "LAZY_MODULE_METADATA_KEY", { enumerable: true, get: function () { return lazy_module_js_1.LAZY_MODULE_METADATA_KEY; } });
+// Free-function wrappers for the LazyModule chain methods.
+var lazy_module_helpers_js_1 = require("./lazy-module-helpers.js");
+Object.defineProperty(exports, "withPreloadHint", { enumerable: true, get: function () { return lazy_module_helpers_js_1.withPreloadHint; } });
+Object.defineProperty(exports, "withLazyConfig", { enumerable: true, get: function () { return lazy_module_helpers_js_1.withLazyConfig; } });
+// ============================================================================
+// Lazy Module Loader
+// ============================================================================
+var lazy_module_loader_js_1 = require("./lazy-module-loader.js");
+Object.defineProperty(exports, "LazyModuleLoader", { enumerable: true, get: function () { return lazy_module_loader_js_1.LazyModuleLoader; } });
+Object.defineProperty(exports, "createLazyModuleLoader", { enumerable: true, get: function () { return lazy_module_loader_js_1.createLazyModuleLoader; } });
+// ============================================================================
+// Lazy Module Manager
+// ============================================================================
+var lazy_module_manager_js_1 = require("./lazy-module-manager.js");
+Object.defineProperty(exports, "LazyModuleManager", { enumerable: true, get: function () { return lazy_module_manager_js_1.LazyModuleManager; } });
+Object.defineProperty(exports, "createLazyModuleManager", { enumerable: true, get: function () { return lazy_module_manager_js_1.createLazyModuleManager; } });
+// ============================================================================
+// Lazy Load Metrics
+// ============================================================================
+var lazy_load_metrics_js_1 = require("./lazy-load-metrics.js");
+Object.defineProperty(exports, "LazyLoadMetrics", { enumerable: true, get: function () { return lazy_load_metrics_js_1.LazyLoadMetrics; } });
+Object.defineProperty(exports, "createLazyLoadMetrics", { enumerable: true, get: function () { return lazy_load_metrics_js_1.createLazyLoadMetrics; } });
+// ============================================================================
+// Lazy Module Warmup
+// ============================================================================
+var lazy_module_warmup_js_1 = require("./lazy-module-warmup.js");
+Object.defineProperty(exports, "LazyModuleWarmup", { enumerable: true, get: function () { return lazy_module_warmup_js_1.LazyModuleWarmup; } });
+Object.defineProperty(exports, "createLazyModuleWarmup", { enumerable: true, get: function () { return lazy_module_warmup_js_1.createLazyModuleWarmup; } });