@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.120

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);
 }

package/src/href-client.ts

@@ -15,7 +15,7 @@
  */
 
 import type { GetRegisteredRoutes } from "./types.js";
-import type { ResponseEnvelope } from "./urls.js";
+import type { JsonSerialize } from "./serialize.js";
 
 /**
  * Parse constraint values into a union type for paths
@@ -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,59 +89,186 @@ 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];
 
 /**
- * Look up the response data type for a route pattern from RegisteredRoutes.
- *
- * Works by reverse-looking up the route name for the given pattern,
- * then extracting the response type from the route entry.
+ * Strip a query (`?…`) and/or hash (`#…`) suffix before matching, so a concrete
+ * URL like `/api/health?ts=1` still resolves to its route's response. Removes
+ * from the earliest of `?`/`#`: a `#` before the first `?` (the query is part of
+ * a fragment, e.g. `/health#top?x=1`) is handled, as is a `/:` that only appears
+ * inside the query (e.g. `/health?next=/:id`).
+ */
+type StripPathSuffix<T extends string> = T extends `${infer Base}?${string}`
+  ? Base extends `${infer Frag}#${string}`
+    ? Frag
+    : Base
+  : T extends `${infer Base}#${string}`
+    ? Base
+    : T;
+
+/** Extract a route entry's response payload (or `never` for RSC routes). */
+type ResponsePayloadOf<TRoutes, K extends keyof TRoutes> = TRoutes[K] extends {
+  readonly response: infer R;
+}
+  ? Exclude<R, Response>
+  : never;
+
+/**
+ * Look up the response payload for a route, keyed by either a route pattern
+ * (`/api/products/:id`) or a concrete path (`/api/products/123`). The same type
+ * serves a pattern lookup and a typed `fetch` wrapper that forwards a concrete
+ * `Rango.Path`:
  *
- * For static routes (no params), pattern === path:
- *   PathResponse<"/api/health"> → { status: string; timestamp: number }
+ *   PathResponse<"/api/products/:id"> → Product   // by pattern
+ *   PathResponse<"/api/products/123"> → Product   // by concrete path
  *
- * For dynamic routes, use the pattern:
- *   PathResponse<"/api/products/:id"> → Product
+ * The query/hash suffix is stripped first; the stripped key is then treated as a
+ * pattern when it contains a `/:param` segment and matched exactly (precise even
+ * for nested dynamic routes), otherwise as a concrete path matched against each
+ * route's `PatternToPath` template. Because those holes are `${string}`
+ * (slash-greedy), a concrete path under a *nested* dynamic route can match several
+ * patterns and union their responses — pattern lookups do not have this
+ * looseness. RSC routes (no response) and unmatched keys resolve to `never`.
  */
-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]>;
+type ResponsePayloadFor<
+  TPath extends string,
+  TRoutes = GetRegisteredRoutes,
+> = ResponsePayloadForKey<StripPathSuffix<TPath>, TRoutes>;
+
+type ResponsePayloadForKey<
+  TKey extends string,
+  TRoutes,
+> = TKey extends `${string}/:${string}`
+  ? {
+      [K in keyof TRoutes]: RoutePattern<TRoutes, K> extends TKey
+        ? ResponsePayloadOf<TRoutes, K>
+        : never;
+    }[keyof TRoutes]
+  : {
+      [K in keyof TRoutes]: TKey extends PatternToPath<RoutePattern<TRoutes, K>>
+        ? ResponsePayloadOf<TRoutes, K>
+        : never;
+    }[keyof TRoutes];
+
+/**
+ * Public response type for a route, keyed by pattern or concrete path. JSON
+ * response routes send the handler's return value verbatim (bare), so the
+ * payload is wrapped only in `JsonSerialize` to describe the JSON **wire** value
+ * a consumer receives from `fetch().then(r => r.json())` — e.g. a handler
+ * returning `{ createdAt: Date }` resolves here to `{ createdAt: string }`.
+ */
+export type PathResponse<
+  TPath extends string,
+  TRoutes = GetRegisteredRoutes,
+> = JsonSerialize<ResponsePayloadFor<TPath, 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
  *
- * Generated from RSCRouter.RegisteredRoutes via module augmentation.
+ * Generated from Rango.RegisteredRoutes via module augmentation.
  * Allows optional query strings and hash fragments.
  */
 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]
+      >;
+
+// Module-scoped alias so the ambient `Rango.PathResponse` below can reference
+// the module-level `PathResponse` without the global namespace shadowing the
+// name when both are called `PathResponse`.
+type GlobalPathResponse<
+  TPattern extends string,
+  TRoutes = GetRegisteredRoutes,
+> = PathResponse<TPattern, TRoutes>;
+
+/**
+ * Ambient path types on the `Rango` namespace.
+ *
+ * These live on the same global namespace consumers already augment for
+ * `Rango.Env` / `Rango.Vars`, so they are reachable with no import wherever the
+ * router's types are in scope. They are the public, recommended surface for
+ * typing anything that wraps `href()`. `ValidPaths` / `PathResponse` stay as the
+ * internal building blocks behind them.
+ */
+declare global {
+  namespace Rango {
+    /**
+     * Union of every valid route path accepted by `href()`.
+     *
+     * Type a wrapper's path parameter as `Rango.Path` so it shares `href()`'s
+     * compile-time validation against the registered routes:
+     *
+     * ```ts
+     * import { href } from "@rangojs/router/client";
+     *
+     * export const appHref = (path: Rango.Path) => href(path);
+     * ```
+     *
+     * Resolves from `Rango.RegisteredRoutes` when augmented, otherwise the
+     * auto-generated `Rango.GeneratedRouteMap`, otherwise a permissive
+     * `/${string}` fallback.
+     */
+    type Path<TRoutes = GetRegisteredRoutes> = ValidPaths<TRoutes>;
+
+    /**
+     * Response payload for a route, looked up from the global route map by
+     * either a route pattern (`/api/products/:id`) or a concrete path
+     * (`/api/products/123`). Because it accepts a concrete `Rango.Path`, it
+     * doubles as the return type of a typed `fetch` wrapper:
+     *
+     * ```ts
+     * type Product = Rango.PathResponse<"/api/products/:id">; // by pattern
+     * type Same = Rango.PathResponse<"/api/products/42">;     // by concrete path
+     *
+     * const get = async <T extends Rango.Path>(
+     *   path: T,
+     * ): Promise<Rango.PathResponse<T>> =>
+     *   fetch(href(path)).then((r) => r.json());
+     * ```
+     *
+     * The payload is the JSON **wire** shape (via `Rango.JsonSerialize`), not the
+     * handler's raw return — a handler returning `{ createdAt: Date }` resolves
+     * here to `{ createdAt: string }` (bare, no envelope), matching what
+     * `fetch().then(r => r.json())` actually yields.
+     *
+     * Only resolves once `Rango.RegisteredRoutes` carries response metadata (the
+     * generated map has paths and search but no payloads). Pass an explicit route
+     * map as the second argument to look up against a non-global map (rarely
+     * needed in app code).
+     */
+    type PathResponse<
+      TPath extends string,
+      TRoutes = GetRegisteredRoutes,
+    > = GlobalPathResponse<TPath, TRoutes>;
+  }
+}
 
 /**
  * Type-safe href function for client-side use
@@ -167,9 +298,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 +317,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) => ({