Log Engine 📜🚂

WG's Log Engine is the ultimate logging solution for Node.js developers - a lightweight, battle-tested utility specifically engineered for Discord bots, Telegram bots, web servers, APIs, and server-side applications. Born from real-world development challenges and proven in production environments like the Unthread Discord Bot, Log Engine delivers enterprise-grade logging with zero complexity and beautiful color-coded console output.

Stop wrestling with logging configurations and start building amazing applications. Whether you're creating the next viral Discord community bot, building high-performance APIs, developing microservices, or deploying production servers, Log Engine provides intelligent terminal-based logging with vibrant colors that scales with your application's growth - from your first "Hello World" to handling millions of requests across distributed systems.

❣️ Motivation

Picture this: It's 2 AM, your server is crashing in production, and you're staring at a terminal filled with thousands of debug messages mixed with critical errors. Sound familiar? I've been there too many times. I created Log Engine because every developer deserves to sleep peacefully, knowing their logs are working intelligently in the background.

Log Engine transforms your development experience from chaotic debugging sessions into confident, data-driven problem solving. No more guessing what went wrong, no more drowning in irrelevant logs, no more manual configuration headaches. Just clear, contextual information exactly when and where you need it. Because great applications deserve great logging, and great developers deserve tools that just work.

✨ Key Features

Lightweight & Fast: Minimal overhead with maximum performance - designed to enhance your application, not slow it down.
No Learning Curve: Dead simple API that you can master in seconds. No extensive documentation, complex configurations, or setup required - Log Engine works instantly.
Colorized Console Output: Beautiful ANSI color-coded log levels with intelligent terminal formatting - instantly identify message severity at a glance with color-coded output.
Multiple Log Modes: Support for DEBUG, INFO, WARN, ERROR, SILENT, OFF, and special LOG levels with smart filtering - just set your mode and let it handle the rest.
Auto-Configuration: Intelligent environment-based setup using NODE_ENV variables. No config files, initialization scripts, or manual setup - Log Engine works perfectly out of the box.
Enhanced Formatting: Structured log entries with dual timestamps (ISO + human-readable) and colored level indicators for maximum readability.
TypeScript Ready: Full TypeScript support with comprehensive type definitions for a seamless development experience.
Zero Dependencies: No external dependencies for maximum compatibility and security - keeps your bundle clean and your project simple.
Easy Integration: Simple API that works seamlessly with existing Node.js applications. Just import and start logging - no middleware, plugins, or configuration required.

🤔 How It Works

Log Engine automatically detects your environment using NODE_ENV and sets appropriate log levels for optimal performance
When you call logging methods, messages are filtered based on the configured severity level (only messages at or above the set level are displayed)
Each log message is instantly formatted with precise timestamps in both ISO and human-readable formats
Messages are output to the console with colorized level indicators and timestamps, making debugging and monitoring effortless - errors show in red, warnings in yellow, info in blue, and debug in purple
ANSI color codes ensure compatibility across different terminal environments while maintaining beautiful, readable output

Ready to streamline your application logging? Get started in seconds with our simple installation!

🤗 Special Thanks

💎 Platinum Sponsor

Unthread Streamlined support ticketing for modern teams.

💸 Sponsored Ads

Open source development is resource-intensive. These sponsored ads help keep Log Engine free and actively maintained while connecting you with tools and services that support open-source development.

📦 Installation

Install the package using npm:

npm install @wgtechlabs/log-engine

Or using yarn:

yarn add @wgtechlabs/log-engine

🕹️ Usage

Quick Start

import { LogEngine, LogMode } from '@wgtechlabs/log-engine';

// Basic usage with auto-configuration based on NODE_ENV
LogEngine.debug('This is a debug message');
LogEngine.info('This is an info message');
LogEngine.warn('This is a warning message');
LogEngine.error('This is an error message');
LogEngine.log('This is a critical message that always shows');

Mode-Based Configuration (Recommended)

Log Engine now uses a modern LogMode system that separates message severity from output control:

import { LogEngine, LogMode } from '@wgtechlabs/log-engine';

// Configure using LogMode (recommended approach)
LogEngine.configure({ mode: LogMode.DEBUG });  // Most verbose
LogEngine.configure({ mode: LogMode.INFO });   // Balanced
LogEngine.configure({ mode: LogMode.WARN });   // Focused  
LogEngine.configure({ mode: LogMode.ERROR });  // Minimal
LogEngine.configure({ mode: LogMode.SILENT }); // Critical only
LogEngine.configure({ mode: LogMode.OFF });    // Complete silence

// Environment-based configuration example
const env = process.env.NODE_ENV || 'development';

if (env === 'production') {
    LogEngine.configure({ mode: LogMode.INFO });
} else if (env === 'staging') {
    LogEngine.configure({ mode: LogMode.WARN });
} else {
    LogEngine.configure({ mode: LogMode.DEBUG });
}

