@rangojs/router 0.0.0-experimental.b9cb8739 → 0.0.0-experimental.bd6e11bc

package/src/debug.ts

@@ -2,7 +2,7 @@
  * Debug utilities for manifest inspection and comparison
  */
 
-import type { EntryData } from "./server/context";
+import { getParallelSlotCount, type EntryData } from "./server/context";
 
 /**
  * Serialized entry for debug output
@@ -64,7 +64,7 @@ export function serializeManifest(
       hasLoader: entry.loader?.length > 0,
       hasMiddleware: entry.middleware?.length > 0,
       hasErrorBoundary: entry.errorBoundary?.length > 0,
-      parallelCount: entry.parallel?.length ?? 0,
+      parallelCount: getParallelSlotCount(entry.parallel),
       interceptCount: entry.intercept?.length ?? 0,
     };
 

package/src/decode-loader-results.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from "react";
+import { isLoaderDataResult } from "./types.js";
+
+// Shared by segment-system (server) and LoaderResolver (client) so the
+// legacy/ok/error-fallback/throw decode of resolved loader values lives once.
+// Last failing loader wins errorFallback; an error without a fallback throws.
+export function decodeLoaderResults(
+  resolvedData: any[],
+  loaderIds: string[],
+): { loaderData: Record<string, any>; errorFallback: ReactNode } {
+  const loaderData: Record<string, any> = {};
+  let errorFallback: ReactNode = null;
+
+  for (let i = 0; i < loaderIds.length; i++) {
+    const id = loaderIds[i];
+    const result = resolvedData[i];
+
+    if (!isLoaderDataResult(result)) {
+      loaderData[id] = result;
+      continue;
+    }
+
+    if (result.ok) {
+      loaderData[id] = result.data;
+      continue;
+    }
+
+    if (result.fallback) {
+      errorFallback = result.fallback;
+    } else {
+      throw new Error(result.error.message);
+    }
+  }
+
+  return { loaderData, errorFallback };
+}

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,
@@ -133,3 +146,43 @@ export function isHandle(value: unknown): value is Handle<unknown, unknown> {
     (value as { __brand: unknown }).__brand === "handle"
   );
 }
+
+/**
+ * Collect handle data from a HandleData map, applying the handle's collect
+ * function over segments in order. Shared between server-side rendered()
+ * reads and client-side useHandle().
+ *
+ * @param handle - The handle to collect data for
+ * @param data - Full handle data map (handleName -> segmentId -> entries[])
+ * @param segmentOrder - Segment IDs in parent -> child resolution order
+ */
+export function collectHandleData<TData, TAccumulated>(
+  handle: Handle<TData, TAccumulated>,
+  data: Record<string, Record<string, unknown[]>>,
+  segmentOrder: string[],
+): TAccumulated {
+  const collectFn = getCollectFn(handle.$$id);
+  if (!collectFn && process.env.NODE_ENV !== "production") {
+    console.warn(
+      `[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.`,
+    );
+  }
+  const collect = (collectFn ??
+    (defaultCollect as unknown as (segments: unknown[][]) => unknown)) as (
+    segments: TData[][],
+  ) => TAccumulated;
+
+  const segmentData = data[handle.$$id];
+  if (!segmentData) return collect([]);
+
+  const segmentArrays: TData[][] = [];
+  for (const segmentId of segmentOrder) {
+    const entries = segmentData[segmentId];
+    if (entries && entries.length > 0) {
+      segmentArrays.push(entries as TData[]);
+    }
+  }
+  return collect(segmentArrays);
+}

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[]>>(