@rangojs/router 0.0.0-experimental.11 → 0.0.0-experimental.111

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,10 +47,39 @@ 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;
 
+/** Whether a value is thenable (a Promise or Promise-like). */
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value !== null &&
+    (typeof value === "object" || typeof value === "function") &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+/**
+ * Whether a resolved value looks like a module namespace from a lazy import -
+ * an object with a `default` export that is a function (a Handler) or a host
+ * router (an object with `match`). Used to detect a `.map(() => import(...))`
+ * misuse: an inline handler should return a Response, not a module.
+ */
+function looksLikeLazyModule(value: unknown): boolean {
+  if (value === null || typeof value !== "object" || !("default" in value)) {
+    return false;
+  }
+  const defaultExport = (value as { default: unknown }).default;
+  return (
+    typeof defaultExport === "function" ||
+    (typeof defaultExport === "object" &&
+      defaultExport !== null &&
+      "match" in defaultExport)
+  );
+}
+
 /**
  * Create a host router
  */
@@ -71,36 +101,48 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
    */
   function createRouteBuilder(
     patterns: string[],
-    isFallback = false
+    isFallback = false,
   ): HostRouteBuilder {
     const middleware: Middleware[] = [];
 
+    function register(
+      handler: Handler | LazyHandler,
+      kind: RouteEntry["kind"],
+    ): HostRouter {
+      const entry: RouteEntry = {
+        patterns,
+        middleware,
+        handler,
+        kind,
+        isFallback,
+      };
+
+      if (isFallback) {
+        fallbackRoute = entry;
+      } else {
+        routes.push(entry);
+      }
+
+      log(
+        `Registered ${isFallback ? "fallback" : "route"} (${kind}):`,
+        patterns.join(", "),
+      );
+
+      return router;
+    }
+
     return {
       use(...mw: Middleware[]): HostRouteBuilder {
         middleware.push(...mw);
         return this;
       },
 
-      map(handler: Handler | LazyHandler): HostRouter {
-        const entry: RouteEntry = {
-          patterns,
-          middleware,
-          handler,
-          isFallback,
-        };
-
-        if (isFallback) {
-          fallbackRoute = entry;
-        } else {
-          routes.push(entry);
-        }
-
-        log(
-          `Registered ${isFallback ? 'fallback' : 'route'}:`,
-          patterns.join(', ')
-        );
+      map(handler: Handler): HostRouter {
+        return register(handler, "handler");
+      },
 
-        return router;
+      lazy(handler: LazyHandler): HostRouter {
+        return register(handler, "lazy");
       },
     };
   }
@@ -110,9 +152,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 +174,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,57 +189,102 @@ 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();
   }
 
   /**
-   * Execute handler (lazy or direct)
+   * Execute a route entry, branching on its declared kind:
+   *   - "lazy": await the loader, then delegate to the default export
+   *     (a nested HostRouter via `.match`, or a request Handler directly).
+   *   - "handler": call the inline handler with the request. A `.map()` handler
+   *     that resolves to a module namespace (`{ default }`) is almost certainly
+   *     a misused lazy import, so it is rejected with a clear message rather
+   *     than silently returning a module object as the response.
    */
   async function executeHandler(
-    handler: Handler | LazyHandler,
+    entry: RouteEntry,
     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 it returns a promise with default export
-      if (result && typeof result === 'object' && 'then' in result) {
-        const module = await result;
-        if (
-          typeof module === 'object' &&
-          module !== null &&
-          'default' in module
-        ) {
-          const defaultExport = (module as { default: Handler | HostRouter })
-            .default;
-
-          // If default export is a router with match method
-          if (
-            typeof defaultExport === 'object' &&
-            defaultExport !== null &&
-            'match' in defaultExport
-          ) {
-            return (defaultExport as HostRouter).match(request, context);
-          }
+    const { handler, kind } = entry;
 
-          // Otherwise treat as handler
-          return (defaultExport as Handler)(request, context);
-        }
-        // If promise resolves to Response
-        return result as Promise<Response>;
+    if (typeof handler !== "function") {
+      throw new InvalidHandlerError(handler, {
+        cause: { handlerType: typeof handler },
+      });
+    }
+
+    if (kind === "lazy") {
+      return executeLazyMount(handler as LazyHandler, request, input);
+    }
+
+    const result = (handler as Handler)(request, input);
+
+    // Inline handlers may be async; await to obtain the Response and to run the
+    // misuse guard below.
+    if (isThenable(result)) {
+      const awaited = await result;
+      if (looksLikeLazyModule(awaited)) {
+        throw new HostRouterError(
+          ".map() is for inline request handlers; use .lazy(() => import(...)) for lazy host mounts.",
+        );
       }
+      return awaited as Response;
+    }
+
+    return result;
+  }
 
-      // Direct handler
-      return result as Response | Promise<Response>;
+  /**
+   * Resolve a `.lazy()` mount: invoke the zero-arg loader, then dispatch to the
+   * module's default export.
+   */
+  async function executeLazyMount(
+    loader: LazyHandler,
+    request: Request,
+    input: RouterRequestInput<any>,
+  ): Promise<Response> {
+    const module = await loader();
+
+    if (typeof module === "object" && module !== null && "default" in module) {
+      const defaultExport = (module as { default: Handler | HostRouter })
+        .default;
+
+      // Default export is a nested host router
+      if (
+        typeof defaultExport === "object" &&
+        defaultExport !== null &&
+        "match" in defaultExport
+      ) {
+        return (defaultExport as HostRouter).match(request, input);
+      }
+
+      // Otherwise treat the default export as a request handler
+      return (defaultExport as Handler)(request, input);
     }
 
-    throw new InvalidHandlerError(handler, {
-      cause: { handlerType: typeof handler },
+    throw new InvalidHandlerError(loader, {
+      cause: {
+        reason:
+          "lazy mount did not resolve to a module with a default export; " +
+          "use .lazy(() => import('./sub-app')) where the module default-exports a handler or host router",
+      },
     });
   }
 
@@ -228,8 +315,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) {
@@ -237,6 +324,7 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
             return {
               pattern,
               handler: route.handler,
+              kind: route.kind,
             };
           }
         }
@@ -245,18 +333,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 +351,17 @@ 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!, request, fallbackInput),
             );
           }
 
