@wgtechlabs/log-engine 1.0.2 → 1.2.0

package/README.md

@@ -19,7 +19,7 @@ Log Engine transforms your development experience from chaotic debugging session
 - **Lightweight & Fast**: Minimal overhead with maximum performance - designed to enhance your application, not slow it down.
 - **No Learning Curve**: Dead simple API that you can master in seconds. No extensive documentation, complex configurations, or setup required - Log Engine works instantly.
 - **Colorized Console Output**: Beautiful ANSI color-coded log levels with intelligent terminal formatting - instantly identify message severity at a glance with color-coded output.
-- **Multiple Log Levels**: Support for DEBUG, INFO, WARN, ERROR, and SILENT levels with smart filtering - just set your level and let it handle the rest.
+- **Multiple Log Modes**: Support for DEBUG, INFO, WARN, ERROR, SILENT, OFF, and special LOG levels with smart filtering - just set your mode and let it handle the rest.
 - **Auto-Configuration**: Intelligent environment-based setup using NODE_ENV variables. No config files, initialization scripts, or manual setup - Log Engine works perfectly out of the box.
 - **Enhanced Formatting**: Structured log entries with dual timestamps (ISO + human-readable) and colored level indicators for maximum readability.
 - **TypeScript Ready**: Full TypeScript support with comprehensive type definitions for a seamless development experience.
@@ -70,38 +70,84 @@ yarn add @wgtechlabs/log-engine
 ### Quick Start
 
 ```typescript
-import { LogEngine, LogLevel } from '@wgtechlabs/log-engine';
+import { LogEngine, LogMode } from '@wgtechlabs/log-engine';
 
 // Basic usage with auto-configuration based on NODE_ENV
 LogEngine.debug('This is a debug message');
 LogEngine.info('This is an info message');
 LogEngine.warn('This is a warning message');
 LogEngine.error('This is an error message');
+LogEngine.log('This is a critical message that always shows');
 ```
 
-### Custom Configuration
+### Mode-Based Configuration (Recommended)
+
+Log Engine now uses a modern **LogMode** system that separates message severity from output control:
 
 ```typescript
-import { LogEngine, LogLevel } from '@wgtechlabs/log-engine';
+import { LogEngine, LogMode } from '@wgtechlabs/log-engine';
 
-// Configure based on your custom environment variable
-const env = process.env.APP_ENV || 'development';
+// Configure using LogMode (recommended approach)
+LogEngine.configure({ mode: LogMode.DEBUG });  // Most verbose
+LogEngine.configure({ mode: LogMode.INFO });   // Balanced
+LogEngine.configure({ mode: LogMode.WARN });   // Focused  
+LogEngine.configure({ mode: LogMode.ERROR });  // Minimal
+LogEngine.configure({ mode: LogMode.SILENT }); // Critical only
+LogEngine.configure({ mode: LogMode.OFF });    // Complete silence
+
+// Environment-based configuration example
+const env = process.env.NODE_ENV || 'development';
 
 if (env === 'production') {
-    LogEngine.configure({ level: LogLevel.ERROR });
+    LogEngine.configure({ mode: LogMode.INFO });
 } else if (env === 'staging') {
-    LogEngine.configure({ level: LogLevel.WARN });
+    LogEngine.configure({ mode: LogMode.WARN });
 } else {
-    LogEngine.configure({ level: LogLevel.DEBUG });
+    LogEngine.configure({ mode: LogMode.DEBUG });
 }
 
-// Now use Log Engine - only messages at or above the configured level will be shown
-LogEngine.debug('This will only show in development');
+// Now use Log Engine - only messages appropriate for the mode will be shown
+LogEngine.debug('This will only show in DEBUG mode');
 LogEngine.info('General information');
 LogEngine.warn('Warning message');
 LogEngine.error('Error message');
+LogEngine.log('Critical message that always shows');
+```
+
+### Legacy Level-Based Configuration (Backwards Compatible)
+
+For backwards compatibility, the old `LogLevel` API is still supported:
+
+```typescript
+import { LogEngine, LogLevel } from '@wgtechlabs/log-engine';
+
+// Legacy configuration (still works but LogMode is recommended)
+LogEngine.configure({ level: LogLevel.DEBUG });
+LogEngine.configure({ level: LogLevel.INFO });
+LogEngine.configure({ level: LogLevel.WARN });
+LogEngine.configure({ level: LogLevel.ERROR });
+```
+
+### Migration Guide: LogLevel → LogMode
+
+**Version 1.2.0+** introduces the new LogMode system for better separation of concerns. Here's how to migrate:
+
+```typescript
+// OLD (v1.1.0 and earlier) - still works but deprecated
+import { LogEngine, LogLevel } from '@wgtechlabs/log-engine';
+LogEngine.configure({ level: LogLevel.DEBUG });
+
+// NEW (v1.2.0+) - recommended approach
+import { LogEngine, LogMode } from '@wgtechlabs/log-engine';
+LogEngine.configure({ mode: LogMode.DEBUG });
 ```
 
