@unchainedshop/logger 4.0.0-rc.17 → 4.0.0-rc.19

package/README.md

@@ -1,5 +1,97 @@
 # Logger (Unchained Engine)
 
-This package handles logging for all modules.
+A high-performance, feature-rich logging package for Unchained Engine with support for multiple formats, log levels, and debug patterns.
 
-It exports two actions _log_ and _createLogger_ to log information based on the initial logger configuration.
+## Features
+
+- 🚀 **High Performance**: Optimized for speed with caching and no-op functions for disabled log levels
+- 🎨 **Multiple Formats**: Support for both human-readable (unchained) and JSON formats
+- 🔍 **Debug Patterns**: Flexible DEBUG environment variable with wildcards and exclusions
+- 📊 **Log Levels**: Five log levels (trace, debug, info, warn, error) with environment-based filtering
+- 💪 **TypeScript**: Full TypeScript support with type definitions
+- 🔧 **Zero Dependencies**: Core functionality with minimal external dependencies
+
+## Installation
+
+```bash
+npm install @unchainedshop/logger
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { createLogger } from '@unchainedshop/logger';
+
+const logger = createLogger('my-module');
+
+logger.info('Application started');
+logger.debug('Debug information', { userId: 123 });
+logger.error('Something went wrong', new Error('Details'));
+```
+
+### Environment Variables
+
+#### `UNCHAINED_LOG_FORMAT`
+Controls the output format:
+- `unchained` (default): Human-readable format with colors
+- `json`: Machine-readable JSON format
+
+```bash
+UNCHAINED_LOG_FORMAT=json node app.js
+```
+
+#### `LOG_LEVEL`
+Sets the minimum log level:
+- `verbose` or `trace`: All logs
+- `debug`: Debug and above
+- `info` (default): Info and above
+- `warn`: Warnings and errors only
+- `error`: Errors only
+
+```bash
+LOG_LEVEL=debug node app.js
+```
+
+#### `DEBUG`
+Enables debug logging for specific modules using pattern matching:
+- Wildcards: `DEBUG=app:*`
+- Exclusions: `DEBUG=*,-app:excluded`
+- Multiple patterns: `DEBUG=app:*,core:*`
+
+```bash
+DEBUG=my-module,other:* node app.js
+```
+
+## API
+
+### `createLogger(moduleName: string): Logger`
+
+Creates a logger instance for the specified module.
+
+**Parameters:**
+- `moduleName` - The name of the module (used for filtering and display)
+
+**Returns:** Logger instance with methods: `trace`, `debug`, `info`, `warn`, `error`
+
+### Default Logger
+
+```typescript
+import { log, defaultLogger } from '@unchainedshop/logger';
+
+// Quick logging with default logger
+log('Quick info message');
+
+// Or use the default logger directly
+defaultLogger.info('Info message');
+```
+
+## Performance
+
+See [benchmarks/README.md](./benchmarks/README.md) for detailed performance metrics.
+
+Key performance features:
+- **Zero-cost disabled logging**: Log levels below the minimum use no-op functions
+- **Regex caching**: Pattern matching results are cached for speed
+- **Optimized hot paths**: Critical logging paths are optimized for maximum throughput

package/benchmarks/README.md

@@ -0,0 +1,32 @@
+# Logger Performance Benchmarks
+
+Run with: `npm run benchmark`
+
+## Latest Results (October 7, 2025)
+
+```
+Test Name                        |      Ops/sec |     Avg Time |   Total Time
+---------------------------------|--------------|--------------|-------------
+Logger creation (default format) |      935.97K |     0.001 ms |      1.07 ms
+Logger creation (JSON format)    |        1.27M |      0.79 µs |      0.79 ms
+Log info (default format)        |        8.15M |      0.12 µs |     12.28 ms
+Log info (JSON format)           |        1.25M |      0.80 µs |     79.87 ms
+Log complex object (JSON)        |      465.65K |     0.002 ms |     21.48 ms
+Debug log (enabled)              |        8.34M |      0.12 µs |     11.99 ms
+Debug log (disabled)             |      299.36M |      0.00 µs |      0.33 ms
+Pattern matching (createLogger)  |        1.21M |      0.82 µs |      4.12 ms
+```
+
+## Key Insights
+
+- JSON format logging is **550.6% slower** than default format
+- Debug logging when disabled is **35.9x faster** (skips log processing entirely)
+- Fastest: Debug log (disabled) at 299.36M ops/s
+- Slowest: Complex object logging at 465.65K ops/s
+
+## Optimizations
+
+The current implementation includes targeted optimizations:
+- **Regex pattern caching**: Compiled RegExp objects are cached to avoid recreation
+- **Pattern result caching**: DEBUG pattern matching results are cached per module
+- **No-op functions**: Disabled log levels return empty functions for zero-cost logging

