@wgtechlabs/log-engine 1.2.0 → 1.3.0

package/README.md

@@ -4,9 +4,9 @@
 
 [![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 and beautiful color-coded console output.
+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, beautiful color-coded console output, and **advanced automatic data redaction with comprehensive PII protection**.
 
-**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.
+**The first logging library with built-in advanced PII protection and comprehensive TypeScript support.** Stop wrestling with logging configurations and start building amazing applications safely. 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, advanced customizable redaction patterns, and automatic sensitive data protection that scales with your application's growth - from your first "Hello World" to handling millions of requests across distributed systems.
 
 ## ❣️ Motivation
 
@@ -16,15 +16,19 @@ Log Engine transforms your development experience from chaotic debugging session
 
 ## ✨ Key Features
 
-- **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 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.
-- **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.
+- **🔒 Advanced Data Redaction (Enhanced!)**: Built-in PII protection with **custom regex patterns**, **dynamic field management**, and **environment-based configuration** - the first logging library with comprehensive security-first logging by default.
+- **⚡ Custom Redaction Patterns**: Add your own regex patterns for advanced field detection and enterprise-specific data protection requirements.
+- **🎯 Dynamic Field Management**: Runtime configuration of sensitive fields with case-insensitive matching and partial field name detection.
+- **🛠️ Developer-Friendly API**: Advanced redaction methods including `testFieldRedaction()`, `withoutRedaction()`, and comprehensive configuration management.
+- **📊 Comprehensive TypeScript Support**: Full type definitions with 10+ interfaces covering all functionality for maximum developer experience and IDE support.
+- **🚀 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 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.
+- **🔗 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 -->
@@ -78,6 +82,25 @@ 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');
+
+// Advanced automatic data redaction (no configuration needed!)
+LogEngine.info('User login', {
+  username: 'john_doe',        // ✅ Visible
+  password: 'secret123',       // ❌ [REDACTED]
+  email: 'john@example.com',   // ❌ [REDACTED]
+  apiKey: 'apikey123'             // ❌ [REDACTED]
+});
+
+// Advanced redaction features - Add custom patterns
+LogEngine.addCustomRedactionPatterns([/internal.*/i, /company.*/i]);
+LogEngine.addSensitiveFields(['companySecret', 'internalToken']);
+
+// Test field redaction
+console.log(LogEngine.testFieldRedaction('password')); // true
+console.log(LogEngine.testFieldRedaction('username')); // false
+
+// Raw logging for debugging (bypasses redaction)
+LogEngine.withoutRedaction().info('Debug data', { password: 'visible-in-debug' });
 ```
 
 ### Mode-Based Configuration (Recommended)
@@ -137,15 +160,17 @@ LogEngine.configure({ level: LogLevel.ERROR });
 import { LogEngine, LogLevel } from '@wgtechlabs/log-engine';
 LogEngine.configure({ level: LogLevel.DEBUG });
 
-// NEW (v1.2.0+) - recommended approach
+// NEW (v1.2.1+) - recommended approach with advanced features
 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
+- **Advanced Features**: New redaction APIs and TypeScript interfaces work with LogMode
+- **Future-Proof**: All new features use the LogMode system
 - **100% Backwards Compatible**: Existing code continues to work unchanged
 
 ### Color-Coded Output 🎨
@@ -255,11 +280,11 @@ Log messages are beautifully formatted with colorized timestamps, levels, and sm
 
 ```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
-[2025-05-29T16:57:49.012Z][4:57 PM][LOG]: Application startup complete
+[2025-05-29T16:57:45.678Z][4:57PM][DEBUG]: Debugging application flow
+[2025-05-29T16:57:46.123Z][4:57PM][INFO]: Server started successfully  
+[2025-05-29T16:57:47.456Z][4:57PM][WARN]: API rate limit approaching
+[2025-05-29T16:57:48.789Z][4:57PM][ERROR]: Database connection failed
+[2025-05-29T16:57:49.012Z][4:57PM][LOG]: Application startup complete
 ```
 
 **Color Scheme:**
@@ -271,6 +296,244 @@ Log messages are beautifully formatted with colorized timestamps, levels, and sm
 - 🟢 **LOG**: Green - Critical messages that always display
 - ⚫ **Timestamps**: Gray (ISO) and Cyan (local time) for easy scanning
 
+## 🔒 Advanced Data Redaction
+
+**LogEngine features comprehensive built-in PII protection with advanced customization capabilities that automatically redacts sensitive information from your logs.** This security-first approach prevents accidental exposure of passwords, tokens, emails, and other sensitive data while maintaining full debugging capabilities with enterprise-grade flexibility.
+
+### Zero Configuration Security
+
+Just use LogEngine normally - **sensitive data is automatically protected**:
+
+```typescript
+import { LogEngine } from '@wgtechlabs/log-engine';
+
+// ✅ Automatic redaction - no setup needed!
+LogEngine.info('User authentication', {
+  username: 'john_doe',        // ✅ Visible
+  password: 'secret123',       // ❌ [REDACTED]
+  email: 'john@example.com',   // ❌ [REDACTED]
+  apiKey: 'apikey123',         // ❌ [REDACTED]
+  timestamp: new Date()        // ✅ Visible
+});
+
+// Output: [INFO]: User authentication {"username":"john_doe","password":"[REDACTED]","email":"[REDACTED]","apiKey":"[REDACTED]","timestamp":"2025-06-17T..."}
+```
+
+### Protected Data Types
+
+**50+ sensitive patterns automatically detected:**
+
+- **Authentication**: `password`, `token`, `apiKey`, `secret`, `jwt`, `auth`, `sessionId`
+- **Personal Info**: `email`, `phone`, `ssn`, `firstName`, `lastName`, `address`
+- **Financial**: `creditCard`, `cvv`, `bankAccount`, `routingNumber`
+- **System**: `clientSecret`, `privateKey`, `webhookSecret`
+
+### Deep Object Scanning
+
+Automatically scans nested objects and arrays:
+
+```typescript
+LogEngine.warn('Payment processing', {
+  order: {
+    id: 'order-123',           // ✅ Visible
+    customer: {
+      username: 'customer1',      // ✅ Visible
+      email: 'user@example.com',  // ❌ [REDACTED]
+      creditCard: '4532-****'     // ❌ [REDACTED]
+    }
+  },
+  metadata: {
+    processor: 'stripe',
+    apiSecret: 'sk_live_...'     // ❌ [REDACTED]
+  }
+});
+```
+
+### Content Truncation
+
+Large content fields are automatically truncated to prevent log bloat:
+
+```typescript
+LogEngine.debug('Large payload', {
+  content: 'Very long content...'.repeat(100), // Truncated at 100 chars + "... [TRUNCATED]"
+  size: 'large',
+  processed: true
+});
+```
+
+### Development-Friendly Features
+
+**Raw Methods for Debugging:**
+
+```typescript
+// ⚠️ Use with caution - bypasses redaction
+LogEngine.debugRaw('Full debug data', {
+  password: 'secret123',    // ⚠️ Visible (not redacted)
+  apiKey: 'full-key'        // ⚠️ Visible (not redacted)
+});
+
+// Or use the helper method
+LogEngine.withoutRedaction().info('Debug mode', sensitiveData);
+```
+
+**Environment-Based Control:**
+
+```bash
+# Development - show everything (redaction disabled)
+NODE_ENV=development
+
+# Explicitly disable redaction  
+LOG_REDACTION_DISABLED=true
+DEBUG_FULL_PAYLOADS=true
+
+# Custom redaction configuration
+LOG_REDACTION_TEXT="***CONFIDENTIAL***"
+LOG_MAX_CONTENT_LENGTH=200
+LOG_SENSITIVE_FIELDS="customField,companySecret,internalData"
+LOG_TRUNCATION_TEXT="... [CUSTOM_TRUNCATED]"
+
+# Advanced environment integration
+LOG_REDACTION_ENABLED=false  # Alternative disable method
+```
+
+### Custom Configuration
+
+**Modify redaction behavior:**
+
+```typescript
+// Custom redaction settings
+LogEngine.configureRedaction({
+  redactionText: '***HIDDEN***',
+  maxContentLength: 200,
+  sensitiveFields: ['myCustomField', 'internalSecret']
+});
+
+// Get current configuration
+const config = LogEngine.getRedactionConfig();
+console.log(config);
+```
+
+### Advanced Redaction Features (v1.2.1+)
+
+**Custom Patterns & Dynamic Field Management:**
+
+```typescript
+// Add custom regex patterns for enterprise-specific data protection
+LogEngine.addCustomRedactionPatterns([
+  /internal.*/i,        // Matches any field starting with "internal"
+  /company.*/i,         // Matches any field starting with "company"  
+  /^config[A-Z]/        // Matches camelCase config fields
+]);
+
+// Add custom sensitive field names dynamically
+LogEngine.addSensitiveFields(['companySecret', 'internalToken', 'proprietaryData']);
+
+// Test field redaction before logging
+if (LogEngine.testFieldRedaction('myField')) {
+  console.log('Field will be redacted');
+}
+
+// Advanced configuration management
+LogEngine.configureRedaction({
+  redactionText: '***CONFIDENTIAL***',
+  maxContentLength: 150,
+  customPatterns: [/private.*/i, /secret.*/i]
+});
+
+// Configuration utilities
+const currentConfig = LogEngine.getRedactionConfig();
+LogEngine.refreshRedactionConfig();  // Refresh from environment
+LogEngine.resetRedactionConfig();    // Reset to defaults
+LogEngine.clearCustomRedactionPatterns(); // Clear custom patterns
+```
+
+**Enhanced Development Workflow:**
+
+```typescript
+// Raw logging methods (bypass redaction) - use with caution
+LogEngine.debugRaw('Full debug data', { password: 'visible', apiKey: 'full-key' });
+
+// Temporary redaction bypass using helper method
+LogEngine.withoutRedaction().info('Debug mode', sensitiveData);
+
+// Compare outputs during development
+LogEngine.info('With redaction', data);                    // ❌ [REDACTED]
+LogEngine.withoutRedaction().info('Without redaction', data); // ⚠️ Visible
+```
+
+### Environment Behavior
+
+| Environment | Redaction Status | Use Case |
+|-------------|------------------|----------|
+| **Production** | 🔒 **Active** | Full protection for live systems |
+| **Development** | 🛠️ **Disabled** | Full data visibility for debugging |
+| **Staging** | 🔒 **Active** | Test with production-like security |
+| **Test** | 🔒 **Active** | Consistent test environment |
+
+### Security Benefits
+
+✅ **Advanced Pattern Recognition** - Custom regex patterns for enterprise-specific data protection  
+✅ **Dynamic Field Management** - Runtime configuration of sensitive fields with intelligent matching  
+✅ **Comprehensive Testing API** - `testFieldRedaction()` for validation and debugging  
+✅ **Environment Integration** - Seamless configuration via environment variables  
+✅ **Development Workflow** - Raw logging methods and temporary redaction bypass for debugging  
+✅ **Prevents Data Leaks** - Automatic protection against accidental exposure with 50+ built-in patterns  
+✅ **Compliance Ready** - Helps meet GDPR, HIPAA, and other privacy requirements  
+✅ **Zero Configuration** - Secure by default, advanced features when needed  
+✅ **Performance Optimized** - Minimal overhead with intelligent processing and depth limiting  
+✅ **TypeScript Excellence** - Full type safety with comprehensive interfaces and type definitions  
+
+**Perfect for:** Enterprise applications, compliance requirements, team development environments, production systems requiring both security and debugging flexibility, and any scenario where sensitive data protection is critical.
+
+## 📚 Comprehensive TypeScript Support
+
+**LogEngine v1.2.1+ includes extensive TypeScript definitions with 10+ interfaces for maximum type safety and developer experience:**
+
+### Core Interfaces
+
+```typescript
+import { 
+  LogEngine, 
+  LogMode, 
+  LogLevel,
+  ILogEngine,
+  ILogEngineWithoutRedaction,
+  RedactionConfig,
+  LoggerConfig,
+  IDataRedactor
+} from '@wgtechlabs/log-engine';
+
+// Full type safety for all methods
+const config: RedactionConfig = {
+  enabled: true,
+  sensitiveFields: ['password', 'token'],
+  redactionText: '[HIDDEN]',
+  maxContentLength: 100,
+  // ... fully typed configuration
+};
+
+// Advanced redaction testing with return types
+const isRedacted: boolean = LogEngine.testFieldRedaction('password');
+const currentConfig: RedactionConfig = LogEngine.getRedactionConfig();
+
+// Type-safe raw logging
+const rawLogger: ILogEngineWithoutRedaction = LogEngine.withoutRedaction();
+rawLogger.info('Debug info', sensitiveData); // Fully typed methods
+```
+
+### Available Interfaces
+
+- **`ILogEngine`** - Complete LogEngine API with all methods
+- **`ILogEngineWithoutRedaction`** - Raw logging methods interface  
+- **`IDataRedactor`** - Static DataRedactor class methods
+- **`RedactionConfig`** - Comprehensive redaction configuration
+- **`LoggerConfig`** - Logger configuration options
+- **`LogEntry`** - Structured log entry interface
+- **`EnvironmentConfig`** - Environment variable documentation
+- **Plus 3+ additional interfaces** for advanced use cases
+
+**IDE Benefits:** IntelliSense, auto-completion, parameter hints, error detection, and comprehensive documentation tooltips throughout your development workflow.
+
 ## 💬 Community Discussions
 
 Join our community discussions to get help, share ideas, and connect with other users:
@@ -334,6 +597,8 @@ This project is licensed under the [GNU Affero General Public License v3.0](http
 
 This project is created by **[Waren Gonzaga](https://github.com/warengonzaga)** under [WG Technology Labs](https://github.com/wgtechlabs), with the help of awesome [contributors](https://github.com/wgtechlabs/log-engine/graphs/contributors).
 
+**Latest Version:** v1.3.0 - Enhanced with advanced redaction features, comprehensive TypeScript support, and 95%+ test coverage.
+
 [![contributors](https://contrib.rocks/image?repo=wgtechlabs/log-engine)](https://github.com/wgtechlabs/log-engine/graphs/contributors)
 
 ---

package/dist/formatter/colors.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ANSI color codes and color management for terminal output
+ * Provides consistent color definitions used throughout the formatting system
+ */
+/**
+ * ANSI color codes for terminal output styling
+ * Used to create colorized console output with consistent theming
+ */
+export declare const colors: {
+    readonly reset: "\u001B[0m";
+    readonly dim: "\u001B[2m";
+    readonly red: "\u001B[31m";
+    readonly yellow: "\u001B[33m";
+    readonly blue: "\u001B[34m";
+    readonly magenta: "\u001B[35m";
+    readonly cyan: "\u001B[36m";
+    readonly white: "\u001B[37m";
+    readonly gray: "\u001B[90m";
+    readonly green: "\u001B[32m";
+};
+/**
+ * Color scheme configuration
+ * Maps semantic meanings to specific colors for consistent theming
+ */
+export declare const colorScheme: {
+    readonly timestamp: "\u001B[90m";
+    readonly timeString: "\u001B[36m";
+    readonly system: "\u001B[33m";
+    readonly data: "\u001B[2m";
+    readonly reset: "\u001B[0m";
+};
+//# sourceMappingURL=colors.d.ts.map

package/dist/formatter/colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colors.d.ts","sourceRoot":"","sources":["../../src/formatter/colors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;CAWT,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;CAMd,CAAC"}

package/dist/formatter/colors.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * ANSI color codes and color management for terminal output
+ * Provides consistent color definitions used throughout the formatting system
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.colorScheme = exports.colors = void 0;
+/**
+ * ANSI color codes for terminal output styling
+ * Used to create colorized console output with consistent theming
+ */
+exports.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)
+    green: '\x1b[32m' // Green text (log level)
+};
+/**
+ * Color scheme configuration
+ * Maps semantic meanings to specific colors for consistent theming
+ */
+exports.colorScheme = {
+    timestamp: exports.colors.gray,
+    timeString: exports.colors.cyan,
+    system: exports.colors.yellow,
+    data: exports.colors.dim,
+    reset: exports.colors.reset
+};

package/dist/formatter/data-formatter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Data formatting utilities for log output
+ * Handles serialization and formatting of data objects in log messages
+ */
+/**
+ * Converts input data to a readable string suitable for log output.
+ *
+ * Returns 'null' for `null`, an empty string for `undefined`, the value itself for strings, and string representations for numbers and booleans. For other types, attempts JSON serialization; if serialization fails, returns '[Object]'.
+ *
+ * @param data - The value to format for logging
+ * @returns The formatted string representation of the input data
+ */
+export declare function formatData(data: any): string;
+/**
+ * Applies color styling to a formatted data string using the provided color codes.
+ *
+ * @param dataString - The string to be styled; if falsy, an empty string is returned.
+ * @param colors - An object containing `data` (the color code prefix) and `reset` (the color code suffix).
+ * @returns The styled data string with color codes applied, or an empty string if `dataString` is falsy.
+ */
+export declare function styleData(dataString: string, colors: {
+    data: string;
+    reset: string;
+}): string;
+//# sourceMappingURL=data-formatter.d.ts.map

package/dist/formatter/data-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-formatter.d.ts","sourceRoot":"","sources":["../../src/formatter/data-formatter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,CA2B5C;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAM7F"}

package/dist/formatter/data-formatter.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Data formatting utilities for log output
+ * Handles serialization and formatting of data objects in log messages
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatData = formatData;
+exports.styleData = styleData;
+/**
+ * Converts input data to a readable string suitable for log output.
+ *
+ * Returns 'null' for `null`, an empty string for `undefined`, the value itself for strings, and string representations for numbers and booleans. For other types, attempts JSON serialization; if serialization fails, returns '[Object]'.
+ *
+ * @param data - The value to format for logging
+ * @returns The formatted string representation of the input data
+ */
+function formatData(data) {
+    if (data === null) {
+        return 'null';
+    }
+    if (data === undefined) {
+        return '';
+    }
+    if (typeof data === 'string') {
+        return data;
+    }
+    if (typeof data === 'number' || typeof data === 'boolean') {
+        return String(data);
+    }
+    if (typeof data === 'symbol') {
+        return data.toString();
+    }
+    try {
+        return JSON.stringify(data, null, 0);
+    }
+    catch (error) {
+        // Fallback for objects that can't be stringified (e.g., circular references)
+        return '[Object]';
+    }
+}
+/**
+ * Applies color styling to a formatted data string using the provided color codes.
+ *
+ * @param dataString - The string to be styled; if falsy, an empty string is returned.
+ * @param colors - An object containing `data` (the color code prefix) and `reset` (the color code suffix).
+ * @returns The styled data string with color codes applied, or an empty string if `dataString` is falsy.
+ */
+function styleData(dataString, colors) {
+    if (!dataString) {
+        return '';
+    }
+    return ` ${colors.data}${dataString}${colors.reset}`;
+}

package/dist/formatter/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Formatter module exports
+ * Provides centralized access to all formatting functionality
+ */
+export { MessageFormatter } from './message-formatter';
+export { colors, colorScheme } from './colors';
+export { getTimestampComponents, formatTimestamp } from './timestamp';
+export { formatData, styleData } from './data-formatter';
+export { MessageFormatter as LogFormatter } from './message-formatter';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/formatter/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGzD,OAAO,EAAE,gBAAgB,IAAI,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/formatter/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Formatter module exports
+ * Provides centralized access to all formatting functionality
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogFormatter = exports.styleData = exports.formatData = exports.formatTimestamp = exports.getTimestampComponents = exports.colorScheme = exports.colors = exports.MessageFormatter = void 0;
+var message_formatter_1 = require("./message-formatter");
+Object.defineProperty(exports, "MessageFormatter", { enumerable: true, get: function () { return message_formatter_1.MessageFormatter; } });
+var colors_1 = require("./colors");
+Object.defineProperty(exports, "colors", { enumerable: true, get: function () { return colors_1.colors; } });
+Object.defineProperty(exports, "colorScheme", { enumerable: true, get: function () { return colors_1.colorScheme; } });
+var timestamp_1 = require("./timestamp");
+Object.defineProperty(exports, "getTimestampComponents", { enumerable: true, get: function () { return timestamp_1.getTimestampComponents; } });
+Object.defineProperty(exports, "formatTimestamp", { enumerable: true, get: function () { return timestamp_1.formatTimestamp; } });
+var data_formatter_1 = require("./data-formatter");
+Object.defineProperty(exports, "formatData", { enumerable: true, get: function () { return data_formatter_1.formatData; } });
+Object.defineProperty(exports, "styleData", { enumerable: true, get: function () { return data_formatter_1.styleData; } });
+// Backward compatibility - maintain the original LogFormatter class interface
+var message_formatter_2 = require("./message-formatter");
+Object.defineProperty(exports, "LogFormatter", { enumerable: true, get: function () { return message_formatter_2.MessageFormatter; } });

package/dist/formatter/message-formatter.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Core message formatting functionality
+ * Handles the main log message formatting with colors, timestamps, and levels
+ */
+import { LogLevel } from '../types';
+/**
+ * Core message formatter class
+ * Provides the main formatting functionality for log messages
+ */
+export declare class MessageFormatter {
+    /**
+     * Formats a log message with timestamp, level indicator, and appropriate coloring
+     * Creates a structured log entry: [ISO_TIMESTAMP][LOCAL_TIME][LEVEL]: message [data]
+     * @param level - The log level to format for
+     * @param message - The message content to format
+     * @param data - Optional data object to include in the log output
+     * @returns Formatted string with ANSI colors and timestamps
+     */
+    static format(level: LogLevel, message: string, data?: any): 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=message-formatter.d.ts.map

package/dist/formatter/message-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-formatter.d.ts","sourceRoot":"","sources":["../../src/formatter/message-formatter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAKpC;;;GAGG;AACH,qBAAa,gBAAgB;IACzB;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,MAAM;IAsBnE;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAUnD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAW3B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;CAU/B"}