@expressots/core 3.0.0 → 4.0.0-preview.1

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

@@ -0,0 +1,332 @@
+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 (TRACE, DEBUG, INFO, WARN, ERROR, FATAL)
+ * - 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;
+    name: string;
+    version: string;
+    author: string;
+    repo: string;
+    constructor();
+    /**
+     * 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 };

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

@@ -0,0 +1,232 @@
+import { LogEntry } from "./utils/log-entry.js";
+import { LogLevel } from "./utils/log-levels.js";
+/**
+ * Configuration for log query and export features.
+ * @public API
+ */
+export interface QueryConfig {
+    /** Enable in-memory log buffer (default: true in dev, false in prod) */
+    enabled?: boolean;
+    /** Maximum number of logs to keep in buffer (default: 1000) */
+    bufferSize?: number;
+    /** Enable markdown export (default: true) */
+    enableExport?: boolean;
+}
+/**
+ * Log query options for filtering logs.
+ * @public API
+ */
+export interface LogQueryOptions {
+    /** Filter by log level */
+    level?: LogLevel | Array<LogLevel>;
+    /** Filter by context (exact match or regex) */
+    context?: string | RegExp;
+    /** Start time (timestamp or Date) */
+    startTime?: number | Date;
+    /** End time (timestamp or Date) */
+    endTime?: number | Date;
+    /** Search term (searches message and data) */
+    search?: string;
+    /** Regex pattern for message matching */
+    messageRegex?: RegExp | string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Sort order: 'asc' (oldest first) or 'desc' (newest first, default) */
+    sort?: "asc" | "desc";
+}
+/**
+ * Log query builder for chainable queries.
+ * @public API
+ */
+export declare class LogQuery {
+    private entries;
+    private results;
+    constructor(entries: Array<LogEntry>);
+    /**
+     * Filter by log level(s).
+     * @param level - Single level or array of levels
+     * @returns Query builder instance
+     * @public API
+     */
+    level(level: LogLevel | Array<LogLevel>): LogQuery;
+    /**
+     * Filter by context (exact match or regex).
+     * @param context - Context string or regex pattern
+     * @returns Query builder instance
+     * @public API
+     */
+    context(context: string | RegExp): LogQuery;
+    /**
+     * Filter by time range.
+     * @param start - Start time (timestamp or Date)
+     * @param end - End time (timestamp or Date)
+     * @returns Query builder instance
+     * @public API
+     */
+    timeRange(start?: number | Date, end?: number | Date): LogQuery;
+    /**
+     * Search in message and data fields.
+     * @param term - Search term (case-insensitive)
+     * @returns Query builder instance
+     * @public API
+     */
+    search(term: string): LogQuery;
+    /**
+     * Filter by regex pattern on message.
+     * @param pattern - Regex pattern (string or RegExp)
+     * @returns Query builder instance
+     * @public API
+     */
+    messageRegex(pattern: RegExp | string): LogQuery;
+    /**
+     * Limit the number of results.
+     * @param limit - Maximum number of results
+     * @returns Query builder instance
+     * @public API
+     */
+    limit(limit: number): LogQuery;
+    /**
+     * Sort results by timestamp.
+     * @param order - Sort order: 'asc' (oldest first) or 'desc' (newest first)
+     * @returns Query builder instance
+     * @public API
+     */
+    sort(order?: "asc" | "desc"): LogQuery;
+    /**
+     * Execute the query and return results.
+     * @returns Array of log entries matching the query
+     * @public API
+     */
+    execute(): Array<LogEntry>;
+    /**
+     * Get the count of matching results.
+     * @returns Number of matching entries
+     * @public API
+     */
+    count(): number;
+    /**
+     * Get statistics about the query results.
+     * @returns Query statistics
+     * @public API
+     */
+    stats(): QueryStats;
+}
+/**
+ * Query statistics.
+ * @public API
+ */
+export interface QueryStats {
+    total: number;
+    byLevel: Record<string, number>;
+    byContext: Record<string, number>;
+    oldest: number | null;
+    newest: number | null;
+}
+/**
+ * Circular buffer for storing log entries in memory.
+ * Thread-safe for single-threaded Node.js (no concurrent access needed).
+ * @public API
+ */
+export declare class LogBuffer {
+    private buffer;
+    private maxSize;
+    private writeIndex;
+    constructor(maxSize?: number);
+    /**
+     * Add a log entry to the buffer.
+     * Uses circular buffer logic for efficient memory usage.
+     * @param entry - Log entry to add
+     */
+    add(entry: LogEntry): void;
+    /**
+     * Query logs with options.
+     * @param options - Query options
+     * @returns Array of matching log entries
+     */
+    query(options?: LogQueryOptions): Array<LogEntry>;
+    /**
+     * Create a chainable query builder.
+     * @returns LogQuery instance
+     */
+    createQuery(): LogQuery;
+    /**
+     * Get all logs in the buffer.
+     * @returns Array of all log entries in chronological order (oldest first)
+     */
+    getAll(): Array<LogEntry>;
+    /**
+     * Clear all logs from the buffer.
+     */
+    clear(): void;
+    /**
+     * Get statistics about the buffer.
+     * @returns Buffer statistics
+     */
+    getStats(): QueryStats;
+    /**
+     * Get the current buffer size.
+     * @returns Number of entries in buffer
+     */
+    size(): number;
+}
+/**
+ * Log query manager for managing in-memory log buffer and queries.
+ * @public API
+ */
+export declare class LogQueryManager {
+    private buffer;
+    private config;
+    constructor(config?: Partial<QueryConfig>);
+    /**
+     * Add a log entry to the buffer (if enabled).
+     * @param entry - Log entry to add
+     */
+    addEntry(entry: LogEntry): void;
+    /**
+     * Query logs with options.
+     * @param options - Query options
+     * @returns Array of matching log entries
+     */
+    query(options?: LogQueryOptions): Array<LogEntry>;
+    /**
+     * Create a chainable query builder.
+     * @returns LogQuery instance
+     */
+    createQuery(): LogQuery;
+    /**
+     * Get all logs in the buffer.
+     * @returns Array of all log entries
+     */
+    getAll(): Array<LogEntry>;
+    /**
+     * Clear all logs from the buffer.
+     */
+    clear(): void;
+    /**
+     * Get statistics about the buffer.
+     * @returns Buffer statistics
+     */
+    getStats(): QueryStats;
+    /**
+     * Check if query features are enabled.
+     * @returns True if enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Configure the query manager.
+     * @param config - Partial configuration
+     */
+    configure(config: Partial<QueryConfig>): void;
+}
+/**
+ * Export logs to markdown format.
+ * @param entries - Log entries to export
+ * @param options - Export options
+ * @returns Markdown string
+ * @public API
+ */
+export declare function exportToMarkdown(entries: Array<LogEntry>, options?: {
+    title?: string;
+    includeStats?: boolean;
+    groupBy?: "level" | "context" | "none";
+}): string;