@rangojs/router 0.0.0-experimental.3 → 0.0.0-experimental.30

package/src/host/testing.ts

@@ -0,0 +1,79 @@
+/**
+ * Testing Utilities for Host Router
+ *
+ * Helper functions for testing host routing.
+ */
+
+import { matchPattern } from "./pattern-matcher.js";
+
+export interface CreateTestRequestOptions {
+  host: string;
+  path?: string;
+  method?: string;
+  cookies?: Record<string, string>;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Create a test request with specific host and cookies
+ *
+ * @example
+ * ```ts
+ * const request = createTestRequest({
+ *   host: 'admin.example.com',
+ *   path: '/dashboard',
+ *   cookies: { 'x-requested-host': 'api.example.com' }
+ * });
+ * ```
+ */
+export function createTestRequest(options: CreateTestRequestOptions): Request {
+  const {
+    host,
+    path = "/",
+    method = "GET",
+    cookies = {},
+    headers = {},
+  } = options;
+
+  const url = `http://${host}${path}`;
+  const requestHeaders = new Headers(headers);
+
+  // Add cookies if provided
+  if (Object.keys(cookies).length > 0) {
+    const cookieString = Object.entries(cookies)
+      .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+      .join("; ");
+    requestHeaders.set("cookie", cookieString);
+  }
+
+  return new Request(url, {
+    method,
+    headers: requestHeaders,
+  });
+}
+
+/**
+ * Test if a pattern matches a hostname
+ *
+ * @example
+ * ```ts
+ * expect(testPattern('admin.*', 'admin.example.com')).toBe(true);
+ * expect(testPattern(['*', 'www.*'], 'example.com')).toBe(true);
+ * ```
+ */
+export function testPattern(
+  pattern: string | string[],
+  hostname: string,
+): boolean {
+  const patterns = Array.isArray(pattern) ? pattern : [pattern];
+  const parts = hostname.split(".");
+  const pathname = "/";
+
+  for (const p of patterns) {
+    if (matchPattern(p, hostname, pathname, parts)) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/host/types.ts

@@ -0,0 +1,146 @@
+/**
+ * Host Router Types
+ *
+ * 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.
+ * The input parameter receives the same RouterRequestInput passed to match().
+ */
+export type Handler = (
+  request: Request,
+  input: RouterRequestInput<any>,
+) => Response | Promise<Response>;
+
+/**
+ * Lazy handler that dynamically imports a module with a default handler or router
+ */
+export type LazyHandler = () => Promise<{ default: Handler | HostRouter }>;
+
+/**
+ * Middleware function that can intercept and modify requests/responses.
+ * The input parameter receives the same RouterRequestInput passed to match().
+ */
+export type Middleware = (
+  request: Request,
+  input: RouterRequestInput<any>,
+  next: () => Promise<Response>,
+) => Promise<Response>;
+
+/**
+ * Host pattern - can be a string or array of strings
+ */
+export type HostPattern = string | string[];
+
+/**
+ * Result from testing a hostname against patterns
+ */
+export interface HostMatchResult {
+  pattern: string;
+  handler: Handler | LazyHandler;
+}
+
+/**
+ * Host route builder for chaining middleware and handler
+ */
+export interface HostRouteBuilder {
+  /**
+   * Add middleware to this host pattern
+   */
+  use(...middleware: Middleware[]): HostRouteBuilder;
+
+  /**
+   * Map to a handler or lazy import
+   */
+  map(handler: Handler | LazyHandler): HostRouter;
+}
+
+/**
+ * Main host router interface
+ */
+export interface HostRouter {
+  /**
+   * Register a host pattern
+   */
+  host(patterns: HostPattern): HostRouteBuilder;
+
+  /**
+   * Register global middleware
+   */
+  use(...middleware: Middleware[]): HostRouter;
+
+  /**
+   * Match an incoming request
+   */
+  match(request: Request, input?: RouterRequestInput<any>): Promise<Response>;
+
+  /**
+   * Register fallback handler for allowed hosts without valid cookie
+   */
+  fallback(): HostRouteBuilder;
+
+  /**
+   * Test which handler would match a hostname
+   */
+  test(hostname: string): HostMatchResult | null;
+}
+
+/**
+ * Host override configuration
+ */
+export interface HostOverrideConfig {
+  /**
+   * Cookie name to read for host override
+   */
+  cookieName: string;
+
+  /**
+   * Hosts that are allowed to use override
+   */
+  allowedHosts: string[];
+
+  /**
+   * Optional validation function
+   */
+  validate?: (
+    request: Request,
+    cookieValue: string,
+    input: RouterRequestInput<any>,
+  ) => string;
+}
+
+/**
+ * Host router options
+ */
+export interface HostRouterOptions {
+  /**
+   * Enable debug logging
+   */
+  debug?: boolean;
+
+  /**
+   * Cookie-based host override configuration
+   */
+  hostOverride?: HostOverrideConfig;
+}
+
+/**
+ * Internal route entry
+ */
+export interface RouteEntry {
+  patterns: string[];
+  middleware: Middleware[];
+  handler: Handler | LazyHandler;
+  isFallback?: boolean;
+}
+
+/**
+ * Pattern match result (internal)
+ */
+export interface PatternMatchResult {
+  matched: boolean;
+  routeEntry?: RouteEntry;
+}

package/src/host/utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Host Router Utilities
+ *
+ * Helper functions for type-safe pattern definitions.
+ */
+
+/**
+ * Define hosts with type safety
+ *
+ * @example
+ * ```ts
+ * const hosts = defineHosts({
+ *   admin: 'admin.*',
+ *   api: 'api.*',
+ *   app: ['*', 'www.*']
+ * });
+ *
+ * router.host(hosts.admin).map(...); // Type-safe!
+ * ```
+ */
+export function defineHosts<T extends Record<string, string | string[]>>(
+  hosts: T,
+): Readonly<T> {
+  return Object.freeze(hosts);
+}

package/src/href-client.ts

@@ -15,6 +15,7 @@
  */
 
 import type { GetRegisteredRoutes } from "./types.js";
+import type { ResponseEnvelope } from "./urls.js";
 
 /**
  * Parse constraint values into a union type for paths
@@ -44,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
@@ -82,10 +87,55 @@ type WithSuffix<T extends string> =
   | `${T}?${string}#${string}`;
 
 /**
- * Helper type to get pattern from routes, handling both Record and interface types
+ * 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;
+
+/**
+ * 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;
+}[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.
+ *
+ * For static routes (no params), pattern === path:
+ *   PathResponse<"/api/health"> → { status: string; timestamp: number }
+ *
+ * For dynamic routes, use the pattern:
+ *   PathResponse<"/api/products/:id"> → Product
  */
-type RoutePattern<TRoutes, K extends keyof TRoutes> =
-  TRoutes[K] extends string ? TRoutes[K] : string;
+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]
+>;
+
+/**
+ * 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;
 
 /**
  * Union of all valid paths from registered routes
@@ -96,41 +146,77 @@ type RoutePattern<TRoutes, K extends keyof TRoutes> =
 export type ValidPaths<TRoutes = GetRegisteredRoutes> =
   keyof TRoutes extends never
     ? `/${string}` // Fallback when no routes are registered
-    : WithSuffix<PatternToPath<RoutePattern<TRoutes, keyof TRoutes>>>;
+    : WithSuffix<
+        {
+          [K in keyof TRoutes]: OptionalTrailingSlash<
+            PatternToPath<RoutePattern<TRoutes, K>>
+          >;
+        }[keyof TRoutes]
+      >;
 
 /**
  * Type-safe href function for client-side use
  *
- * This is an identity function - it returns the path unchanged.
- * The value is in TypeScript validation: invalid paths cause compile errors.
- *
- * Works with:
- * - Static paths: href("/about")
- * - Dynamic segments: href("/blog/my-post")
- * - Multiple segments: href("/shop/product/widget/reviews/123")
- *
- * Does NOT validate:
- * - Query strings (passed through as-is)
- * - Hash fragments (passed through as-is)
+ * Without mount: identity function, validates absolute paths at compile time.
+ * With mount: prepends mount path, for use with useMount() inside include() scopes.
  *
  * @param path - A valid path matching one of the registered route patterns
- * @returns The path unchanged
+ * @param mount - Optional mount prefix from useMount() for include-scoped paths
+ * @returns The resolved path
  *
  * @example
  * ```typescript
- * // Valid paths (compile)
- * href("/blog/hello");                    // matches /blog/:slug
- * href("/shop/product/widget");           // matches /shop/product/:slug
- * href("/shop/product/widget/reviews");   // matches /shop/product/:slug/reviews
+ * // Absolute paths (type-safe)
+ * href("/blog/hello");           // "/blog/hello"
+ * href("/shop/product/widget");  // "/shop/product/widget"
  *
- * // Query strings and hashes pass through (not validated)
+ * // With mount (inside an include)
+ * const mount = useMount();      // "/articles"
+ * href("/", mount);              // "/articles/"
+ * href("/my-post", mount);       // "/articles/my-post"
+ *
+ * // Query strings and hashes pass through
  * href("/blog/hello?page=1");
  * href("/about#contact");
- *
- * // Invalid paths (TypeScript error)
- * href("/nonexistent");  // Error: not assignable to ValidPaths
  * ```
  */
-export function href<T extends ValidPaths>(path: T): T {
+export function href<T extends ValidPaths>(path: T, mount?: string): string {
+  if (mount && mount !== "/") {
+    // 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;
 }
+
+/**
+ * Props shape returned by href.json() etc. for spreading on <Link>.
+ * Sets data-external to trigger hard navigation (skips RSC fetch).
+ */
+export interface ResponseHrefProps {
+  to: string;
+  "data-external": "";
+}
+
+type ResponseHrefFn = <T extends ValidPaths>(
+  path: T,
+  mount?: string,
+) => ResponseHrefProps;
+
+function createResponseHrefTag(): ResponseHrefFn {
+  return (path, mount) => ({
+    to: href(path, mount),
+    "data-external": "" as const,
+  });
+}
+
+export namespace href {
+  export const json: ResponseHrefFn = createResponseHrefTag();
+  export const text: ResponseHrefFn = createResponseHrefTag();
+  export const html: ResponseHrefFn = createResponseHrefTag();
+  export const xml: ResponseHrefFn = createResponseHrefTag();
+  export const md: ResponseHrefFn = createResponseHrefTag();
+  export const image: ResponseHrefFn = createResponseHrefTag();
+  export const stream: ResponseHrefFn = createResponseHrefTag();
+  export const any: ResponseHrefFn = createResponseHrefTag();
+}