Log

Zero-dependency console logging with tags, verbosity control, and unlimited custom log levels.

Why Log

Log follows Unix philosophy: do logging well, let the system handle output routing. Ship organized, controllable console output that integrates seamlessly with containers, process managers, and log aggregation systems.

Key Benefits:

• Zero dependencies - No supply chain risks or version conflicts
• Unlimited log levels - Create custom methods like log.success(), log.database(), or log.security() alongside native console methods
• Production-ready - Tagged loggers, verbosity filtering, color coding, and global registry management in ~1KB
• Container-native - Structured output ready for Docker, Kubernetes, and log aggregation systems

Installation

npm install fatlard1993/log
# or
bun install fatlard1993/log

Quick Start

Create tagged loggers that share instances and support unlimited custom methods:

import Log from 'log';

// Create tagged logger instances
const api = new Log({ tag: 'api', verbosity: 2, color: true });
const db = new Log({ tag: 'database', verbosity: 1 });

// Use all console methods
api.info('Server started');
api.warn('High memory usage');
api.error('Connection failed');

// Custom methods work automatically
api.success('Request completed');
db.query('SELECT * FROM users');

// Control verbosity levels
api(1)('Debug info'); // Shows if verbosity >= 1
api(3)('Trace data'); // Hidden if verbosity < 3

Core Features

Tagged Logger Registry

Identical tags return the same logger instance, preventing duplicates and enabling cross-module coordination:

// Module A
const log = new Log({ tag: 'app', verbosity: 1 });

// Module B - gets same logger instance
const log = new Log({ tag: 'app' }); // Inherits verbosity: 1

// Access any logger globally
import { loggers } from 'log';
loggers.app.options.verbosity = 3; // Updates everywhere

Verbosity Control

Filter log visibility with verbosity levels. Lower numbers display more frequently:

const log = new Log({ verbosity: 2 });

log('Always visible'); // Verbosity 0 - production logs
log(1)('High priority'); // Shows if verbosity >= 1
log(2)('Debug info'); // Shows if verbosity >= 2
log(5)('Trace data'); // Hidden unless verbosity >= 5

// Combine methods with verbosity
log.warn(1)('Important warning');
log.error(0)('Critical error');

Unlimited Log Methods

Create unlimited custom log methods alongside native console methods:

const log = new Log({ tag: 'app' });

// Native console methods
log.info('Information');
log.warn('Warning');
log.error('Error');
log.debug('Debug data');

// Custom methods work automatically
log.success('Operation completed');
log.database('Query executed');
log.network('Request sent');
log.cache('Cache hit');
log.security('Auth failed');

Color Output

Add color support for enhanced terminal readability:

const log = new Log({ color: true });

log.info('Blue text'); // Built-in blue
log.warn('Yellow text'); // Built-in yellow
log.error('Red text'); // Built-in red

// Custom colors per tag or method
const colorLog = new Log({
	color: true,
	colorMap: {
		success: '\x1b[32m', // Green
		critical: '\x1b[91m', // Bright red
	},
});

Configuration Options

const log = new Log({
	tag: 'myapp', // Logger identifier
	verbosity: 1, // Show logs with level <= 1
	color: false, // Disable color output
	silentTag: false, // Hide [tag] prefix
	methodTag: false, // Hide [method] for native methods
	colorMap: {}, // Custom ANSI color codes
	defaults: {}, // Override global defaults
	methodMap: {}, // Map custom methods to console methods
});

Advanced Usage

Dynamic Configuration

const log = new Log({ tag: 'api', verbosity: 1 });

log(2)('This is hidden');

// Increase verbosity at runtime
log.options.verbosity = 3;

log(2)('Now visible');

Tag Management

const log = new Log({ tag: 'init' });
log('Starting up');

// Switch to different tag
log.setTag('runtime');
log('Now running');

Method Mapping

const log = new Log({
	methodMap: {
		critical: 'error', // log.critical() uses console.error
		trace: 'debug', // log.trace() uses console.debug
	},
});

Cross-Module Coordination

// logger.js
import Log from 'log';
export const appLog = new Log({ tag: 'app', verbosity: 1 });

// module1.js
import { appLog } from './logger.js';
appLog.info('Module 1 loaded');

// module2.js
import { loggers } from 'log';
loggers.app.warn('Module 2 warning'); // Same logger instance

Production Deployment

Container Logging

Integrate seamlessly with Docker/Kubernetes environments:

# Application logs to stdout
docker run myapp

# System routes output
docker run myapp > /var/log/myapp.log 2>&1

# Kubernetes handles log collection automatically
kubectl logs pod/myapp-123

Process Management

Integrate with systemd, PM2, and supervisor:

# PM2 handles log rotation and persistence
pm2 start app.js --log /var/log/app.log

# systemd captures and routes output
systemctl start myapp
journalctl -u myapp -f

Log Aggregation

Generate structured output for ELK, Fluentd, and Datadog:

// JSON-like output for parsing
const log = new Log({
	tag: 'api',
	silentTag: false, // Keep tags for parsing
	color: false, // Disable colors for log aggregation
});

log.info('user_login', { userId: 123, ip: '1.2.3.4' });
// Output: [api][info] user_login { userId: 123, ip: '1.2.3.4' }

Environment Configuration

const log = new Log({
	tag: process.env.SERVICE_NAME || 'app',
	verbosity: process.env.LOG_LEVEL || 1,
	color: process.env.NODE_ENV === 'development',
});

Performance

• Zero dependencies - No supply chain risks or version conflicts
• Minimal overhead - ~200 lines of code, ~1KB bundle size
• Singleton efficiency - Tagged loggers prevent duplicate instances
• Native speed - Direct console method calls, no JSON serialization
• Efficient filtering - Verbosity checks prevent expensive operations when logs won't display

Comparison

Feature	Log	Winston	Pino	Debug
Bundle Size	~1KB	~2MB	~1MB	~8KB
Dependencies	0	Many	Some	1
Log Levels	Unlimited	6 + custom	6 standard	1
Verbosity Control	✓ Core	✓	✓	Environment
Tags/Namespaces	✓ Singleton	✓	✓	✓
Transports	System responsibility	20+ built-in	Plugin ecosystem	None
Container-Native	✓	Configuration required	✓	✓

API Reference

Constructor

new Log(options?: {
  tag?: string;           // Default: '__default'
  verbosity?: number;     // Default: 0
  color?: boolean;        // Default: false
  silentTag?: boolean;    // Default: false
  methodTag?: boolean;    // Default: false
  colorMap?: object;      // Custom colors
  defaults?: object;      // Global defaults override
  methodMap?: object;     // Method name mapping
})

Logger Methods

log(message: any, ...args: any[]): void;
log(verbosity: number): (message: any, ...args: any[]) => void;
log.methodName(message: any, ...args: any[]): void;
log.methodName(verbosity: number): (message: any, ...args: any[]) => void;

Instance Methods

log.setTag(newTag: string): void;
log.options: object;  // Mutable configuration

Exports

import Log, { loggers, defaults, methodMap } from 'log';

Contributing

Contributions welcome! Submit Pull Requests for improvements. Open issues first for major changes.

Development Setup

# Clone and setup
git clone https://github.com/fatlard1993/log.git
cd log
bun install

# Development workflow
bun test           # Run tests
bun run demo       # Run examples
bun run lint       # Check code style
bun test --watch   # Watch mode

License

MIT License - see the LICENSE file for details.