vjsrouter/src/utils/Logger.js

A modern, file-system based router for vanilla JavaScript with SSR support.

// File: src/utils/Logger.js

/**
 * @description Defines the available logging levels.
 * The levels are numerical to allow for easy comparison. A higher number indicates a higher priority.
 * For example, if the current level is WARN (2), only WARN (2) and ERROR (3) messages will be displayed.
 */
export const LogLevel = {
  DEBUG: 0, // Detailed information for debugging purposes.
  INFO: 1,  // General information about library operation.
  WARN: 2,  // Warnings about potential issues or deprecated usage.
  ERROR: 3, // Errors that have been handled but indicate a problem.
  NONE: 4,  // No logging will be output.
};

/**
 * @class Logger
 * @description A singleton class for handling all logging within the vjsrouter library.
 * It provides level-based logging to control output verbosity and formats messages
 * consistently for easy identification and debugging.
 */
class Logger {
  /**
   * The single instance of the Logger.
   * @private
   * @type {Logger|null}
   */
  static #instance = null;

  /**
   * The current logging level. Only messages at or above this level will be logged.
   * @private
   * @type {number}
   */
  #level = LogLevel.INFO; // Default to INFO level.

  /**
   * The constructor is private to enforce the singleton pattern.
   * Use Logger.getInstance() to get the logger instance.
   * @private
   */
  constructor() {
    // The private constructor ensures no one can create a new instance with `new Logger()`.
  }

  /**
   * @description Gets the single, shared instance of the Logger.
   * This ensures that all parts of the library share the same log level and configuration.
   * @returns {Logger} The singleton Logger instance.
   */
  static getInstance() {
    if (!Logger.#instance) {
      Logger.#instance = new Logger();
    }
    return Logger.#instance;
  }

  /**
   * @description Sets the minimum log level for messages to be displayed.
   * For example, setting the level to LogLevel.WARN will suppress DEBUG and INFO messages.
   * @param {number} level - The desired log level from the LogLevel enum.
   */
  setLevel(level) {
    if (typeof level === 'number' && level >= LogLevel.DEBUG && level <= LogLevel.NONE) {
      this.#level = level;
    } else {
      this.warn('Logger', `Invalid log level provided. Using current level: ${this.#level}.`);
    }
  }

  /**
   * @description Logs a message at the DEBUG level.
   * These messages are for detailed, granular debugging and are typically disabled in production.
   * @param {string} source - The name of the module or component logging the message (e.g., 'VJSRouter', 'HistoryManager').
   * @param {string} message - The log message.
   * @param {...any} args - Additional data or objects to include in the log output.
   */
  debug(source, message, ...args) {
    if (this.#level <= LogLevel.DEBUG) {
      console.debug(`[vjsrouter::${source}] DEBUG: ${message}`, ...args);
    }
  }

  /**
   * @description Logs a message at the INFO level.
   * These messages provide general information about the library's state and operations.
   * @param {string} source - The name of the module or component logging the message.
   * @param {string} message - The log message.
   * @param {...any} args - Additional data or objects to include in the log output.
   */
  info(source, message, ...args) {
    if (this.#level <= LogLevel.INFO) {
      console.info(`[vjsrouter::${source}] INFO: ${message}`, ...args);
    }
  }

  /**
   * @description Logs a message at the WARN level.
   * These messages indicate potential problems or deprecated API usage that don't prevent the library from functioning.
   * @param {string} source - The name of the module or component logging the message.
   * @param {string} message - The log message.
   * @param {...any} args - Additional data or objects to include in the log output.
   */
  warn(source, message, ...args) {
    if (this.#level <= LogLevel.WARN) {
      console.warn(`[vjsrouter::${source}] WARN: ${message}`, ...args);
    }
  }

  /**
   * @description Logs a message at the ERROR level.
   * These messages indicate that an error occurred, but it was caught and handled by the library.
   * @param {string} source - The name of the module or component logging the message.
   * @param {string} message - The log message.
   * @param {...any} args - Additional data or objects to include in the log output.
   */
  error(source, message, ...args) {
    if (this.#level <= LogLevel.ERROR) {
      console.error(`[vjsrouter::${source}] ERROR: ${message}`, ...args);
    }
  }
}

// Export a single instance of the logger for the entire library to use.
// This ensures a consistent logging configuration across all modules.
export const logger = Logger.getInstance();