@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/cjs/types/provider/logger/logger.grouping.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @file logger.grouping.ts
+ * @description Log grouping and noise reduction system
+ * @module @expressots/core/provider/logger
+ *
+ * Features:
+ * - String similarity detection for grouping similar logs
+ * - Time window grouping for repeated logs
+ * - Configurable thresholds and windows
+ * - Grouped output formatting
+ */
+import { LogEntry } from "./utils/log-entry.js";
+/**
+ * Configuration for log grouping.
+ * @public API
+ */
+export interface GroupingConfig {
+    /** Enable log grouping (default: true in dev, false in prod) */
+    enabled: boolean;
+    /** Similarity threshold for grouping (0-1, default: 0.8 = 80%) */
+    similarityThreshold: number;
+    /** Time window in milliseconds (default: 5000ms = 5 seconds) */
+    timeWindow: number;
+    /** Minimum occurrences to group (default: 3) */
+    minOccurrences: number;
+    /** Consider context when grouping (default: true) */
+    considerContext: boolean;
+    /** Maximum groups to track (default: 100) */
+    maxGroups: number;
+}
+/**
+ * Default grouping configuration.
+ * @returns Default config
+ * @public API
+ */
+export declare function getDefaultGroupingConfig(): GroupingConfig;
+/**
+ * Grouped log entry representing multiple similar logs.
+ * @public API
+ */
+export interface GroupedLogEntry {
+    /** Representative log entry (first occurrence) */
+    representative: LogEntry;
+    /** Number of times this log appeared */
+    count: number;
+    /** First occurrence timestamp */
+    firstOccurrence: Date;
+    /** Last occurrence timestamp */
+    lastOccurrence: Date;
+    /** All unique log entries in this group (for expansion) */
+    entries: Array<LogEntry>;
+    /** Group key (normalized message + context) */
+    groupKey: string;
+}
+/**
+ * Calculate similarity between two strings (0-1).
+ * @param str1 - First string
+ * @param str2 - Second string
+ * @returns Similarity score (0 = completely different, 1 = identical)
+ * @public API
+ */
+export declare function calculateSimilarity(str1: string, str2: string): number;
+/**
+ * Log grouping manager.
+ * Groups similar logs within time windows to reduce noise.
+ * @public API
+ */
+export declare class LogGroupingManager {
+    private config;
+    private groups;
+    private lastCleanup;
+    private readonly cleanupInterval;
+    constructor(config?: Partial<GroupingConfig>);
+    /**
+     * Update grouping configuration.
+     * @param config - Partial configuration to merge
+     */
+    configure(config: Partial<GroupingConfig>): void;
+    /**
+     * Process a log entry and determine if it should be grouped.
+     * @param entry - Log entry to process
+     * @returns Grouped entry if grouped, or original entry if not grouped
+     */
+    processEntry(entry: LogEntry): LogEntry | GroupedLogEntry;
+    /**
+     * Find a similar group using string similarity.
+     * @param entry - Log entry to match
+     * @returns Similar group if found, null otherwise
+     */
+    private findSimilarGroup;
+    /**
+     * Create a new group for a log entry.
+     * @param groupKey - Group key
+     * @param entry - First log entry in group
+     */
+    private createNewGroup;
+    /**
+     * Clean up groups that are outside the time window.
+     */
+    private cleanupOldGroups;
+    /**
+     * Flush all pending groups.
+     * Useful when shutting down or switching modes.
+     * @returns Array of grouped entries that should be logged
+     */
+    flush(): Array<GroupedLogEntry>;
+    /**
+     * Reset all groups.
+     */
+    reset(): void;
+    /**
+     * Get current group statistics.
+     * @returns Statistics about current groups
+     */
+    getStats(): {
+        totalGroups: number;
+        groups: Array<{
+            key: string;
+            count: number;
+            firstOccurrence: Date;
+            lastOccurrence: Date;
+        }>;
+    };
+}

package/lib/cjs/types/provider/logger/logger.health.d.ts

