@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.101

package/src/host/router.ts

@@ -14,22 +14,23 @@ import type {
   HostPattern,
   RouteEntry,
   HostMatchResult,
-} from './types.js';
+} from "./types.js";
+import type { RouterRequestInput } from "../router/router-interfaces.js";
 import {
   matchPattern,
   parseRequest,
   normalizePattern,
   validatePattern,
-} from './pattern-matcher.js';
+} from "./pattern-matcher.js";
 import {
   handleCookieOverride,
   createCookieErrorResponse,
-} from './cookie-handler.js';
+} from "./cookie-handler.js";
 import {
   HostRouterError,
   NoRouteMatchError,
   InvalidHandlerError,
-} from './errors.js';
+} from "./errors.js";
 
 /**
  * Registry entry for a host router instance.
@@ -46,7 +47,8 @@ export interface HostRouterRegistryEntry {
  * Populated by createHostRouter() so the build-time discovery plugin can find
  * host routers and resolve their lazy handlers to trigger sub-app createRouter() calls.
  */
-export const HostRouterRegistry: Map<string, HostRouterRegistryEntry> = new Map();
+export const HostRouterRegistry: Map<string, HostRouterRegistryEntry> =
+  new Map();
 
 let hostRouterAutoId = 0;
 
@@ -71,7 +73,7 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
    */
   function createRouteBuilder(
     patterns: string[],
-    isFallback = false
+    isFallback = false,
   ): HostRouteBuilder {
     const middleware: Middleware[] = [];
 
@@ -96,8 +98,8 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
         }
 
         log(
-          `Registered ${isFallback ? 'fallback' : 'route'}:`,
-          patterns.join(', ')
+          `Registered ${isFallback ? "fallback" : "route"}:`,
+          patterns.join(", "),
         );
 
         return router;
