@b9g/router 0.1.6 → 0.1.8

package/README.md

@@ -117,7 +117,7 @@ router.use(cacheMiddleware);
 - `GeneratorMiddleware` - Generator-based middleware type using `yield`
 - `FunctionMiddleware` - Simple function middleware type
 - `Middleware` - Union of GeneratorMiddleware | FunctionMiddleware
-- `HttpMethod` - HTTP method string literal type
+- `HTTPMethod` - HTTP method string literal type
 - `RouteConfig` - Route configuration object
 
 ## API Reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/router",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Universal request router for ServiceWorker applications. Built on web standards with cache-aware routing and generator-based middleware.",
   "keywords": [
     "router",
@@ -13,6 +13,7 @@
     "shovel"
   ],
   "dependencies": {
+    "@b9g/http-errors": "^0.1.5",
     "@b9g/match-pattern": "^0.1.7"
   },
   "devDependencies": {

package/src/index.d.ts

@@ -30,14 +30,14 @@ export type Handler = (request: Request, context: RouteContext) => Response | Pr
  * Generator middleware signature - uses yield for continuation
  * Provides clean syntax and eliminates control flow bugs
  */
-export type GeneratorMiddleware = (request: Request, context: RouteContext) => AsyncGenerator<Request, Response | null | undefined, Response>;
+export type GeneratorMiddleware = (request: Request, context: RouteContext) => Generator<Request, Response | null | undefined, Response> | AsyncGenerator<Request, Response | null | undefined, Response>;
 /**
  * Function middleware signature - supports short-circuiting
  * Can modify request and context, and can return a Response to short-circuit
  * - Return Response: short-circuits, skipping remaining middleware and handler
  * - Return null/undefined: continues to next middleware (fallthrough)
  */
-export type FunctionMiddleware = (request: Request, context: RouteContext) => null | undefined | Response | Promise<null | undefined | Response>;
+export type FunctionMiddleware = (request: Request, context: RouteContext) => Response | null | undefined | Promise<Response | null | undefined>;
 /**
  * Union type for all supported middleware types
  * Framework automatically detects type and executes appropriately
@@ -46,7 +46,7 @@ export type Middleware = GeneratorMiddleware | FunctionMiddleware;
 /**
  * HTTP methods supported by the router
  */
-export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+export type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
 /**
  * Route configuration options
  */
@@ -67,6 +67,8 @@ interface RouteEntry {
  */
 interface MiddlewareEntry {
     middleware: Middleware;
+    /** If set, middleware only runs for paths matching this prefix */
+    pathPrefix?: string;
 }
 /**
  * RouteBuilder provides a chainable API for defining routes with multiple HTTP methods
@@ -126,9 +128,9 @@ export declare class Router {
      */
     use(middleware: Middleware): void;
     /**
-     * Register a handler for a specific pattern
+     * Register middleware that only applies to routes matching the path prefix
      */
-    use(pattern: string, handler: Handler): void;
+    use(pathPrefix: string, middleware: Middleware): void;
     /**
      * Create a route builder for the given pattern
      * Returns a chainable interface for registering HTTP method handlers
@@ -144,7 +146,7 @@ export declare class Router {
      * Internal method called by RouteBuilder to register routes
      * Public for RouteBuilder access, but not intended for direct use
      */
-    addRoute(method: HttpMethod, pattern: string, handler: Handler): void;
+    addRoute(method: HTTPMethod, pattern: string, handler: Handler): void;
     /**
      * Handle a request - main entrypoint for ServiceWorker usage
      * Returns a response or throws if no route matches
@@ -187,4 +189,28 @@ export declare class Router {
         compiled: boolean;
     };
 }
+/**
+ * Mode for trailing slash normalization
+ * - "strip": Redirect /path/ → /path (removes trailing slash)
+ * - "add": Redirect /path → /path/ (adds trailing slash)
+ */
+export type TrailingSlashMode = "strip" | "add";
+/**
+ * Middleware that normalizes trailing slashes via 301 redirect
+ *
+ * @param mode - "strip" removes trailing slash, "add" adds trailing slash
+ * @returns Function middleware that redirects non-canonical URLs
+ *
+ * @example
+ * ```typescript
+ * import { Router, trailingSlash } from "@b9g/router";
+ *
+ * const router = new Router();
+ * router.use(trailingSlash("strip")); // Redirect /path/ → /path
+ *
+ * // Can also be scoped to specific paths
+ * router.use("/api", trailingSlash("strip"));
+ * ```
+ */
+export declare function trailingSlash(mode: TrailingSlashMode): FunctionMiddleware;
 export {};

package/src/index.js

@@ -5,6 +5,11 @@ import {
   isSimplePattern,
   compilePathname
 } from "@b9g/match-pattern";
+import {
+  InternalServerError,
+  NotFound,
+  isHTTPError
+} from "@b9g/http-errors";
 var RadixNode = class {
   children;
   // char -> RadixNode
@@ -116,12 +121,18 @@ var RadixTreeExecutor = class {
       }
       return null;
     }
-    const handler = node.handlers.get(method);
+    let handler = node.handlers.get(method);
+    if (!handler && method === "HEAD") {
+      handler = node.handlers.get("GET");
+    }
     if (handler) {
       return { handler, params };
     }
     if (node.wildcardChild) {
-      const wildcardHandler = node.wildcardChild.handlers.get(method);
+      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 };
@@ -144,7 +155,8 @@ var RadixTreeExecutor = class {
       };
     }
     for (const route of this.#complexRoutes) {
-      if (route.method !== method) {
+      const methodMatches = route.method === method || method === "HEAD" && route.method === "GET";
+      if (!methodMatches) {
         continue;
       }
       const match = pathname.match(route.compiled.regex);
@@ -268,7 +280,7 @@ var Router = class {
           );
         } else {
           const notFoundHandler = async () => {
-            return new Response("Not Found", { status: 404 });
+            throw new NotFound();
           };
           const mutableRequest = this.#createMutableRequest(request);
           return await this.#executeMiddlewareStack(
@@ -286,28 +298,27 @@ var Router = class {
     };
     this.handler = this.#handlerImpl;
   }
-  use(patternOrMiddleware, handler) {
-    if (typeof patternOrMiddleware === "string" && handler) {
-      this.addRoute("GET", patternOrMiddleware, handler);
-      this.addRoute("POST", patternOrMiddleware, handler);
-      this.addRoute("PUT", patternOrMiddleware, handler);
-      this.addRoute("DELETE", patternOrMiddleware, handler);
-      this.addRoute("PATCH", patternOrMiddleware, handler);
-      this.addRoute("HEAD", patternOrMiddleware, handler);
-      this.addRoute("OPTIONS", patternOrMiddleware, handler);
-    } else if (typeof patternOrMiddleware === "function") {
-      if (!this.#isValidMiddleware(patternOrMiddleware)) {
+  use(pathPrefixOrMiddleware, maybeMiddleware) {
+    if (typeof pathPrefixOrMiddleware === "string") {
+      const middleware = maybeMiddleware;
+      if (!this.#isValidMiddleware(middleware)) {
         throw new Error(
           "Invalid middleware type. Must be function or async generator function."
         );
       }
-      this.#middlewares.push({ middleware: patternOrMiddleware });
-      this.#dirty = true;
+      this.#middlewares.push({
+        middleware,
+        pathPrefix: pathPrefixOrMiddleware
+      });
     } else {
-      throw new Error(
-        "Invalid middleware type. Must be function or async generator function."
-      );
+      if (!this.#isValidMiddleware(pathPrefixOrMiddleware)) {
+        throw new Error(
+          "Invalid middleware type. Must be function or async generator function."
+        );
+      }
+      this.#middlewares.push({ middleware: pathPrefixOrMiddleware });
     }
+    this.#dirty = true;
   }
   route(patternOrConfig) {
     if (typeof patternOrConfig === "string") {
@@ -354,21 +365,38 @@ var Router = class {
       handler = matchResult.handler;
       context = matchResult.context;
     } else {
-      handler = async () => new Response("Not Found", { status: 404 });
+      handler = async () => {
+        throw new NotFound();
+      };
       context = { params: {} };
     }
-    const response = await this.#executeMiddlewareStack(
-      this.#middlewares,
-      mutableRequest,
-      context,
-      handler,
-      originalURL,
-      this.#executor
-      // Pass executor for re-routing
-    );
+    let response;
+    try {
+      response = await this.#executeMiddlewareStack(
+        this.#middlewares,
+        mutableRequest,
+        context,
+        handler,
+        originalURL,
+        this.#executor
+        // Pass executor for re-routing
+      );
+    } catch (error) {
+      if (!matchResult && isHTTPError(error) && error.status === 404) {
+        return null;
+      }
+      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;
   }
   /**
@@ -412,7 +440,19 @@ var Router = class {
     }
     const submiddlewares = subrouter.getMiddlewares();
     for (const submiddleware of submiddlewares) {
-      this.#middlewares.push(submiddleware);
+      let composedPrefix;
+      if (submiddleware.pathPrefix) {
+        composedPrefix = this.#combinePaths(
+          normalizedMountPath,
+          submiddleware.pathPrefix
+        );
+      } else {
+        composedPrefix = normalizedMountPath;
+      }
+      this.#middlewares.push({
+        middleware: submiddleware.middleware,
+        pathPrefix: composedPrefix
+      });
     }
     this.#dirty = true;
   }
@@ -445,13 +485,29 @@ var Router = class {
    */
   #isValidMiddleware(middleware) {
     const constructorName = middleware.constructor.name;
-    return constructorName === "AsyncGeneratorFunction" || constructorName === "AsyncFunction" || constructorName === "Function";
+    return constructorName === "AsyncGeneratorFunction" || constructorName === "GeneratorFunction" || constructorName === "AsyncFunction" || constructorName === "Function";
   }
   /**
    * Detect if a function is a generator middleware
    */
   #isGeneratorMiddleware(middleware) {
-    return middleware.constructor.name === "AsyncGeneratorFunction";
+    const name = middleware.constructor.name;
+    return name === "GeneratorFunction" || name === "AsyncGeneratorFunction";
+  }
+  /**
+   * Check if a request pathname matches a middleware's path prefix
+   * Matches on segment boundaries: /admin matches /admin, /admin/, /admin/users
+   * but NOT /administrator
+   */
+  #matchesPathPrefix(pathname, pathPrefix) {
+    if (pathname === pathPrefix) {
+      return true;
+    }
+    if (pathname.startsWith(pathPrefix)) {
+      const nextChar = pathname[pathPrefix.length];
+      return nextChar === "/" || nextChar === void 0;
+    }
+    return false;
   }
   /**
    * Execute middleware stack with guaranteed execution using Rack-style LIFO order
@@ -459,8 +515,13 @@ var Router = class {
   async #executeMiddlewareStack(middlewares, request, context, handler, originalURL, executor) {
     const runningGenerators = [];
     let currentResponse = null;
+    const requestPathname = new URL(request.url).pathname;
     for (let i = 0; i < middlewares.length; i++) {
-      const middleware = middlewares[i].middleware;
+      const entry = middlewares[i];
+      const middleware = entry.middleware;
+      if (entry.pathPrefix && !this.#matchesPathPrefix(requestPathname, entry.pathPrefix)) {
+        continue;
+      }
       if (this.#isGeneratorMiddleware(middleware)) {
         const generator = middleware(request, context);
         const result = await generator.next();
@@ -506,10 +567,18 @@ var Router = class {
         handlerError = error;
       }
       if (handlerError) {
-        currentResponse = await this.#handleErrorThroughGenerators(
-          handlerError,
-          runningGenerators
-        );
+        if (request.url !== originalURL) {
+          currentResponse = this.#handleAutomaticRedirect(
+            originalURL,
+            request.url,
+            request.method
+          );
+        } else {
+          currentResponse = await this.#handleErrorThroughGenerators(
+            handlerError,
+            runningGenerators
+          );
+        }
       }
     }
     if (request.url !== originalURL && currentResponse) {
@@ -522,7 +591,7 @@ var Router = class {
     for (let i = runningGenerators.length - 1; i >= 0; i--) {
       const { generator } = runningGenerators[i];
       const result = await generator.next(currentResponse);
-      if (result.value) {
+      if (result.value && result.done) {
         currentResponse = result.value;
       }
     }
@@ -536,7 +605,7 @@ var Router = class {
       const { generator } = runningGenerators[i];
       try {
         const result = await generator.throw(error);
-        if (result.value) {
+        if (result.done && result.value) {
           runningGenerators.splice(i, 1);
           return result.value;
         }
@@ -612,40 +681,36 @@ var Router = class {
   }
   /**
    * Create an error response for unhandled errors
-   * In development mode, includes error details; in production, returns generic message
+   * Uses HTTPError.toResponse() for consistent error formatting
    */
   #createErrorResponse(error) {