package/benchmarks/benchmark.ts

@@ -0,0 +1,273 @@
+import { performance } from 'node:perf_hooks';
+import { createLogger, resetLoggerInitialization } from '../src/createLogger.js';
+
+interface BenchmarkResult {
+  name: string;
+  totalTime: number;
+  operations: number;
+  opsPerSecond: number;
+  avgTimeMs: number;
+}
+
+class LoggerBenchmark {
+  private originalConsole = {
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+    error: console.error,
+    debug: console.debug,
+  };
+
+  private suppressConsole() {
+    const noop = () => {
+      /* intentionally empty */
+    };
+    console.log = noop;
+    console.info = noop;
+    console.warn = noop;
+    console.error = noop;
+    console.debug = noop;
+  }
+
+  private restoreConsole() {
+    Object.assign(console, this.originalConsole);
+  }
+
+  private benchmark(name: string, iterations: number, fn: () => void): BenchmarkResult {
+    // Warm-up phase
+    for (let i = 0; i < Math.min(100, iterations / 10); i++) {
+      fn();
+    }
+
+    // Actual benchmark
+    const start = performance.now();
+    for (let i = 0; i < iterations; i++) {
+      fn();
+    }
+    const totalTime = performance.now() - start;
+
+    return {
+      name,
+      totalTime,
+      operations: iterations,
+      opsPerSecond: (iterations / totalTime) * 1000,
+      avgTimeMs: totalTime / iterations,
+    };
+  }
+
+  async run() {
+    this.restoreConsole();
+    console.log('🚀 Logger Performance Benchmark\n');
+    console.log('Running benchmarks...\n');
+
+    const results: BenchmarkResult[] = [];
+
+    // Test 1: Logger creation performance
+    this.suppressConsole();
+    resetLoggerInitialization();
+    delete process.env.UNCHAINED_LOG_FORMAT;
+    delete process.env.DEBUG;
+    delete process.env.LOG_LEVEL;
+
+    results.push(
+      this.benchmark('Logger creation (default format)', 1000, () => {
+        createLogger(`module-${Math.random()}`);
+      }),
+    );
+
+    // Test 2: Logger creation with JSON format
+    resetLoggerInitialization();
+    process.env.UNCHAINED_LOG_FORMAT = 'json';
+
+    results.push(
+      this.benchmark('Logger creation (JSON format)', 1000, () => {
+        createLogger(`module-json-${Math.random()}`);
+      }),
+    );
+
+    // Test 3: Logging performance - default format
+    resetLoggerInitialization();
+    delete process.env.UNCHAINED_LOG_FORMAT;
+    const defaultLogger = createLogger('benchmark');
+
+    results.push(
+      this.benchmark('Log info (default format)', 100000, () => {
+        defaultLogger.info('Test message');
+      }),
+    );
+
+    // Test 4: Logging performance - JSON format
+    resetLoggerInitialization();
+    process.env.UNCHAINED_LOG_FORMAT = 'json';
+    const jsonLogger = createLogger('benchmark-json');
+
+    results.push(
+      this.benchmark('Log info (JSON format)', 100000, () => {
+        jsonLogger.info('Test message', { id: 123 });
+      }),
+    );
+
+    // Test 5: Complex object logging
+    const complexObject = {
+      user: { id: 'user123', name: 'John Doe', roles: ['admin', 'user'] },
+      action: 'purchase',
+      items: [
+        { id: 'item1', name: 'Product A', price: 99.99, quantity: 2 },
+        { id: 'item2', name: 'Product B', price: 49.99, quantity: 1 },
+      ],
+      metadata: {
+        timestamp: new Date().toISOString(),
+        source: 'web',
+        version: '1.0.0',
+      },
+    };
+
+    results.push(
+      this.benchmark('Log complex object (JSON)', 10000, () => {
+        jsonLogger.info('Complex operation', complexObject);
+      }),
+    );
+
+    // Test 6: Debug logging when enabled
+    resetLoggerInitialization();
+    delete process.env.UNCHAINED_LOG_FORMAT;
+    process.env.DEBUG = 'benchmark-debug';
+    const debugEnabledLogger = createLogger('benchmark-debug');
+
+    results.push(
+      this.benchmark('Debug log (enabled)', 100000, () => {
+        debugEnabledLogger.debug('Debug message');
+      }),
+    );
+
+    // Test 7: Debug logging when disabled
+    resetLoggerInitialization();
+    process.env.DEBUG = 'other-module';
+    const debugDisabledLogger = createLogger('benchmark-no-debug');
+
+    results.push(
+      this.benchmark('Debug log (disabled)', 100000, () => {
+        debugDisabledLogger.debug('Debug message');
+      }),
+    );
+
+    // Test 8: Pattern matching performance
+    resetLoggerInitialization();
+    process.env.DEBUG = 'app:*,!app:excluded,special-*,test:module:*';
+    const testModules = [
+      'app:users',
+      'app:excluded',
+      'special-feature',
+      'test:module:sub',
+      'other:module',
+    ];
+
+    results.push(
+      this.benchmark('Pattern matching (createLogger)', 5000, () => {
+        const module = testModules[Math.floor(Math.random() * testModules.length)];
+        createLogger(module);
+      }),
+    );
+
+    this.restoreConsole();
+    this.printResults(results);
+  }
+
+  private printResults(results: BenchmarkResult[]) {
+    console.log('\n📊 Benchmark Results:\n');
+
+    // Header
+    const cols = {
+      name: 'Test Name',
+      ops: 'Ops/sec',
+      avgTime: 'Avg Time',
+      total: 'Total Time',
+    };
+
+    const widths = {
+      name: Math.max(cols.name.length, ...results.map((r) => r.name.length)),
+      ops: 12,
+      avgTime: 12,
+      total: 12,
+    };
+
+    // Print header
+    console.log(
+      `${cols.name.padEnd(widths.name)} | ${cols.ops.padStart(widths.ops)} | ${cols.avgTime.padStart(
+        widths.avgTime,
+      )} | ${cols.total.padStart(widths.total)}`,
+    );
+    console.log(
+      `${'-'.repeat(widths.name)}-|-${'-'.repeat(widths.ops)}-|-${'-'.repeat(widths.avgTime)}-|-${'-'.repeat(widths.total)}`,
+    );
+
+    // Print results
+    for (const result of results) {
+      const opsPerSec = this.formatNumber(result.opsPerSecond);
+      const avgTime = this.formatTime(result.avgTimeMs);
+      const totalTime = `${result.totalTime.toFixed(2)} ms`;
+
+      console.log(
+        `${result.name.padEnd(widths.name)} | ${opsPerSec.padStart(widths.ops)} | ${avgTime.padStart(
+          widths.avgTime,
+        )} | ${totalTime.padStart(widths.total)}`,
+      );
+    }
+
+    // Performance insights
+    console.log('\n💡 Performance Insights:\n');
+
+    // Compare format performance
+    const defaultLog = results.find((r) => r.name === 'Log info (default format)');
+    const jsonLog = results.find((r) => r.name === 'Log info (JSON format)');
+    if (defaultLog && jsonLog) {
+      const diff = ((jsonLog.avgTimeMs - defaultLog.avgTimeMs) / defaultLog.avgTimeMs) * 100;
+      console.log(
+        `• JSON format logging is ${Math.abs(diff).toFixed(1)}% ${diff > 0 ? 'slower' : 'faster'} than default format`,
+      );
+    }
+
+    // Compare debug enabled vs disabled
+    const debugEnabled = results.find((r) => r.name === 'Debug log (enabled)');
+    const debugDisabled = results.find((r) => r.name === 'Debug log (disabled)');
+    if (debugEnabled && debugDisabled) {
+      const speedup = debugEnabled.avgTimeMs / debugDisabled.avgTimeMs;
+      console.log(
+        `• Debug logging when disabled is ${speedup.toFixed(1)}x faster (skips log processing entirely)`,
+      );
+    }
+
+    // Find fastest and slowest
+    const sorted = [...results].sort((a, b) => b.opsPerSecond - a.opsPerSecond);
+    console.log(
+      `• Fastest operation: ${sorted[0].name} (${this.formatNumber(sorted[0].opsPerSecond)} ops/s)`,
+    );
+    console.log(
+      `• Slowest operation: ${sorted[sorted.length - 1].name} (${this.formatNumber(
+        sorted[sorted.length - 1].opsPerSecond,
+      )} ops/s)`,
+    );
+
+    // Memory note
+    console.log(
+      `\n📝 Note: These benchmarks measure execution speed. Memory usage and garbage collection`,
+    );
+    console.log(`   impact are not measured but may be important factors in production environments.`);
+  }
+
+  private formatNumber(num: number): string {
+    if (num >= 1000000) return `${(num / 1000000).toFixed(2)}M`;
+    if (num >= 1000) return `${(num / 1000).toFixed(2)}K`;
+    return num.toFixed(0);
+  }
+
+  private formatTime(ms: number): string {
+    if (ms < 0.001) return `${(ms * 1000).toFixed(2)} µs`;
+    if (ms < 1) return `${ms.toFixed(3)} ms`;
+    return `${ms.toFixed(2)} ms`;
+  }
+}
+
+// Run benchmark
+const benchmark = new LoggerBenchmark();
+benchmark.run().catch(console.error);

