vjsrouter/src/index.js

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

// File: src/index.js

import { VJSRouter } from './core/VJSRouter.js';
import { logger, LogLevel } from './utils/Logger.js';

/**
 * @description A global namespace for the vjsrouter library to expose its core components
 * and provide a single point of access for developers who might want to interact with it.
 * @namespace
 */
const vjsrouter = {
  /**
   * The main router class. Can be used for advanced manual instantiation if needed.
   * @type {typeof VJSRouter}
   */
  Router: VJSRouter,

  /**
   * The active router instance after initialization. Will be null until the DOM is ready.
   * @type {VJSRouter|null}
   */
  instance: null,

  /**
   * Exposes the logger instance so developers can adjust the log level at runtime for debugging.
   * Example: `vjsrouter.logger.setLevel(vjsrouter.LogLevel.DEBUG);`
   * @type {import('./utils/Logger.js').logger}
   */
  logger: logger,

  /**
   * Exposes the LogLevel enum for convenience when setting the log level.
   * @type {import('./utils/Logger.js').LogLevel}
   */
  LogLevel: LogLevel,
};

/**
 * @description The main initialization function for the library.
 * It waits for the DOM to be fully loaded, then creates and starts the router instance.
 * This self-starting mechanism makes the library extremely easy to use via a simple script tag.
 */
function initialize() {
  const source = 'GlobalInitializer';
  logger.info(source, 'DOM content loaded. Initializing vjsrouter...');

  try {
    // Instantiate the router. This will throw an error if the #app container is missing,
    // which is a desired fail-fast behavior.
    const routerInstance = new VJSRouter();

    // Store the instance on the global namespace for potential developer access.
    vjsrouter.instance = routerInstance;

    // Start the router. This will fetch the manifest, set up all listeners, and render the initial page.
    routerInstance.start();

  } catch (error) {
    // The VJSRouter constructor or start method will have already logged the specific error.
    // This catch block is a final safeguard to prevent a library failure from crashing the user's entire script.
    logger.error(source, 'A critical error occurred during router initialization. The router will not be active.', error.message);
  }
}

// --- Self-Initialization Logic ---

// We assign our namespace to the global `window` object so it can be accessed
// from the browser's console or other scripts (e.g., `window.vjsrouter`).
window.vjsrouter = vjsrouter;

// We check if the DOM is already loaded. This handles cases where the script
// might be loaded asynchronously or deferred after the DOMContentLoaded event has already fired.
if (document.readyState === 'loading') {
  // If the document is still loading, we wait for the DOMContentLoaded event.
  // This is the standard and most reliable way to ensure the DOM is ready for manipulation.
  document.addEventListener('DOMContentLoaded', initialize);
} else {
  // If the DOM is already interactive or complete, we can initialize immediately.
  initialize();
}