ntlogger 2.9.1 → 3.0.0

package/index.d.ts

@@ -3,214 +3,218 @@
  * @file index.d.ts
  */
 
-/**
- * Log levels supported by NightTimeLogger
- */
-export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'internal';
-
-/**
- * Sampling configuration for log levels
- */
-export interface SamplingConfig {
-    [level: string]: number; // 0.0 to 1.0, where 1.0 = log all, 0.1 = log 10%
-}
-
-/**
- * Rate limit configuration for a log level
- */
-export interface RateLimitConfig {
-    max: number;    // Maximum number of logs
-    window: number; // Time window in milliseconds
-}
-
-/**
- * Rate limiting configuration for log levels
- */
-export interface RateLimitConfigMap {
-    [level: string]: RateLimitConfig;
-}
-
-/**
- * Deduplication configuration
- */
-export interface DeduplicationConfig {
-    enabled: boolean;
-    threshold: number;  // Number of duplicates before squishing (default: 3)
-    window: number;     // Time window in milliseconds (default: 60000)
-}
-
-/**
- * Plugin configuration
- */
-export interface PluginConfig {
-    name: string;
-    enabled?: boolean;
-    config?: Record<string, any>;
-}
-
-/**
- * Logger configuration options
- */
-export interface LoggerConfig {
-    /** Minimum log level to be logged */
-    level?: LogLevel;
-    /** Enable console logging (default: true) */
-    console?: boolean;
-    /** Enable file logging (default: true) */
-    file?: boolean;
-    /** Filename for log file (default: `${location}.log`) */
-    filename?: string;
-    /** Directory path where log files will be saved (default: './logs') */
-    path?: string;
-    /** Maximum size of log file in bytes (default: 1048576 = 1MB) */
-    maxSize?: number;
-    /** Maximum number of log files to retain (default: 5) */
-    maxFiles?: number;
-    /** Include timestamp in log messages (default: true) */
-    timestamp?: boolean;
-    /** Skip cache and create new logger instance (default: false) */
-    skipCache?: boolean;
-    /** Enable call site path reporting (default: false) */
-    reportPath?: boolean;
-    /** Enable debug mode for logger itself (default: false) */
-    debug?: boolean;
-    /** Log sampling rates per level */
-    sampling?: SamplingConfig;
-    /** Rate limiting configuration per level */
-    rateLimit?: RateLimitConfigMap;
-    /** Log deduplication configuration */
-    deduplication?: DeduplicationConfig;
-    /** Enable performance metrics (default: NODE_ENV === 'development') */
-    performanceMetrics?: boolean;
-    /** Interval in milliseconds to log statistics (default: 0 = disabled) */
-    statsInterval?: number;
-    /** Plugin configurations */
-    plugins?: PluginConfig[];
-}
-
-/**
- * Statistics object returned by getStats()
- */
-export interface LoggerStats {
-    sampling: {
-        total: Record<string, number>;
-        sampled: Record<string, number>;
-        rateLimited: Record<string, number>;
-    } | null;
-    deduplication: {
-        totalDeduplicated: number;
-        uniqueMessages: number;
-        activeEntries: number;
-    } | null;
-    performance: {
-        enabled: boolean;
-        avgLogProcessingTime?: number;
-        avgTransportTime?: number;
-        logProcessingSamples?: number;
-        transportSamples?: number;
-    } | null;
-}
-
-/**
- * Logger instance interface
- */
-export interface Logger {
-    /**
-     * Log an informational message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
-     */
-    info(message: string, meta?: Record<string, any>): void;
-    info(message: Record<string, any>): void;
-
+declare namespace logger {
     /**
-     * Log a warning message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
+     * Log levels supported by NightTimeLogger
      */
-    warn(message: string, meta?: Record<string, any>): void;
-    warn(message: Record<string, any>): void;
+    export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'internal';
 
     /**
-     * Log an error message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
+     * Sampling configuration for log levels
      */
-    error(message: string, meta?: Record<string, any>): void;
-    error(message: Record<string, any>): void;
+    export interface SamplingConfig {
+        [level: string]: number; // 0.0 to 1.0, where 1.0 = log all, 0.1 = log 10%
+    }
 
     /**
-     * Log a debug message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
+     * Rate limit configuration for a log level
      */
-    debug(message: string, meta?: Record<string, any>): void;
-    debug(message: Record<string, any>): void;
+    export interface RateLimitConfig {
+        max: number;    // Maximum number of logs
+        window: number; // Time window in milliseconds
+    }
 
     /**
-     * Log a trace message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
+     * Rate limiting configuration for log levels
      */
-    trace(message: string, meta?: Record<string, any>): void;
-    trace(message: Record<string, any>): void;
+    export interface RateLimitConfigMap {
+        [level: string]: RateLimitConfig;
+    }
 
     /**
-     * Log a fatal message
-     * @param message - The message to log
-     * @param meta - Optional metadata object
+     * Deduplication configuration
      */
-    fatal(message: string, meta?: Record<string, any>): void;
-    fatal(message: Record<string, any>): void;
-
-    /**
-     * Log an internal message (logger system messages)
-     * @param message - The message to log
-     * @param meta - Optional metadata object
-     */
-    internal(message: string, meta?: Record<string, any>): void;
-    internal(message: Record<string, any>): void;
-
-    /**
-     * Create a child logger with persistent context
-     * @param context - Context object to merge into all logs
-     * @returns Child logger instance
-     */
-    child(context: Record<string, any>): Logger;
-
-    /**
-     * Start a performance timer (development mode only)
-     * @param label - Timer label
-     */
-    time?(label: string): void;
+    export interface DeduplicationConfig {
+        enabled: boolean;
+        threshold: number;  // Number of duplicates before squishing (default: 3)
+        window: number;     // Time window in milliseconds (default: 60000)
+    }
 
     /**
-     * End a performance timer and log duration (development mode only)
-     * @param label - Timer label
-     * @returns Duration in milliseconds or null if timer not found
+     * Plugin configuration
      */
-    timeEnd?(label: string): number | null;
+    export interface PluginConfig {
+        name: string;
+        enabled?: boolean;
+        config?: Record<string, any>;
+    }
 
     /**
-     * Get logging statistics
-     * @returns Statistics object
+     * Logger configuration options
      */
-    getStats(): LoggerStats;
+    export interface LoggerConfig {
+        /** Minimum log level to be logged */
+        level?: LogLevel;
+        /** Enable console logging (default: true) */
+        console?: boolean;
+        /** Enable file logging (default: true) */
+        file?: boolean;
+        /** Filename for combined log file (default: combined.log) */
+        filename?: string;
+        /** Directory path where log files will be saved (default: './logs') */
+        path?: string;
+        /** Maximum size of log file in bytes (default: 1048576 = 1MB) */
+        maxSize?: number;
+        /** Maximum number of log files to retain (default: 5) */
+        maxFiles?: number;
+        /** Include timestamp in log messages (default: true) */
+        timestamp?: boolean;
+        /** Skip cache and create new logger instance (default: false) */
+        skipCache?: boolean;
+        /** Enable call site path reporting (default: false) */
+        reportPath?: boolean;
+        /** Enable debug mode for logger itself (default: false) */
+        debug?: boolean;
+        /** Log sampling rates per level */
+        sampling?: SamplingConfig;
+        /** Rate limiting configuration per level */
+        rateLimit?: RateLimitConfigMap;
+        /** Log deduplication configuration */
+        deduplication?: DeduplicationConfig;
+        /** Enable performance metrics (default: NODE_ENV === 'development') */
+        performanceMetrics?: boolean;
+        /** Interval in milliseconds to log statistics (default: 0 = disabled) */
+        statsInterval?: number;
+        /** Maximum flush/stream shutdown wait in milliseconds (default: 30000). */
+        shutdownTimeout?: number;
+        /** Plugin configurations */
+        plugins?: PluginConfig[];
+    }
 
     /**
-     * Flush all pending logs (returns Promise)
-     * @returns Promise that resolves when all logs are flushed
+     * Statistics object returned by getStats()
      */
-    flush(): Promise<void>;
+    export interface LoggerStats {
+        sampling: {
+            total: Record<string, number>;
+            sampled: Record<string, number>;
+            rateLimited: Record<string, number>;
+        } | null;
+        deduplication: {
+            totalDeduplicated: number;
+            uniqueMessages: number;
+            activeEntries: number;
+        } | null;
+        performance: {
+            enabled: boolean;
+            avgLogProcessingTime?: number;
+            avgTransportTime?: number;
+            logProcessingSamples?: number;
+            transportSamples?: number;
+        } | null;
+    }
 
     /**
-     * Close the logger and flush all pending logs (returns Promise)
-     * @returns Promise that resolves when logger is closed
+     * Logger instance interface
      */
-    close(): Promise<void>;
-
-    /** Current log level */
-    level: string;
+    export interface Logger {
+        /**
+         * Log an informational message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        info(message: string, meta?: Record<string, any>): void;
+        info(message: Record<string, any>): void;
+
+        /**
+         * Log a warning message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        warn(message: string, meta?: Record<string, any>): void;
+        warn(message: Record<string, any>): void;
+
+        /**
+         * Log an error message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        error(message: string, meta?: Record<string, any>): void;
+        error(message: Record<string, any>): void;
+
+        /**
+         * Log a debug message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        debug(message: string, meta?: Record<string, any>): void;
+        debug(message: Record<string, any>): void;
+
+        /**
+         * Log a trace message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        trace(message: string, meta?: Record<string, any>): void;
+        trace(message: Record<string, any>): void;
+
+        /**
+         * Log a fatal message
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        fatal(message: string, meta?: Record<string, any>): void;
+        fatal(message: Record<string, any>): void;
+
+        /**
+         * Log an internal message (logger system messages)
+         * @param message - The message to log
+         * @param meta - Optional metadata object
+         */
+        internal(message: string, meta?: Record<string, any>): void;
+        internal(message: Record<string, any>): void;
+
+        /**
+         * Create a child logger with persistent context
+         * @param context - Context object to merge into all logs
+         * @returns Child logger instance
+         */
+        child(context: Record<string, any>): Logger;
+
+        /**
+         * Start a performance timer (development mode only)
+         * @param label - Timer label
+         */
+        time?(label: string): void;
+
+        /**
+         * End a performance timer and log duration (development mode only)
+         * @param label - Timer label
+         * @returns Duration in milliseconds or null if timer not found
+         */
+        timeEnd?(label: string): number | null;
+
+        /**
+         * Get logging statistics
+         * @returns Statistics object
+         */
+        getStats(): LoggerStats;
+
+        /**
+         * Flush all pending logs (returns Promise)
+         * @returns Promise that resolves when all logs are flushed
+         */
+        flush(): Promise<void>;
+
+        /**
+         * Close the logger and flush all pending logs (returns Promise)
+         * @returns Promise that resolves when logger is closed
+         */
+        close(): Promise<void>;
+
+        /** Current log level */
+        level: string;
+    }
 }
 
 /**
@@ -219,7 +223,12 @@ export interface Logger {
  * @param config - Configuration options for the logger
  * @returns Logger instance
  */
-declare function logger(location?: string, config?: LoggerConfig): Logger;
+declare function logger(location?: string, config?: logger.LoggerConfig): logger.Logger;
+
+declare namespace logger {
+    /** Opt in to process-wide signal handlers; returns an unregister function. */
+    function setupSignalHandlers(options?: { timeout?: number }): () => void;
+}
 
 export = logger;
 

package/lib/lifecycle.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const delay = () => new Promise(resolve => setTimeout(resolve, 1));
+
+function withTimeout(operation, timeout, label) {
+    let timer;
+    return Promise.race([
+        operation,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeout}ms`)), timeout);
+        }),
+    ]).finally(() => clearTimeout(timer));
+}
+
+// Winston uses readable-stream, so inspect both its buffers and file sinks.
+function busy(stream) {
+    return !!(stream && (stream._writableState?.length || stream._readableState?.length));
+}
+
+async function drain(logger, state, timeout = 5000) {
+    const deadline = Date.now() + timeout;
+    while (state.pending || busy(logger) || logger.transports.some(t =>
+        busy(t) || busy(t._stream) || busy(t._dest) || t._opening || t._rotate)) {
+        if (state.error) throw state.error;
+        if (Date.now() >= deadline) throw new Error('Logger drain timed out');
+        await delay();
+    }
+    if (state.error) throw state.error;
+}
+
+// Winston calls close on unpipe but doesn't await the result. Retain that promise.
+function trackClose(transport) {
+    if (transport._ntlClose) return;
+    const close = transport.close?.bind(transport);
+    let promise;
+    transport._ntlClose = () => {
+        if (!promise) {
+            // File._final already ended and drained this stream before unpipe.
+            // Calling File.close(callback) on that finished stream never calls back.
+            if (transport instanceof require('winston').transports.File && transport._stream?._writableState.finished) {
+                return (promise = Promise.resolve());
+            }
+            promise = close && close.length > 0
+                ? new Promise((resolve, reject) => close(err => err ? reject(err) : resolve()))
+                : Promise.resolve().then(() => close?.());
+            promise.catch(() => {}); // unpipe cannot consume a rejected promise
+        }
+        return promise;
+    };
+    transport.close = transport._ntlClose;
+}
+
+module.exports = { withTimeout, drain, trackClose };