@b9g/router 0.1.10 → 0.2.0-beta.1

package/src/index.js

@@ -6,15 +6,17 @@ import {
   compilePathname
 } from "@b9g/match-pattern";
 import {
+  isHTTPError,
   InternalServerError,
-  NotFound,
-  isHTTPError
+  NotFound
 } from "@b9g/http-errors";
+import { getLogger } from "@logtape/logtape";
+var logger = getLogger(["shovel", "router"]);
 var RadixNode = class {
   children;
   // char -> RadixNode
-  handlers;
-  // method -> handler
+  routes;
+  // method -> RouteEntry
   paramName;
   // param name if this is a :param segment
   paramChild;
@@ -23,7 +25,7 @@ var RadixNode = class {
   // child node for * wildcard
   constructor() {
     this.children = /* @__PURE__ */ new Map();
-    this.handlers = /* @__PURE__ */ new Map();
+    this.routes = /* @__PURE__ */ new Map();
     this.paramName = null;
     this.paramChild = null;
     this.wildcardChild = null;
@@ -38,22 +40,17 @@ var RadixTreeExecutor = class {
     for (const route of routes) {
       const pathname = route.pattern.pathname;
       if (isSimplePattern(pathname)) {
-        this.#addToTree(pathname, route.method, route.handler);
+        this.#addToTree(pathname, route);
       } else {
         const compiled = compilePathname(pathname);
-        this.#complexRoutes.push({
-          compiled,
-          method: route.method,
-          handler: route.handler,
-          pattern: route.pattern
-        });
+        this.#complexRoutes.push({ compiled, route });
       }
     }
   }
   /**
    * Add a simple pattern to the radix tree
    */
-  #addToTree(pathname, method, handler) {
+  #addToTree(pathname, route) {
     let node = this.#root;
     let i = 0;
     while (i < pathname.length) {
@@ -84,15 +81,18 @@ var RadixTreeExecutor = class {
       node = node.children.get(char);
       i++;
     }
-    node.handlers.set(method, handler);
+    node.routes.set(route.method, route);
   }
   /**
-   * Match a pathname against the radix tree
+   * Match a pathname against the radix tree (for URL matching)
    */
-  #matchTree(pathname, method) {
+  #matchTreeByPath(pathname) {
     const params = {};
     let node = this.#root;
     let i = 0;
+    if (!pathname) {
+      return node.routes.size > 0 ? { node, params } : null;
+    }
     while (i < pathname.length) {
       const char = pathname[i];
       if (node.children.has(char)) {
@@ -121,55 +121,101 @@ var RadixTreeExecutor = class {
       }
       return null;
     }
-    let handler = node.handlers.get(method);
-    if (!handler && method === "HEAD") {
-      handler = node.handlers.get("GET");
+    if (node.routes.size > 0) {
+      return { node, params };
     }
-    if (handler) {
-      return { handler, params };
+    if (node.wildcardChild && node.wildcardChild.routes.size > 0) {
+      params["0"] = "";
+      return { node: node.wildcardChild, params };
     }
-    if (node.wildcardChild) {
-      let wildcardHandler = node.wildcardChild.handlers.get(method);
-      if (!wildcardHandler && method === "HEAD") {
-        wildcardHandler = node.wildcardChild.handlers.get("GET");
-      }
-      if (wildcardHandler) {
-        params["0"] = "";
-        return { handler: wildcardHandler, params };
+    return null;
+  }
+  /**
+   * Match a pathname against the radix tree (for request handling with method)
+   */
+  #matchTree(pathname, method) {
+    const result = this.#matchTreeByPath(pathname);
+    if (!result) return null;
+    const { node, params } = result;
+    let entry = node.routes.get(method);
+    if (!entry && method === "HEAD") {
+      entry = node.routes.get("GET");
+    }
+    if (entry) {
+      return { entry, params };
+    }
+    return null;
+  }
+  /**
+   * Match a URL against registered routes (returns RouteMatch info)
+   */
+  matchURL(url) {
+    const urlObj = typeof url === "string" ? new URL(url, "http://localhost") : url;
+    const pathname = urlObj.pathname;
+    const treeResult = this.#matchTreeByPath(pathname);
+    if (treeResult) {
+      const { node, params } = treeResult;
+      const methods = Array.from(node.routes.keys());
+      const firstEntry = node.routes.values().next().value;
+      return {
+        params,
+        methods,
+        name: firstEntry?.name,
+        pattern: firstEntry?.pattern.pathname ?? ""
+      };
+    }
+    for (const { compiled, route } of this.#complexRoutes) {
+      const match = pathname.match(compiled.regex);
+      if (match) {
+        const params = {};
+        for (let i = 0; i < compiled.paramNames.length; i++) {
+          if (match[i + 1] !== void 0) {
+            params[compiled.paramNames[i]] = match[i + 1];
+          }
+        }
+        const methods = this.#complexRoutes.filter((r) => r.route.pattern.pathname === route.pattern.pathname).map((r) => r.route.method);
+        return {
+          params,
+          methods,
+          name: route.name,
+          pattern: route.pattern.pathname
+        };
       }
     }
     return null;
   }
   /**
-   * Find the first route that matches the request
+   * Find the first route that matches the request (for handling)
    */
-  match(request) {
+  matchRequest(request) {
     const url = new URL(request.url);
     const method = request.method.toUpperCase();
     const pathname = url.pathname;
     const treeResult = this.#matchTree(pathname, method);
     if (treeResult) {
       return {
-        handler: treeResult.handler,
-        context: { params: treeResult.params }
+        handler: treeResult.entry.handler,
+        context: { params: treeResult.params },
+        entry: treeResult.entry
       };
     }
-    for (const route of this.#complexRoutes) {
+    for (const { compiled, route } of this.#complexRoutes) {
       const methodMatches = route.method === method || method === "HEAD" && route.method === "GET";
       if (!methodMatches) {
         continue;
       }
-      const match = pathname.match(route.compiled.regex);
+      const match = pathname.match(compiled.regex);
       if (match) {
         const params = {};
-        for (let i = 0; i < route.compiled.paramNames.length; i++) {
+        for (let i = 0; i < compiled.paramNames.length; i++) {
           if (match[i + 1] !== void 0) {
-            params[route.compiled.paramNames[i]] = match[i + 1];
+            params[compiled.paramNames[i]] = match[i + 1];
           }
         }
         return {
           handler: route.handler,
-          context: { params }
+          context: { params },
+          entry: route
         };
       }
     }
@@ -179,57 +225,110 @@ var RadixTreeExecutor = class {
 var RouteBuilder = class {
   #router;
   #pattern;
-  constructor(router, pattern) {
+  #name;
+  #middlewares;
+  constructor(router, pattern, options) {
     this.#router = router;
     this.#pattern = pattern;
+    this.#name = options?.name;
+    this.#middlewares = [];
+  }
+  /**
+   * Add route-scoped middleware that only runs when this pattern matches
+   */
+  use(middleware) {
+    this.#middlewares.push(middleware);
+    return this;
   }
   /**
    * Register a GET handler for this route pattern
    */
   get(handler) {
-    this.#router.addRoute("GET", this.#pattern, handler);
+    this.#router.addRoute(
+      "GET",
+      this.#pattern,
+      handler,
+      this.#name,
+      this.#middlewares
+    );
     return this;
   }
   /**
    * Register a POST handler for this route pattern
    */
   post(handler) {
-    this.#router.addRoute("POST", this.#pattern, handler);
+    this.#router.addRoute(
+      "POST",
+      this.#pattern,
+      handler,
+      this.#name,
+      this.#middlewares
+    );
     return this;
   }
   /**
    * Register a PUT handler for this route pattern
    */
   put(handler) {
-    this.#router.addRoute("PUT", this.#pattern, handler);
+    this.#router.addRoute(
+      "PUT",
+      this.#pattern,
+      handler,
+      this.#name,
+      this.#middlewares
+    );
     return this;
   }
   /**
    * Register a DELETE handler for this route pattern
    */
   delete(handler) {
-    this.#router.addRoute("DELETE", this.#pattern, handler);
+    this.#router.addRoute(
+      "DELETE",
+      this.#pattern,
+      handler,
+      this.#name,
+      this.#middlewares
+    );
     return this;
   }
   /**
    * Register a PATCH handler for this route pattern
    */
   patch(handler) {
-    this.#router.addRoute("PATCH", this.#pattern, handler);
+    this.#router.addRoute(
+      "PATCH",
+      this.#pattern,
+      handler,
+      this.#name,
+      this.#middlewares
+    );
     return this;
   }
   /**
    * Register a HEAD handler for this route pattern
    */
   head(handler) {
-    this.#router.addRoute("HEAD", this.#pattern, handler);
+    this.#router.addRoute(
+      "HEAD",
+      this.#pattern,
+      handler,
+      this.#name,
+      this.#middlewares
+    );
     return this;
   }
   /**
    * Register an OPTIONS handler for this route pattern
    */
   options(handler) {
-    this.#router.addRoute("OPTIONS", this.#pattern, handler);
+    this.#router.addRoute(
+      "OPTIONS",
+      this.#pattern,
+      handler,
+      this.#name,
+      this.#middlewares
+    );
     return this;
   }
   /**
@@ -246,51 +345,34 @@ var RouteBuilder = class {
       "OPTIONS"
     ];
     methods.forEach((method) => {
-      this.#router.addRoute(method, this.#pattern, handler);
+      this.#router.addRoute(
+        method,
+        this.#pattern,
+        handler,
+        this.#name,
+        this.#middlewares
+      );
     });
     return this;
   }
 };
 var Router = class {
-  #routes;
-  #middlewares;
+  routes;
+  middlewares;
   #executor;
-  #dirty;
   constructor() {
-    this.#routes = [];
-    this.#middlewares = [];
+    this.routes = [];
+    this.middlewares = [];
     this.#executor = null;
-    this.#dirty = false;
-    this.#handlerImpl = async (request) => {
-      try {
-        if (this.#dirty || !this.#executor) {
-          this.#executor = new RadixTreeExecutor(this.#routes);
-          this.#dirty = false;
-        }
-        const matchResult = this.#executor.match(request);
-        if (matchResult) {
-          return await this.#executeMiddlewareStack(
-            this.#middlewares,
-            request,
-            matchResult.context,
-            matchResult.handler
-          );
-        } else {
-          const notFoundHandler = async () => {
-            throw new NotFound();
-          };
-          return await this.#executeMiddlewareStack(
-            this.#middlewares,
-            request,
-            { params: {} },
-            notFoundHandler
-          );
-        }
-      } catch (error) {
-        return this.#createErrorResponse(error);
-      }
-    };
-    this.handler = this.#handlerImpl;
+  }
+  /**
+   * Ensure the executor is compiled and up to date
+   */
+  #ensureCompiled() {
+    if (!this.#executor) {
+      this.#executor = new RadixTreeExecutor(this.routes);
+    }
+    return this.#executor;
   }
   use(pathPrefixOrMiddleware, maybeMiddleware) {
     if (typeof pathPrefixOrMiddleware === "string") {
@@ -300,7 +382,7 @@ var Router = class {
           "Invalid middleware type. Must be function or async generator function."
         );
       }
-      this.#middlewares.push({
+      this.middlewares.push({
         middleware,
         pathPrefix: pathPrefixOrMiddleware
       });
@@ -310,95 +392,89 @@ var Router = class {
           "Invalid middleware type. Must be function or async generator function."
         );
       }
-      this.#middlewares.push({ middleware: pathPrefixOrMiddleware });
+      this.middlewares.push({ middleware: pathPrefixOrMiddleware });
     }
-    this.#dirty = true;
+    this.#executor = null;
   }
-  route(patternOrConfig) {
-    if (typeof patternOrConfig === "string") {
-      return new RouteBuilder(this, patternOrConfig);
-    } else {
-      return new RouteBuilder(this, patternOrConfig.pattern);
-    }
+  /**
+   * Create a route builder for the given pattern
+   * Returns a chainable interface for registering HTTP method handlers
+   *
+   * Example:
+   *   router.route('/api/users/:id', { name: 'user' })
+   *     .use(authMiddleware)
+   *     .get(getUserHandler)
+   *     .put(updateUserHandler);
+   */
+  route(pattern, options) {
+    return new RouteBuilder(this, pattern, options);
   }
   /**
    * Internal method called by RouteBuilder to register routes
    * Public for RouteBuilder access, but not intended for direct use
    */
-  addRoute(method, pattern, handler) {
+  addRoute(method, pattern, handler, name, middlewares = []) {
     const matchPattern = new MatchPattern(pattern);
-    this.#routes.push({
+    this.routes.push({
       pattern: matchPattern,
       method: method.toUpperCase(),
-      handler
+      handler,
+      name,
+      middlewares
     });
-    this.#dirty = true;
+    this.#executor = null;
   }
   /**
-   * Handle a request - main entrypoint for ServiceWorker usage
-   * Returns a response or throws if no route matches
+   * Match a URL against registered routes
+   * Returns route info (params, methods, name, pattern) or null if no match
+   * Does not execute handlers - use handle() for that
    */
-  handler;
-  #handlerImpl;
+  match(url) {
+    const executor = this.#ensureCompiled();
+    return executor.matchURL(url);
+  }
   /**
-   * Match a request against registered routes and execute the handler chain
-   * Returns the response from the matched handler, or null if no route matches
-   * Note: Global middleware executes even if no route matches
+   * Handle a request - main entrypoint for ServiceWorker usage
+   * Executes the matched handler with middleware chain
    */
-  async match(request) {
-    if (this.#dirty || !this.#executor) {
-      this.#executor = new RadixTreeExecutor(this.#routes);
-      this.#dirty = false;
-    }
-    let matchResult = this.#executor.match(request);
-    let handler;
-    let context;
-    if (matchResult) {
-      handler = matchResult.handler;
-      context = matchResult.context;
-    } else {
-      handler = async () => {
-        throw new NotFound();
-      };
-      context = { params: {} };
-    }
-    let response;
+  async handle(request) {
+    const executor = this.#ensureCompiled();
     try {
-      response = await this.#executeMiddlewareStack(
-        this.#middlewares,
+      const matchResult = executor.matchRequest(request);
+      let handler;
+      let context;
+      let routeMiddleware = [];
+      if (matchResult) {
+        if (!matchResult.handler) {
+          throw new NotFound("Route has no handler");
+        }
+        handler = matchResult.handler;
+        context = matchResult.context;
+        routeMiddleware = matchResult.entry.middlewares;
+      } else {
+        handler = async () => {
+          throw new NotFound();
+        };
+        context = { params: {} };
+      }
+      let response = await this.#executeMiddlewareStack(
+        this.middlewares,
+        routeMiddleware,
         request,
         context,
         handler
       );
-    } catch (error) {
-      if (!matchResult && isHTTPError(error) && error.status === 404) {
-        return null;
+      if (request.method.toUpperCase() === "HEAD") {
+        response = new Response(null, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers
+        });
       }
-      throw error;
-    }
-    if (!matchResult && response?.status === 404) {
-      return null;
-    }
-    if (response && request.method.toUpperCase() === "HEAD") {
-      response = new Response(null, {
-        status: response.status,
-        statusText: response.statusText,
-        headers: response.headers
-      });
+      return response;
+    } catch (error) {
+      return this.#createErrorResponse(error);
     }
-    return response;
-  }
-  /**
-   * Get registered routes for debugging/introspection
-   */
-  getRoutes() {
-    return [...this.#routes];
-  }
-  /**
-   * Get registered middleware for debugging/introspection
-   */
-  getMiddlewares() {
-    return [...this.#middlewares];
   }
   /**
    * Mount a subrouter at a specific path prefix
@@ -415,19 +491,21 @@ var Router = class {
    */
   mount(mountPath, subrouter) {
     const normalizedMountPath = this.#normalizeMountPath(mountPath);
-    const subroutes = subrouter.getRoutes();
+    const subroutes = subrouter.routes;
     for (const subroute of subroutes) {
       const mountedPattern = this.#combinePaths(
         normalizedMountPath,
         subroute.pattern.pathname
       );
-      this.#routes.push({
+      this.routes.push({
         pattern: new MatchPattern(mountedPattern),
         method: subroute.method,
-        handler: subroute.handler
+        handler: subroute.handler,
+        name: subroute.name,
+        middlewares: subroute.middlewares
       });
     }
-    const submiddlewares = subrouter.getMiddlewares();
+    const submiddlewares = subrouter.middlewares;
     for (const submiddleware of submiddlewares) {
       let composedPrefix;
       if (submiddleware.pathPrefix) {
@@ -438,12 +516,12 @@ var Router = class {
       } else {
         composedPrefix = normalizedMountPath;
       }
-      this.#middlewares.push({
+      this.middlewares.push({
         middleware: submiddleware.middleware,
         pathPrefix: composedPrefix
       });
     }
-    this.#dirty = true;
+    this.#executor = null;
   }
   /**
    * Normalize mount path: ensure it starts with / and doesn't end with /
@@ -498,39 +576,58 @@ var Router = class {
     }
     return false;
   }
+  /**
+   * Execute a single middleware and track generator state
+   * Returns true if middleware short-circuited (returned Response early)
+   */
+  async #executeMiddleware(middleware, request, context, runningGenerators) {
+    if (this.#isGeneratorMiddleware(middleware)) {
+      const generator = middleware(request, context);
+      const result = await generator.next();
+      if (result.done) {
+        if (result.value) {
+          return result.value;
+        }
+      } else {
+        runningGenerators.push({ generator });
+      }
+    } else {
+      const result = await middleware(request, context);
+      if (result) {
+        return result;
+      }
+    }
+    return null;
+  }
   /**
    * Execute middleware stack with guaranteed execution using Rack-style LIFO order
+   * Global/path middleware runs first, then route-scoped middleware, then handler
    */
-  async #executeMiddlewareStack(middlewares, request, context, handler) {
+  async #executeMiddlewareStack(globalMiddlewares, routeMiddlewares, request, context, handler) {
     const runningGenerators = [];
     let currentResponse = null;
     const requestPathname = new URL(request.url).pathname;
-    for (let i = 0; i < middlewares.length; i++) {
-      const entry = middlewares[i];
-      const middleware = entry.middleware;
+    for (const entry of globalMiddlewares) {
       if (entry.pathPrefix && !this.#matchesPathPrefix(requestPathname, entry.pathPrefix)) {
         continue;
       }
-      if (this.#isGeneratorMiddleware(middleware)) {
-        const generator = middleware(request, context);
-        const result = await generator.next();
-        if (result.done) {
-          if (result.value) {
-            currentResponse = result.value;
-            break;
-          }
-        } else {
-          runningGenerators.push({ generator, index: i });
-        }
-      } else {
-        const result = await middleware(
+      currentResponse = await this.#executeMiddleware(
+        entry.middleware,
+        request,
+        context,
+        runningGenerators
+      );
+      if (currentResponse) break;
+    }
+    if (!currentResponse) {
+      for (const middleware of routeMiddlewares) {
+        currentResponse = await this.#executeMiddleware(
+          middleware,
           request,
-          context
+          context,
+          runningGenerators
         );
-        if (result) {
-          currentResponse = result;
-          break;
-        }
+        if (currentResponse) break;
       }
     }
     if (!currentResponse) {
@@ -575,48 +672,20 @@ var Router = class {
     }
     throw error;
   }
-  /**
-   * Get route statistics
-   */
-  getStats() {
-    return {
-      routeCount: this.#routes.length,
-      middlewareCount: this.#middlewares.length,
-      compiled: !this.#dirty && this.#executor !== null
-    };
-  }
   /**
    * Create an error response for unhandled errors
    * Uses HTTPError.toResponse() for consistent error formatting
    */
   #createErrorResponse(error) {
-    const httpError = isHTTPError(error) ? error : new InternalServerError(error.message, { cause: error });
     const isDev = import.meta.env?.MODE !== "production";
+    if (isDev && !isHTTPError(error)) {
+      logger.error`Unhandled error: ${error}`;
+    }
+    const httpError = isHTTPError(error) ? error : new InternalServerError(error.message, { cause: error });
     return httpError.toResponse(isDev);
   }
 };
-function trailingSlash(mode) {
-  return (request, _context) => {
-    const url = new URL(request.url);
-    const pathname = url.pathname;
-    if (pathname === "/")
-      return;
-    let newPathname = null;
-    if (mode === "strip" && pathname.endsWith("/")) {
-      newPathname = pathname.slice(0, -1);
-    } else if (mode === "add" && !pathname.endsWith("/")) {
-      newPathname = pathname + "/";
-    }
-    if (newPathname) {
-      url.pathname = newPathname;
-      return new Response(null, {
-        status: 301,
-        headers: { Location: url.toString() }
-      });
-    }
-  };
-}
 export {
-  Router,
-  trailingSlash
+  RouteBuilder,
+  Router
 };