Logger (Unchained Engine)

A high-performance, feature-rich logging package for Unchained Engine with support for multiple formats, log levels, and debug patterns.

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

npm install @unchainedshop/logger

Usage

Basic Usage

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

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

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:*

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

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 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