@unchainedshop/logger 5.0.0-alpha.1 → 5.0.0-alpha.10

package/README.md

@@ -9,7 +9,7 @@ A high-performance, feature-rich logging package for Unchained Engine with suppo
 - 🔍 **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
+- 🔧 **Zero Runtime Dependencies**: Uses Node.js built-ins
 
 ## Installation
 

package/lib/createLogger.d.ts

@@ -5,5 +5,7 @@ export interface Logger {
     warn: (message: any, ...args: any[]) => void;
     error: (message: any, ...args: any[]) => void;
 }
+export type LogContextProvider = () => Record<string, unknown> | undefined;
+export declare const setLogContextProvider: (provider: LogContextProvider | undefined) => void;
 export declare const resetLoggerInitialization: () => void;
 export declare const createLogger: (moduleName: string) => Logger;

package/lib/createLogger.js

@@ -1,5 +1,5 @@
 import { inspect } from 'node:util';
-import { stringify } from 'safe-stable-stringify';
+import { safeStringify } from "./safe-stringify.js";
 import { LogLevel } from "./logger.types.js";
 const regexCache = new Map();
 const debugPatternCache = new Map();
@@ -87,15 +87,14 @@ const formatTimestamp = () => {
     const seconds = now.getSeconds().toString().padStart(2, '0');
     return `${hours}:${minutes}:${seconds}`;
 };
-const bigintReplacer = (_key, value) => {
-    if (typeof value === 'bigint') {
-        return value.toString();
-    }
-    return value;
+let logContextProvider;
+export const setLogContextProvider = (provider) => {
+    logContextProvider = provider;
 };
 export const resetLoggerInitialization = () => {
     regexCache.clear();
     debugPatternCache.clear();
+    logContextProvider = undefined;
 };
 export const createLogger = (moduleName) => {
     const { DEBUG = '', LOG_LEVEL = LogLevel.Info, UNCHAINED_LOG_FORMAT = 'unchained' } = process.env;
@@ -130,7 +129,21 @@ export const createLogger = (moduleName) => {
                     logObject[key] = args[0][key];
                 }
             }
-            console.log(stringify(logObject, bigintReplacer));
+            if (logContextProvider) {
+                try {
+                    const extra = logContextProvider();
+                    if (extra) {
+                        for (const key in extra) {
+                            if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+                                continue;
+                            logObject[key] = extra[key];
+                        }
+                    }
+                }
+                catch {
+                }
+            }
+            console.log(safeStringify(logObject));
         }
         else {
             const timestamp = formatTimestamp();

package/lib/logger-index.d.ts

@@ -1,3 +1,4 @@
 export * from './createLogger.ts';
+export * from './safe-stringify.ts';
 export * from './logger.types.ts';
 export * from './log.ts';

package/lib/logger-index.js

@@ -1,3 +1,4 @@
 export * from "./createLogger.js";
+export * from "./safe-stringify.js";
 export * from "./logger.types.js";
 export * from "./log.js";

package/lib/safe-stringify.d.ts

@@ -0,0 +1,2 @@
+export declare function safeStringify(value: any, replacer?: ((this: any, key: string, value: any) => any) | null, space?: string | number): string | undefined;
+export default safeStringify;

package/lib/safe-stringify.js

@@ -0,0 +1,19 @@
+export function safeStringify(value, replacer, space) {
+    const ancestors = [];
+    return JSON.stringify(value, function (key, val) {
+        const replaced = replacer ? replacer.call(this, key, val) : val;
+        if (typeof replaced === 'bigint')
+            return replaced.toString();
+        if (typeof replaced !== 'object' || replaced === null)
+            return replaced;
+        if (replaced instanceof BigInt)
+            return String(replaced);
+        while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this)
+            ancestors.pop();
+        if (ancestors.includes(replaced))
+            return '[Circular]';
+        ancestors.push(replaced);
+        return replaced;
+    }, space);
+}
+export default safeStringify;

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@unchainedshop/logger",
   "description": "High-performance logging package for the Unchained Engine",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.0-alpha.10",
+  "files": [
+    "lib"
+  ],
   "main": "lib/logger-index.js",
   "types": "lib/logger-index.d.ts",
   "type": "module",
@@ -36,11 +39,8 @@
     "url": "https://github.com/unchainedshop/unchained/issues"
   },
   "homepage": "https://github.com/unchainedshop/unchained#readme",
-  "dependencies": {
-    "safe-stable-stringify": "^2.5.0"
-  },
   "devDependencies": {
-    "@types/node": "^25.0.0",
-    "typescript": "^5.8.3"
+    "@types/node": "^26.2.0",
+    "typescript": "^6.0.3"
   }
 }

package/benchmarks/README.md

@@ -1,32 +0,0 @@
-# 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

@@ -1,273 +0,0 @@
-import { performance } from 'node:perf_hooks';
-import { createLogger, resetLoggerInitialization } from '../src/createLogger.ts';
-
-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);