package/lib/createLogger.d.ts

@@ -1,3 +1,24 @@
-import { default as log } from 'loglevel';
-export declare const createLogger: (moduleName: string) => log.Logger;
+export interface Logger {
+    trace: (message: any, ...args: any[]) => void;
+    debug: (message: any, ...args: any[]) => void;
+    info: (message: any, ...args: any[]) => void;
+    warn: (message: any, ...args: any[]) => void;
+    error: (message: any, ...args: any[]) => void;
+}
+/**
+ * Resets all internal caches. Used for testing to ensure a clean state.
+ */
+export declare const resetLoggerInitialization: () => void;
+/**
+ * Creates a logger instance for the specified module name.
+ * The logger respects DEBUG, LOG_LEVEL, and UNCHAINED_LOG_FORMAT environment variables.
+ *
+ * Performance optimizations:
+ * - Returns no-op functions for disabled log levels (zero-cost logging)
+ * - Caches regex patterns and debug results for fast pattern matching
+ *
+ * @param moduleName - The name of the module (used for filtering and display)
+ * @returns A logger instance with trace, debug, info, warn, and error methods
+ */
+export declare const createLogger: (moduleName: string) => Logger;
 //# sourceMappingURL=createLogger.d.ts.map

package/lib/createLogger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createLogger.d.ts","sourceRoot":"","sources":["../src/createLogger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,GAAG,EAAE,MAAM,UAAU,CAAC;AAsE1C,eAAO,MAAM,YAAY,GAAI,YAAY,MAAM,eAc9C,CAAC"}
+{"version":3,"file":"createLogger.d.ts","sourceRoot":"","sources":["../src/createLogger.ts"],"names":[],"mappings":"AA8FA,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9C,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC9C,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC7C,IAAI,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAC7C,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;CAC/C;AAyBD;;GAEG;AACH,eAAO,MAAM,yBAAyB,QAAO,IAG5C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GAAI,YAAY,MAAM,KAAG,MAmFjD,CAAC"}