@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,334 @@
+/**
+ * @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
+ */
+import { AsyncLocalStorage } from "async_hooks";
+/**
+ * Default configuration for context detection.
+ */
+export function getDefaultContextDetectionConfig() {
+    return {
+        detectClassName: true,
+        detectMethodName: true,
+        maxStackDepth: 10,
+        skipPatterns: [
+            /node_modules/,
+            /^internal\//,
+            /^node:/,
+            /logger\.provider/,
+            /logger\.context/,
+        ],
+    };
+}
+/**
+ * AsyncLocalStorage for request-scoped context.
+ * This allows context to flow through async operations automatically.
+ */
+const contextStorage = new AsyncLocalStorage();
+/**
+ * Context manager for the logging system.
+ * Provides automatic context detection and management.
+ * @public API
+ */
+export class ContextManager {
+    static config = getDefaultContextDetectionConfig();
+    static globalContext = {};
+    /**
+     * Configure context detection behavior.
+     * @param config - Partial configuration to merge
+     */
+    static configure(config) {
+        ContextManager.config = {
+            ...ContextManager.config,
+            ...config,
+        };
+    }
+    /**
+     * Set global context that applies to all logs.
+     * @param context - Global context to set
+     */
+    static setGlobalContext(context) {
+        ContextManager.globalContext = { ...context };
+    }
+    /**
+     * Get the current global context.
+     */
+    static getGlobalContext() {
+        return { ...ContextManager.globalContext };
+    }
+    /**
+     * Get the current request-scoped context.
+     */
+    static getCurrentContext() {
+        return contextStorage.getStore();
+    }
+    /**
+     * 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(context, fn) {
+        return contextStorage.run(context, fn);
+    }
+    /**
+     * 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 async runWithContextAsync(context, fn) {
+        return contextStorage.run(context, fn);
+    }
+    /**
+     * 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, skipAutoDetect) {
+        const globalContext = ContextManager.globalContext;
+        const requestContext = contextStorage.getStore() || {};
+        const autoContext = skipAutoDetect
+            ? {}
+            : ContextManager.autoDetectContext();
+        return {
+            ...globalContext,
+            ...requestContext,
+            ...autoContext,
+            ...manualContext,
+        };
+    }
+    /**
+     * Automatically detect context from the call stack.
+     * @returns Detected context
+     */
+    static autoDetectContext() {
+        if (!ContextManager.config.detectClassName &&
+            !ContextManager.config.detectMethodName) {
+            return {};
+        }
+        const context = {};
+        const stack = ContextManager.getCallStack();
+        for (let i = 0; i < Math.min(stack.length, ContextManager.config.maxStackDepth); i++) {
+            const frame = stack[i];
+            // Skip frames matching skip patterns
+            if (ContextManager.config.skipPatterns.some((pattern) => pattern.test(frame.file || ""))) {
+                continue;
+            }
+            // Skip anonymous or native functions
+            if (!frame.functionName || frame.functionName === "anonymous") {
+                continue;
+            }
+            // Try to extract class and method names
+            const { className, methodName } = ContextManager.parseFrameName(frame.functionName);
+            if (ContextManager.config.detectClassName &&
+                className &&
+                !context.className) {
+                context.className = className;
+            }
+            if (ContextManager.config.detectMethodName &&
+                methodName &&
+                !context.methodName) {
+                context.methodName = methodName;
+            }
+            // Stop if we have both
+            if (context.className && context.methodName) {
+                break;
+            }
+        }
+        return context;
+    }
+    /**
+     * Parse a stack frame to extract the function/method name.
+     */
+    static getCallStack() {
+        const originalPrepareStackTrace = Error.prepareStackTrace;
+        const originalStackTraceLimit = Error.stackTraceLimit;
+        try {
+            Error.stackTraceLimit = ContextManager.config.maxStackDepth + 5;
+            const stack = [];
+            // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+            Error.prepareStackTrace = (_err, structuredStack) => {
+                for (const frame of structuredStack) {
+                    stack.push({
+                        functionName: frame.getFunctionName() || frame.getMethodName() || undefined,
+                        file: frame.getFileName() || undefined,
+                        line: frame.getLineNumber() || undefined,
+                        column: frame.getColumnNumber() || undefined,
+                    });
+                }
+                return "";
+            };
+            // Create and access error to populate stack
+            const err = new Error();
+            // Access .stack to trigger prepareStackTrace
+            void err.stack;
+            return stack;
+        }
+        finally {
+            Error.prepareStackTrace = originalPrepareStackTrace;
+            Error.stackTraceLimit = originalStackTraceLimit;
+        }
+    }
+    /**
+     * Parse a function name to extract class and method names.
+     * Handles patterns like:
+     * - "ClassName.methodName"
+     * - "ClassName.prototype.methodName"
+     * - "methodName" (standalone function)
+     */
+    static parseFrameName(name) {
+        if (!name) {
+            return {};
+        }
+        // Handle "ClassName.prototype.methodName" or "ClassName.methodName"
+        const prototypeMatch = name.match(/^(\w+)(?:\.prototype)?\.(\w+)$/);
+        if (prototypeMatch) {
+            return {
+                className: prototypeMatch[1],
+                methodName: prototypeMatch[2],
+            };
+        }
+        // Handle "new ClassName" (constructor)
+        const constructorMatch = name.match(/^new (\w+)$/);
+        if (constructorMatch) {
+            return {
+                className: constructorMatch[1],
+                methodName: "constructor",
+            };
+        }
+        // Handle simple function name
+        const simpleMatch = name.match(/^(\w+)$/);
+        if (simpleMatch) {
+            return {
+                methodName: simpleMatch[1],
+            };
+        }
+        return {};
+    }
+    /**
+     * Create HTTP context from an Express request.
+     * @param req - Express request object
+     * @param options - Optional header configuration
+     * @returns HTTP context
+     */
+    static createHttpContext(req, options) {
+        const requestIdHeader = options?.requestIdHeader || "x-request-id";
+        const correlationIdHeader = options?.correlationIdHeader || "x-correlation-id";
+        // Generate or get request ID from configured header
+        const requestId = req.headers?.[requestIdHeader.toLowerCase()] ||
+            ContextManager.generateRequestId();
+        // Get correlation ID from configured header (defaults to request ID if not present)
+        const correlationId = req.headers?.[correlationIdHeader.toLowerCase()] || requestId;
+        return {
+            requestId,
+            correlationId,
+            method: req.method || "UNKNOWN",
+            path: req.path || req.url || "/",
+            ip: req.ip || req.headers?.["x-forwarded-for"] || undefined,
+            userAgent: req.headers?.["user-agent"],
+            userId: req.user?.id || req.user?.sub || undefined,
+            tenantId: req.headers?.["x-tenant-id"] || undefined,
+            startTime: Date.now(),
+            headers: ContextManager.extractSafeHeaders(req.headers),
+        };
+    }
+    /**
+     * Generate a unique request ID.
+     * Uses a combination of timestamp and random string.
+     */
+    static generateRequestId() {
+        const timestamp = Date.now().toString(36);
+        const random = Math.random().toString(36).slice(2, 10);
+        return `req_${timestamp}_${random}`;
+    }
+    /**
+     * Extract safe headers (exclude sensitive ones).
+     */
+    static extractSafeHeaders(headers) {
+        if (!headers)
+            return undefined;
+        const sensitiveHeaders = [
+            "authorization",
+            "cookie",
+            "x-api-key",
+            "x-auth-token",
+            "x-csrf-token",
+        ];
+        const safeHeaders = {};
+        for (const [key, value] of Object.entries(headers)) {
+            if (!sensitiveHeaders.includes(key.toLowerCase()) &&
+                value !== undefined) {
+                safeHeaders[key] = Array.isArray(value) ? value.join(", ") : value;
+            }
+        }
+        return Object.keys(safeHeaders).length > 0 ? safeHeaders : undefined;
+    }
+    /**
+     * Format context for display (e.g., "[ClassName.methodName]").
+     * @param context - Context to format
+     * @returns Formatted string
+     */
+    static formatContext(context) {
+        const parts = [];
+        if (context.className && context.methodName) {
+            parts.push(`${context.className}.${context.methodName}`);
+        }
+        else if (context.className) {
+            parts.push(context.className);
+        }
+        else if (context.methodName) {
+            parts.push(context.methodName);
+        }
+        else if (context.label) {
+            parts.push(context.label);
+        }
+        if (context.requestId) {
+            parts.push(`req:${context.requestId.slice(0, 8)}`);
+        }
+        return parts.length > 0 ? `[${parts.join(" | ")}]` : "";
+    }
+}
+/**
+ * Decorator for automatically setting context on a class.
+ * @param contextName - Context name to use (defaults to class name)
+ * @returns Class decorator
+ */
+export function LogContext(contextName) {
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    return function (target) {
+        // Store context name as metadata
+        Reflect.defineMetadata("log:context", contextName || target.name, target);
+    };
+}
+/**
+ * Decorator for automatically setting context on a method.
+ * @param contextName - Context name to use (defaults to method name)
+ * @returns Method decorator
+ */
+export function LogMethod(contextName) {
+    // eslint-disable-next-line @typescript-eslint/ban-types, @typescript-eslint/explicit-function-return-type
+    return function (_target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        const methodName = contextName || String(propertyKey);
+        // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+        descriptor.value = function (...args) {
+            const className = Reflect.getMetadata("log:context", this.constructor) ||
+                this.constructor.name;
+            return ContextManager.runWithContext({
+                className,
+                methodName,
+            }, () => originalMethod.apply(this, args));
+        };
+        return descriptor;
+    };
+}

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

