tru.mjs

/**
 * tru.mjs v1 - Tiny Router Utility
 * Routers without the pain.
 *
 * @author Shinon
 * @license MIT
 */

/**
 * @typedef {Object} TruRouter
 * @property {function(string, function(Record<string, string>): void): TruRouter} add Registers a new route.
 * @property {function(function(string): void): TruRouter} fallback Registers a fallback for unmatched routes.
 * @property {function(string): void} go Programmatically navigates to a new path.
 * @property {function(): TruRouter} start Initializes event listeners and triggers the initial route.
 */

/**
 * Creates a new instance of the Tiny Router Utility.
 * 
 * @returns {TruRouter} The router instance.
 */
export function createRouter() {
  /** @type {Array<{pattern: URLPattern, callback: function(Record<string, string>): void}>} */
  const routes = [];
  
  /** @type {function(string): void} */
  let notFoundHandler = () => console.warn("Route not found");

  /**
   * Internal method to match a URL against registered patterns.
   * @param {string} url - The full URL to match.
   */
  const match = (url) => {
    for (const route of routes) {
      // 1. Let the browser's native API do the heavy lifting
      const result = route.pattern.exec(url);

      if (result) {
        // 2. URLPattern automatically extracts named capture groups!
        // e.g., for '/users/:id', it returns { id: "42" }
        return route.callback(result.pathname.groups);
      }
    }
    return notFoundHandler(new URL(url).pathname);
  };

  /** @type {TruRouter} */
  const router = {
    
    /**
     * Registers a new route.
     * @param {string} path - The path pattern (e.g., '/users/:id').
     * @param {function(Record<string, string>): void} callback - Function to execute when matched.
     * @returns {TruRouter} The router instance for chaining.
     */
    add(path, callback) {
      // Create a native URLPattern. By passing an object,
      // we tell it to strictly match the pathname and ignore the domain.
      routes.push({
        pattern: new URLPattern({ pathname: path }),
        callback,
      });
      return this;
    },

    /**
     * Registers a fallback handler for unmatched routes.
     * @param {function(string): void} callback - Function to execute when no route matches.
     * @returns {TruRouter} The router instance for chaining.
     */
    fallback(callback) {
      notFoundHandler = callback;
      return this;
    },

    /**
     * Programmatically navigates to a new path.
     * @param {string} path - The local path to navigate to.
     */
    go(path) {
      history.pushState(null, "", path);
      match(window.location.href); // Pass the full, newly updated URL
    },

    /**
     * Initializes the router, attaches event listeners, and triggers the initial route.
     * @returns {TruRouter} The router instance.
     */
    start() {
      window.addEventListener("popstate", () => match(window.location.href));

      document.body.addEventListener("click", (e) => {
        /** @type {HTMLAnchorElement | null} */
        const link = e.target.closest("a");

        if (
          link && // Check if link is valid
          link.href && // And has a href
          link.origin === window.location.origin && // Same origin to prevent external navigation
          !link.hasAttribute("download") && // Ignore file downloads
          link.target !== "_blank" &&
          link.target !== "_top" && // Ignore iframe escapes
          !link.hasAttribute("data-bypass") && // Custom escape hatch
          e.button === 0 &&
          !e.metaKey &&
          !e.ctrlKey
        ) {
          // Check if ANY registered pattern matches this URL
          // Note: URLPattern.test() is faster than .exec() just for checking true/false
          const isKnownRoute = routes.some((route) =>
            route.pattern.test(link.href),
          );

          // If we know the route, hijack the click.
          // If we don't know it, do nothing and let the browser handle the error/navigation natively.
          if (isKnownRoute) {
            e.preventDefault();
            router.go(link.href);
          }
        }
      });

      match(window.location.href);
      return this;
    },
  };

  return router;
}