@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/urls/response-types.ts

@@ -32,21 +32,32 @@ type ResponseReverseFunction = [DefaultReverseRouteMap] extends [
  * Symbol marking a route as a response route (non-RSC).
  * Stored on PathOptions and UrlPatterns to signal the trie to short-circuit.
  */
-export const RESPONSE_TYPE: unique symbol = Symbol.for(
-  "rangojs.responseType",
-) as any;
+export const RESPONSE_TYPE: unique symbol = Symbol.for("rangojs.responseType");
 
 /**
- * Handler that must return Response (not ReactNode).
- * Used by path.image(), path.stream(), path.any() (binary/streaming data).
+ * Shared shape of a response-route handler: a function returning TReturn (or a
+ * promise of it), plus an optional composable `use` thunk merged at mount time.
  */
-export type ResponseHandler<TParams = Record<string, string>, TEnv = any> = ((
+type ResponseHandlerOf<
+  TReturn,
+  TParams = Record<string, string>,
+  TEnv = any,
+> = ((
   ctx: ResponseHandlerContext<TParams, TEnv>,
-) => Response | Promise<Response>) & {
+) => TReturn | Promise<TReturn>) & {
   /** Composable default DSL items merged when the handler is mounted. */
   use?: () => UseItems<ResponseRouteUseItem>;
 };
 
+/**
+ * Handler that must return Response (not ReactNode).
+ * Used by path.image(), path.stream(), path.any() (binary/streaming data).
+ */
+export type ResponseHandler<
+  TParams = Record<string, string>,
+  TEnv = any,
+> = ResponseHandlerOf<Response, TParams, TEnv>;
+
 /**
  * JSON-serializable value type for auto-wrap support.
  */
@@ -65,12 +76,7 @@ export type JsonValue =
 export type JsonResponseHandler<
   TParams = Record<string, string>,
   TEnv = any,
-> = ((
-  ctx: ResponseHandlerContext<TParams, TEnv>,
-) => JsonValue | Response | Promise<JsonValue | Response>) & {
-  /** Composable default DSL items merged when the handler is mounted. */
-  use?: () => UseItems<ResponseRouteUseItem>;
-};
+> = ResponseHandlerOf<JsonValue | Response, TParams, TEnv>;
 
 /**
  * Handler for text-based response routes (text, html, xml).
@@ -79,12 +85,7 @@ export type JsonResponseHandler<
 export type TextResponseHandler<
   TParams = Record<string, string>,
   TEnv = any,
-> = ((
-  ctx: ResponseHandlerContext<TParams, TEnv>,
-) => string | Response | Promise<string | Response>) & {
-  /** Composable default DSL items merged when the handler is mounted. */
-  use?: () => UseItems<ResponseRouteUseItem>;
-};
+> = ResponseHandlerOf<string | Response, TParams, TEnv>;
 
 /**
  * Lighter handler context for response routes.

package/src/urls/type-extraction.ts

@@ -1,4 +1,4 @@
-import type { ExtractParams } from "../types.js";
+import type { JsonSerialize } from "../serialize.js";
 import type {
   TypedRouteItem,
   TypedIncludeItem,
@@ -6,11 +6,7 @@ import type {
   TypedCacheItem,
   TypedTransitionItem,
 } from "../route-types.js";
-import type {
-  LocalOnlyInclude,
-  UnnamedRoute,
-  UrlPatterns,
-} from "./pattern-types.js";
+import type { LocalOnlyInclude, UnnamedRoute } from "./pattern-types.js";
 
 // ============================================================================
 // Route Type Extraction Utilities
@@ -67,62 +63,6 @@ type PrefixPatterns<
       : TRoutes[K];
 };
 
-/**
- * Depth counter for limiting recursion (max 40 levels)
- * Supports up to 40 sibling items at any level of a urls() call
- * Note: Higher values hit TypeScript's internal recursion limits
- */
-type Depth = [
-  never,
-  0,
-  1,
-  2,
-  3,
-  4,
-  5,
-  6,
-  7,
-  8,
-  9,
-  10,
-  11,
-  12,
-  13,
-  14,
-  15,
-  16,
-  17,
-  18,
-  19,
-  20,
-  21,
-  22,
-  23,
-  24,
-  25,
-  26,
-  27,
-  28,
-  29,
-  30,
-  31,
-  32,
-  33,
-  34,
-  35,
-  36,
-  37,
-  38,
-  39,
-];
-
-/**
- * Force TypeScript to eagerly evaluate a type.
- * This helps with interface extension by creating a "concrete" object type.
- */
-type Simplify<T> =
-  T extends Record<string, string> ? { [K in keyof T]: T[K] } : T;
-
 /**
  * Convert a union type to an intersection type.
  * Used to combine route maps from multiple siblings without recursive tuple processing.
@@ -135,24 +75,32 @@ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
 
 /**
  * Extract routes from a single item (path, include, layout, cache with children)
- * D is the current depth level for nested layouts/caches
  */
-type ExtractRoutesFromItem<T, D extends number = 40> = [D] extends [never]
-  ? {} // Max depth reached, stop recursion
-  : // TypedRouteItem: extract name -> pattern (exclude unnamed routes)
-    // When search schema is non-empty, value becomes { path, search } object
-    T extends TypedRouteItem<infer TName, infer TPattern, any, infer TSearch>
+type ExtractRoutesFromItem<T> =
+  // TypedRouteItem: extract name -> pattern (exclude unnamed routes)
+  // When search schema is non-empty, value becomes { path, search } object
+  T extends TypedRouteItem<infer TName, infer TPattern, any, infer TSearch>
     ? TName extends string
-      ? TName extends UnnamedRoute
-        ? {} // Exclude unnamed routes from type map
-        : {} extends TSearch
-          ? { [K in TName]: TPattern }
-          : {
-              [K in TName]: {
-                readonly path: TPattern;
-                readonly search: TSearch;
-              };
-            }
+      ? // Widened-name guard (#642): some name-less call forms — notably the
+        // 3-arg children-fn overload path(pattern, component, () => [...]) —
+        // let TName infer to the bare `string` constraint instead of the
+        // UnnamedRoute sentinel, because the children-fn argument structurally
+        // satisfies the all-optional PathOptions<TName> union member. Mapping
+        // over a bare `string` key would emit `{ [K in string]: TPattern }`, an
+        // index signature that poisons the whole sibling map (Rango.Path
+        // collapses to never). Treat an unresolved name as unnamed.
+        string extends TName
+        ? {}
+        : TName extends UnnamedRoute
+          ? {} // Exclude unnamed routes from type map
+          : {} extends TSearch
+            ? { [K in TName]: TPattern }
+            : {
+                [K in TName]: {
+                  readonly path: TPattern;
+                  readonly search: TSearch;
+                };
+              }
       : {}
     : // TypedIncludeItem: extract prefixed routes (both name and URL prefix)
       T extends TypedIncludeItem<
@@ -185,30 +133,28 @@ type ExtractRoutesFromItem<T, D extends number = 40> = [D] extends [never]
  * Extract routes from an array of items using mapped types.
  * Uses UnionToIntersection to combine routes without recursive tuple processing,
  * removing the sibling limit that was caused by TypeScript recursion limits.
- * D is passed to ExtractRoutesFromItem for nested depth tracking.
  */
-type ExtractRoutesFromItems<
-  T extends readonly any[],
-  D extends number = 40,
-> = T extends readonly any[]
+type ExtractRoutesFromItems<T extends readonly any[]> = T extends readonly any[]
   ? UnionToIntersection<
-      { [K in keyof T]: ExtractRoutesFromItem<T[K], D> }[number]
+      { [K in keyof T]: ExtractRoutesFromItem<T[K]> }[number]
     > extends infer R
-    ? R extends Record<string, any>
-      ? R
-      : {}
+    ? // Blast-radius guard: never let a single malformed item collapse the
+      // whole map. A `never` intersection satisfies `extends Record<string,any>`
+      // (never extends everything), so check it explicitly first and fall back
+      // to `{}` rather than propagating `never`. See #642.
+      [R] extends [never]
+      ? {}
+      : R extends Record<string, any>
+        ? R
+        : {}
     : {}
   : {};
 
 /**
  * Main utility: extract route map from urls() callback return type
  * Uses mapped types for sibling processing (no sibling limit).
- * Uses Simplify to force eager evaluation for interface extension compatibility.
  */
-export type ExtractRoutes<T extends readonly any[]> = ExtractRoutesFromItems<
-  T,
-  40
->;
+export type ExtractRoutes<T extends readonly any[]> = ExtractRoutesFromItems<T>;
 
 // ============================================================================
 // Response Type Extraction Utilities
@@ -236,13 +182,18 @@ type PrefixKeys<
  * Extract response data types from a single item.
  * Parallel to ExtractRoutesFromItem but extracts name -> TData mapping.
  */
-type ExtractResponsesFromItem<T, D extends number = 40> = [D] extends [never]
-  ? {}
-  : T extends TypedRouteItem<infer TName, any, infer TData>
+type ExtractResponsesFromItem<T> =
+  T extends TypedRouteItem<infer TName, any, infer TData>
     ? TName extends string
-      ? TName extends UnnamedRoute
+      ? // Widened-name guard (#642), parallels ExtractRoutesFromItem. A name-less
+        // children-fn path.json(pattern, handler, () => [...]) infers TName as
+        // bare `string`; without this the response map picks up an index
+        // signature { [K in string]: TData } that wipes named siblings.
+        string extends TName
         ? {}
-        : { [K in TName]: TData }
+        : TName extends UnnamedRoute
+          ? {}
+          : { [K in TName]: TData }
       : {}
     : T extends TypedIncludeItem<any, infer TNamePrefix, any, infer TResponses>
       ? TNamePrefix extends LocalOnlyInclude
@@ -272,86 +223,75 @@ type ExtractResponsesFromItem<T, D extends number = 40> = [D] extends [never]
  * Extract responses from an array of items using mapped types.
  * Parallel to ExtractRoutesFromItems.
  */
-type ExtractResponsesFromItems<
-  T extends readonly any[],
-  D extends number = 40,
-> = T extends readonly any[]
-  ? UnionToIntersection<
-      { [K in keyof T]: ExtractResponsesFromItem<T[K], D> }[number]
-    > extends infer R
-    ? R extends Record<string, unknown>
-      ? R
+type ExtractResponsesFromItems<T extends readonly any[]> =
+  T extends readonly any[]
+    ? UnionToIntersection<
+        { [K in keyof T]: ExtractResponsesFromItem<T[K]> }[number]
+      > extends infer R
+      ? // Blast-radius guard (parallels ExtractRoutesFromItems). See #642.
+        [R] extends [never]
+        ? {}
+        : R extends Record<string, unknown>
+          ? R
+          : {}
       : {}
-    : {}
-  : {};
+    : {};
 
 /**
  * Main utility: extract response data type map from urls() callback return type.
  * Parallel to ExtractRoutes.
  */
 export type ExtractResponses<T extends readonly any[]> =
-  ExtractResponsesFromItems<T, 40>;
-
-// ============================================================================
-// Type Utilities for path()
-// ============================================================================
-
-/**
- * Extract route names from a UrlPatterns result
- * Used for type-safe href() generation
- */
-export type ExtractRouteNames<T extends UrlPatterns<any>> =
-  T extends UrlPatterns<infer _TEnv>
-    ? string // For now, will be refined with full implementation
-    : never;
-
-/**
- * Extract params for a specific route name
- */
-export type ExtractPathParams<
-  T extends UrlPatterns<any>,
-  K extends string,
-> = ExtractParams<string>; // Will be refined with pattern tracking
+  ExtractResponsesFromItems<T>;
 
 // ============================================================================
-// Response Envelope Types
+// Response Error (RFC 9457 problem+json) Type
 // ============================================================================
 
 /**
- * Error shape returned in the `{ error }` side of a JSON response envelope.
- */
-export interface ResponseError {
-  message: string;
-  code?: string;
-  type?: string;
-  stack?: string;
-}
-
-/**
- * Discriminated union envelope for JSON response routes.
- * Consumers check `result.error` to discriminate between success and failure.
+ * RFC 9457 (problem+json) error body returned by JSON response routes on a
+ * non-2xx status. Sent verbatim as the response body (not wrapped) with
+ * content-type `application/problem+json`.
  *
  * @example
  * ```typescript
- * const result: ResponseEnvelope<Product> = await fetch(url).then(r => r.json());
- * if (result.error) {
- *   console.log(result.error.message, result.error.code);
+ * const res = await fetch(url);
+ * if (!res.ok) {
+ *   const problem: ProblemDetails = await res.json();
+ *   console.log(problem.code, problem.detail); // "NOT_FOUND", "Product not found"
  *   return;
  * }
- * result.data.name // fully typed
+ * const product = await res.json(); // bare value, no envelope
  * ```
  */
-export type ResponseEnvelope<T> =
-  | { data: T; error?: undefined }
-  | { data?: undefined; error: ResponseError };
+export interface ProblemDetails {
+  /**
+   * URI reference identifying the problem type. Omitted in this phase (per RFC
+   * 9457 an absent `type` is treated as `"about:blank"` — no semantics beyond
+   * the HTTP status); per-route problem-type URIs arrive with the
+   * declared-errors map later.
+   */
+  type?: string;
+  /** Short, human-readable summary (the HTTP status reason phrase). */
+  title: string;
+  /** The HTTP status code. */
+  status: number;
+  /** Human-readable explanation specific to this occurrence (the error message). */
+  detail: string;
+  /** Stable machine-readable error code (`RouterError.code`, else `"INTERNAL"`). */
+  code: string;
+  /** Stack trace, included in development only. */
+  stack?: string;
+}
 
 // ============================================================================
 // Response Type Consumer Utilities
 // ============================================================================
 
 /**
- * Extract the response data type for a named route from a UrlPatterns instance.
- * Wraps in ResponseEnvelope since JSON response routes return enveloped data.
+ * Extract the JSON response payload type for a named route from a UrlPatterns
+ * instance. JSON response routes send the handler's return value verbatim
+ * (bare), so this resolves to the wire value a consumer receives — no envelope.
  *
  * @example
  * ```typescript
@@ -360,13 +300,17 @@ export type ResponseEnvelope<T> =
  * ]);
  *
  * type HealthData = RouteResponse<typeof apiPatterns, "health">;
- * // ResponseEnvelope<{ status: string; timestamp: number }>
+ * // { status: string; timestamp: number }
  * ```
+ *
+ * The payload is the JSON wire shape (via `Rango.JsonSerialize`), matching
+ * `Rango.PathResponse` and what `fetch().then(r => r.json())` actually yields —
+ * e.g. a `Date` field resolves as `string`.
  */
 export type RouteResponse<TPatterns, TName extends string> = TPatterns extends {
   readonly _responses?: infer R;
 }
   ? TName extends keyof R
-    ? ResponseEnvelope<Exclude<R[TName], Response>>
+    ? JsonSerialize<Exclude<R[TName], Response>>
     : never
   : never;

package/src/urls/urls-function.ts

@@ -3,7 +3,7 @@ import type { AllUseItems } from "../route-types.js";
 import { getContext } from "../server/context";
 import { invariant } from "../errors";
 import { createRouteHelpers } from "../route-definition.js";
-import type { PathDefinition, UrlPatterns } from "./pattern-types.js";
+import type { UrlPatterns } from "./pattern-types.js";
 import type { PathHelpers } from "./path-helper-types.js";
 import type { ExtractRoutes, ExtractResponses } from "./type-extraction.js";
 import { createPathHelper, attachPathResponseTags } from "./path-helper.js";
@@ -34,27 +34,18 @@ export function urls<
 >(
   builder: (helpers: PathHelpers<TEnv>) => TItems,
 ): UrlPatterns<TEnv, ExtractRoutes<TItems>, ExtractResponses<TItems>> {
-  // Collect path definitions during build
-  const definitions: PathDefinition[] = [];
-
-  // Create the handler function that will be called by the router
   const handler = () => {
     invariant(
       typeof builder === "function",
       "urls() expects a builder function as its argument",
     );
 
-    // Get base helpers from the existing route-definition module
     const baseHelpers = createRouteHelpers<any, TEnv>();
 
-    // Create the path helper (with .json, .text, .html, .xml, .image, .stream, .any tags)
     const pathHelper = attachPathResponseTags(createPathHelper<TEnv>());
 
-    // Create the include helper
     const includeHelper = createIncludeHelper<TEnv>();
 
-    // Combine all helpers
-    // Note: layout and cache are cast to their typed versions - phantom types don't affect runtime
     const helpers: PathHelpers<TEnv> = {
       path: pathHelper as any,
       include: includeHelper as any,
@@ -67,26 +58,17 @@ export function urls<
       loading: baseHelpers.loading,
       errorBoundary: baseHelpers.errorBoundary,
       notFoundBoundary: baseHelpers.notFoundBoundary,
-      when: baseHelpers.when,
       cache: baseHelpers.cache as PathHelpers<TEnv>["cache"],
       transition: baseHelpers.transition as PathHelpers<TEnv>["transition"],
     };
 
-    // Execute builder directly - manifest.ts handles RootLayout wrapping
-    // for inline handlers (non-Promise results).
-    // For nested include() calls, routes inherit the outer RootLayout.
     const builderResult = builder(helpers).flat(3) as AllUseItems[];
     return processItems(builderResult);
   };
 
-  // trailingSlash config is populated when handler() runs
-  // We expose it via a getter that reads from the context after handler execution
   return {
-    definitions,
     handler,
     get trailingSlash() {
-      // Get the trailingSlash map from the current context
-      // This will be populated after handler() is called
       const store = getContext();
       const ctx = store.context.getStore();
       if (!ctx?.trailingSlash) {