+**Key Benefits of LogMode:**
+- **Clearer API**: Separates message severity (`LogLevel`) from output control (`LogMode`)
+- **Better Environment Defaults**: `development→DEBUG`, `staging→WARN`, `test→ERROR`
+- **Future-Proof**: New features will use the LogMode system
+- **100% Backwards Compatible**: Existing code continues to work unchanged
+
 ### Color-Coded Output 🎨
 
 Log Engine now features beautiful, color-coded console output that makes debugging and monitoring a breeze:
@@ -114,6 +160,7 @@ LogEngine.debug('🔍 Debugging user authentication flow');    // Purple/Magenta
 LogEngine.info('ℹ️ User successfully logged in');            // Blue  
 LogEngine.warn('⚠️ API rate limit at 80% capacity');         // Yellow
 LogEngine.error('❌ Database connection timeout');           // Red
+LogEngine.log('🚀 Application started successfully');        // Green
 ```
 
 **Why Colors Matter:**
@@ -123,24 +170,84 @@ LogEngine.error('❌ Database connection timeout');           // Red
 - **Production Monitoring**: Easily scan logs for critical issues in terminal environments
 - **Enhanced Readability**: Color-coded timestamps and level indicators reduce eye strain
 
-### Log Levels
+### Log Modes
+
+Log Engine uses a **LogMode** system that controls output verbosity and filtering:
 
-Log Engine supports the following levels (in order of severity):
+- `LogMode.DEBUG` (0) - Most verbose: shows DEBUG, INFO, WARN, ERROR, LOG messages
+- `LogMode.INFO` (1) - Balanced: shows INFO, WARN, ERROR, LOG messages  
+- `LogMode.WARN` (2) - Focused: shows WARN, ERROR, LOG messages
+- `LogMode.ERROR` (3) - Minimal: shows ERROR, LOG messages
+- `LogMode.SILENT` (4) - Critical only: shows LOG messages only
+- `LogMode.OFF` (5) - Complete silence: shows no messages at all
+
+### Message Severity Levels
+
+Individual log messages have severity levels that determine their importance:
 
 - `LogLevel.DEBUG` (0) - Detailed information for debugging
 - `LogLevel.INFO` (1) - General information
 - `LogLevel.WARN` (2) - Warning messages
 - `LogLevel.ERROR` (3) - Error messages
-- `LogLevel.SILENT` (4) - No output
+- `LogLevel.LOG` (99) - Critical messages that always show (except when OFF mode is set)
 
 ### Auto-Configuration
 
 Log Engine automatically configures itself based on the `NODE_ENV` environment variable:
 
-- `production` → `LogLevel.WARN`
-- `development` → `LogLevel.DEBUG`
-- `test` → `LogLevel.ERROR`
-- `default` → `LogLevel.INFO`
+- `development` → `LogMode.DEBUG` (most verbose)
+- `production` → `LogMode.INFO` (balanced)
+- `staging` → `LogMode.WARN` (focused)
+- `test` → `LogMode.ERROR` (minimal)
+- `default` → `LogMode.INFO` (balanced)
+
+### Special LOG Level
+
+The `LOG` level is special and behaves differently from other levels:
+
+- **Always Visible**: LOG messages are always displayed regardless of the configured log mode (except when OFF mode is set)
+- **Critical Information**: Perfect for essential system messages, application lifecycle events, and operational information that must never be filtered out
+- **Green Color**: Uses green coloring to distinguish it from other levels
+- **Use Cases**: Application startup/shutdown, server listening notifications, critical configuration changes, deployment information
+
+```typescript
+import { LogEngine, LogMode } from '@wgtechlabs/log-engine';
+
+// Even with SILENT mode, LOG messages still appear
+LogEngine.configure({ mode: LogMode.SILENT });
+
+LogEngine.debug('Debug message');    // Hidden
+LogEngine.info('Info message');      // Hidden
+LogEngine.warn('Warning message');   // Hidden  
+LogEngine.error('Error message');    // Hidden
+LogEngine.log('Server started on port 3000'); // ✅ Always visible!
+
+// But with OFF mode, even LOG messages are hidden
+LogEngine.configure({ mode: LogMode.OFF });
+LogEngine.log('This LOG message is hidden'); // ❌ Hidden with OFF mode
+```
+
+### Complete Silence with OFF Mode
+
+The `OFF` mode provides complete logging silence when you need to disable all output:
+
+- **Total Silence**: Disables ALL logging including the special LOG level messages
+- **Testing & CI/CD**: Perfect for automated testing environments where no console output is desired
+- **Performance**: Minimal overhead when logging is completely disabled
+- **Use Cases**: Unit tests, CI/CD pipelines, production environments requiring zero log output
+
+```typescript
+import { LogEngine, LogMode } from '@wgtechlabs/log-engine';
+
+// Comparison: SILENT vs OFF
+LogEngine.configure({ mode: LogMode.SILENT });
+LogEngine.info('Info message');  // Hidden
+LogEngine.log('Critical message'); // ✅ Still visible with SILENT
+
+LogEngine.configure({ mode: LogMode.OFF });
+LogEngine.info('Info message');  // Hidden
+LogEngine.log('Critical message'); // ❌ Hidden with OFF - complete silence!
+```
 
 ### Log Format
 
@@ -152,6 +259,7 @@ Log messages are beautifully formatted with colorized timestamps, levels, and sm
 [2025-05-29T16:57:46.123Z][4:57 PM][INFO]: Server started successfully  
 [2025-05-29T16:57:47.456Z][4:57 PM][WARN]: API rate limit approaching
 [2025-05-29T16:57:48.789Z][4:57 PM][ERROR]: Database connection failed
+[2025-05-29T16:57:49.012Z][4:57 PM][LOG]: Application startup complete
 ```
 
 **Color Scheme:**