@@ -110,9 +112,9 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
    */
   function findMatchingRoute(
     hostname: string,
-    pathname: string
+    pathname: string,
   ): RouteEntry | null {
-    const parts = hostname.split('.');
+    const parts = hostname.split(".");
 
     for (const route of routes) {
       for (const pattern of route.patterns) {
@@ -132,8 +134,8 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
   async function executeMiddleware(
     middleware: Middleware[],
     request: Request,
-    context: any,
-    finalHandler: () => Promise<Response>
+    input: RouterRequestInput<any>,
+    finalHandler: () => Promise<Response>,
   ): Promise<Response> {
     let index = 0;
 
@@ -147,7 +149,20 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
         return finalHandler();
       }
 
-      return mw(request, context, next);
+      // Guard against double next() calls — a second call would
+      // re-enter the downstream chain and run handlers/side-effects twice.
+      let nextCalled = false;
+      const guardedNext = (): Promise<Response> => {
+        if (nextCalled) {
+          throw new Error(
+            `[HostRouter] Middleware called next() more than once.`,
+          );
+        }
+        nextCalled = true;
+        return next();
+      };
+
+      return mw(request, input, guardedNext);
     }
 
     return next();
@@ -159,34 +174,34 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
   async function executeHandler(
     handler: Handler | LazyHandler,
     request: Request,
-    context: any
+    input: RouterRequestInput<any>,
   ): Promise<Response> {
     // Check if it's a lazy handler (function that returns promise)
-    if (typeof handler === 'function') {
-      const result = handler(request, context);
+    if (typeof handler === "function") {
+      const result = handler(request, input);
 
       // If it returns a promise with default export
-      if (result && typeof result === 'object' && 'then' in result) {
+      if (result && typeof result === "object" && "then" in result) {
         const module = await result;
         if (
-          typeof module === 'object' &&
+          typeof module === "object" &&
           module !== null &&
-          'default' in module
+          "default" in module
         ) {
           const defaultExport = (module as { default: Handler | HostRouter })
             .default;
 
           // If default export is a router with match method
           if (
-            typeof defaultExport === 'object' &&
+            typeof defaultExport === "object" &&
             defaultExport !== null &&
-            'match' in defaultExport
+            "match" in defaultExport
           ) {
-            return (defaultExport as HostRouter).match(request, context);
+            return (defaultExport as HostRouter).match(request, input);
           }
 
           // Otherwise treat as handler
-          return (defaultExport as Handler)(request, context);
+          return (defaultExport as Handler)(request, input);
         }
         // If promise resolves to Response
         return result as Promise<Response>;
@@ -228,8 +243,8 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
     },
 
     test(hostname: string): HostMatchResult | null {
-      const parts = hostname.split('.');
-      const pathname = '/';
+      const parts = hostname.split(".");
+      const pathname = "/";
 
       for (const route of routes) {
         for (const pattern of route.patterns) {
@@ -245,18 +260,17 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
       return null;
     },
 
-    async match(request: Request, context: any = {}): Promise<Response> {
+    async match(
+      request: Request,
+      input: RouterRequestInput<any> = {},
+    ): Promise<Response> {
       log(`Request: ${request.url}`);
 
       let effectiveHostname: string;
 
       try {
         // Handle cookie override (may throw HostRouterError)
-        effectiveHostname = handleCookieOverride(
-          request,
-          hostOverride,
-          context
-        );
+        effectiveHostname = handleCookieOverride(request, hostOverride, input);
       } catch (error) {
         // If it's a HostRouterError from cookie override
         if (error instanceof HostRouterError) {
@@ -264,14 +278,18 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
 
           // If fallback exists, use it
           if (fallbackRoute) {
-            context.error = error;
+            const fallbackInput = { ...input, error };
             const allMiddleware = [
               ...globalMiddleware,
               ...fallbackRoute.middleware,
             ];
 
-            return executeMiddleware(allMiddleware, request, context, () =>
-              executeHandler(fallbackRoute!.handler, request, context)
+            return executeMiddleware(
+              allMiddleware,
+              request,
+              fallbackInput,
+              () =>
+                executeHandler(fallbackRoute!.handler, request, fallbackInput),
             );
           }
 
@@ -279,7 +297,7 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
           if (hostOverride) {
             return createCookieErrorResponse(
               hostOverride.cookieName,
-              error.message
+              error.message,
             );
           }
         }
@@ -311,8 +329,8 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
       const allMiddleware = [...globalMiddleware, ...matchedRoute.middleware];
 
       // Execute middleware chain and handler
-      return executeMiddleware(allMiddleware, request, context, () =>
-        executeHandler(matchedRoute.handler, request, context)
+      return executeMiddleware(allMiddleware, request, input, () =>
+        executeHandler(matchedRoute.handler, request, input),
       );
     },
   };
@@ -322,8 +340,12 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
   // added via .host().map() after this point.
   const registryId = `host-router-${hostRouterAutoId++}`;
   HostRouterRegistry.set(registryId, {
-    get routes() { return routes; },
-    get fallback() { return fallbackRoute; },
+    get routes() {
+      return routes;
+    },
+    get fallback() {
+      return fallbackRoute;
+    },
   });
 
   return router;

package/src/host/testing.ts

@@ -4,7 +4,7 @@
  * Helper functions for testing host routing.
  */
 
-import { matchPattern } from './pattern-matcher.js';
+import { matchPattern } from "./pattern-matcher.js";
 
 export interface CreateTestRequestOptions {
   host: string;
@@ -29,8 +29,8 @@ export interface CreateTestRequestOptions {
 export function createTestRequest(options: CreateTestRequestOptions): Request {
   const {
     host,
-    path = '/',
-    method = 'GET',
+    path = "/",
+    method = "GET",
     cookies = {},
     headers = {},
   } = options;
@@ -42,8 +42,8 @@ export function createTestRequest(options: CreateTestRequestOptions): Request {
   if (Object.keys(cookies).length > 0) {
     const cookieString = Object.entries(cookies)
       .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
-      .join('; ');
-    requestHeaders.set('cookie', cookieString);
+      .join("; ");
+    requestHeaders.set("cookie", cookieString);
   }
 
   return new Request(url, {
@@ -63,11 +63,11 @@ export function createTestRequest(options: CreateTestRequestOptions): Request {
  */
 export function testPattern(
   pattern: string | string[],
-  hostname: string
+  hostname: string,
 ): boolean {
   const patterns = Array.isArray(pattern) ? pattern : [pattern];
-  const parts = hostname.split('.');
-  const pathname = '/';
+  const parts = hostname.split(".");
+  const pathname = "/";
 
   for (const p of patterns) {
     if (matchPattern(p, hostname, pathname, parts)) {

package/src/host/types.ts

@@ -4,12 +4,15 @@
  * Type definitions for the host-based routing system.
  */
 
+import type { RouterRequestInput } from "../router/router-interfaces.js";
+
 /**
- * Handler function that processes a request and returns a response
+ * Handler function that processes a request and returns a response.
+ * The input parameter receives the same RouterRequestInput passed to match().
  */
 export type Handler = (
   request: Request,
-  context: any
+  input: RouterRequestInput<any>,
 ) => Response | Promise<Response>;
 
 /**
@@ -18,12 +21,13 @@ export type Handler = (
 export type LazyHandler = () => Promise<{ default: Handler | HostRouter }>;
 
 /**
- * Middleware function that can intercept and modify requests/responses
+ * Middleware function that can intercept and modify requests/responses.
+ * The input parameter receives the same RouterRequestInput passed to match().
  */
 export type Middleware = (
   request: Request,
-  context: any,
-  next: () => Promise<Response>
+  input: RouterRequestInput<any>,
+  next: () => Promise<Response>,
 ) => Promise<Response>;
 
 /**
@@ -71,7 +75,7 @@ export interface HostRouter {
   /**
    * Match an incoming request
    */
-  match(request: Request, context?: any): Promise<Response>;
+  match(request: Request, input?: RouterRequestInput<any>): Promise<Response>;
 
   /**
    * Register fallback handler for allowed hosts without valid cookie
@@ -101,7 +105,11 @@ export interface HostOverrideConfig {
   /**
    * Optional validation function
    */
-  validate?: (request: Request, cookieValue: string, context: any) => string;
+  validate?: (
+    request: Request,
+    cookieValue: string,
+    input: RouterRequestInput<any>,
+  ) => string;
 }
 
 /**

package/src/host/utils.ts

@@ -19,7 +19,7 @@
  * ```
  */
 export function defineHosts<T extends Record<string, string | string[]>>(
-  hosts: T
+  hosts: T,
 ): Readonly<T> {
   return Object.freeze(hosts);
 }

package/src/href-client.ts

@@ -45,30 +45,34 @@ type ParseConstraintPath<T extends string> =
 export type PatternToPath<T extends string> =
   // Optional + constrained param in middle: /:param(a|b)?/rest
   T extends `${infer Before}:${infer _Name}(${infer Constraint})?/${infer After}`
-    ? PatternToPath<`${Before}${After}`> | `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
-  // Optional + constrained param at end: /path/:param(a|b)?
-  : T extends `${infer Before}:${infer _Name}(${infer Constraint})?`
-    ? Before | `${Before}${ParseConstraintPath<Constraint>}`
-  // Constrained param in middle: /:param(a|b)/rest
-  : T extends `${infer Before}:${infer _Name}(${infer Constraint})/${infer After}`
-    ? `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
-  // Constrained param at end: /path/:param(a|b)
-  : T extends `${infer Before}:${infer _Name}(${infer Constraint})`
-    ? `${Before}${ParseConstraintPath<Constraint>}`
-  // Optional param in middle: /:param?/rest
-  : T extends `${infer Before}:${infer _Param}?/${infer After}`
-    ? PatternToPath<`${Before}${After}`> | `${Before}${string}/${PatternToPath<After>}`
-  // Optional param at end: /path/:param?
-  : T extends `${infer Before}:${infer _Param}?`
-    ? Before | `${Before}${string}`
-  // Required param in middle: /:param/rest
-  : T extends `${infer Before}:${infer _Param}/${infer After}`
-    ? `${Before}${string}/${PatternToPath<After>}`
-  // Required param at end: /path/:param
-  : T extends `${infer Before}:${infer _Param}`
-    ? `${Before}${string}`
-  // Static path
-  : T;
+    ?
+        | PatternToPath<`${Before}${After}`>
+        | `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
+    : // Optional + constrained param at end: /path/:param(a|b)?
+      T extends `${infer Before}:${infer _Name}(${infer Constraint})?`
+      ? Before | `${Before}${ParseConstraintPath<Constraint>}`
+      : // Constrained param in middle: /:param(a|b)/rest
+        T extends `${infer Before}:${infer _Name}(${infer Constraint})/${infer After}`
+        ? `${Before}${ParseConstraintPath<Constraint>}/${PatternToPath<After>}`
+        : // Constrained param at end: /path/:param(a|b)
+          T extends `${infer Before}:${infer _Name}(${infer Constraint})`
+          ? `${Before}${ParseConstraintPath<Constraint>}`
+          : // Optional param in middle: /:param?/rest
+            T extends `${infer Before}:${infer _Param}?/${infer After}`
+            ?
+                | PatternToPath<`${Before}${After}`>
+                | `${Before}${string}/${PatternToPath<After>}`
+            : // Optional param at end: /path/:param?
+              T extends `${infer Before}:${infer _Param}?`
+              ? Before | `${Before}${string}`
+              : // Required param in middle: /:param/rest
+                T extends `${infer Before}:${infer _Param}/${infer After}`
+                ? `${Before}${string}/${PatternToPath<After>}`
+                : // Required param at end: /path/:param
+                  T extends `${infer Before}:${infer _Param}`
+                  ? `${Before}${string}`
+                  : // Static path
+                    T;
 
 /**
  * Allow optional query string (?...) and/or hash fragment (#...) suffix
@@ -85,19 +89,17 @@ type WithSuffix<T extends string> =
 /**
  * Helper type to get pattern from routes, handling string values and { path, response } objects
  */
-type RoutePattern<TRoutes, K extends keyof TRoutes> =
-  TRoutes[K] extends string ? TRoutes[K]
-  : TRoutes[K] extends { readonly path: infer P extends string } ? P
-  : string;
+type RoutePattern<TRoutes, K extends keyof TRoutes> = TRoutes[K] extends string
+  ? TRoutes[K]
+  : TRoutes[K] extends { readonly path: infer P extends string }
+    ? P
+    : string;
 
 /**
  * Reverse lookup: find route name where the pattern matches TPattern
  */
-type NameForPattern<
-  TPattern extends string,
-  TRoutes = GetRegisteredRoutes
-> = {
-  [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern ? K : never
+type NameForPattern<TPattern extends string, TRoutes = GetRegisteredRoutes> = {
+  [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern ? K : never;
 }[keyof TRoutes];
 
 /**
@@ -112,19 +114,28 @@ type NameForPattern<
  * For dynamic routes, use the pattern:
  *   PathResponse<"/api/products/:id"> → Product
  */
-export type PathResponse<TPattern extends string, TRoutes = GetRegisteredRoutes> =
-  ResponseEnvelope<{
+export type PathResponse<
+  TPattern extends string,
+  TRoutes = GetRegisteredRoutes,
+> = ResponseEnvelope<
+  {
     [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TPattern
-      ? TRoutes[K] extends { readonly response: infer R } ? Exclude<R, Response> : never
-      : never
-  }[keyof TRoutes]>;
+      ? TRoutes[K] extends { readonly response: infer R }
+        ? Exclude<R, Response>
+        : never
+      : never;
+  }[keyof TRoutes]
+>;
 
 /**
  * Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
  * Allows navigation to include() prefixes without requiring trailing slash
  */
-type OptionalTrailingSlash<T extends string> =
-  T extends `${infer Base}/` ? (Base extends "" ? T : Base | T) : T;
+type OptionalTrailingSlash<T extends string> = T extends `${infer Base}/`
+  ? Base extends ""
+    ? T
+    : Base | T
+  : T;
 
 /**
  * Union of all valid paths from registered routes
@@ -135,9 +146,13 @@ type OptionalTrailingSlash<T extends string> =
 export type ValidPaths<TRoutes = GetRegisteredRoutes> =
   keyof TRoutes extends never
     ? `/${string}` // Fallback when no routes are registered
-    : WithSuffix<{
-        [K in keyof TRoutes]: OptionalTrailingSlash<PatternToPath<RoutePattern<TRoutes, K>>>
-      }[keyof TRoutes]>;
+    : WithSuffix<
+        {
+          [K in keyof TRoutes]: OptionalTrailingSlash<
+            PatternToPath<RoutePattern<TRoutes, K>>
+          >;
+        }[keyof TRoutes]
+      >;
 
 /**
  * Type-safe href function for client-side use
@@ -167,9 +182,14 @@ export type ValidPaths<TRoutes = GetRegisteredRoutes> =
  */
 export function href<T extends ValidPaths>(path: T, mount?: string): string {
   if (mount && mount !== "/") {
-    return mount + path;
+    // Strip trailing slash from mount to avoid double-slash when joining
+    const normalizedMount = mount.endsWith("/") ? mount.slice(0, -1) : mount;
+    return normalizedMount + path;
   }
-  return path;
+  // ValidPaths is built from template literals so T does extend string at
+  // runtime, but the inference can fail past a certain route-union complexity
+  // and TypeScript reports T as not assignable to string.
+  return path as string;
 }
 
 /**
@@ -181,7 +201,10 @@ export interface ResponseHrefProps {
   "data-external": "";
 }
 
-type ResponseHrefFn = <T extends ValidPaths>(path: T, mount?: string) => ResponseHrefProps;
+type ResponseHrefFn = <T extends ValidPaths>(
+  path: T,
+  mount?: string,
+) => ResponseHrefProps;
 
 function createResponseHrefTag(): ResponseHrefFn {
   return (path, mount) => ({