d-logger/README.md

logger

Flexible console logging utility with colors, and multiple output formats

Features

• Multiple log levels: silent, error, warn, info, debug
• Flexible output formats: JSON or simple text
• Caller detection: Automatically identifies source file and line number based on log level
• Color support: Automatic TTY detection with colored output
• ESM only: Modern ES module support

Install

Install with npm:

$ npm install @iankulin/logger

Quick Start

import Logger from '@iankulin/logger';

const logger = new Logger();
logger.info('Hello from logger');
logger.error('Something went wrong');

Usage Examples

Basic Logging

import Logger from '@iankulin/logger';
const logger = new Logger({ level: 'info' });

logger.error('Critical error occurred');
logger.warn('This is a warning');
logger.info('Informational message');
logger.debug('Debug info'); // Won't be shown (level is 'info')

Log Levels

The logger supports five log levels (from least to most verbose):

• silent - Suppresses all output
• error - Only error messages
• warn - Error and warning messages
• info - Error, warning, and info messages (default)
• debug - All messages

const logger = new Logger({ level: 'debug' });

// All of these will be logged
logger.error('Error message');
logger.warn('Warning message');
logger.info('Info message');
logger.debug('Debug message');

// Change level dynamically
logger.level('error');
logger.info('This will not be logged');

// Get current level
console.log(logger.level()); // 'error'

Output Formats

JSON Format (Default)

const logger = new Logger({ format: 'json' });
logger.info('Hello world');

{
  "level": "info",
  "levelNumber": 2,
  "time": "2025-06-02T12:00:00.000Z",
  "pid": 12345,
  "hostname": "my-computer",
  "msg": "Hello world",
  "callerFile": "file:///path/to/file.js",
  "callerLine": 3
}

Simple Format

const logger = new Logger({ format: 'simple' });
logger.error('Something failed');

[2025-07-04 22:50] [ERROR] [basic.js:3] Something failed

Message Formatting

The logger uses Node.js util.format() for message formatting with placeholders like %s, %d, %j.

const logger = new Logger({ format: 'json' });

// String formatting
logger.info('User %s has %d points', 'john', 100);
// Output: {"level":"info","msg":"User john has 100 points",...}

// JSON formatting
logger.info('Config: %j', { debug: true, port: 3000 });
// Output: {"level":"info","msg":"Config: {\"debug\":true,\"port\":3000}",...}

// Simple format example
const simpleLogger = new Logger({ format: 'simple' });
simpleLogger.warn('Processing file %s (%d bytes)', 'data.txt', 1024);
// Output: [2025-07-05 10:30] [WARN ] [app.js:15] Processing file data.txt (1024 bytes)

Custom Colors

const logger = new Logger({
  colours: {
    error: '\x1b[31m', // Red
    warn: '\x1b[93m', // Bright yellow
    info: '\x1b[36m', // Cyan
    debug: '\x1b[90m', // Dark gray
  },
});

Caller Level Control

Control when caller information (file and line number) is included in log messages. This is useful for performance optimization since caller detection can be expensive.

// Default: only include caller info for warnings and errors
const logger = new Logger({ callerLevel: 'warn' });

logger.error('Critical error'); // Includes caller info
logger.warn('Warning message'); // Includes caller info
logger.info('Info message'); // No caller info
logger.debug('Debug message'); // No caller info

JSON Format Output:

{"level":"error","msg":"Critical error","callerFile":"/path/to/file.js","callerLine":42}
{"level":"info","msg":"Info message"}

Simple Format Output:

[2025-07-04 13:13] [ERROR] [app.js:42] Critical error
[2025-07-04 13:13] [INFO ] Info message

Available callerLevel Options:

• 'silent' - Never include caller info (best performance)
• 'error' - Only include caller info for errors
• 'warn' - Include caller info for warnings and errors (default)
• 'info' - Include caller info for info, warnings, and errors
• 'debug' - Always include caller info

Performance Tip: For production applications that primarily log info/debug messages, setting callerLevel: 'error' can significantly improve performance by avoiding expensive stack trace analysis for routine logging.

Constructor Options

Option	Type	Default	Description
level	string	'info'	Minimum log level to output ('silent', 'error', 'warn', 'info', 'debug')
format	string	'json'	Output format ('json' or 'simple')
callerLevel	string	'warn'	Minimum log level to include caller info ('silent', 'error', 'warn', 'info', 'debug')
colours	object	See below	Color codes for each log level
levels	object	See below	Custom level names and numeric values

Common Usage Patterns

import Logger from '@iankulin/logger';

// Production: JSON format with environment-based level
const prodLogger = new Logger({
  level: process.env.LOG_LEVEL || 'info',
  format: 'json',
  callerLevel: 'error', // Performance optimization
});

// Development: Simple format with debug level
const devLogger = new Logger({
  level: 'debug',
  format: 'simple',
});

// Testing: Silent mode
const testLogger = new Logger({ level: 'silent' });

Requirements

• Node.js 18.0.0 or higher
• ES modules support

License

MIT

Versions

• 0.1.5 - Initial release
• 0.1.6 - Added tests, improved error handling, caller detection loop prevention, silent logging level
• 1.0.0 - Production release
• 1.0.2 - Added types for intellisense
• 1.1.0 - added { time: 'short' } option, refactor tests, added { callerLevel: 'warn' } option
• 1.1.2 - dependencies update following chalk supply chain attack although not affected.