@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/provider/logger/logger.metrics-collector.js

@@ -0,0 +1,180 @@
+import { detectFeaturesStatus, } from "./logger.metrics.js";
+import { METADATA_KEY } from "../../di/binding-decorator/constants.js";
+import { GuardRegistry } from "../../authorization/guard-registry.js";
+import { ExceptionFilterRegistry } from "../../error/exception-filter-registry.js";
+import { InterceptorRegistry } from "../../interceptor/interceptor-registry.js";
+import { EventRegistry } from "../../event/event-registry.js";
+import { LazyModuleLoader } from "../../lazy-loading/lazy-module-loader.js";
+import { INTERCEPTOR_METADATA_KEY } from "../../interceptor/interceptor-constants.js";
+import { EVENT_METADATA } from "../../event/event.interfaces.js";
+/**
+ * Collect application metrics from container and metadata.
+ * @public API
+ */
+export class MetricsCollector {
+    /**
+     * Collect metrics from the application.
+     * @param container - InversifyJS container
+     * @param options - Collection options
+     * @returns Application metrics and features status
+     */
+    static collect(container, options) {
+        // Count controllers
+        const controllers = options.getControllersFromMetadata();
+        const controllerCount = controllers.length;
+        // Count routes by iterating through controllers
+        let routeCount = 0;
+        try {
+            const controllerInstances = options.getControllersFromContainer();
+            controllerInstances.forEach((controller) => {
+                const constructor = controller
+                    .constructor;
+                const methods = options.getControllerMethodMetadata(constructor);
+                if (methods) {
+                    routeCount += methods.length;
+                }
+            });
+        }
+        catch {
+            // Fallback: estimate routes (assume 4 routes per controller on average)
+            routeCount = controllerCount * 4;
+        }
+        // Count providers from metadata
+        const provideMetadata = Reflect.getMetadata(METADATA_KEY.provide, Reflect) || [];
+        const providerCount = provideMetadata.length;
+        // Count bootstrap/shutdown providers
+        let bootstrapCount = 0;
+        let shutdownCount = 0;
+        provideMetadata.forEach((metadata) => {
+            const target = metadata.implementationType;
+            if (target?.prototype) {
+                if (typeof target.prototype.bootstrap === "function") {
+                    bootstrapCount++;
+                }
+                if (typeof target.prototype.shutdown === "function") {
+                    shutdownCount++;
+                }
+            }
+        });
+        // Count middleware
+        const middlewareCount = options.getMiddlewareCount();
+        // Count guards (check if GuardRegistry is bound)
+        let guardsCount = 0;
+        try {
+            if (container.isBound(GuardRegistry)) {
+                // GuardRegistry doesn't expose count, so we check metadata
+                const guardMetadata = Reflect.getMetadata("guard", Reflect) || [];
+                guardsCount = guardMetadata.length;
+            }
+        }
+        catch {
+            // Guards not available
+        }
+        // Count exception filters (check if ExceptionFilterRegistry is bound)
+        let filtersCount = 0;
+        try {
+            if (container.isBound(ExceptionFilterRegistry)) {
+                // ExceptionFilterRegistry doesn't expose count, so we check metadata
+                const filterMetadata = Reflect.getMetadata("exception-filter", Reflect) || [];
+                filtersCount = filterMetadata.length;
+            }
+        }
+        catch {
+            // Filters not available
+        }
+        // Count interceptors (check metadata and registry)
+        let interceptorsCount = 0;
+        let hasInterceptors = false;
+        try {
+            // Check metadata for registered interceptors
+            const interceptorMetadata = Reflect.getMetadata(INTERCEPTOR_METADATA_KEY.interceptor, Reflect) ||
+                [];
+            interceptorsCount = interceptorMetadata.length;
+            hasInterceptors = interceptorsCount > 0;
+            // Also check if InterceptorRegistry is bound and has interceptors
+            if (!hasInterceptors && container.isBound(InterceptorRegistry)) {
+                const registry = container.get(InterceptorRegistry);
+                const allInterceptors = registry.getAll();
+                interceptorsCount = allInterceptors.length;
+                hasInterceptors = interceptorsCount > 0;
+            }
+        }
+        catch {
+            // Interceptors not available
+        }
+        // Count event handlers (check EventRegistry)
+        let eventHandlersCount = 0;
+        let hasEventSystem = false;
+        try {
+            if (container.isBound(EventRegistry)) {
+                const registry = container.get(EventRegistry);
+                const handlers = registry.getHandlerClasses();
+                eventHandlersCount = handlers.length;
+                hasEventSystem = eventHandlersCount > 0;
+            }
+            else {
+                // Fallback: check metadata for event handlers
+                const provideMetadataForEvents = Reflect.getMetadata(METADATA_KEY.provide, Reflect) || [];
+                provideMetadataForEvents.forEach((metadata) => {
+                    const target = metadata.implementationType;
+                    if (target) {
+                        const isHandler = Reflect.getMetadata(EVENT_METADATA.IS_EVENT_HANDLER, target);
+                        if (isHandler) {
+                            eventHandlersCount++;
+                            hasEventSystem = true;
+                        }
+                    }
+                });
+            }
+        }
+        catch {
+            // Event system not available
+        }
+        // Count lazy modules (check LazyModuleLoader)
+        let lazyModulesCount = 0;
+        let hasLazyLoading = false;
+        try {
+            if (container.isBound(LazyModuleLoader)) {
+                const loader = container.get(LazyModuleLoader);
+                const allModules = loader.getAll();
+                lazyModulesCount = allModules.length;
+                hasLazyLoading = lazyModulesCount > 0;
+            }
+        }
+        catch {
+            // Lazy loading not available
+        }
+        // Detect enhanced configuration
+        const hasEnhancedConfiguration = options.hasEnhancedConfiguration?.() ?? false;
+        const metrics = {
+            controllers: controllerCount,
+            providers: providerCount,
+            middleware: middlewareCount,
+            guards: guardsCount,
+            filters: filtersCount,
+            routes: routeCount,
+            bootstrapProviders: bootstrapCount > 0 ? bootstrapCount : undefined,
+            shutdownProviders: shutdownCount > 0 ? shutdownCount : undefined,
+            interceptors: interceptorsCount > 0 ? interceptorsCount : undefined,
+            eventHandlers: eventHandlersCount > 0 ? eventHandlersCount : undefined,
+            lazyModules: lazyModulesCount > 0 ? lazyModulesCount : undefined,
+        };
+        const features = detectFeaturesStatus({
+            hasContentNegotiation: options.hasContentNegotiation(),
+            hasSmartValidation: options.hasSmartValidation(),
+            hasAuthorization: options.hasAuthorization(),
+            hasExceptionFilters: options.hasExceptionFilters(),
+            hasLifecycleHooks: bootstrapCount > 0 || shutdownCount > 0,
+            hasCustomScopes: options.hasCustomScopes?.() ?? false,
+            hasApiVersioning: options.hasApiVersioning?.() ?? false,
+            hasGlobalRoutePrefix: options.hasGlobalRoutePrefix?.() ?? false,
+            hasErrorHandler: options.hasErrorHandler?.() ?? false,
+            hasRequestLogging: options.hasRequestLogging?.() ?? false,
+            hasInterceptors,
+            hasEventSystem,
+            hasLazyLoading,
+            hasEnhancedConfiguration,
+        });
+        return { metrics, features };
+    }
+}