@@ -160,6 +268,7 @@ Log messages are beautifully formatted with colorized timestamps, levels, and sm
 - 🔵 **INFO**: Blue - General informational messages  
 - 🟡 **WARN**: Yellow - Warning messages that need attention
 - 🔴 **ERROR**: Red - Error messages requiring immediate action
+- 🟢 **LOG**: Green - Critical messages that always display
 - ⚫ **Timestamps**: Gray (ISO) and Cyan (local time) for easy scanning
 
 ## 💬 Community Discussions

package/dist/formatter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Log message formatter that provides colorized console output with timestamps
+ * Handles ANSI color codes and structured log message formatting
+ */
+import { LogLevel } from './types';
+/**
+ * LogFormatter class responsible for formatting log messages with colors and timestamps
+ * Creates readable, colored console output with ISO timestamps and local time
+ */
+export declare class LogFormatter {
+    private static readonly colors;
+    /**
+     * Formats a log message with timestamp, level indicator, and appropriate coloring
+     * Creates a structured log entry: [ISO_TIMESTAMP][LOCAL_TIME][LEVEL]: message
+     * @param level - The log level to format for
+     * @param message - The message content to format
+     * @returns Formatted string with ANSI colors and timestamps
+     */
+    static format(level: LogLevel, message: string): string;
+    /**
+     * Formats a Log Engine system message with [LOG ENGINE] prefix instead of log levels
+     * Used for internal messages like deprecation warnings that should be distinguished from user logs
+     * @param message - The system message content to format
+     * @returns Formatted string with ANSI colors, timestamps, and LOG ENGINE prefix
+     */
+    static formatSystemMessage(message: string): string;
+    /**
+     * Converts LogLevel enum to human-readable string
+     * @param level - The LogLevel to convert
+     * @returns String representation of the log level
+     */
+    private static getLevelName;
+    /**
+     * Maps LogLevel to appropriate ANSI color code
+     * Colors help quickly identify message severity in console output
+     * @param level - The LogLevel to get color for
+     * @returns ANSI color escape sequence
+     */
+    private static getLevelColor;
+}
+//# sourceMappingURL=formatter.d.ts.map

package/dist/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../src/formatter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC;;;GAGG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAW5B;IAEF;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAoBvD;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAkBnD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAW3B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;CAU/B"}

package/dist/formatter.js

@@ -34,6 +34,27 @@ class LogFormatter {
         const coloredLevel = `${levelColor}[${levelName}]${this.colors.reset}`;
         return `${coloredTimestamp}${coloredTimeString}${coloredLevel}: ${message}`;
     }