@@ -0,0 +1,123 @@
+import { Logger } from "./logger.provider.js";
+/**
+ * Health status data.
+ * @public API
+ */
+export interface HealthStatus {
+    /** Overall health status */
+    status: "healthy" | "degraded" | "unhealthy";
+    /** Application uptime in milliseconds */
+    uptime: number;
+    /** Uptime formatted as human-readable string */
+    uptimeFormatted: string;
+    /** Memory usage in bytes */
+    memoryUsage: number;
+    /** Memory usage formatted (e.g., "45MB") */
+    memoryUsageFormatted: string;
+    /** Memory usage percentage (heap used / heap total) */
+    memoryUsagePercent: number;
+    /** CPU usage percentage (if available) */
+    cpuUsage?: number;
+    /** External service statuses */
+    services?: Record<string, ServiceStatus>;
+    /** Timestamp of health check */
+    timestamp: number;
+}
+/**
+ * External service status.
+ * @public API
+ */
+export interface ServiceStatus {
+    /** Service name */
+    name: string;
+    /** Service status: 'healthy', 'degraded', 'unhealthy' */
+    status: "healthy" | "degraded" | "unhealthy";
+    /** Response time in milliseconds (if applicable) */
+    responseTime?: number;
+    /** Error message if unhealthy */
+    error?: string;
+    /** Last checked timestamp */
+    lastChecked: number;
+}
+/**
+ * Health check configuration.
+ * @public API
+ */
+export interface HealthConfig {
+    /** Enable periodic health logging */
+    enabled?: boolean;
+    /** Interval between health checks in milliseconds (default: 60000 = 60s) */
+    interval?: number;
+    /** Memory usage threshold percentage (default: 80) */
+    memoryThreshold?: number;
+    /** CPU usage threshold percentage (default: 90) */
+    cpuThreshold?: number;
+    /** Enable alert logging when thresholds are exceeded */
+    alertsEnabled?: boolean;
+    /** Custom health check functions for external services */
+    serviceChecks?: Array<() => Promise<ServiceStatus>>;
+    /** Log level for health status logs (default: 'info') */
+    logLevel?: "info" | "debug";
+    /** Log level for alerts (default: 'warn') */
+    alertLogLevel?: "warn" | "error";
+}
+/**
+ * Get default health configuration.
+ * @param environment - Current environment
+ * @returns Default health config
+ * @public API
+ */
+export declare function getDefaultHealthConfig(environment?: string): Required<Omit<HealthConfig, "serviceChecks">>;
+/**
+ * Format uptime as human-readable string.
+ * @param ms - Milliseconds
+ * @returns Formatted string (e.g., "2h 30m 15s")
+ * @public API
+ */
+export declare function formatUptime(ms: number): string;
+/**
+ * Collect current health status.
+ * @param serviceChecks - Optional service check functions
+ * @returns Health status
+ * @public API
+ */
+export declare function collectHealthStatus(serviceChecks?: Array<() => Promise<ServiceStatus>>): Promise<HealthStatus>;
+/**
+ * Health monitor for periodic health checks and alerts.
+ * @public API
+ */
+export declare class HealthMonitor {
+    private logger;
+    private config;
+    private intervalId;
+    private startTime;
+    private lastCpuUsage;
+    private lastCpuCheck;
+    /**
+     * Create a new health monitor.
+     * @param logger - Logger instance
+     * @param config - Health configuration
+     */
+    constructor(logger: Logger, config?: Partial<HealthConfig>);
+    /**
+     * Start periodic health monitoring.
+     */
+    start(): void;
+    /**
+     * Stop periodic health monitoring.
+     */
+    stop(): void;
+    /**
+     * Perform a health check and log results.
+     */
+    private checkHealth;
+    /**
+     * Check health thresholds and log alerts if exceeded.
+     */
+    private checkThresholds;
+    /**
+     * Get current health status (without logging).
+     * @returns Current health status
+     */
+    getCurrentHealth(): Promise<HealthStatus>;
+}

package/lib/cjs/types/provider/logger/logger.metrics-collector.d.ts

@@ -0,0 +1,44 @@
+import { interfaces } from "../../di/inversify.js";
+import { ApplicationMetrics, FeaturesStatus } from "./logger.metrics.js";
+/**
+ * Collect application metrics from container and metadata.
+ * @public API
+ */
+export declare class MetricsCollector {
+    /**
+     * Collect metrics from the application.
+     * @param container - InversifyJS container
+     * @param options - Collection options
+     * @returns Application metrics and features status
+     */
+    static collect(container: interfaces.Container, options: {
+        getControllersFromMetadata: () => Array<unknown>;
+        getControllersFromContainer: () => Array<unknown>;
+        getControllerMethodMetadata: (constructor: NewableFunction) => Array<{
+            method: string;
+            path: string;
+        }> | undefined;
+        getMiddlewareCount: () => number;
+        hasContentNegotiation: () => boolean;
+        hasSmartValidation: () => boolean;
+        hasAuthorization: () => boolean;
+        hasExceptionFilters: () => boolean;
+        hasApiVersioning?: () => boolean;
+        hasGlobalRoutePrefix?: () => boolean;
+        hasErrorHandler?: () => boolean;
+        hasRequestLogging?: () => boolean;
+        hasEnhancedConfiguration?: () => boolean;
+        /**
+         * Optional. The adapter (or app) can pass a probe that returns true
+         * when the application has registered scopes outside of Inversify's
+         * built-in `Singleton` / `Transient` / `Request` (e.g. tenant scope).
+         *
+         * When omitted, `customScopes` is reported as `false` — accurate by
+         * default for vanilla apps.
+         */
+        hasCustomScopes?: () => boolean;
+    }): {
+        metrics: ApplicationMetrics;
+        features: FeaturesStatus;
+    };
+}

