@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/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/esm/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 {};

package/lib/esm/types/provider/logger/logger.provider.d.ts

@@ -0,0 +1,363 @@
+import { IProvider } from "../provider-manager.js";
+import { LogLevelString } from "./utils/log-levels.js";
+import { LogEntry } from "./utils/log-entry.js";
+import { LoggerConfig } from "./logger.config.js";
+import { LogContext } from "./logger.context.js";
+import { ITimer, PerformanceMetricsCollector } from "./logger.performance.js";
+import { HealthStatus } from "./logger.health.js";
+import { LogQueryOptions, LogQuery, QueryStats } from "./logger.query.js";
+/**
+ * Enhanced Logger provider with structured logging, multiple levels, and pluggable transports.
+ * Features:
+ * - Automatic context detection (class/method names)
+ * - Request-scoped context via AsyncLocalStorage
+ * - Child logger creation with inherited context
+ * - Multiple log levels (ALL, DEBUG, INFO, WARN, ERROR, FATAL, SILENT)
+ * - Pluggable transports (console, file, HTTP)
+ * @public API
+ */
+declare class Logger implements IProvider {
+    private pid;
+    private config;
+    private transports;
+    private currentContext;
+    private contextObject;
+    private autoDetectContext;
+    private groupingManager;
+    private healthMonitor;
+    private queryManager;
+    /**
+     * Module-level overrides applied by `Logger.configure(...)` on top of the
+     * built-in defaults. Used by the constructor of every future `Logger`
+     * instance so application-wide config (e.g. log level, transports) can be
+     * set once before bootstrap, before any DI container exists.
+     */
+    private static defaultOverrides;
+    name: string;
+    version: string;
+    author: string;
+    repo: string;
+    constructor();
+    /**
+     * Configure the default LoggerConfig used by every future `Logger`
+     * instance constructed in this process.
+     *
+     * Use this from application config files **before** bootstrap so the DI
+     * container's Logger picks up the correct level / transports / grouping /
+     * health / redaction settings without needing to inject and reconfigure it.
+     * Calls are merged: later calls override earlier ones, but unspecified
+     * keys keep their previously-set values.
+     *
+     * Already-constructed Logger instances are NOT mutated by this call —
+     * use the instance method `logger.configure(...)` to update a live one.
+     *
+     * @param config - Partial configuration to merge with the defaults.
+     * @public API
+     */
+    static configure(config: Partial<LoggerConfig>): void;
+    /**
+     * Reset the module-level overrides set by `Logger.configure`. Useful in
+     * tests to undo cross-test pollution.
+     *
+     * @public API
+     */
+    static resetConfigure(): void;
+    /**
+     * Configure the logger.
+     * @param config - Partial configuration to merge with defaults
+     * @public API
+     */
+    configure(config: Partial<LoggerConfig>): void;
+    /**
+     * Get the current logger configuration.
+     * @returns Current logger configuration
+     * @public API
+     */
+    getConfig(): LoggerConfig;
+    /**
+     * Log a trace message (ultra-detailed diagnostic).
+     * @param message - The message to log
+     * @param data - Optional structured data
+     * @public API
+     */
+    trace(message: string, data?: unknown): void;
+    /**
+     * Log a debug message (detailed diagnostic).
+     * @param message - The message to log
+     * @param data - Optional structured data
+     * @public API
+     */
+    debug(message: string, data?: unknown): void;
+    /**
+     * Log an informational message.
+     * @param message - The message to log
+     * @param module - Optional module/context name (legacy API)
+     * @param data - Optional structured data (new API)
+     * @public API
+     */
+    info(message: string, module?: string, data?: unknown): void;
+    /**
+     * Log a warning message.
+     * @param message - The message to log
+     * @param module - Optional module/context name (legacy API)
+     * @param data - Optional structured data (new API)
+     * @public API
+     */
+    warn(message: string, module?: string, data?: unknown): void;
+    /**
+     * Log an error message.
+     * @param message - The message to log
+     * @param module - Optional module/context name (legacy API)
+     * @param error - Optional error object (new API)
+     * @public API
+     */
+    error(message: string, module?: string, error?: Error | unknown): void;
+    /**
+     * Log a fatal error message.
+     * @param message - The message to log
+     * @param error - Optional error object
+     * @public API
+     */
+    fatal(message: string, error?: Error | unknown): void;
+    /**
+     * Log a generic message (legacy API - maps to INFO).
+     * @param message - The message to log
+     * @param module - Optional module name
+     * @public API
+     */
+    msg(message: string, module?: string): void;
+    /**
+     * Create a child logger with inherited context.
+     * @param context - Context name for the child logger
+     * @returns New Logger instance with context
+     * @public API
+     */
+    child(context: string): Logger;
+    /**
+     * Set context for subsequent logs.
+     * @param context - Context name, object, or LogContext
+     * @returns Logger instance for chaining
+     * @public API
+     *
+     * @example
+     * // String context
+     * logger.withContext("UserService").info("User created");
+     *
+     * @example
+     * // Object context
+     * logger.withContext({ className: "UserService", methodName: "create" }).info("User created");
+     *
+     * @example
+     * // Request context (typically set by middleware)
+     * logger.withContext({ requestId: "req_123", userId: "user_456" }).info("Processing request");
+     */
+    withContext(context: string | Partial<LogContext>): Logger;
+    /**
+     * Disable automatic context detection for this logger.
+     * @returns Logger instance for chaining
+     * @public API
+     */
+    noAutoContext(): Logger;
+    /**
+     * Enable automatic context detection for this logger.
+     * @returns Logger instance for chaining
+     * @public API
+     */
+    enableAutoContext(): Logger;
+    /**
+     * Run a function with request-scoped context.
+     * All logs within the function (including async operations) will include this context.
+     * @param context - Context to use for the duration of the function
+     * @param fn - Function to run
+     * @returns Result of the function
+     * @public API
+     *
+     * @example
+     * await logger.runWithContext({ requestId: "req_123" }, async () => {
+     *   logger.info("Processing..."); // Will include requestId
+     *   await someAsyncOperation(); // Nested logs also include requestId
+     * });
+     */
+    runWithContext<T>(context: Partial<LogContext>, fn: () => T | Promise<T>): T | Promise<T>;
+    /**
+     * Core logging method.
+     * Supports automatic context detection, request-scoped context, and manual context.
+     * @param level - Log level
+     * @param message - Log message
+     * @param options - Additional options
+     */
+    private log;
+    /**
+     * Check if a log entry is a grouped entry.
+     * @param entry - Log entry or grouped entry
+     * @returns True if grouped entry
+     */
+    private isGroupedLogEntry;
+    /**
+     * Send a grouped log entry to transports.
+     * Formats grouped entries and writes them directly to stdout/stderr.
+     * @param groupedEntry - Grouped log entry
+     */
+    private sendGroupedEntry;
+    /**
+     * Send a regular log entry to transports.
+     * @param entry - Log entry
+     */
+    private sendEntry;
+    /**
+     * Start a high-resolution timer.
+     * @param label - Label for this timer
+     * @param logLevel - Log level when timer ends (default: "debug")
+     * @returns Timer object with end() method
+     * @public API
+     *
+     * @example
+     * ```typescript
+     * const timer = logger.startTimer("database-query");
+     * // ... do work ...
+     * timer.end(); // Logs: "Timer 'database-query' completed in 45.23ms"
+     * ```
+     */
+    startTimer(label: string, logLevel?: "debug" | "info" | "warn"): ITimer;
+    /**
+     * Get a metrics collector for tracking multiple operations.
+     * @returns PerformanceMetricsCollector instance
+     * @public API
+     *
+     * @example
+     * ```typescript
+     * const metrics = logger.metrics();
+     * metrics.start("db-query").end("db-query");
+     * metrics.start("api-call").end("api-call");
+     * metrics.summary(); // Logs detailed breakdown
+     * ```
+     */
+    metrics(): PerformanceMetricsCollector;
+    /**
+     * Measure performance of an async function.
+     * @param fn - Async function to measure
+     * @param label - Label for this measurement
+     * @returns Promise with result and performance data
+     * @public API
+     *
+     * @example
+     * ```typescript
+     * const { result, performance } = await logger.measure(
+     *   async () => await fetchData(),
+     *   "fetch-data"
+     * );
+     * // Logs: "fetch-data took 123.45ms"
+     * ```
+     */
+    measure<T>(fn: () => T | Promise<T>, label: string): Promise<{
+        result: T;
+        performance: {
+            duration: number;
+            memoryDelta: number;
+            cpuUsage?: number;
+        };
+    }>;
+    /**
+     * Measure performance of a synchronous function.
+     * @param fn - Function to measure
+     * @param label - Label for this measurement
+     * @returns Result and performance data
+     * @public API
+     *
+     * @example
+     * ```typescript
+     * const { result, performance } = logger.measureSync(
+     *   () => processData(),
+     *   "process-data"
+     * );
+     * ```
+     */
+    measureSync<T>(fn: () => T, label: string): {
+        result: T;
+        performance: {
+            duration: number;
+            memoryDelta: number;
+            cpuUsage?: number;
+        };
+    };
+    /**
+     * Flush all transports.
+     * @returns Promise that resolves when all transports are flushed
+     * @public API
+     */
+    flush(): Promise<void>;
+    /**
+     * Close all transports.
+     * @returns Promise that resolves when all transports are closed
+     * @public API
+     */
+    close(): Promise<void>;
+    /**
+     * Get current health status.
+     * @returns Current health status
+     * @public API
+     */
+    getHealth(): Promise<HealthStatus>;
+    /**
+     * Query logs from the in-memory buffer.
+     * @param options - Query options
+     * @returns Array of matching log entries
+     * @public API
+     */
+    queryLogs(options?: LogQueryOptions): Array<LogEntry>;
+    /**
+     * Create a chainable query builder for logs.
+     * @returns LogQuery instance
+     * @public API
+     */
+    query(): LogQuery;
+    /**
+     * Get all logs from the buffer.
+     * @returns Array of all log entries
+     * @public API
+     */
+    getAllLogs(): Array<LogEntry>;
+    /**
+     * Get statistics about logs in the buffer.
+     * @returns Log statistics
+     * @public API
+     */
+    getLogStats(): QueryStats;
+    /**
+     * Clear all logs from the query buffer.
+     * @public API
+     */
+    clearLogs(): void;
+    /**
+     * Export logs to markdown format.
+     * @param options - Export options
+     * @returns Markdown string
+     * @public API
+     */
+    exportLogsToMarkdown(options?: {
+        query?: LogQueryOptions;
+        title?: string;
+        includeStats?: boolean;
+        groupBy?: "level" | "context" | "none";
+    }): string;
+    /**
+     * Start health monitoring (if configured).
+     * @public API
+     */
+    startHealthMonitoring(): void;
+    /**
+     * Stop health monitoring.
+     * @public API
+     */
+    stopHealthMonitoring(): void;
+    /**
+     * Legacy formatMessage method for backward compatibility.
+     * @deprecated Use the new structured logging API instead
+     * @param logLevel - The level of the log
+     * @param message - The main log message
+     * @param module - Optional module name
+     * @returns The formatted log message
+     */
+    protected formatMessage(logLevel: LogLevelString | "NONE", message: string, module?: string): string;
+}
+export { Logger };