@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,189 @@
+/**
+ * @file logger.context.ts
+ * @description Context management for structured logging with automatic detection
+ * @module @expressots/core/provider/logger
+ *
+ * Provides:
+ * - Automatic class/method detection from call stack
+ * - HTTP request context enrichment
+ * - Child logger creation with inherited context
+ * - Thread-safe context storage using AsyncLocalStorage
+ */
+/**
+ * Represents the context for a single log entry.
+ * @public API
+ */
+export interface LogContext {
+    /** Class name (auto-detected or manual) */
+    className?: string;
+    /** Method name (auto-detected or manual) */
+    methodName?: string;
+    /** Custom context label */
+    label?: string;
+    /** Request ID for HTTP requests */
+    requestId?: string;
+    /** User identifier (if authenticated) */
+    userId?: string;
+    /** Tenant identifier (for multi-tenant apps) */
+    tenantId?: string;
+    /** Correlation ID for distributed tracing */
+    correlationId?: string;
+    /** Parent span ID for tracing */
+    parentSpanId?: string;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * HTTP-specific context for request logging.
+ * @public API
+ */
+export interface HttpContext {
+    /** Request ID (generated or from header) */
+    requestId: string;
+    /** Correlation ID for distributed tracing (defaults to requestId if not provided) */
+    correlationId?: string;
+    /** HTTP method (GET, POST, etc.) */
+    method: string;
+    /** Request path */
+    path: string;
+    /** Client IP address */
+    ip?: string;
+    /** User agent string */
+    userAgent?: string;
+    /** User identifier */
+    userId?: string;
+    /** Tenant identifier */
+    tenantId?: string;
+    /** Request start time (for duration calculation) */
+    startTime: number;
+    /** Request headers (selected) */
+    headers?: Record<string, string>;
+}
+/**
+ * Configuration for automatic context detection.
+ * @public API
+ */
+export interface ContextDetectionConfig {
+    /** Enable automatic class name detection */
+    detectClassName: boolean;
+    /** Enable automatic method name detection */
+    detectMethodName: boolean;
+    /** Maximum stack depth to search */
+    maxStackDepth: number;
+    /** Patterns to skip in stack trace (e.g., node_modules) */
+    skipPatterns: Array<RegExp>;
+}
+/**
+ * Default configuration for context detection.
+ */
+export declare function getDefaultContextDetectionConfig(): ContextDetectionConfig;
+/**
+ * Context manager for the logging system.
+ * Provides automatic context detection and management.
+ * @public API
+ */
+export declare class ContextManager {
+    private static config;
+    private static globalContext;
+    /**
+     * Configure context detection behavior.
+     * @param config - Partial configuration to merge
+     */
+    static configure(config: Partial<ContextDetectionConfig>): void;
+    /**
+     * Set global context that applies to all logs.
+     * @param context - Global context to set
+     */
+    static setGlobalContext(context: LogContext): void;
+    /**
+     * Get the current global context.
+     */
+    static getGlobalContext(): LogContext;
+    /**
+     * Get the current request-scoped context.
+     */
+    static getCurrentContext(): LogContext | undefined;
+    /**
+     * Run a function with a specific context.
+     * The context will be available to all async operations within the function.
+     * @param context - Context to use
+     * @param fn - Function to run
+     * @returns Result of the function
+     */
+    static runWithContext<T>(context: LogContext, fn: () => T): T;
+    /**
+     * Run an async function with a specific context.
+     * @param context - Context to use
+     * @param fn - Async function to run
+     * @returns Promise with result of the function
+     */
+    static runWithContextAsync<T>(context: LogContext, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get the merged context (global + request-scoped + auto-detected).
+     * @param manualContext - Optional manual context to include
+     * @param skipAutoDetect - Skip automatic detection (for performance)
+     * @returns Merged context
+     */
+    static getContext(manualContext?: Partial<LogContext>, skipAutoDetect?: boolean): LogContext;
+    /**
+     * Automatically detect context from the call stack.
+     * @returns Detected context
+     */
+    static autoDetectContext(): Partial<LogContext>;
+    /**
+     * Parse a stack frame to extract the function/method name.
+     */
+    private static getCallStack;
+    /**
+     * Parse a function name to extract class and method names.
+     * Handles patterns like:
+     * - "ClassName.methodName"
+     * - "ClassName.prototype.methodName"
+     * - "methodName" (standalone function)
+     */
+    private static parseFrameName;
+    /**
+     * Create HTTP context from an Express request.
+     * @param req - Express request object
+     * @param options - Optional header configuration
+     * @returns HTTP context
+     */
+    static createHttpContext(req: {
+        method?: string;
+        path?: string;
+        url?: string;
+        ip?: string;
+        headers?: Record<string, string | Array<string> | undefined>;
+        user?: any;
+    }, options?: {
+        requestIdHeader?: string;
+        correlationIdHeader?: string;
+    }): HttpContext;
+    /**
+     * Generate a unique request ID.
+     * Uses a combination of timestamp and random string.
+     */
+    static generateRequestId(): string;
+    /**
+     * Extract safe headers (exclude sensitive ones).
+     */
+    private static extractSafeHeaders;
+    /**
+     * Format context for display (e.g., "[ClassName.methodName]").
+     * @param context - Context to format
+     * @returns Formatted string
+     */
+    static formatContext(context: LogContext): string;
+}
+/**
+ * Decorator for automatically setting context on a class.
+ * @param contextName - Context name to use (defaults to class name)
+ * @returns Class decorator
+ */
+export declare function LogContext(contextName?: string): ClassDecorator;
+/**
+ * Decorator for automatically setting context on a method.
+ * @param contextName - Context name to use (defaults to method name)
+ * @returns Method decorator
+ */
+export declare function LogMethod(contextName?: string): MethodDecorator;

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

@@ -0,0 +1,165 @@
+/**
+ * @file logger.flow.ts
+ * @description Request flow tracking and visualization system
+ * @module @expressots/core
+ *
+ * Features:
+ * - Track request flow through middleware, guards, controllers
+ * - Structured JSON data for web UI consumption
+ * - ASCII visualization for console display
+ * - Timing data for each step
+ * - Memory tracking
+ */
+/**
+ * Type of flow step.
+ * @public API
+ */
+export type FlowStepType = "middleware" | "guard" | "validation" | "controller" | "use-case" | "exception-filter" | "response";
+/**
+ * Status of a flow step.
+ * @public API
+ */
+export type FlowStepStatus = "success" | "failure" | "skipped";
+/**
+ * A single step in the request flow.
+ * @public API
+ */
+export interface FlowStep {
+    /** Type of step */
+    type: FlowStepType;
+    /** Name/identifier of the step */
+    name: string;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Status of the step */
+    status: FlowStepStatus;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Nested child steps (for complex flows) */
+    children?: Array<FlowStep>;
+    /** Start time (high-resolution timestamp) */
+    startTime: number;
+    /** End time (high-resolution timestamp) */
+    endTime: number;
+}
+/**
+ * Complete request flow data.
+ * @public API
+ */
+export interface RequestFlow {
+    /** Unique request identifier */
+    requestId: string;
+    /** HTTP method */
+    method: string;
+    /** HTTP path */
+    path: string;
+    /** Request start time (high-resolution timestamp) */
+    startTime: number;
+    /** Request end time (high-resolution timestamp) */
+    endTime: number;
+    /** Total duration in milliseconds */
+    totalDuration: number;
+    /** Flow steps */
+    steps: Array<FlowStep>;
+    /** Memory delta in bytes */
+    memoryDelta: number;
+    /** HTTP status code */
+    statusCode?: number;
+    /** Error if request failed */
+    error?: {
+        message: string;
+        stack?: string;
+        name?: string;
+    };
+}
+/**
+ * Configuration for flow tracking.
+ * @public API
+ */
+export interface FlowConfig {
+    /** Enable flow tracking */
+    enabled: boolean;
+    /** Show flow visualization in console (dev mode) */
+    showVisualization: boolean;
+    /** Minimum duration to show flow (ms) - only show slow requests */
+    minDuration?: number;
+    /** Track memory usage */
+    trackMemory: boolean;
+    /** Track nested steps */
+    trackNested: boolean;
+}
+/**
+ * Default flow configuration.
+ */
+export declare function getDefaultFlowConfig(): FlowConfig;
+/**
+ * Flow tracker for a single request.
+ * Tracks the complete lifecycle of a request through the application.
+ * @public API
+ */
+export declare class FlowTracker {
+    private flow;
+    private currentStep;
+    private stepStack;
+    private config;
+    private startMemory;
+    /**
+     * Create a new flow tracker for a request.
+     */
+    constructor(requestId: string, method: string, path: string, config?: Partial<FlowConfig>);
+    /**
+     * Start tracking a new step.
+     */
+    startStep(type: FlowStepType, name: string, metadata?: Record<string, unknown>): void;
+    /**
+     * End the current step.
+     */
+    endStep(status?: FlowStepStatus, error?: Error): void;
+    /**
+     * Mark current step as skipped.
+     */
+    skipStep(): void;
+    /**
+     * Mark current step as failed.
+     */
+    failStep(error?: Error): void;
+    /**
+     * Finalize the flow and return the complete flow data.
+     */
+    finalize(statusCode?: number, error?: Error): RequestFlow;
+    /**
+     * Get the current flow data (without finalizing).
+     */
+    getFlow(): RequestFlow;
+    /**
+     * Check if flow tracking is enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Check if visualization should be shown.
+     */
+    shouldShowVisualization(): boolean;
+}
+/**
+ * Get or create a flow tracker for a request.
+ * @param requestId - Request identifier
+ * @param method - HTTP method
+ * @param path - HTTP path
+ * @param config - Flow configuration
+ * @returns FlowTracker instance
+ * @public API
+ */
+export declare function getFlowTracker(requestId: string, method: string, path: string, config?: Partial<FlowConfig>): FlowTracker;
+/**
+ * Get existing flow tracker for a request.
+ * @param requestId - Request identifier
+ * @returns FlowTracker instance or undefined
+ * @public API
+ */
+export declare function findFlowTracker(requestId: string): FlowTracker | undefined;
+/**
+ * Remove flow tracker (cleanup after request completes).
+ * @param requestId - Request identifier
+ * @public API
+ */
+export declare function removeFlowTracker(requestId: string): void;

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

@@ -0,0 +1,54 @@
+import { LogEntry } from "./utils/log-entry.js";
+import { Redactor } from "./logger.redaction.js";
+import { GroupedLogEntry } from "./logger.grouping.js";
+/**
+ * Options for log formatting.
+ */
+export interface FormatOptions {
+    /** Enable redaction of sensitive data */
+    redact?: boolean;
+    /** Custom redactor instance (uses global if not provided) */
+    redactor?: Redactor;
+    /**
+     * Emit ANSI color escape codes. When false, the formatted output is
+     * post-processed to strip every ANSI escape. Defaults to true (colored).
+     *
+     * Disable this for non-TTY consumers like cloud log viewers (Azure
+     * App Service, AWS CloudWatch, Heroku, Kubernetes, etc.) and Studio's
+     * Live Logs panel, all of which display the raw text without
+     * interpreting terminal escape sequences.
+     */
+    colors?: boolean;
+}
+/**
+ * Format log entry for development (human-readable, colored).
+ * @param entry - Log entry to format
+ * @param options - Formatting options (redaction, etc.)
+ * @returns Formatted string
+ * @public API
+ */
+export declare function formatDev(entry: LogEntry, options?: FormatOptions): string;
+/**
+ * Format log entry for production (JSON structured).
+ * @param entry - Log entry to format
+ * @param options - Formatting options (redaction, etc.)
+ * @returns JSON string
+ * @public API
+ */
+export declare function formatProd(entry: LogEntry, options?: FormatOptions): string;
+/**
+ * Format a grouped log entry for development output.
+ * @param groupedEntry - Grouped log entry
+ * @param options - Formatting options
+ * @returns Formatted string
+ * @public API
+ */
+export declare function formatGroupedDev(groupedEntry: GroupedLogEntry, options?: FormatOptions): string;
+/**
+ * Format a grouped log entry for production (JSON).
+ * @param groupedEntry - Grouped log entry
+ * @param options - Formatting options
+ * @returns JSON string
+ * @public API
+ */
+export declare function formatGroupedProd(groupedEntry: GroupedLogEntry, options?: FormatOptions): string;

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