package/lib/cjs/types/provider/logger/logger.metrics.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Application metrics for banner display.
+ * @public API
+ */
+export interface ApplicationMetrics {
+    /** Number of controllers loaded */
+    controllers: number;
+    /** Number of providers registered */
+    providers: number;
+    /** Number of middleware active */
+    middleware: number;
+    /** Number of guards active */
+    guards: number;
+    /** Number of exception filters active */
+    filters: number;
+    /** Number of routes registered */
+    routes: number;
+    /** Number of bootstrap providers */
+    bootstrapProviders?: number;
+    /** Number of shutdown providers */
+    shutdownProviders?: number;
+    /** Number of interceptors active */
+    interceptors?: number;
+    /** Number of event handlers registered */
+    eventHandlers?: number;
+    /** Number of lazy modules registered */
+    lazyModules?: number;
+}
+/**
+ * Framework features status.
+ * @public API
+ */
+export interface FeaturesStatus {
+    /** Content Negotiation enabled */
+    contentNegotiation: boolean;
+    /** Smart Validation enabled */
+    smartValidation: boolean;
+    /** Authorization (Guards) enabled */
+    authorization: boolean;
+    /** Exception Filters enabled */
+    exceptionFilters: boolean;
+    /** Graceful Shutdown enabled */
+    gracefulShutdown: boolean;
+    /** Lifecycle Hooks enabled */
+    lifecycleHooks: boolean;
+    /** Custom Scopes enabled */
+    customScopes: boolean;
+    /** API Versioning enabled */
+    apiVersioning: boolean;
+    /** Global Route Prefix configured */
+    globalRoutePrefix: boolean;
+    /** Error Handler configured */
+    errorHandler: boolean;
+    /** Request Logging enabled */
+    requestLogging: boolean;
+    /** Interceptors enabled */
+    interceptors: boolean;
+    /** Event System enabled */
+    eventSystem: boolean;
+    /** Lazy Loading enabled */
+    lazyLoading: boolean;
+    /** Enhanced Configuration enabled */
+    enhancedConfiguration: boolean;
+}
+/**
+ * Performance metrics for startup.
+ * @public API
+ */
+export interface StartupMetrics {
+    /** Startup time in milliseconds */
+    startupTime: number;
+    /** Memory usage in bytes */
+    memoryUsage: number;
+    /** Memory usage formatted (e.g., "45MB") */
+    memoryUsageFormatted: string;
+}
+/**
+ * Banner configuration.
+ * @public API
+ */
+export interface BannerConfig {
+    /** Banner style: 'full', 'compact', 'minimal', 'none' */
+    style?: "full" | "compact" | "minimal" | "none";
+    /** Show application metrics */
+    showMetrics?: boolean;
+    /** Show framework features status */
+    showFeatures?: boolean;
+    /** Show configuration info */
+    showConfig?: boolean;
+    /** Show performance metrics */
+    showPerformance?: boolean;
+    /** Show system health status */
+    showHealth?: boolean;
+    /** Show resources/links */
+    showResources?: boolean;
+    /** Show middleware pipeline section */
+    showMiddlewarePipeline?: boolean;
+    /** Show provider registry section */
+    showProviderRegistry?: boolean;
+    /** Maximum middleware entries to display */
+    maxMiddlewareDisplay?: number;
+    /** Maximum provider entries to display */
+    maxProviderDisplay?: number;
+    /** Custom ASCII art file path */
+    customArt?: string;
+    /** Environment-specific configuration */
+    environment?: {
+        /** Banner settings for development */
+        development?: Partial<Omit<BannerConfig, "environment">>;
+        /** Banner settings for production */
+        production?: Partial<Omit<BannerConfig, "environment">>;
+    };
+    /** Only show banner in specific environments */
+    showInEnvironments?: Array<"development" | "production" | "staging" | "test">;
+    /** Suppress all logs until banner is displayed */
+    suppressLogsUntilBanner?: boolean;
+}
+/**
+ * Get default banner configuration.
+ * @param environment - Current environment
+ * @returns Default banner config
+ * @public API
+ */
+export declare function getDefaultBannerConfig(environment?: string): Required<Omit<BannerConfig, "environment" | "customArt">>;
+/**
+ * Merge banner configuration with environment-specific overrides.
+ * @param config - User config
+ * @param environment - Current environment
+ * @returns Merged configuration
+ * @public API
+ */
+export declare function resolveBannerConfig(config: BannerConfig | undefined, environment: string): BannerConfig;
+/**
+ * Detect framework features status.
+ * @param options - Feature detection options
+ * @returns Features status
+ * @public API
+ */
+export declare function detectFeaturesStatus(options?: {
+    hasContentNegotiation?: boolean;
+    hasSmartValidation?: boolean;
+    hasAuthorization?: boolean;
+    hasExceptionFilters?: boolean;
+    hasGracefulShutdown?: boolean;
+    hasLifecycleHooks?: boolean;
+    hasCustomScopes?: boolean;
+    hasApiVersioning?: boolean;
+    hasGlobalRoutePrefix?: boolean;
+    hasErrorHandler?: boolean;
+    hasRequestLogging?: boolean;
+    hasInterceptors?: boolean;
+    hasEventSystem?: boolean;
+    hasLazyLoading?: boolean;
+    hasEnhancedConfiguration?: boolean;
+}): FeaturesStatus;
+/**
+ * Format memory usage.
+ * @param bytes - Memory in bytes
+ * @returns Formatted string (e.g., "45MB")
+ * @public API
+ */
+export declare function formatMemory(bytes: number): string;

