@wgtechlabs/log-engine 1.0.1 → 1.0.2

package/README.md

@@ -1,12 +1,12 @@
-# Log Engine 📝 ![gitHub actions workflow status](https://img.shields.io/github/actions/workflow/status/wgtechlabs/log-engine/test.yml?branch=main&style=flat-square&logo=github&labelColor=181717&link=https%3A%2F%2Fgithub.com%2Fwgtechlabs%2Flog-engine%2Factions%2Fworkflows%2Ftest.yml) ![codecov](https://img.shields.io/codecov/c/github/wgtechlabs/log-engine?token=PWRJTBVKQ9&style=flat-square&logo=codecov&labelColor=181717&link=https%3A%2F%2Fcodecov.io%2Fgh%2Fwgtechlabs%2Flog-engine)
+# Log Engine 📜🚂 [![made by](https://img.shields.io/badge/made%20by-WG%20Tech%20Labs-0060a0.svg?logo=github&longCache=true&labelColor=181717&style=flat-square)](https://github.com/wgtechlabs)
 
-[![made by](https://img.shields.io/badge/made%20by-WG%20Technology%20Labs-0060a0.svg?logo=github&longCache=true&labelColor=181717&style=flat-square)](https://github.com/wgtechlabs) [![sponsors](https://img.shields.io/badge/sponsor-%E2%9D%A4-%23db61a2.svg?&logo=github&logoColor=white&labelColor=181717&style=flat-square)](https://github.com/sponsors/wgtechlabs) [![release](https://img.shields.io/github/release/wgtechlabs/log-engine.svg?logo=github&labelColor=181717&color=green&style=flat-square)](https://github.com/wgtechlabs/log-engine/releases) [![star](https://img.shields.io/github/stars/wgtechlabs/log-engine.svg?&logo=github&labelColor=181717&color=yellow&style=flat-square)](https://github.com/wgtechlabs/log-engine/stargazers) [![license](https://img.shields.io/github/license/wgtechlabs/log-engine.svg?&logo=github&labelColor=181717&style=flat-square)](https://github.com/wgtechlabs/log-engine/blob/main/license)
+[![github actions workflow status](https://img.shields.io/github/actions/workflow/status/wgtechlabs/log-engine/test.yml?branch=main&style=flat-square&logo=github&labelColor=181717)](https://github.com/wgtechlabs/log-engine/actions/workflows/test.yml) [![codecov](https://img.shields.io/codecov/c/github/wgtechlabs/log-engine?token=PWRJTBVKQ9&style=flat-square&logo=codecov&labelColor=181717)](https://codecov.io/gh/wgtechlabs/log-engine) [![npm downloads](https://img.shields.io/npm/d18m/%40wgtechlabs%2Flog-engine?style=flat-square&logo=npm&label=installs&labelColor=181717&color=%23CD0000)](https://www.npmjs.com/package/@wgtechlabs/log-engine) [![sponsors](https://img.shields.io/badge/sponsor-%E2%9D%A4-%23db61a2.svg?&logo=github&logoColor=white&labelColor=181717&style=flat-square)](https://github.com/sponsors/wgtechlabs) [![release](https://img.shields.io/github/release/wgtechlabs/log-engine.svg?logo=github&labelColor=181717&color=green&style=flat-square)](https://github.com/wgtechlabs/log-engine/releases) [![star](https://img.shields.io/github/stars/wgtechlabs/log-engine.svg?&logo=github&labelColor=181717&color=yellow&style=flat-square)](https://github.com/wgtechlabs/log-engine/stargazers) [![license](https://img.shields.io/github/license/wgtechlabs/log-engine.svg?&logo=github&labelColor=181717&style=flat-square)](https://github.com/wgtechlabs/log-engine/blob/main/license)
 
 [![banner](https://raw.githubusercontent.com/wgtechlabs/log-engine/main/.github/assets/repo_banner.jpg)](https://github.com/wgtechlabs/log-engine)
 
-WG's Log Engine is the **ultimate logging solution for Node.js developers** - a lightweight, battle-tested utility specifically engineered for Discord bots, Telegram bots, web servers, APIs, and server-side applications. Born from real-world development challenges and proven in production environments like the [Unthread Discord Bot](https://github.com/wgtechlabs/unthread-discord-bot/), Log Engine delivers enterprise-grade logging with zero complexity.
+WG's Log Engine is the **ultimate logging solution for Node.js developers** - a lightweight, battle-tested utility specifically engineered for Discord bots, Telegram bots, web servers, APIs, and server-side applications. Born from real-world development challenges and proven in production environments like the [Unthread Discord Bot](https://github.com/wgtechlabs/unthread-discord-bot/), Log Engine delivers enterprise-grade logging with zero complexity and beautiful color-coded console output.
 
-**Stop wrestling with logging configurations and start building amazing applications.** Whether you're creating the next viral Discord community bot, building high-performance APIs, developing microservices, or deploying production servers, Log Engine provides intelligent terminal-based logging that scales with your application's growth - from your first "Hello World" to handling millions of requests across distributed systems.
+**Stop wrestling with logging configurations and start building amazing applications.** Whether you're creating the next viral Discord community bot, building high-performance APIs, developing microservices, or deploying production servers, Log Engine provides intelligent terminal-based logging with vibrant colors that scales with your application's growth - from your first "Hello World" to handling millions of requests across distributed systems.
 
 ## ❣️ Motivation
 
@@ -18,22 +18,24 @@ 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.
 - **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.
-- **Timestamp Support**: Formatted timestamps with both ISO and human-readable formats - all the formatting you need built right in.
+- **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.
 - **Zero Dependencies**: No external dependencies for maximum compatibility and security - keeps your bundle clean and your project simple.
 - **Easy Integration**: Simple API that works seamlessly with existing Node.js applications. Just `import` and start logging - no middleware, plugins, or configuration required.
 
 ## 🤔 How It Works
-
+<!-- markdownlint-disable MD051 -->
 1. Log Engine automatically detects your environment using `NODE_ENV` and sets appropriate log levels for optimal performance
 2. When you call logging methods, messages are filtered based on the configured severity level (only messages at or above the set level are displayed)
 3. Each log message is instantly formatted with precise timestamps in both ISO and human-readable formats
-4. Messages are output to the console with clear level indicators, making debugging and monitoring effortless
+4. Messages are output to the console with **colorized level indicators and timestamps**, making debugging and monitoring effortless - errors show in red, warnings in yellow, info in blue, and debug in purple
+5. ANSI color codes ensure compatibility across different terminal environments while maintaining beautiful, readable output
 
 Ready to streamline your application logging? Get started in seconds with our [simple installation](#📦-installation)!
-
+<!-- markdownlint-enable MD051 -->
 ## 🤗 Special Thanks
 
 <!-- markdownlint-disable MD033 -->
@@ -43,6 +45,12 @@ Ready to streamline your application logging? Get started in seconds with our [s
 | <div align="center"><a href="https://unthread.com" target="_blank"><b>Unthread</b></a><br/>Streamlined support ticketing for modern teams.</div> |
 <!-- markdownlint-enable MD033 -->
 
+## 💸 Sponsored Ads
+
+Open source development is resource-intensive. These **sponsored ads help keep Log Engine free and actively maintained** while connecting you with tools and services that support open-source development.
+
+[![sponsored ads](https://gitads.dev/v1/ad-serve?source=wgtechlabs/log-engine@github)](https://gitads.dev/v1/ad-track?source=wgtechlabs/log-engine@github)
+
 ## 📦 Installation
 
 Install the package using npm:
@@ -94,6 +102,27 @@ LogEngine.warn('Warning message');
 LogEngine.error('Error message');
 ```
 
+### Color-Coded Output 🎨
+
+Log Engine now features beautiful, color-coded console output that makes debugging and monitoring a breeze:
+
+```typescript
+import { LogEngine } from '@wgtechlabs/log-engine';
+
+// Each log level gets its own distinct color for instant recognition
+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
+```
+
+**Why Colors Matter:**
+
+- **Instant Recognition**: Quickly spot errors, warnings, and debug info without reading every line
+- **Better Debugging**: Visually separate different types of messages during development
+- **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 Engine supports the following levels (in order of severity):
@@ -115,12 +144,24 @@ Log Engine automatically configures itself based on the `NODE_ENV` environment v
 
 ### Log Format
 
-Log messages are formatted with timestamps and levels:
+Log messages are beautifully formatted with colorized timestamps, levels, and smart terminal output:
 
-```
-[2025-05-20T16:57:45.678Z] [4:57 PM] [INFO] Message here.
+```bash
+# Example colorized output (colors visible in terminal)
+[2025-05-29T16:57:45.678Z][4:57 PM][DEBUG]: Debugging application flow
+[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
 ```
 
+**Color Scheme:**
+
+- 🟣 **DEBUG**: Magenta/Purple - Detailed debugging information
+- 🔵 **INFO**: Blue - General informational messages  
+- 🟡 **WARN**: Yellow - Warning messages that need attention
+- 🔴 **ERROR**: Red - Error messages requiring immediate action
+- ⚫ **Timestamps**: Gray (ISO) and Cyan (local time) for easy scanning
+
 ## 💬 Community Discussions
 
 Join our community discussions to get help, share ideas, and connect with other users:
@@ -136,11 +177,12 @@ Join our community discussions to get help, share ideas, and connect with other
 ### Getting Help
 
 Need assistance with the library? Here's how to get help:
-
+<!-- markdownlint-disable MD051 -->
 - **Community Support**: Check the [Help & Support](https://github.com/wgtechlabs/log-engine/discussions/categories/help-support) category in our GitHub Discussions for answers to common questions.
 - **Ask a Question**: Create a [new discussion](https://github.com/wgtechlabs/log-engine/discussions/new?category=help-support) if you can't find answers to your specific issue.
 - **Documentation**: Review the [usage instructions](#🕹️-usage) in this README for common examples and configurations.
 - **Known Issues**: Browse [existing issues](https://github.com/wgtechlabs/log-engine/issues) to see if your problem has already been reported.
+<!-- markdownlint-enable MD051 -->
 
 ### Reporting Issues
 
@@ -187,4 +229,6 @@ This project is created by **[Waren Gonzaga](https://github.com/warengonzaga)**
 
 ---
 
-💻 with ❤️ by [Waren Gonzaga](https://warengonzaga.com) under [WG Technology Labs](https://wgtechlabs.com), and [Him](https://www.youtube.com/watch?v=HHrxS4diLew&t=44s) 🙏
+💻 with ❤️ by [Waren Gonzaga](https://warengonzaga.com) under [WG Technology Labs](https://wgtechlabs.com), and [Him](https://www.youtube.com/watch?v=HHrxS4diLew&t=44s) 🙏
+
+<!-- GitAds-Verify: O4MESJK7VTBCELWNTFQAWB5HDX57H9MS -->

package/dist/formatter.js

@@ -1,8 +1,23 @@
 "use strict";
+/**
+ * Log message formatter that provides colorized console output with timestamps
+ * Handles ANSI color codes and structured log message formatting
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LogFormatter = void 0;
 const types_1 = require("./types");
+/**
+ * LogFormatter class responsible for formatting log messages with colors and timestamps
+ * Creates readable, colored console output with ISO timestamps and local time
+ */
 class LogFormatter {
+    /**
+     * 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, message) {
         const now = new Date();
         const isoTimestamp = now.toISOString();
@@ -12,8 +27,18 @@ class LogFormatter {
             hour12: true
         });
         const levelName = this.getLevelName(level);
-        return `[${isoTimestamp}] [${timeString}] [${levelName}] ${message}`;
+        const levelColor = this.getLevelColor(level);
+        // Apply colors to each component for better readability
+        const coloredTimestamp = `${this.colors.gray}[${isoTimestamp}]${this.colors.reset}`;
+        const coloredTimeString = `${this.colors.cyan}[${timeString}]${this.colors.reset}`;
+        const coloredLevel = `${levelColor}[${levelName}]${this.colors.reset}`;
+        return `${coloredTimestamp}${coloredTimeString}${coloredLevel}: ${message}`;
     }
+    /**
+     * Converts LogLevel enum to human-readable string
+     * @param level - The LogLevel to convert
+     * @returns String representation of the log level
+     */
     static getLevelName(level) {
         switch (level) {
             case types_1.LogLevel.DEBUG: return 'DEBUG';
@@ -24,5 +49,33 @@ class LogFormatter {
             default: return 'UNKNOWN';
         }
     }
+    /**
+     * 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
+     */
+    static getLevelColor(level) {
+        switch (level) {
+            case types_1.LogLevel.DEBUG: return this.colors.magenta; // Purple for debug info
+            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)
+            default: return this.colors.white; // White for unknown levels
+        }
+    }
 }
 exports.LogFormatter = LogFormatter;
+// ANSI color codes for terminal output styling
+LogFormatter.colors = {
+    reset: '\x1b[0m', // Reset all formatting
+    dim: '\x1b[2m', // Dim/faded text
+    red: '\x1b[31m', // Red text (errors)
+    yellow: '\x1b[33m', // Yellow text (warnings)
+    blue: '\x1b[34m', // Blue text (info)
+    magenta: '\x1b[35m', // Magenta text (debug)
+    cyan: '\x1b[36m', // Cyan text (timestamps)
+    white: '\x1b[37m', // White text (default)
+    gray: '\x1b[90m' // Gray text (timestamps)
+};

package/dist/index.js

@@ -1,10 +1,22 @@
 "use strict";
+/**
+ * Main entry point for the Log Engine library
+ * Provides a simple, configurable logging interface with environment-based auto-configuration
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 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();
-// Auto-configure based on NODE_ENV if available
+/**
+ * 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)
+ * - default: INFO (balanced logging for other environments)
+ * @returns The appropriate LogLevel for the current environment
+ */
 const getDefaultLogLevel = () => {
     const nodeEnv = process.env.NODE_ENV;
     switch (nodeEnv) {
@@ -18,12 +30,70 @@ const getDefaultLogLevel = () => {
             return types_1.LogLevel.INFO;
     }
 };
+// Initialize logger with environment-appropriate default level
 logger.configure({ level: getDefaultLogLevel() });
+/**
+ * Main LogEngine API - provides all logging functionality with a clean interface
+ * Auto-configured based on NODE_ENV, but can be reconfigured at runtime
+ */
 exports.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) => logger.configure(config),
+    /**
+     * 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) => logger.debug(message),
+    /**
+     * 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) => logger.info(message),
+    /**
+     * 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) => logger.warn(message),
+    /**
+     * 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) => logger.error(message)
 };
 var types_2 = require("./types");

package/dist/logger.js

@@ -1,38 +1,79 @@
 "use strict";
+/**
+ * Core Logger class that handles log message output with configurable levels
+ * Supports DEBUG, INFO, WARN, ERROR levels with intelligent filtering
+ * Uses colorized console output with timestamps for better readability
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Logger = void 0;
 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
+ */
 class Logger {
     constructor() {
+        // Internal configuration state with sensible defaults
         this.config = {
             level: types_1.LogLevel.INFO
         };
     }
+    /**
+     * Updates logger configuration with new settings
+     * Merges provided config with existing settings (partial update)
+     * @param config - Partial configuration object to apply
+     */
     configure(config) {
         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
+     * @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;
     }
+    /**
+     * 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) {
         if (this.shouldLog(types_1.LogLevel.DEBUG)) {
             const formatted = formatter_1.LogFormatter.format(types_1.LogLevel.DEBUG, message);
             console.log(formatted);
         }
     }
+    /**
+     * 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) {
         if (this.shouldLog(types_1.LogLevel.INFO)) {
             const formatted = formatter_1.LogFormatter.format(types_1.LogLevel.INFO, message);
             console.log(formatted);
         }
     }
+    /**
+     * 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) {
         if (this.shouldLog(types_1.LogLevel.WARN)) {
             const formatted = formatter_1.LogFormatter.format(types_1.LogLevel.WARN, message);
             console.warn(formatted);
         }
     }
+    /**
+     * 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) {
         if (this.shouldLog(types_1.LogLevel.ERROR)) {
             const formatted = formatter_1.LogFormatter.format(types_1.LogLevel.ERROR, message);

package/dist/types/index.js

@@ -1,11 +1,25 @@
 "use strict";
+/**
+ * Type definitions for the Log Engine library
+ * Provides strongly-typed interfaces for configuration and log levels
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 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
+ */
 var LogLevel;
 (function (LogLevel) {
+    /** Detailed diagnostic information, typically only of interest during development */
     LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    /** General information about application flow and state */
     LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    /** Potentially harmful situations that don't prevent operation */
     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";
 })(LogLevel || (exports.LogLevel = LogLevel = {}));

package/package.json

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