@@ -0,0 +1,248 @@
+/**
+ * @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
+ */
+/**
+ * Default flow configuration.
+ */
+export function getDefaultFlowConfig() {
+    const isDevelopment = process.env.NODE_ENV !== "production";
+    return {
+        enabled: isDevelopment, // Enabled in dev, disabled in prod by default
+        showVisualization: isDevelopment,
+        trackMemory: true,
+        trackNested: true,
+    };
+}
+/**
+ * Flow tracker for a single request.
+ * Tracks the complete lifecycle of a request through the application.
+ * @public API
+ */
+export class FlowTracker {
+    flow;
+    currentStep = null;
+    stepStack = [];
+    config;
+    startMemory;
+    /**
+     * Create a new flow tracker for a request.
+     */
+    constructor(requestId, method, path, config) {
+        this.config = { ...getDefaultFlowConfig(), ...config };
+        this.startMemory = process.memoryUsage().heapUsed;
+        const startTime = performance.now();
+        this.flow = {
+            requestId,
+            method,
+            path,
+            startTime,
+            endTime: startTime,
+            totalDuration: 0,
+            steps: [],
+            memoryDelta: 0,
+        };
+    }
+    /**
+     * Start tracking a new step.
+     */
+    startStep(type, name, metadata) {
+        if (!this.config.enabled) {
+            return;
+        }
+        const startTime = performance.now();
+        const step = {
+            type,
+            name,
+            duration: 0,
+            status: "success",
+            metadata,
+            children: this.config.trackNested ? [] : undefined,
+            startTime,
+            endTime: startTime,
+        };
+        if (this.currentStep && this.config.trackNested) {
+            // Add as child of current step
+            if (!this.currentStep.children) {
+                this.currentStep.children = [];
+            }
+            this.currentStep.children.push(step);
+            this.stepStack.push(this.currentStep);
+        }
+        else {
+            // Add as top-level step
+            this.flow.steps.push(step);
+        }
+        this.currentStep = step;
+    }
+    /**
+     * End the current step.
+     */
+    endStep(status = "success", error) {
+        if (!this.config.enabled || !this.currentStep) {
+            return;
+        }
+        const endTime = performance.now();
+        this.currentStep.endTime = endTime;
+        this.currentStep.duration = endTime - this.currentStep.startTime;
+        this.currentStep.status = status;
+        if (error && this.currentStep.metadata) {
+            this.currentStep.metadata.error = {
+                message: error.message,
+                name: error.name,
+                stack: error.stack,
+            };
+        }
+        // Pop from stack if we have nested steps
+        if (this.stepStack.length > 0) {
+            this.currentStep = this.stepStack.pop() || null;
+        }
+        else {
+            this.currentStep = null;
+        }
+    }
+    /**
+     * Mark current step as skipped.
+     */
+    skipStep() {
+        this.endStep("skipped");
+    }
+    /**
+     * Mark current step as failed.
+     */
+    failStep(error) {
+        this.endStep("failure", error);
+    }
+    /**
+     * Finalize the flow and return the complete flow data.
+     */
+    finalize(statusCode, error) {
+        if (!this.config.enabled) {
+            return this.flow;
+        }
+        // End any remaining steps
+        while (this.currentStep) {
+            this.endStep("success");
+        }
+        const endTime = performance.now();
+        this.flow.endTime = endTime;
+        this.flow.totalDuration = endTime - this.flow.startTime;
+        if (this.config.trackMemory) {
+            const endMemory = process.memoryUsage().heapUsed;
+            this.flow.memoryDelta = endMemory - this.startMemory;
+        }
+        if (statusCode !== undefined) {
+            this.flow.statusCode = statusCode;
+        }
+        if (error) {
+            this.flow.error = {
+                message: error.message,
+                name: error.name,
+                stack: error.stack,
+            };
+        }
+        return this.flow;
+    }
+    /**
+     * Get the current flow data (without finalizing).
+     */
+    getFlow() {
+        return this.flow;
+    }
+    /**
+     * Check if flow tracking is enabled.
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Check if visualization should be shown.
+     */
+    shouldShowVisualization() {
+        if (!this.config.enabled || !this.config.showVisualization) {
+            return false;
+        }
+        // Check min duration threshold
+        if (this.config.minDuration !== undefined) {
+            const currentDuration = performance.now() - this.flow.startTime;
+            return currentDuration >= this.config.minDuration;
+        }
+        return true;
+    }
+}
+/**
+ * Flow tracker storage using AsyncLocalStorage for request-scoped tracking.
+ */
+class FlowTrackerStorage {
+    storage = new Map();
+    /**
+     * Store a flow tracker for a request.
+     */
+    set(requestId, tracker) {
+        this.storage.set(requestId, tracker);
+    }
+    /**
+     * Get a flow tracker for a request.
+     */
+    get(requestId) {
+        return this.storage.get(requestId);
+    }
+    /**
+     * Remove a flow tracker (cleanup).
+     */
+    remove(requestId) {
+        this.storage.delete(requestId);
+    }
+    /**
+     * Clear all trackers (for testing/cleanup).
+     */
+    clear() {
+        this.storage.clear();
+    }
+}
+/**
+ * Global flow tracker storage instance.
+ */
+const flowTrackerStorage = new FlowTrackerStorage();
+/**
+ * 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 function getFlowTracker(requestId, method, path, config) {
+    let tracker = flowTrackerStorage.get(requestId);
+    if (!tracker) {
+        tracker = new FlowTracker(requestId, method, path, config);
+        flowTrackerStorage.set(requestId, tracker);
+    }
+    return tracker;
+}
+/**
+ * Get existing flow tracker for a request.
+ * @param requestId - Request identifier
+ * @returns FlowTracker instance or undefined
+ * @public API
+ */
+export function findFlowTracker(requestId) {
+    return flowTrackerStorage.get(requestId);
+}
+/**
+ * Remove flow tracker (cleanup after request completes).
+ * @param requestId - Request identifier
+ * @public API
+ */
+export function removeFlowTracker(requestId) {
+    flowTrackerStorage.remove(requestId);
+}