@@ -279,7 +369,7 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
           if (hostOverride) {
             return createCookieErrorResponse(
               hostOverride.cookieName,
-              error.message
+              error.message,
             );
           }
         }
@@ -311,19 +401,23 @@ 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, request, input),
       );
     },
   };
 
   // Register in the global HostRouterRegistry for build-time discovery.
   // The routes array and fallbackRoute ref are live - they reflect routes
-  // added via .host().map() after this point.
+  // added via .host().map()/.lazy() 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>;
 
 /**
@@ -31,12 +35,24 @@ export type Middleware = (
  */
 export type HostPattern = string | string[];
 
+/**
+ * Whether a route entry is an inline request handler or a lazy module mount.
+ *
+ * Stored on the entry so discovery and runtime act on the consumer's declared
+ * intent instead of inferring it from the function's shape (arity/return value),
+ * which is ambiguous: a lazy loader may declare an ignored param, and an inline
+ * handler may be async. `.map()` registers `"handler"`, `.lazy()` registers
+ * `"lazy"`.
+ */
+export type RouteEntryKind = "handler" | "lazy";
+
 /**
  * Result from testing a hostname against patterns
  */
 export interface HostMatchResult {
   pattern: string;
   handler: Handler | LazyHandler;
+  kind: RouteEntryKind;
 }
 
 /**
@@ -49,9 +65,24 @@ export interface HostRouteBuilder {
   use(...middleware: Middleware[]): HostRouteBuilder;
 
   /**
-   * Map to a handler or lazy import
+   * Map to an inline request handler `(request, input) => Response`.
+   *
+   * For a lazily-imported sub-app or handler module, use {@link lazy} instead -
+   * `.map(() => import(...))` is rejected (the return type is not a `Response`)
+   * and would not be discovered at build time.
+   */
+  map(handler: Handler): HostRouter;
+
+  /**
+   * Mount a lazily-imported handler or host router:
+   * `.lazy(() => import("./sub-app"))`.
+   *
+   * The loader takes no arguments and resolves to a module whose `default`
+   * export is a request `Handler` or a nested `HostRouter`. Only `.lazy()`
+   * entries are invoked during build-time discovery to trigger the sub-app's
+   * `createRouter()` registration.
    */
-  map(handler: Handler | LazyHandler): HostRouter;
+  lazy(handler: LazyHandler): HostRouter;
 }
 
 /**
@@ -71,7 +102,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 +132,11 @@ export interface HostOverrideConfig {
   /**
    * Optional validation function
    */
-  validate?: (request: Request, cookieValue: string, context: any) => string;
+  validate?: (
+    request: Request,
+    cookieValue: string,
+    input: RouterRequestInput<any>,
+  ) => string;
 }
 
 /**
@@ -126,6 +161,8 @@ export interface RouteEntry {
   patterns: string[];
   middleware: Middleware[];
   handler: Handler | LazyHandler;
+  /** Whether `handler` is an inline request handler or a lazy module mount. */
+  kind: RouteEntryKind;
   isFallback?: boolean;
 }
 

package/src/host/utils.ts

@@ -15,11 +15,11 @@
  *   app: ['*', 'www.*']
  * });
  *
- * router.host(hosts.admin).map(...); // Type-safe!
+ * router.host(hosts.admin).lazy(() => import("./apps/admin")); // Type-safe!
  * ```
  */
 export function defineHosts<T extends Record<string, string | string[]>>(
-  hosts: T
+  hosts: T,
 ): Readonly<T> {
   return Object.freeze(hosts);
 }