// Now use Log Engine - only messages appropriate for the mode will be shown
LogEngine.debug('This will only show in DEBUG mode');
LogEngine.info('General information');
LogEngine.warn('Warning message');
LogEngine.error('Error message');
LogEngine.log('Critical message that always shows');

Legacy Level-Based Configuration (Backwards Compatible)

For backwards compatibility, the old LogLevel API is still supported:

import { LogEngine, LogLevel } from '@wgtechlabs/log-engine';

// Legacy configuration (still works but LogMode is recommended)
LogEngine.configure({ level: LogLevel.DEBUG });
LogEngine.configure({ level: LogLevel.INFO });
LogEngine.configure({ level: LogLevel.WARN });
LogEngine.configure({ level: LogLevel.ERROR });

Migration Guide: LogLevel → LogMode

Version 1.2.0+ introduces the new LogMode system for better separation of concerns. Here's how to migrate:

// OLD (v1.1.0 and earlier) - still works but deprecated
import { LogEngine, LogLevel } from '@wgtechlabs/log-engine';
LogEngine.configure({ level: LogLevel.DEBUG });

// NEW (v1.2.0+) - recommended approach
import { LogEngine, LogMode } from '@wgtechlabs/log-engine';
LogEngine.configure({ mode: LogMode.DEBUG });

Key Benefits of LogMode:

Clearer API: Separates message severity (LogLevel) from output control (LogMode)
Better Environment Defaults: development→DEBUG, staging→WARN, test→ERROR
Future-Proof: New features will use the LogMode system
100% Backwards Compatible: Existing code continues to work unchanged

Color-Coded Output 🎨

Log Engine now features beautiful, color-coded console output that makes debugging and monitoring a breeze:

import { LogEngine } from '@wgtechlabs/log-engine';

// Each log level gets its own distinct color for instant recognition
LogEngine.debug('🔍 Debugging user authentication flow');    // Purple/Magenta
LogEngine.info('ℹ️ User successfully logged in');            // Blue  
LogEngine.warn('⚠️ API rate limit at 80% capacity');         // Yellow
LogEngine.error('❌ Database connection timeout');           // Red
LogEngine.log('🚀 Application started successfully');        // Green

Why Colors Matter:

Instant Recognition: Quickly spot errors, warnings, and debug info without reading every line
Better Debugging: Visually separate different types of messages during development
Production Monitoring: Easily scan logs for critical issues in terminal environments
Enhanced Readability: Color-coded timestamps and level indicators reduce eye strain

Log Modes

Log Engine uses a LogMode system that controls output verbosity and filtering:

LogMode.DEBUG (0) - Most verbose: shows DEBUG, INFO, WARN, ERROR, LOG messages
LogMode.INFO (1) - Balanced: shows INFO, WARN, ERROR, LOG messages
LogMode.WARN (2) - Focused: shows WARN, ERROR, LOG messages
LogMode.ERROR (3) - Minimal: shows ERROR, LOG messages
LogMode.SILENT (4) - Critical only: shows LOG messages only
LogMode.OFF (5) - Complete silence: shows no messages at all

Message Severity Levels

Individual log messages have severity levels that determine their importance:

LogLevel.DEBUG (0) - Detailed information for debugging
LogLevel.INFO (1) - General information
LogLevel.WARN (2) - Warning messages
LogLevel.ERROR (3) - Error messages
LogLevel.LOG (99) - Critical messages that always show (except when OFF mode is set)

Auto-Configuration

Log Engine automatically configures itself based on the NODE_ENV environment variable:

development → LogMode.DEBUG (most verbose)
production → LogMode.INFO (balanced)
staging → LogMode.WARN (focused)
test → LogMode.ERROR (minimal)
default → LogMode.INFO (balanced)

Special LOG Level

The LOG level is special and behaves differently from other levels:

Always Visible: LOG messages are always displayed regardless of the configured log mode (except when OFF mode is set)
Critical Information: Perfect for essential system messages, application lifecycle events, and operational information that must never be filtered out
Green Color: Uses green coloring to distinguish it from other levels
Use Cases: Application startup/shutdown, server listening notifications, critical configuration changes, deployment information

import { LogEngine, LogMode } from '@wgtechlabs/log-engine';

// Even with SILENT mode, LOG messages still appear
LogEngine.configure({ mode: LogMode.SILENT });

LogEngine.debug('Debug message');    // Hidden
LogEngine.info('Info message');      // Hidden
LogEngine.warn('Warning message');   // Hidden  
LogEngine.error('Error message');    // Hidden
LogEngine.log('Server started on port 3000'); // ✅ Always visible!

// But with OFF mode, even LOG messages are hidden
LogEngine.configure({ mode: LogMode.OFF });
LogEngine.log('This LOG message is hidden'); // ❌ Hidden with OFF mode

Complete Silence with OFF Mode

The OFF mode provides complete logging silence when you need to disable all output:

Total Silence: Disables ALL logging including the special LOG level messages
Testing & CI/CD: Perfect for automated testing environments where no console output is desired
Performance: Minimal overhead when logging is completely disabled
Use Cases: Unit tests, CI/CD pipelines, production environments requiring zero log output