package/lib/esm/provider/logger/logger.metrics.js

@@ -0,0 +1,85 @@
+/**
+ * Get default banner configuration.
+ * @param environment - Current environment
+ * @returns Default banner config
+ * @public API
+ */
+export function getDefaultBannerConfig(environment) {
+    const isDev = environment === "development" || !environment;
+    return {
+        style: isDev ? "full" : "compact",
+        showMetrics: true,
+        showFeatures: false, // Disabled by default - user can enable
+        showConfig: true,
+        showPerformance: true,
+        showHealth: true,
+        showResources: false, // Disabled by default - user can enable
+        showMiddlewarePipeline: false, // Disabled by default - user can enable
+        showProviderRegistry: false, // Disabled by default - user can enable
+        maxMiddlewareDisplay: 6,
+        maxProviderDisplay: 5,
+        showInEnvironments: ["development", "production", "staging", "test"],
+        suppressLogsUntilBanner: true,
+    };
+}
+/**
+ * Merge banner configuration with environment-specific overrides.
+ * @param config - User config
+ * @param environment - Current environment
+ * @returns Merged configuration
+ * @public API
+ */
+export function resolveBannerConfig(config, environment) {
+    const defaults = getDefaultBannerConfig(environment);
+    const baseConfig = { ...defaults, ...config };
+    // Apply environment-specific overrides
+    if (config?.environment) {
+        const envConfig = environment === "production"
+            ? config.environment.production
+            : config.environment.development;
+        if (envConfig) {
+            return { ...baseConfig, ...envConfig };
+        }
+    }
+    return baseConfig;
+}
+/**
+ * Detect framework features status.
+ * @param options - Feature detection options
+ * @returns Features status
+ * @public API
+ */
+export function detectFeaturesStatus(options) {
+    return {
+        contentNegotiation: options?.hasContentNegotiation ?? false,
+        smartValidation: options?.hasSmartValidation ?? false,
+        authorization: options?.hasAuthorization ?? false,
+        exceptionFilters: options?.hasExceptionFilters ?? false,
+        gracefulShutdown: options?.hasGracefulShutdown ?? true, // Always enabled
+        lifecycleHooks: options?.hasLifecycleHooks ?? false,
+        customScopes: options?.hasCustomScopes ?? false,
+        apiVersioning: options?.hasApiVersioning ?? false,
+        globalRoutePrefix: options?.hasGlobalRoutePrefix ?? false,
+        errorHandler: options?.hasErrorHandler ?? false,
+        requestLogging: options?.hasRequestLogging ?? false,
+        interceptors: options?.hasInterceptors ?? false,
+        eventSystem: options?.hasEventSystem ?? false,
+        lazyLoading: options?.hasLazyLoading ?? false,
+        enhancedConfiguration: options?.hasEnhancedConfiguration ?? false,
+    };
+}
+/**
+ * Format memory usage.
+ * @param bytes - Memory in bytes
+ * @returns Formatted string (e.g., "45MB")
+ * @public API
+ */
+export function formatMemory(bytes) {
+    if (bytes < 1024) {
+        return `${bytes}B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    }
+    return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}

package/lib/esm/provider/logger/logger.performance.js

@@ -0,0 +1,299 @@
+/**
+ * @file logger.performance.ts
+ * @description Performance metrics and timing utilities for logging
+ * @module @expressots/core/provider/logger
+ *
+ * Features:
+ * - High-resolution timer API
+ * - Metrics collector for tracking multiple operations
+ * - Automatic performance logging
+ * - Memory and CPU usage tracking
+ */
+/**
+ * Timer implementation using performance.now() for high-resolution timing.
+ * @public API
+ */
+export class Timer {
+    label;
+    startTime;
+    logger;
+    logLevel;
+    ended = false;
+    cancelled = false;
+    constructor(label, logger, logLevel = "debug") {
+        this.label = label;
+        this.logger = logger;
+        this.logLevel = logLevel;
+        // Use performance.now() for sub-millisecond accuracy
+        this.startTime = globalThis.performance.now();
+    }
+    /**
+     * Get elapsed time in milliseconds without ending the timer.
+     * @returns Elapsed time in milliseconds
+     */
+    elapsed() {
+        return globalThis.performance.now() - this.startTime;
+    }
+    /**
+     * End the timer and log the duration.
+     * @returns Elapsed time in milliseconds
+     */
+    end() {
+        if (this.ended || this.cancelled) {
+            return this.elapsed();
+        }
+        this.ended = true;
+        const duration = this.elapsed();
+        // Log with appropriate level
+        const message = `⏱️  Timer "${this.label}" completed in ${duration.toFixed(2)}ms`;
+        const logData = {
+            timer: this.label,
+            duration: `${duration.toFixed(2)}ms`,
+            durationMs: duration,
+        };
+        switch (this.logLevel) {
+            case "info":
+                this.logger.info(message, undefined, logData);
+                break;
+            case "warn":
+                this.logger.warn(message, undefined, logData);
+                break;
+            case "debug":
+            default:
+                this.logger.debug(message, logData);
+                break;
+        }
+        return duration;
+    }
+    /**
+     * Cancel the timer (don't log).
+     */
+    cancel() {
+        this.cancelled = true;
+    }
+}
+/**
+ * Performance metrics collector for tracking multiple operations and generating summaries.
+ * @public API
+ *
+ * @example
+ * ```typescript
+ * const metrics = logger.metrics();
+ * metrics.start("database-query");
+ * // ... do work ...
+ * metrics.end("database-query");
+ *
+ * metrics.start("api-call");
+ * // ... do work ...
+ * metrics.end("api-call");
+ *
+ * const summary = metrics.summary();
+ * // Logs detailed breakdown with percentages
+ * ```
+ */
+export class PerformanceMetricsCollector {
+    metrics = new Map();
+    logger;
+    startTime;
+    constructor(logger) {
+        this.logger = logger;
+        this.startTime = globalThis.performance.now();
+    }
+    /**
+     * Start tracking a metric.
+     * @param label - Label for this metric
+     * @returns This collector for chaining
+     */
+    start(label) {
+        const existing = this.metrics.get(label);
+        if (existing && !existing.endTime) {
+            // Already started, don't restart
+            return this;
+        }
+        this.metrics.set(label, {
+            label,
+            startTime: globalThis.performance.now(),
+            count: existing?.count || 0,
+            totalDuration: existing?.totalDuration || 0,
+            minDuration: existing?.minDuration || Infinity,
+            maxDuration: existing?.maxDuration || 0,
+        });
+        return this;
+    }
+    /**
+     * End tracking a metric.
+     * @param label - Label for this metric
+     * @returns This collector for chaining
+     */
+    end(label) {
+        const metric = this.metrics.get(label);
+        if (!metric || metric.endTime) {
+            // Not started or already ended
+            return this;
+        }
+        const endTime = globalThis.performance.now();
+        const duration = endTime - metric.startTime;
+        metric.endTime = endTime;
+        metric.duration = duration;
+        metric.count = (metric.count || 0) + 1;
+        metric.totalDuration = (metric.totalDuration || 0) + duration;
+        metric.minDuration = Math.min(metric.minDuration, duration);
+        metric.maxDuration = Math.max(metric.maxDuration, duration);
+        return this;
+    }
+    /**
+     * Get current metric value without ending it.
+     * @param label - Label for this metric
+     * @returns Current duration or undefined if not started
+     */
+    get(label) {
+        const metric = this.metrics.get(label);
+        if (!metric || metric.endTime) {
+            return undefined;
+        }
+        return globalThis.performance.now() - metric.startTime;
+    }
+    /**
+     * Reset all metrics.
+     */
+    reset() {
+        this.metrics.clear();
+    }
+    /**
+     * Generate and log a summary of all metrics.
+     * @param options - Summary options
+     * @returns Summary object
+     */
+    summary(options) {
+        const totalTime = globalThis.performance.now() - this.startTime;
+        const completedMetrics = [];
+        for (const [label, metric] of this.metrics.entries()) {
+            if (metric.endTime && metric.count > 0) {
+                completedMetrics.push({
+                    label,
+                    count: metric.count,
+                    totalDuration: metric.totalDuration,
+                    averageDuration: metric.totalDuration / metric.count,
+                    minDuration: metric.minDuration === Infinity ? 0 : metric.minDuration,
+                    maxDuration: metric.maxDuration,
+                    percentage: (metric.totalDuration / totalTime) * 100,
+                });
+            }
+        }
+        // Sort by total duration (descending)
+        completedMetrics.sort((a, b) => b.totalDuration - a.totalDuration);
+        const summary = {
+            totalTime,
+            metrics: completedMetrics,
+        };
+        // Log summary if requested
+        if (options?.log !== false) {
+            const logLevel = options?.logLevel || "info";
+            const message = `📊 Performance Summary (Total: ${totalTime.toFixed(2)}ms)`;
+            const logData = {
+                totalTime: `${totalTime.toFixed(2)}ms`,
+                metrics: completedMetrics.map((m) => ({
+                    label: m.label,
+                    count: m.count,
+                    total: `${m.totalDuration.toFixed(2)}ms`,
+                    average: `${m.averageDuration.toFixed(2)}ms`,
+                    min: `${m.minDuration.toFixed(2)}ms`,
+                    max: `${m.maxDuration.toFixed(2)}ms`,
+                    percentage: `${m.percentage.toFixed(1)}%`,
+                })),
+            };
+            switch (logLevel) {
+                case "debug":
+                    this.logger.debug(message, logData);
+                    break;
+                case "warn":
+                    this.logger.warn(message, undefined, logData);
+                    break;
+                case "info":
+                default:
+                    this.logger.info(message, undefined, logData);
+                    break;
+            }
+        }
+        return summary;
+    }
+    /**
+     * Get all metrics as a map.
+     * @returns Map of label to metric entry
+     */
+    getAll() {
+        return new Map(this.metrics);
+    }
+}
+/**
+ * Measure performance of a function execution.
+ * @param fn - Function to measure
+ * @param label - Label for this measurement
+ * @param logger - Logger instance
+ * @returns Performance result
+ * @public API
+ */
+export async function measurePerformance(fn, label, logger) {
+    const startMemory = process.memoryUsage().heapUsed;
+    const startTime = globalThis.performance.now();
+    const startCpu = process.cpuUsage();
+    const result = await fn();
+    const endTime = globalThis.performance.now();
+    const endMemory = process.memoryUsage().heapUsed;
+    const endCpu = process.cpuUsage();
+    const duration = endTime - startTime;
+    const memoryDelta = endMemory - startMemory;
+    const cpuDelta = {
+        user: endCpu.user - startCpu.user,
+        system: endCpu.system - startCpu.system,
+    };
+    const cpuUsage = ((cpuDelta.user + cpuDelta.system) / 1000 / duration) * 100; // Convert to percentage
+    const performance = {
+        duration,
+        memoryDelta,
+        cpuUsage: isNaN(cpuUsage) ? undefined : cpuUsage,
+    };
+    logger.debug(`⏱️  "${label}" took ${duration.toFixed(2)}ms`, {
+        label,
+        duration: `${duration.toFixed(2)}ms`,
+        memoryDelta: `${(memoryDelta / 1024).toFixed(1)}KB`,
+        cpuUsage: cpuUsage ? `${cpuUsage.toFixed(1)}%` : undefined,
+    });
+    return { result, performance };
+}
+/**
+ * Synchronous version of measurePerformance.
+ * @param fn - Function to measure
+ * @param label - Label for this measurement
+ * @param logger - Logger instance
+ * @returns Performance result
+ * @public API
+ */
+export function measurePerformanceSync(fn, label, logger) {
+    const startMemory = process.memoryUsage().heapUsed;
+    const startTime = globalThis.performance.now();
+    const startCpu = process.cpuUsage();
+    const result = fn();
+    const endTime = globalThis.performance.now();
+    const endMemory = process.memoryUsage().heapUsed;
+    const endCpu = process.cpuUsage();
+    const duration = endTime - startTime;
+    const memoryDelta = endMemory - startMemory;
+    const cpuDelta = {
+        user: endCpu.user - startCpu.user,
+        system: endCpu.system - startCpu.system,
+    };
+    const cpuUsage = ((cpuDelta.user + cpuDelta.system) / 1000 / duration) * 100;
+    const performance = {
+        duration,
+        memoryDelta,
+        cpuUsage: isNaN(cpuUsage) ? undefined : cpuUsage,
+    };
+    logger.debug(`⏱️  "${label}" took ${duration.toFixed(2)}ms`, {
+        label,
+        duration: `${duration.toFixed(2)}ms`,
+        memoryDelta: `${(memoryDelta / 1024).toFixed(1)}KB`,
+        cpuUsage: cpuUsage ? `${cpuUsage.toFixed(1)}%` : undefined,
+    });
+    return { result, performance };
+}