@rangojs/router 0.0.0-experimental.fb4fdc18 → 0.0.0-experimental.fce7fbd1

package/src/errors.ts

@@ -1,5 +1,5 @@
 /**
- * Custom error classes for RSC Router
+ * Custom error classes for Rango
  *
  * All errors include:
  * - Descriptive names for easy identification
@@ -27,6 +27,17 @@ export class RouteNotFoundError extends Error {
   }
 }
 
+// name fallback covers cross-realm errors (Vite dev dupes, RSC serialization)
+// where instanceof fails.
+export function isRouteNotFoundError(
+  error: unknown,
+): error is RouteNotFoundError {
+  return (
+    error instanceof RouteNotFoundError ||
+    (error instanceof Error && error.name === "RouteNotFoundError")
+  );
+}
+
 /**
  * Thrown when data is not found (e.g., product with ID doesn't exist)
  * Use this in handlers/loaders to trigger the nearest notFoundBoundary
@@ -109,6 +120,24 @@ export class BuildError extends Error {
   }
 }
 
+/**
+ * Thrown when a route-definition DSL helper (route/layout/loader/cache/…) is
+ * called outside an active urls()/map() builder, so there is no
+ * AsyncLocalStorage build context to attach to. The message names the specific
+ * helper and how to fix it; the `cause` records the mechanical reason so the
+ * failure mode is identifiable (not conflated with an unrelated throw).
+ */
+export class DslContextError extends Error {
+  name = "DslContextError" as const;
+  cause?: unknown;
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message);
+    Object.setPrototypeOf(this, DslContextError.prototype);
+    this.cause = options?.cause;
+  }
+}
+
 /**
  * Thrown when a network request fails (server unreachable, no internet, etc.)
  * This error triggers the root error boundary with retry capability.

package/src/handle.ts

@@ -1,3 +1,5 @@
+import { missingInjectedIdError } from "./missing-id-error.js";
+
 /**
  * Handle definition for accumulating data across route segments.
  *
@@ -43,6 +45,11 @@ function defaultCollect<T>(segments: T[][]): T[] {
 // Used by useHandle() to recover collect when handle is deserialized from RSC prop.
 const collectRegistry = new Map<string, (segments: unknown[][]) => unknown>();
 
+// Monotonic counter for runtime fallback ids (see createHandle). Module-scoped
+// and deterministic, so each createHandle() call gets a stable, unique id within
+// the process. Only used when no build id was injected (a bare unit test).
+let runtimeHandleIdCounter = 0;
+
 /**
  * Look up a collect function from the registry by handle $$id.
  * Returns undefined if not registered (falls back to defaultCollect in useHandle).
@@ -93,14 +100,22 @@ export function createHandle<TData, TAccumulated = TData[]>(
   collect?: (segments: TData[][]) => TAccumulated,
   __injectedId?: string,
 ): Handle<TData, TAccumulated> {
-  const handleId = __injectedId ?? "";
+  let handleId = __injectedId ?? "";
 
   if (!handleId && process.env.NODE_ENV === "development") {
-    throw new Error(
-      "[rsc-router] Handle is missing $$id. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the handle is exported with: export const MyHandle = createHandle(...)",
-    );
+    throw missingInjectedIdError("Handle", "createHandle");
+  }
+
+  // No build-injected id. This only happens in a bare unit test — every real
+  // build runs the rango Vite plugin, which always injects a stable id (and the
+  // line above throws for a genuinely non-exported handle in dev). Assign a
+  // process-stable runtime id so the collect registers below and the handle is
+  // fully exercisable in tests (useHandle, collectHandle, renderRoute's `handles`
+  // seeding run the REAL collect). Provably inert in production: the fallback
+  // never triggers when the plugin injects the id, so server/client id
+  // consistency (required for RSC recovery) is unaffected.
+  if (!handleId) {
+    handleId = `__rango_runtime_handle_${runtimeHandleIdCounter++}`;
   }
 
   const collectFn =
@@ -109,12 +124,10 @@ export function createHandle<TData, TAccumulated = TData[]>(
 
   // Register collect in module-level registry so useHandle() can recover it
   // when the handle is deserialized from RSC props (toJSON strips collect).
-  if (handleId) {
-    collectRegistry.set(
-      handleId,
-      collectFn as (segments: unknown[][]) => unknown,
-    );
-  }
+  collectRegistry.set(
+    handleId,
+    collectFn as (segments: unknown[][]) => unknown,
+  );
 
   return {
     __brand: "handle" as const,
@@ -151,7 +164,7 @@ export function collectHandleData<TData, TAccumulated>(
   const collectFn = getCollectFn(handle.$$id);
   if (!collectFn && process.env.NODE_ENV !== "production") {
     console.warn(
-      `[rsc-router] Handle "${handle.$$id}" has no registered collect function. ` +
+      `[rango] Handle "${handle.$$id}" has no registered collect function. ` +
         `Falling back to flat array. Ensure the handle module is imported so ` +
         `createHandle() runs and registers the collect function.`,
     );

package/src/host/index.ts

@@ -11,8 +11,8 @@
  *
  * const router = createHostRouter();
  *
- * router.host(['.']).map(() => import('./apps/main'));
- * router.host(['admin.*']).map(() => import('./apps/admin'));
+ * router.host(['.']).lazy(() => import('./apps/main'));
+ * router.host(['admin.*']).lazy(() => import('./apps/admin'));
  *
  * export default {
  *   fetch(request) {

package/src/host/router.ts

@@ -52,6 +52,34 @@ export const HostRouterRegistry: Map<string, HostRouterRegistryEntry> =
 
 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
  */
