🪵 LogBuddy.js

Your friendly neighborhood logging companion for Node.js applications

LogBuddy.js is a lightweight, configurable logging library for Node.js that provides intelligent file rotation, multiple log levels, and flexible configuration options. Whether you're building a small script or a large application, LogBuddy.js has got your logging needs covered! 🎯

✨ Features

• 🔄 Smart File Rotation - Automatic log rotation based on file size or time intervals
• 📊 Multiple Log Levels - Debug, Info, Warning, Error, and Fatal levels
• ⚙️ Flexible Configuration - JSON-based configuration with builder patterns
• 📁 Custom File Naming - Configurable file prefixes for organized logs
• 🚀 Zero Dependencies - Lightweight and fast
• 💾 Size-based Rolling - From 1KB to 100MB thresholds
• ⏰ Time-based Rolling - Minutely, hourly, daily, weekly, monthly, or yearly rotation

🚀 Quick Start

Installation

npm install logbuddy-js

Basic Usage

const { Logger, LogLevel } = require("logbuddy-js");

// Create a logger with default settings
const logger = Logger.with_defaults();

// Start logging!
logger.info("Hello from Log Buddy! 🎉");
logger.error("Something went wrong 😱");
logger.debug("Debug information");

With Configuration

const {
  Logger,
  LogConfig,
  LogLevel,
  RollingSizeOptions,
  RollingTimeOptions,
} = require("logbuddy-js");

// Create custom configuration
const config = LogConfig.with_defaults()
  .with_log_level(LogLevel.Debug)
  .with_file_prefix("MyApp_")
  .with_rolling_config({
    size_threshold: RollingSizeOptions.TenMB,
    time_threshold: RollingTimeOptions.Daily,
  });

const logger = Logger.with_config(config);

📋 Configuration

JSON Configuration

Create a config.json file:

{
  "level": 1,
  "file_prefix": "MyApp_",
  "rolling_config": {
    "size_threshold": 10485760,
    "time_threshold": 86400
  }
}

Load from file:

const { Logger, LogConfig } = require("logbuddy-js");

const logger = Logger.with_config(LogConfig.from_file("./config.json"));

Log Levels

| Level | Value | Description | | --------- | ----- | ------------------------------ | | Debug | 0 | Detailed debugging information | | Info | 1 | General information messages | | Warning | 2 | Warning messages | | Error | 3 | Error messages | | Fatal | 4 | Critical error messages |

Rolling Size Options

const { RollingSizeOptions } = require("logbuddy-js");

// Pre-defined size constants
RollingSizeOptions.OneKB; // 1,024 bytes
RollingSizeOptions.FiveKB; // 5,120 bytes
RollingSizeOptions.TenKB; // 10,240 bytes
RollingSizeOptions.HundredKB; // 102,400 bytes
RollingSizeOptions.OneMB; // 1,048,576 bytes
RollingSizeOptions.FiveMB; // 5,242,880 bytes (default)
RollingSizeOptions.TenMB; // 10,485,760 bytes
RollingSizeOptions.HundredMB; // 104,857,600 bytes

Rolling Time Options

const { RollingTimeOptions } = require("logbuddy-js");

// Pre-defined time intervals
RollingTimeOptions.Minutely; // 60 seconds
RollingTimeOptions.Hourly; // 3,600 seconds (default)
RollingTimeOptions.Daily; // 86,400 seconds
RollingTimeOptions.Weekly; // 604,800 seconds
RollingTimeOptions.Monthly; // 2,592,000 seconds
RollingTimeOptions.Yearly; // 31,104,000 seconds

🎯 API Reference

Logger Class

const logger = Logger.with_config(config);

// Logging methods
logger.debug("Debug message");
logger.info("Info message");
logger.warn("Warning message");
logger.error("Error message");
logger.critical("Critical message");

// Access configuration
console.log(logger.level); // Current log level
console.log(logger.file_prefix); // File prefix
console.log(logger.size_threshold); // Size threshold in bytes
console.log(logger.time_threshold); // Time threshold in seconds

LogConfig Class

const config = LogConfig.with_defaults()
  .with_log_level(LogLevel.Info)
  .with_file_prefix("MyApp_")
  .with_rolling_config({
    size_threshold: RollingSizeOptions.FiveMB,
    time_threshold: RollingTimeOptions.Hourly,
  });

// Load from JSON
const config = LogConfig.from_file("./config.json");
const config = LogConfig.from_json(jsonObject);

RollingConfig Class

const rolling = RollingConfig.with_defaults()
  .with_size_threshold(RollingSizeOptions.TenMB)
  .with_time_threshold(RollingTimeOptions.Daily);

// Access thresholds
console.log(rolling.size_threshold); // Size in bytes
console.log(rolling.time_threshold); // Time in seconds

📚 Examples

Example 1: Web Server Logging

const { Logger, LogConfig, LogLevel } = require("logbuddy-js");

const config = LogConfig.with_defaults()
  .with_log_level(LogLevel.Info)
  .with_file_prefix("WebServer_")
  .with_rolling_config({
    size_threshold: 5242880, // 5MB
    time_threshold: 86400, // Daily rotation
  });

const logger = Logger.with_config(config);

// In your server code
app.get("/api/users", (req, res) => {
  logger.info(`API request: GET /api/users from ${req.ip}`);

  try {
    const users = getUsersFromDB();
    logger.debug(`Retrieved ${users.length} users`);
    res.json(users);
  } catch (error) {
    logger.error(`Database error: ${error.message}`);
    res.status(500).json({ error: "Internal server error" });
  }
});

Example 2: Debug Mode Development

const { Logger, LogConfig, LogLevel } = require("logbuddy-js");

const isDevelopment = process.env.NODE_ENV === "development";

const config = LogConfig.with_defaults()
  .with_log_level(isDevelopment ? LogLevel.Debug : LogLevel.Info)
  .with_file_prefix("App_")
  .with_rolling_config({
    size_threshold: 1048576, // 1MB for development
    time_threshold: 3600, // Hourly rotation
  });

const logger = Logger.with_config(config);

logger.debug("This only appears in development mode");
logger.info("This appears in all modes");

Example 3: Error Monitoring

const { Logger, LogConfig, LogLevel } = require("logbuddy-js");

const errorLogger = Logger.with_config(
  LogConfig.with_defaults()
    .with_log_level(LogLevel.Error)
    .with_file_prefix("Errors_")
    .with_rolling_config({
      size_threshold: 10485760, // 10MB
      time_threshold: 86400, // Daily
    })
);

process.on("uncaughtException", (error) => {
  errorLogger.fatal(`Uncaught Exception: ${error.message}`);
  errorLogger.fatal(`Stack: ${error.stack}`);
});

process.on("unhandledRejection", (reason, promise) => {
  errorLogger.error(`Unhandled Rejection at: ${promise}, reason: ${reason}`);
});

🧪 Testing

Run the test example:

npm start

This will run the test file and demonstrate the logging functionality.

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/itsmaazashraf/logbuddy-js.git
cd logbuddy-js
npm install

📝 License

This project is licensed under the ISC License - see the LICENSE file for details.

🐛 Issues & Support

Found a bug or need help? Please open an issue on our GitHub repository.

🌟 Acknowledgments

• Built with ❤️ for the Node.js community
• Inspired by the need for simple, effective logging

Happy Logging! 🪵✨