@expressots/core 3.0.0 → 4.0.0-preview.1

package/lib/esm/types/provider/dto-validator/dto-validator.provider.d.ts

@@ -0,0 +1,10 @@
+import "reflect-metadata";
+import { RequestHandler } from "express";
+/**
+ * Validate the DTO using class-validator and class-transformer.
+ * @param type - The type of the DTO to validate.
+ * @returns A RequestHandler function.
+ * @throws An exception if the DTO is invalid.
+ * @public API
+ */
+export declare function ValidateDTO<T extends object>(type: new () => T): RequestHandler;

package/lib/esm/types/provider/dto-validator/package-resolver.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve package from the current working directory.
+ * @param packageName
+ * @param options
+ * @returns
+ */
+export declare function packageResolver(packageName: string, ...options: Array<any>): Promise<any>;

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

@@ -0,0 +1,7 @@
+export { IProvider, ProviderManager } from "./provider-manager.js";
+export * from "./logger/index.js";
+export { ValidateDTO } from "./dto-validator/dto-validator.provider.js";
+export * from "./db-in-memory/index.js";
+export * from "./validation/index.js";
+export { ProviderRegistry } from "./provider-registry.js";
+export { IHealthCheck, IMetrics, IConfigurable, HealthCheckResult, ProviderMetrics, ConfigurationResult, ProviderCapabilities, ProviderInfo, ProviderSource, HealthDashboard, MetricsDashboard, isHealthCheck, isMetrics, isConfigurable, } from "./provider.interface.js";

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

@@ -0,0 +1 @@
+export * from "./log-performance.decorator.js";