+    /**
+     * Formats a Log Engine system message with [LOG ENGINE] prefix instead of log levels
+     * Used for internal messages like deprecation warnings that should be distinguished from user logs
+     * @param message - The system message content to format
+     * @returns Formatted string with ANSI colors, timestamps, and LOG ENGINE prefix
+     */
+    static formatSystemMessage(message) {
+        const now = new Date();
+        const isoTimestamp = now.toISOString();
+        const timeString = now.toLocaleTimeString('en-US', {
+            hour: 'numeric',
+            minute: '2-digit',
+            hour12: true
+        });
+        // Apply colors to each component for better readability
+        const coloredTimestamp = `${LogFormatter.colors.gray}[${isoTimestamp}]${LogFormatter.colors.reset}`;
+        const coloredTimeString = `${LogFormatter.colors.cyan}[${timeString}]${LogFormatter.colors.reset}`;
+        const coloredLogEngine = `${LogFormatter.colors.yellow}[LOG ENGINE]${LogFormatter.colors.reset}`;
+        const coloredMessage = `${LogFormatter.colors.yellow}${message}${LogFormatter.colors.reset}`;
+        return `${coloredTimestamp}${coloredTimeString}${coloredLogEngine}: ${coloredMessage}`;
+    }
     /**
      * Converts LogLevel enum to human-readable string
      * @param level - The LogLevel to convert
@@ -45,7 +66,7 @@ class LogFormatter {
             case types_1.LogLevel.INFO: return 'INFO';
             case types_1.LogLevel.WARN: return 'WARN';
             case types_1.LogLevel.ERROR: return 'ERROR';
-            case types_1.LogLevel.SILENT: return 'SILENT';
+            case types_1.LogLevel.LOG: return 'LOG';
             default: return 'UNKNOWN';
         }
     }
@@ -61,7 +82,7 @@ class LogFormatter {
             case types_1.LogLevel.INFO: return this.colors.blue; // Blue for general info
             case types_1.LogLevel.WARN: return this.colors.yellow; // Yellow for warnings
             case types_1.LogLevel.ERROR: return this.colors.red; // Red for errors
-            case types_1.LogLevel.SILENT: return this.colors.dim; // Dim for silent (shouldn't be used)
+            case types_1.LogLevel.LOG: return this.colors.green; // Green for always-on log messages
             default: return this.colors.white; // White for unknown levels
         }
     }
@@ -77,5 +98,6 @@ LogFormatter.colors = {
     magenta: '\x1b[35m', // Magenta text (debug)
     cyan: '\x1b[36m', // Cyan text (timestamps)
     white: '\x1b[37m', // White text (default)
-    gray: '\x1b[90m' // Gray text (timestamps)
+    gray: '\x1b[90m', // Gray text (timestamps)
+    green: '\x1b[32m' // Green text (log level)
 };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Main entry point for the Log Engine library
+ * Provides a simple, configurable logging interface with environment-based auto-configuration
+ */
+import { LoggerConfig } from './types';
+/**
+ * Main LogEngine API - provides all logging functionality with a clean interface
+ * Auto-configured based on NODE_ENV, but can be reconfigured at runtime
+ */
+export declare const LogEngine: {
+    /**
+     * Configure the logger with custom settings
+     * @param config - Partial configuration object containing level and/or environment
+     * @example
+     * ```typescript
+     * LogEngine.configure({ level: LogLevel.DEBUG });
+     * LogEngine.configure({ level: LogLevel.WARN, environment: 'staging' });
+     * ```
+     */
+    configure: (config: Partial<LoggerConfig>) => void;
+    /**
+     * Log a debug message (lowest priority)
+     * Only shown when log level is DEBUG or lower
+     * Useful for detailed diagnostic information during development
+     * @param message - The debug message to log
+     * @example
+     * ```typescript
+     * LogEngine.debug('User authentication flow started');
+     * LogEngine.debug(`Processing ${items.length} items`);
+     * ```
+     */
+    debug: (message: string) => void;
+    /**
+     * Log an informational message
+     * General information about application flow and state
+     * Shown when log level is INFO or lower
+     * @param message - The info message to log
+     * @example
+     * ```typescript
+     * LogEngine.info('Application started successfully');
+     * LogEngine.info('User logged in: john@example.com');
+     * ```
+     */
+    info: (message: string) => void;
+    /**
+     * Log a warning message
+     * Indicates potential issues that don't prevent operation
+     * Shown when log level is WARN or lower
+     * @param message - The warning message to log
+     * @example
+     * ```typescript
+     * LogEngine.warn('API rate limit approaching');
+     * LogEngine.warn('Deprecated function called');
+     * ```
+     */
+    warn: (message: string) => void;
+    /**
+     * Log an error message (highest priority)
+     * Indicates serious problems that need attention
+     * Always shown unless log level is SILENT
+     * @param message - The error message to log
+     * @example
+     * ```typescript
+     * LogEngine.error('Database connection failed');
+     * LogEngine.error('Authentication token expired');
+     * ```
+     */
+    error: (message: string) => void;
+    /**
+     * Log a critical message that always outputs
+     * Essential messages that should always be visible regardless of log mode
+     * Always shown no matter what log mode is configured (except OFF mode)
+     * @param message - The critical log message to log
+     * @example
+     * ```typescript
+     * LogEngine.log('Application starting up');
+     * LogEngine.log('Server listening on port 3000');
+     * LogEngine.log('Graceful shutdown initiated');
+     * ```
+     */
+    log: (message: string) => void;
+};
+export { LogLevel, LogMode, LoggerConfig } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAW,YAAY,EAAE,MAAM,SAAS,CAAC;AAiChD;;;GAGG;AACH,eAAO,MAAM,SAAS;IAClB;;;;;;;;OAQG;wBACiB,OAAO,CAAC,YAAY,CAAC;IAEzC;;;;;;;;;;OAUG;qBACc,MAAM;IAEvB;;;;;;;;;;OAUG;oBACa,MAAM;IAEtB;;;;;;;;;;OAUG;oBACa,MAAM;IAEtB;;;;;;;;;;OAUG;qBACc,MAAM;IAEvB;;;;;;;;;;;OAWG;mBACY,MAAM;CACxB,CAAC;AAEF,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -4,34 +4,37 @@
  * Provides a simple, configurable logging interface with environment-based auto-configuration
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLevel = exports.LogEngine = void 0;
+exports.LogMode = exports.LogLevel = exports.LogEngine = void 0;
 const logger_1 = require("./logger");
 const types_1 = require("./types");
 // Create singleton logger instance
 const logger = new logger_1.Logger();
 /**
- * Determines the appropriate default log level based on NODE_ENV
- * - production: WARN (reduce noise in production)
- * - development: DEBUG (verbose logging for development)
- * - test: ERROR (minimal logging during tests)
+ * Determines the appropriate default log mode based on NODE_ENV
+ * - development: DEBUG (most verbose - shows all messages)
+ * - production: INFO (balanced - shows info, warn, error, log)
+ * - staging: WARN (focused - shows warn, error, log only)
+ * - test: ERROR (minimal - shows error and log only)
  * - default: INFO (balanced logging for other environments)
- * @returns The appropriate LogLevel for the current environment
+ * @returns The appropriate LogMode for the current environment
  */
