📝 Node-Log

A high-performance TypeScript logging utility for modern Node.js (ESM) applications. It automatically manages directory creation and generates structured .log files with both ANSI-colored console output and clean, plain-text file persistence.

✨ Features

• Dual Output: Logs beautifully colored messages to the console while saving clean, uncolored text to your log files.
• Auto-Directory Creation: Never worry about ENOENT errors. If your log folder doesn't exist, the utility creates it for you automatically.
• Five Log Levels: Built-in support for INFO, WARNING, ERROR, AUDIT, EVENT and DEBUG.
• Contextual Tagging: Easily attach a location or module name to your logs for lightning-fast debugging.
• Zero-Config Ready: Works out of the box, or can be easily customized via .env variables.
• Native ESM: Built specifically for modern "type": "module" Node.js environments.

---

📦 Installation

Install the package via npm:

npm i @kubex3/node-log

---

⚙️ Configuration

By default, file logging is enabled and logs are saved to ./logs/system.log. Note that debug logging and file output are environment-dependent for example, detailed debug traces are typically disabled when NODE_ENV="production" to ensure system stability.

Configuration Options

Variable	Description	Default
LOG_ENABLED	Set to true to write logs to a file, or false to only show them in the console.	true
LOG_FILE_PATH	The relative or absolute path where the log file should be created.	./logs/system.log
NODE_ENV	Set to production to optimize logging and suppress verbose debug output.	development

Example .env Setup

# Enable or disable file logging (true/false)
LOG_ENABLED="true"

# Custom location for your log files
LOG_FILE_PATH="./src/storage/logs/application.log"

# Environment setting (affects log verbosity)
NODE_ENV="production"

---

🚀 Usage

Import the logging functions into your file. Since this is an ESM package, you can use modern import syntax.

import { 
  logInfo, 
  logWarning, 
  logError, 
  logAudit, 
  logEvent 
} from "node-log";

// 1. Basic Logging
logInfo("Server successfully started on port 3000");
logEvent("Daily database backup triggered");

// 2. Logging with Context/Location (Highly Recommended)
// Adding a second string argument tags the log with a specific module or file name.
logWarning("High memory usage detected", "SystemMonitor");
logError("Failed to connect to Redis cluster", "CacheService");
logAudit("User password updated successfully", "AuthModule");

💻 Console Output (With ANSI Colors)

[2026-03-27 - 14:30:15] [  INFO   ] - Server successfully started on port 3000
[2026-03-27 - 14:30:15] [  EVENT  ] - Daily database backup triggered
[2026-03-27 - 14:30:16] [ WARNING ] - [SystemMonitor] - High memory usage detected
[2026-03-27 - 14:30:16] [  ERROR  ] - [CacheService] - Failed to connect to Redis cluster
[2026-03-27 - 14:30:17] [  AUDIT  ] - [AuthModule] - User password updated successfully

📄 File Output (system.log)

The exact same logs are safely appended to your .log file, stripped of ANSI color codes for clean parsing by tools like Datadog, Splunk, or ElasticSearch.

[2026-03-27 - 14:30:15] [  INFO   ] - Server successfully started on port 3000
[2026-03-27 - 14:30:15] [  EVENT  ] - Daily database backup triggered
[2026-03-27 - 14:30:16] [ WARNING ] - [SystemMonitor] - High memory usage detected
[2026-03-27 - 14:30:16] [  ERROR  ] - [CacheService] - Failed to connect to Redis cluster
[2026-03-27 - 14:30:17] [  AUDIT  ] - [AuthModule] - User password updated successfully

---

🛠️ API Reference

All functions share the same signature: functionName(message: string, location?: string): void

Function	Color	Best Used For
logInfo()	🟢 Green	Standard system operations, startup messages, and expected behaviors.
logWarning()	🟡 Yellow	Non-critical issues, deprecations, or approaching limits (e.g., high RAM).
logError()	🔴 Red	Fatal exceptions, unhandled rejections, and system failures.
logAudit()	🔵 Cyan	Security events, login attempts, configuration changes, and authorization.
logEvent()	🟣 Magenta	Business logic milestones, cron job executions, and user-triggered workflows.
logDebug()	⚪ White	Verbose "behind-the-scenes" data, variable states, and deep troubleshooting.

---

👨‍💻 Development

Want to contribute to the project?

1. Clone the repository:

   git clone https://github.com/KubeX3/node-log.git

2. Install dependencies:

   npm install

3. Run the test suite:

   npm run test

4. Build the project:

   npm run build

📜 License

Designed and developed by KubeX3.

Licensed under the Apache License 2.0.