package/lib/esm/types/provider/logger/decorators/log-performance.decorator.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file log-performance.decorator.ts
+ * @description Decorator for automatic performance logging of methods
+ * @module @expressots/core/provider/logger/decorators
+ *
+ * Features:
+ * - Automatic method entry/exit logging
+ * - Execution time measurement
+ * - Works with sync and async methods
+ * - Includes class and method name in logs
+ */
+/**
+ * Options for @LogPerformance decorator.
+ * @public API
+ */
+export interface LogPerformanceOptions {
+    /** Log level for performance logs (default: "debug") */
+    logLevel?: "debug" | "info" | "warn";
+    /** Custom label (default: "ClassName.methodName") */
+    label?: string;
+    /** Log method entry (default: true) */
+    logEntry?: boolean;
+    /** Log method exit (default: true) */
+    logExit?: boolean;
+    /** Minimum duration to log (in ms, default: 0 = log all) */
+    minDuration?: number;
+}
+/**
+ * Decorator for automatically logging method performance.
+ * Logs method entry, exit, and execution time.
+ *
+ * @param options - Performance logging options
+ * @returns Method decorator
+ * @public API
+ *
+ * @example
+ * ```typescript
+ * class UserService {
+ *   constructor(private logger: Logger) {}
+ *
+ *   @LogPerformance({ logLevel: "info" })
+ *   async getUser(id: string) {
+ *     // Method execution is automatically timed and logged
+ *     return await this.db.findUser(id);
+ *   }
+ * }
+ * ```
+ */
+export declare function LogPerformance(options?: LogPerformanceOptions): (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor;

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

@@ -0,0 +1,17 @@
+export { Logger } from "./logger.provider.js";
+export * from "./utils/index.js";
+export * from "./transports/index.js";
+export * from "./logger.config.js";
+export * from "./logger.formatter.js";
+export * from "./logger.banner.js";
+export * from "./logger.metrics.js";
+export * from "./logger.metrics-collector.js";
+export * from "./logger.context.js";
+export * from "./logger.redaction.js";
+export * from "./logger.performance.js";
+export * from "./logger.grouping.js";
+export * from "./logger.flow.js";
+export * from "./logger.suggestions.js";
+export * from "./logger.health.js";
+export * from "./logger.query.js";
+export * from "./decorators/index.js";

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

@@ -0,0 +1,94 @@
+import { IConsoleMessage } from "@expressots/shared";
+import { ApplicationMetrics, FeaturesStatus, BannerConfig } from "./logger.metrics.js";
+import { MiddlewareCategory } from "../../middleware/middleware-service.js";
+/**
+ * Middleware view entry for banner display.
+ */
+export interface MiddlewareView {
+    entries: Array<{
+        name: string;
+        category: MiddlewareCategory;
+        type: "built-in" | "custom";
+    }>;
+    total: number;
+    remaining: number;
+}
+/**
+ * Provider view entry for banner display.
+ */
+export interface ProviderView {
+    entries: Array<{
+        name: string;
+        scope: string;
+        hasLifecycle: boolean;
+        hasHealthCheck: boolean;
+        hasMetrics: boolean;
+        /** Provider is an event handler */
+        isEventHandler?: boolean;
+        /** Provider is an interceptor */
+        isInterceptor?: boolean;
+        /** Provider is a lazy module */
+        isLazyModule?: boolean;
+    }>;
+    total: number;
+    remaining: number;
+}
+/**
+ * Extended banner data including middleware and provider info.
+ */
+export interface BannerData {
+    appInfo?: IConsoleMessage & {
+        apiVersions?: Array<string>;
+    };
+    metrics?: ApplicationMetrics;
+    features?: FeaturesStatus;
+    config?: Record<string, unknown>;
+    middlewareView?: MiddlewareView;
+    providerView?: ProviderView;
+}
+/**
+ * Generate startup banner.
+ * @public API
+ */
+export declare class BannerGenerator {
+    private startTime;
+    private config;
+    constructor(config?: BannerConfig);
+    /**
+     * Generate and display the banner.
+     * @param port - Server port
+     * @param environment - Server environment
+     * @param appInfo - Application info
+     * @param metrics - Application metrics
+     * @param features - Features status
+     * @param config - Runtime configuration
+     * @param bannerData - Extended banner data (middleware/provider views)
+     */
+    display(port: number, environment: string, appInfo?: IConsoleMessage, metrics?: ApplicationMetrics, features?: FeaturesStatus, config?: Record<string, unknown>, bannerData?: BannerData): void;
+    /**
+     * Display full banner with clean 3-column layout.
+     * Default shows: Banner, Server Status, Configuration, System Health, Performance
+     * Optional (user-enabled): Features, Middleware Pipeline, Provider Registry, Resources
+     */
+    private displayFullBanner;
+    /**
+     * Display compact banner.
+     */
+    private displayCompactBanner;
+    /**
+     * Display minimal banner.
+     */
+    private displayMinimalBanner;
+    /**
+     * Color environment based on type.
+     */
+    private colorEnvironment;
+    /**
+     * Get color for middleware category.
+     */
+    private getCategoryColor;
+    /**
+     * Get color for provider scope.
+     */
+    private getScopeColor;
+}

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

@@ -0,0 +1,55 @@
+import { LogLevel, LogLevelString } from "./utils/log-levels.js";
+import { ILogTransport } from "./transports/transport.interface.js";
+import { RedactionConfig } from "./logger.redaction.js";
+import { GroupingConfig } from "./logger.grouping.js";
+import { FlowConfig } from "./logger.flow.js";
+import { SuggestionsConfig } from "./logger.suggestions.js";
+import { HealthConfig } from "./logger.health.js";
+import { QueryConfig } from "./logger.query.js";
+/**
+ * Filter configuration for log filtering.
+ * @public API
+ */
+export interface FilterConfig {
+    /** Include only these contexts (empty = all) */
+    include?: Array<string>;
+    /** Exclude these contexts */
+    exclude?: Array<string>;
+    /** Minimum request duration to log (in ms) */
+    minDuration?: number;
+}
+/**
+ * Logger configuration interface.
+ * @public API
+ */
+export interface LoggerConfig {
+    /** Minimum log level to output */
+    level: LogLevel | LogLevelString;
+    /** Log transports to use */
+    transports: Array<ILogTransport>;
+    /** Filter configuration */
+    filters?: FilterConfig;
+    /** Enable structured logging (JSON in production) */
+    structured?: boolean;
+    /** Enable colors in output (default: true in dev, false in prod) */
+    colors?: boolean;
+    /** Pretty print output (default: true in dev, false in prod) */
+    pretty?: boolean;
+    /** Redaction configuration for sensitive data */
+    redaction?: Partial<RedactionConfig>;
+    /** Log grouping configuration for noise reduction */
+    grouping?: Partial<GroupingConfig>;
+    /** Flow tracking configuration for request visualization */
+    flow?: Partial<FlowConfig>;
+    /** Error suggestions configuration */
+    suggestions?: Partial<SuggestionsConfig>;
+    /** Health monitoring configuration */
+    health?: Partial<HealthConfig>;
+    /** Log query and export configuration */
+    query?: Partial<QueryConfig>;
+}
+/**
+ * Default logger configuration.
+ * @public API
+ */
+export declare function getDefaultLoggerConfig(): LoggerConfig;

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,44 @@
+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;
+}
+/**
+ * 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;