@@ -77,32 +105,44 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
   ): 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");
       },
     };
   }
@@ -169,50 +209,82 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
   }
 
   /**
-   * 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,
     input: RouterRequestInput<any>,
   ): Promise<Response> {
-    // Check if it's a lazy handler (function that returns promise)
-    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) {
-        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, input);
-          }
+    const { handler, kind } = entry;
 
-          // Otherwise treat as handler
-          return (defaultExport as Handler)(request, input);
-        }
-        // 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;
+  }
+
+  /**
+   * 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);
       }
 
-      // Direct handler
-      return result as Response | Promise<Response>;
+      // 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",
+      },
     });
   }
 
@@ -252,6 +324,7 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
             return {
               pattern,
               handler: route.handler,
+              kind: route.kind,
             };
           }
         }
@@ -288,8 +361,7 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
               allMiddleware,
               request,
               fallbackInput,
-              () =>
-                executeHandler(fallbackRoute!.handler, request, fallbackInput),
+              () => executeHandler(fallbackRoute!, request, fallbackInput),
             );
           }
 
@@ -330,14 +402,14 @@ export function createHostRouter(options: HostRouterOptions = {}): HostRouter {
 
       // Execute middleware chain and handler
       return executeMiddleware(allMiddleware, request, input, () =>
-        executeHandler(matchedRoute.handler, 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() {

package/src/host/types.ts

@@ -35,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;
 }
 
 /**
@@ -53,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;
 }
 
 /**
@@ -134,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,7 +15,7 @@
  *   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[]>>(

package/src/href-client.ts

@@ -15,6 +15,7 @@
  */
 
 import type { GetRegisteredRoutes } from "./types.js";
+import type { JsonSerialize } from "./serialize.js";
 import type { ResponseEnvelope } from "./urls.js";
 
 /**
@@ -103,29 +104,75 @@ type NameForPattern<TPattern extends string, TRoutes = GetRegisteredRoutes> = {
 }[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`.
+ */
+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. The
+ * payload is wrapped in `JsonSerialize` so it describes the JSON **wire** value a
+ * consumer receives from `fetch().then(r => r.json())`, not the handler's raw
+ * return type — e.g. a handler returning `{ createdAt: Date }` resolves here to
+ * `ResponseEnvelope<{ createdAt: string }>`.
  */
 export type PathResponse<
-  TPattern extends string,
+  TPath 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]
->;
+> = ResponseEnvelope<JsonSerialize<ResponsePayloadFor<TPath, TRoutes>>>;
 
 /**
  * Strip trailing slash from a path (e.g., "/blog/" -> "/blog" | "/blog/")
@@ -140,7 +187,7 @@ type OptionalTrailingSlash<T extends string> = T extends `${infer Base}/`
 /**
  * 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> =
@@ -154,6 +201,76 @@ export type ValidPaths<TRoutes = GetRegisteredRoutes> =
         }[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 `ResponseEnvelope<{ createdAt: string }>`, 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
  *
@@ -186,7 +303,10 @@ export function href<T extends ValidPaths>(path: T, mount?: string): string {
     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;
 }
 
 /**