package/lib/cjs/types/provider/logger/logger.performance.d.ts

@@ -0,0 +1,179 @@
+/**
+ * @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
+ */
+import { Logger } from "./logger.provider.js";
+/**
+ * Timer interface for measuring execution time.
+ * @public API
+ */
+export interface ITimer {
+    /** Label for this timer */
+    readonly label: string;
+    /** Start time in milliseconds (high-resolution) */
+    readonly startTime: number;
+    /** End the timer and log the duration */
+    end(): number;
+    /** Get elapsed time without ending the timer */
+    elapsed(): number;
+    /** Cancel the timer (don't log) */
+    cancel(): void;
+}
+/**
+ * Timer implementation using performance.now() for high-resolution timing.
+ * @public API
+ */
+export declare class Timer implements ITimer {
+    readonly label: string;
+    readonly startTime: number;
+    private readonly logger;
+    private readonly logLevel;
+    private ended;
+    private cancelled;
+    constructor(label: string, logger: Logger, logLevel?: "debug" | "info" | "warn");
+    /**
+     * Get elapsed time in milliseconds without ending the timer.
+     * @returns Elapsed time in milliseconds
+     */
+    elapsed(): number;
+    /**
+     * End the timer and log the duration.
+     * @returns Elapsed time in milliseconds
+     */
+    end(): number;
+    /**
+     * Cancel the timer (don't log).
+     */
+    cancel(): void;
+}
+/**
+ * Individual metric entry for tracking operation duration.
+ */
+interface MetricEntry {
+    label: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+    count: number;
+    totalDuration: number;
+    minDuration: number;
+    maxDuration: number;
+}
+/**
+ * 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 declare class PerformanceMetricsCollector {
+    private metrics;
+    private readonly logger;
+    private readonly startTime;
+    constructor(logger: Logger);
+    /**
+     * Start tracking a metric.
+     * @param label - Label for this metric
+     * @returns This collector for chaining
+     */
+    start(label: string): this;
+    /**
+     * End tracking a metric.
+     * @param label - Label for this metric
+     * @returns This collector for chaining
+     */
+    end(label: string): this;
+    /**
+     * Get current metric value without ending it.
+     * @param label - Label for this metric
+     * @returns Current duration or undefined if not started
+     */
+    get(label: string): number | undefined;
+    /**
+     * Reset all metrics.
+     */
+    reset(): void;
+    /**
+     * Generate and log a summary of all metrics.
+     * @param options - Summary options
+     * @returns Summary object
+     */
+    summary(options?: {
+        /** Log the summary (default: true) */
+        log?: boolean;
+        /** Log level (default: "info") */
+        logLevel?: "debug" | "info" | "warn";
+    }): {
+        totalTime: number;
+        metrics: Array<{
+            label: string;
+            count: number;
+            totalDuration: number;
+            averageDuration: number;
+            minDuration: number;
+            maxDuration: number;
+            percentage: number;
+        }>;
+    };
+    /**
+     * Get all metrics as a map.
+     * @returns Map of label to metric entry
+     */
+    getAll(): Map<string, MetricEntry>;
+}
+/**
+ * Performance measurement result.
+ * @public API
+ */
+export interface PerformanceResult {
+    /** Duration in milliseconds */
+    duration: number;
+    /** Memory delta in bytes */
+    memoryDelta: number;
+    /** CPU usage percentage (if available) */
+    cpuUsage?: number;
+}
+/**
+ * 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 declare function measurePerformance<T>(fn: () => T | Promise<T>, label: string, logger: Logger): Promise<{
+    result: T;
+    performance: PerformanceResult;
+}>;
+/**
+ * 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 declare function measurePerformanceSync<T>(fn: () => T, label: string, logger: Logger): {
+    result: T;
+    performance: PerformanceResult;
+};
+export {};