-    const isDev = typeof import.meta !== "undefined" && import.meta.env?.MODE !== "production";
-    if (isDev) {
-      const html = `<!DOCTYPE html>
-<html>
-<head>
-  <title>500 Internal Server Error</title>
-  <style>
-    body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
-    h1 { color: #dc2626; }
-    pre { background: #1e1e1e; color: #d4d4d4; padding: 1rem; overflow-x: auto; border-radius: 4px; }
-    .message { font-size: 1.25rem; color: #374151; }
-  </style>
-</head>
-<body>
-  <h1>500 Internal Server Error</h1>
-  <p class="message">${escapeHtml(error.message)}</p>
-  <pre>${escapeHtml(error.stack || "No stack trace available")}</pre>
-</body>
-</html>`;
-      return new Response(html, {
-        status: 500,
-        headers: { "Content-Type": "text/html; charset=utf-8" }
-      });
-    } else {
-      return new Response("Internal Server Error", { status: 500 });
-    }
+    const httpError = isHTTPError(error) ? error : new InternalServerError(error.message, { cause: error });
+    const isDev = import.meta.env?.MODE !== "production";
+    return httpError.toResponse(isDev);
   }
 };
-function escapeHtml(str) {
-  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
+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
+  Router,
+  trailingSlash
 };