import { LogEngine, LogMode } from '@wgtechlabs/log-engine';

// Comparison: SILENT vs OFF
LogEngine.configure({ mode: LogMode.SILENT });
LogEngine.info('Info message');  // Hidden
LogEngine.log('Critical message'); // ✅ Still visible with SILENT

LogEngine.configure({ mode: LogMode.OFF });
LogEngine.info('Info message');  // Hidden
LogEngine.log('Critical message'); // ❌ Hidden with OFF - complete silence!

Log Format

Log messages are beautifully formatted with colorized timestamps, levels, and smart terminal output:

# Example colorized output (colors visible in terminal)
[2025-05-29T16:57:45.678Z][4:57PM][DEBUG]: Debugging application flow
[2025-05-29T16:57:46.123Z][4:57PM][INFO]: Server started successfully  
[2025-05-29T16:57:47.456Z][4:57PM][WARN]: API rate limit approaching
[2025-05-29T16:57:48.789Z][4:57PM][ERROR]: Database connection failed
[2025-05-29T16:57:49.012Z][4:57PM][LOG]: Application startup complete

Color Scheme:

🟣 DEBUG: Magenta/Purple - Detailed debugging information
🔵 INFO: Blue - General informational messages
🟡 WARN: Yellow - Warning messages that need attention
🔴 ERROR: Red - Error messages requiring immediate action
🟢 LOG: Green - Critical messages that always display
⚫ Timestamps: Gray (ISO) and Cyan (local time) for easy scanning

💬 Community Discussions

Join our community discussions to get help, share ideas, and connect with other users:

📣 Announcements: Official updates from the maintainer
📸 Showcase: Show and tell your implementation
💖 Wall of Love: Share your experience with the library
🛟 Help & Support: Get assistance from the community
🧠 Ideas: Suggest new features and improvements

🛟 Help & Support

Getting Help

Need assistance with the library? Here's how to get help:

Community Support: Check the Help & Support category in our GitHub Discussions for answers to common questions.
Ask a Question: Create a new discussion if you can't find answers to your specific issue.
Documentation: Review the usage instructions in this README for common examples and configurations.
Known Issues: Browse existing issues to see if your problem has already been reported.

Reporting Issues

Please report any issues, bugs, or improvement suggestions by creating a new issue. Before submitting, please check if a similar issue already exists to avoid duplicates.

Security Vulnerabilities

For security vulnerabilities, please do not report them publicly. Follow the guidelines in our security policy to responsibly disclose security issues.

Your contributions to improving this project are greatly appreciated! 🙏✨

🎯 Contributing

Contributions are welcome, create a pull request to this repo and I will review your code. Please consider to submit your pull request to the dev branch. Thank you!

Read the project's contributing guide for more info, including testing guidelines and requirements.

🙏 Sponsor

Like this project? Leave a star! ⭐⭐⭐⭐⭐

There are several ways you can support this project:

Become a sponsor and get some perks! 💖
Buy me a coffee if you just love what I do! ☕

⭐ GitHub Star Nomination

Found this project helpful? Consider nominating me (@warengonzaga) for the GitHub Star program! This recognition supports ongoing development of this project and my other open-source projects. GitHub Stars are recognized for their significant contributions to the developer community - your nomination makes a difference and encourages continued innovation!

📋 Code of Conduct

I'm committed to providing a welcoming and inclusive environment for all contributors and users. Please review the project's Code of Conduct to understand the community standards and expectations for participation.

📃 License

This project is licensed under the GNU Affero General Public License v3.0. This license requires that all modifications to the code must be shared under the same license, especially when the software is used over a network. See the LICENSE file for the full license text.

📝 Author

This project is created by Waren Gonzaga under WG Technology Labs, with the help of awesome contributors.

💻 with ❤️ by Waren Gonzaga under WG Technology Labs, and Him 🙏

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
src		src
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
codecov.yml		codecov.yml
jest.config.js		jest.config.js
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Uh oh!

License

wgtechlabs/log-engine

Folders and files

Latest commit

History

Repository files navigation

Log Engine 📜🚂

❣️ Motivation

✨ Key Features

🤔 How It Works

🤗 Special Thanks

💸 Sponsored Ads

📦 Installation

🕹️ Usage

Quick Start

Mode-Based Configuration (Recommended)

Legacy Level-Based Configuration (Backwards Compatible)

Migration Guide: LogLevel → LogMode

Color-Coded Output 🎨

Log Modes

Message Severity Levels

Auto-Configuration

Special LOG Level

Complete Silence with OFF Mode

Log Format

💬 Community Discussions

🛟 Help & Support

Getting Help

Reporting Issues

Security Vulnerabilities

🎯 Contributing

🙏 Sponsor

⭐ GitHub Star Nomination

📋 Code of Conduct

📃 License

📝 Author

About

Topics

Resources

License

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 5

Sponsor this project

Uh oh!

Uh oh!

Contributors 3

Uh oh!

Languages