-const getDefaultLogLevel = () => {
+const getDefaultLogMode = () => {
     const nodeEnv = process.env.NODE_ENV;
     switch (nodeEnv) {
-        case 'production':
-            return types_1.LogLevel.WARN;
         case 'development':
-            return types_1.LogLevel.DEBUG;
+            return types_1.LogMode.DEBUG;
+        case 'production':
+            return types_1.LogMode.INFO;
+        case 'staging':
+            return types_1.LogMode.WARN;
         case 'test':
-            return types_1.LogLevel.ERROR;
+            return types_1.LogMode.ERROR;
         default:
-            return types_1.LogLevel.INFO;
+            return types_1.LogMode.INFO;
     }
 };
-// Initialize logger with environment-appropriate default level
-logger.configure({ level: getDefaultLogLevel() });
+// Initialize logger with environment-appropriate default mode
+logger.configure({ mode: getDefaultLogMode() });
 /**
  * Main LogEngine API - provides all logging functionality with a clean interface
  * Auto-configured based on NODE_ENV, but can be reconfigured at runtime
@@ -94,7 +97,21 @@ exports.LogEngine = {
      * LogEngine.error('Authentication token expired');
      * ```
      */
-    error: (message) => logger.error(message)
+    error: (message) => logger.error(message),
+    /**
+     * Log a critical message that always outputs
+     * Essential messages that should always be visible regardless of log mode
+     * Always shown no matter what log mode is configured (except OFF mode)
+     * @param message - The critical log message to log
+     * @example
+     * ```typescript
+     * LogEngine.log('Application starting up');
+     * LogEngine.log('Server listening on port 3000');
+     * LogEngine.log('Graceful shutdown initiated');
+     * ```
+     */
+    log: (message) => logger.log(message)
 };
 var types_2 = require("./types");
 Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return types_2.LogLevel; } });
+Object.defineProperty(exports, "LogMode", { enumerable: true, get: function () { return types_2.LogMode; } });

package/dist/logger.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Core Logger class that handles log message output with configurable levels
+ * Supports DEBUG, INFO, WARN, ERROR, and LOG levels with intelligent filtering
+ * LOG level always outputs regardless of configuration
+ * Uses colorized console output with timestamps for better readability
+ */
+import { LoggerConfig } from './types';
+/**
+ * Logger class responsible for managing log output and configuration
+ * Provides mode-based filtering and formatted console output
+ */
+export declare class Logger {
+    private config;
+    /**
+     * Updates logger configuration with new settings
+     * Merges provided config with existing settings (partial update)
+     * Supports backwards compatibility by mapping level to mode with deprecation warnings
+     * @param config - Partial configuration object to apply
+     */
+    configure(config: Partial<LoggerConfig>): void;
+    /**
+     * Maps LogLevel values to severity ranks for consistent comparison
+     * This prevents issues if enum numeric values change in the future
+     */
+    private static readonly SEVERITY_RANKS;
+    /**
+     * Maps LogMode values to minimum severity rank required for output
+     * This defines the filtering threshold for each mode
+     */
+    private static readonly MODE_THRESHOLDS;
+    /**
+     * Determines if a message should be logged based on current log mode
+     * Messages are shown only if their level is appropriate for the configured mode
+     * LOG level is special - it always outputs regardless of configured mode (except when OFF is set)
+     * OFF mode disables all logging including LOG level messages
+     * @param level - The log level of the message to check
+     * @returns true if message should be logged, false otherwise
+     */
+    private shouldLog;
+    /**
+     * Log a debug message with DEBUG level formatting
+     * Uses console.log for output with purple/magenta coloring
+     * @param message - The debug message to log
+     */
+    debug(message: string): void;
+    /**
+     * Log an informational message with INFO level formatting
+     * Uses console.log for output with blue coloring
+     * @param message - The info message to log
+     */
+    info(message: string): void;
+    /**
+     * Log a warning message with WARN level formatting
+     * Uses console.warn for output with yellow coloring
+     * @param message - The warning message to log
+     */
+    warn(message: string): void;
+    /**
+     * Log an error message with ERROR level formatting
+     * Uses console.error for output with red coloring
+     * @param message - The error message to log
+     */
+    error(message: string): void;
+    /**
+     * Log a critical message that always outputs (LOG level)
+     * Uses console.log for output with green coloring
+     * Always shown regardless of configured log level
+     * @param message - The critical log message to log
+     */
+    log(message: string): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAqB,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D;;;GAGG;AACH,qBAAa,MAAM;IAEf,OAAO,CAAC,MAAM,CAEZ;IAEF;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAmC9C;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAMpC;IAEF;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAOrC;IAEF;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAajB;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAO5B;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAO3B;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAO3B;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAO5B;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;CAM7B"}

package/dist/logger.js

@@ -1,7 +1,8 @@
 "use strict";
 /**
  * Core Logger class that handles log message output with configurable levels
- * Supports DEBUG, INFO, WARN, ERROR levels with intelligent filtering
+ * Supports DEBUG, INFO, WARN, ERROR, and LOG levels with intelligent filtering
+ * LOG level always outputs regardless of configuration
  * Uses colorized console output with timestamps for better readability
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -10,31 +11,69 @@ const types_1 = require("./types");
 const formatter_1 = require("./formatter");
 /**
  * Logger class responsible for managing log output and configuration
- * Provides level-based filtering and formatted console output
+ * Provides mode-based filtering and formatted console output
  */
 class Logger {
     constructor() {
         // Internal configuration state with sensible defaults
         this.config = {
-            level: types_1.LogLevel.INFO
+            mode: types_1.LogMode.INFO
         };
     }
     /**
      * Updates logger configuration with new settings
      * Merges provided config with existing settings (partial update)
+     * Supports backwards compatibility by mapping level to mode with deprecation warnings
      * @param config - Partial configuration object to apply
      */
     configure(config) {
-        this.config = { ...this.config, ...config };
+        // Handle backwards compatibility - if level is provided but mode is not
+        if (config.level !== undefined && config.mode === undefined) {
+            // Only show deprecation warning in non-test environments
+            if (process.env.NODE_ENV !== 'test') {
+                console.warn(formatter_1.LogFormatter.formatSystemMessage('⚠️  DEPRECATION WARNING: The "level" configuration is deprecated and will be removed in v2.0.0. Please use "mode" instead.'));
+                console.warn(formatter_1.LogFormatter.formatSystemMessage('   Migration: LogEngine.configure({ level: LogLevel.DEBUG }) → LogEngine.configure({ mode: LogMode.DEBUG })'));
+                console.warn(formatter_1.LogFormatter.formatSystemMessage('   See: https://github.com/wgtechlabs/log-engine#migration-guide-loglevel--logmode'));
+            }
+            // Map legacy level values to new LogMode values (including SILENT=4, OFF=5)
+            // This provides backwards compatibility for all legacy values
+            const levelValue = config.level;
+            const levelToModeMap = {
+                [types_1.LogLevel.DEBUG]: types_1.LogMode.DEBUG, // 0 -> 0
+                [types_1.LogLevel.INFO]: types_1.LogMode.INFO, // 1 -> 1
+                [types_1.LogLevel.WARN]: types_1.LogMode.WARN, // 2 -> 2
+                [types_1.LogLevel.ERROR]: types_1.LogMode.ERROR, // 3 -> 3
+                [types_1.LogLevel.LOG]: types_1.LogMode.SILENT, // 99 -> 4 (preserves critical-only behavior)
+                4: types_1.LogMode.SILENT, // Legacy SILENT -> 4
+                5: types_1.LogMode.OFF // Legacy OFF -> 5
+            };
+            const mappedMode = levelToModeMap[levelValue];
+            if (mappedMode === undefined) {
+                throw new Error(`Invalid LogLevel value: ${config.level}. Valid values are: DEBUG(0), INFO(1), WARN(2), ERROR(3), LOG(99), or use LogMode instead.`);
+            }
+            this.config = { ...this.config, mode: mappedMode };
+        }
+        else {
+            // Normal configuration update
+            this.config = { ...this.config, ...config };
+        }
     }
     /**
-     * Determines if a message should be logged based on current log level
-     * Messages are shown only if their level >= configured minimum level
+     * Determines if a message should be logged based on current log mode
+     * Messages are shown only if their level is appropriate for the configured mode
+     * LOG level is special - it always outputs regardless of configured mode (except when OFF is set)
+     * OFF mode disables all logging including LOG level messages
      * @param level - The log level of the message to check
      * @returns true if message should be logged, false otherwise
      */
     shouldLog(level) {
-        return level >= this.config.level;
+        const currentMode = this.config.mode !== undefined ? this.config.mode : types_1.LogMode.INFO;
+        // Get the severity rank for the message level
+        const messageSeverity = Logger.SEVERITY_RANKS[level];
+        // Get the minimum severity threshold for the current mode
+        const modeThreshold = Logger.MODE_THRESHOLDS[currentMode];
+        // Allow the message if its severity meets or exceeds the mode threshold
+        return messageSeverity >= modeThreshold;
     }
     /**
      * Log a debug message with DEBUG level formatting
@@ -80,5 +119,40 @@ class Logger {
             console.error(formatted);
         }
     }
+    /**
+     * Log a critical message that always outputs (LOG level)
+     * Uses console.log for output with green coloring
+     * Always shown regardless of configured log level
+     * @param message - The critical log message to log
+     */
+    log(message) {
+        if (this.shouldLog(types_1.LogLevel.LOG)) {
+            const formatted = formatter_1.LogFormatter.format(types_1.LogLevel.LOG, message);
+            console.log(formatted);
+        }
+    }
 }
 exports.Logger = Logger;
+/**
+ * Maps LogLevel values to severity ranks for consistent comparison
+ * This prevents issues if enum numeric values change in the future
+ */
+Logger.SEVERITY_RANKS = {
+    [types_1.LogLevel.DEBUG]: 0,
+    [types_1.LogLevel.INFO]: 1,
+    [types_1.LogLevel.WARN]: 2,
+    [types_1.LogLevel.ERROR]: 3,
+    [types_1.LogLevel.LOG]: 99 // Special case - always outputs (except when OFF)
+};
+/**
+ * Maps LogMode values to minimum severity rank required for output
+ * This defines the filtering threshold for each mode
+ */
+Logger.MODE_THRESHOLDS = {
+    [types_1.LogMode.DEBUG]: 0, // Shows DEBUG and above
+    [types_1.LogMode.INFO]: 1, // Shows INFO and above
+    [types_1.LogMode.WARN]: 2, // Shows WARN and above
+    [types_1.LogMode.ERROR]: 3, // Shows ERROR and above
+    [types_1.LogMode.SILENT]: 99, // Only shows LOG messages
+    [types_1.LogMode.OFF]: 100 // Shows nothing
+};

package/dist/types/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Type definitions for the Log Engine library
+ * Provides strongly-typed interfaces for configuration and log levels
+ */
+/**
+ * Log levels representing message severity (lowest to highest)
+ * Used for filtering messages based on importance
+ */
+export declare enum LogLevel {
+    /** Detailed diagnostic information, typically only of interest during development */
+    DEBUG = 0,
+    /** General information about application flow and state */
+    INFO = 1,
+    /** Potentially harmful situations that don't prevent operation */
+    WARN = 2,
+    /** Error events that might still allow the application to continue */
+    ERROR = 3,
+    /** Critical messages that always output regardless of configured mode (except when OFF is set) */
+    LOG = 99
+}
+/**
+ * Log modes controlling output behavior and filtering
+ * Determines what messages are displayed based on verbosity requirements
+ */
+export declare enum LogMode {
+    /** Most verbose - shows DEBUG, INFO, WARN, ERROR, LOG messages */
+    DEBUG = 0,
+    /** Balanced - shows INFO, WARN, ERROR, LOG messages */
+    INFO = 1,
+    /** Focused - shows WARN, ERROR, LOG messages */
+    WARN = 2,
+    /** Minimal - shows ERROR, LOG messages */
+    ERROR = 3,
+    /** Critical only - shows LOG messages only */
+    SILENT = 4,
+    /** Complete silence - shows no messages at all */
+    OFF = 5
+}
+/**
+ * Represents a single log entry with timestamp, level, and message
+ * Used internally for structured logging operations
+ */
+export interface LogEntry {
+    /** When the log entry was created */
+    timestamp: Date;
+    /** The severity level of this log entry */
+    level: LogLevel;
+    /** The actual log message content */
+    message: string;
+}
+/**
+ * Configuration options for the logger
+ * Supports both legacy level-based and new mode-based configuration
+ */
+export interface LoggerConfig {
+    /** Log mode controlling output behavior (new API) */
+    mode?: LogMode;
+    /** Legacy: Minimum log level to display (backwards compatibility)
+     * Note: If both mode and level are provided, mode takes precedence */
+    level?: LogLevel;
+    /** Optional environment identifier for context (e.g., 'production', 'staging') */
+    environment?: string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,oBAAY,QAAQ;IAChB,qFAAqF;IACrF,KAAK,IAAI;IACT,2DAA2D;IAC3D,IAAI,IAAI;IACR,kEAAkE;IAClE,IAAI,IAAI;IACR,sEAAsE;IACtE,KAAK,IAAI;IACT,kGAAkG;IAClG,GAAG,KAAK;CACX;AAED;;;GAGG;AACH,oBAAY,OAAO;IACf,kEAAkE;IAClE,KAAK,IAAI;IACT,uDAAuD;IACvD,IAAI,IAAI;IACR,gDAAgD;IAChD,IAAI,IAAI;IACR,0CAA0C;IAC1C,KAAK,IAAI;IACT,8CAA8C;IAC9C,MAAM,IAAI;IACV,kDAAkD;IAClD,GAAG,IAAI;CACV;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACrB,qCAAqC;IACrC,SAAS,EAAE,IAAI,CAAC;IAChB,2CAA2C;IAC3C,KAAK,EAAE,QAAQ,CAAC;IAChB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;0EACsE;IACtE,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/types/index.js

@@ -4,11 +4,10 @@
  * Provides strongly-typed interfaces for configuration and log levels
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLevel = void 0;
+exports.LogMode = exports.LogLevel = void 0;
 /**
- * Log levels in order of priority (lowest to highest)
- * Higher numeric values represent higher priority levels
- * When a level is set, only messages at that level or higher are shown
+ * Log levels representing message severity (lowest to highest)
+ * Used for filtering messages based on importance
  */
 var LogLevel;
 (function (LogLevel) {
@@ -20,6 +19,25 @@ var LogLevel;
     LogLevel[LogLevel["WARN"] = 2] = "WARN";
     /** Error events that might still allow the application to continue */
     LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
-    /** Completely disable all logging output */
-    LogLevel[LogLevel["SILENT"] = 4] = "SILENT";
+    /** Critical messages that always output regardless of configured mode (except when OFF is set) */
+    LogLevel[LogLevel["LOG"] = 99] = "LOG";
 })(LogLevel || (exports.LogLevel = LogLevel = {}));
+/**
+ * Log modes controlling output behavior and filtering
+ * Determines what messages are displayed based on verbosity requirements
+ */
+var LogMode;
+(function (LogMode) {
+    /** Most verbose - shows DEBUG, INFO, WARN, ERROR, LOG messages */
+    LogMode[LogMode["DEBUG"] = 0] = "DEBUG";
+    /** Balanced - shows INFO, WARN, ERROR, LOG messages */
+    LogMode[LogMode["INFO"] = 1] = "INFO";
+    /** Focused - shows WARN, ERROR, LOG messages */
+    LogMode[LogMode["WARN"] = 2] = "WARN";
+    /** Minimal - shows ERROR, LOG messages */
+    LogMode[LogMode["ERROR"] = 3] = "ERROR";
+    /** Critical only - shows LOG messages only */
+    LogMode[LogMode["SILENT"] = 4] = "SILENT";
+    /** Complete silence - shows no messages at all */
+    LogMode[LogMode["OFF"] = 5] = "OFF";
+})(LogMode || (exports.LogMode = LogMode = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wgtechlabs/log-engine",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "A lightweight and efficient logging utility designed specifically for bot applications running on Node.js.",
   "keywords": [
     "logging",