@rangojs/router 0.0.0-experimental.debug-cache-2383ca26 → 0.0.0-experimental.df410dd5

package/src/urls/path-helper.ts

@@ -1,21 +1,17 @@
 import type { ReactNode } from "react";
 import type { Handler } from "../types.js";
-import type {
-  AllUseItems,
-  RouteItem,
-  RouteUseItem,
-  UseItems,
-} from "../route-types.js";
+import type { RouteItem, RouteUseItem, UseItems } from "../route-types.js";
 import {
-  getContext,
   getUrlPrefix,
   getNamePrefix,
   getRootScoped,
+  requireDslContext,
 } from "../server/context";
-import { invariant } from "../errors";
+import { invariant, DataNotFoundError } from "../errors";
 import { validateUserRouteName } from "../route-name.js";
 import {
   isPrerenderHandler,
+  isPassthroughHandler,
   type PrerenderHandlerDefinition,
 } from "../prerender.js";
 import {
@@ -34,35 +30,14 @@ import type {
   JsonResponsePathFn,
   TextResponsePathFn,
 } from "./path-helper-types.js";
-
-/**
- * Check if a value is a valid use item
- */
-const isValidUseItem = (item: any): item is AllUseItems | undefined | null => {
-  return (
-    typeof item === "undefined" ||
-    item === null ||
-    (item &&
-      typeof item === "object" &&
-      "type" in item &&
-      [
-        "layout",
-        "route",
-        "middleware",
-        "revalidate",
-        "parallel",
-        "intercept",
-        "loader",
-        "loading",
-        "errorBoundary",
-        "notFoundBoundary",
-        "when",
-        "cache",
-        "transition",
-        "include",
-      ].includes(item.type))
-  );
-};
+import {
+  resolveHandlerUse,
+  mergeHandlerUse,
+} from "../route-definition/resolve-handler-use.js";
+import {
+  emptySegmentBase,
+  runAndValidateUseItems,
+} from "../route-definition/dsl-helpers.js";
 
 /**
  * Apply URL prefix to a pattern
@@ -107,9 +82,9 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
     optionsOrUse?: PathOptions | (() => UseItems<RouteUseItem>),
     maybeUse?: () => UseItems<RouteUseItem>,
   ): RouteItem => {
-    const store = getContext();
-    const ctx = store.getStore();
-    if (!ctx) throw new Error("path() must be called inside urls()");
+    const { store, ctx } = requireDslContext(
+      "path() must be called inside urls()",
+    );
 
     invariant(
       !ctx.parent || ctx.parent.type !== "parallel",
@@ -142,6 +117,12 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       use = maybeUse;
     }
 
+    // Merge handler.use() defaults with explicit use()
+    // Response routes (path.json, path.text, etc.) only allow middleware + cache
+    const handlerUseFn = resolveHandlerUse(handler);
+    const mountSite = resolveResponseType(options) ? "response" : "path";
+    const mergedUse = mergeHandlerUse(handlerUseFn, use, mountSite);
+
     // Get prefixes from context (set by include())
     const urlPrefix = getUrlPrefix();
     const namePrefix = getNamePrefix();
@@ -176,16 +157,34 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
     }
 
     // Ensure handler is always a function (wrap ReactNode or extract from prerender/static def)
+    // For prerender stubs (production builds where handler code is evicted),
+    // handler.handler is undefined — provide a notFound fallback so requests
+    // for non-prerendered params get 404 instead of "handler is not a function".
     const wrappedHandler: Handler<any, any, TEnv> =
       typeof handler === "function"
         ? (handler as Handler<any, any, TEnv>)
-        : isPrerenderHandler(handler)
-          ? (handler.handler as Handler<any, any, TEnv>)
-          : isStaticHandler(handler)
-            ? (handler.handler as Handler<any, any, TEnv>)
-            : () => handler;
+        : isPassthroughHandler(handler)
+          ? typeof handler.prerenderDef.handler === "function"
+            ? (handler.prerenderDef.handler as Handler<any, any, TEnv>)
+            : () => {
+                throw new DataNotFoundError(
+                  "No prerender data found for this route",
+                );
+              }
+          : isPrerenderHandler(handler)
+            ? typeof handler.handler === "function"
+              ? (handler.handler as Handler<any, any, TEnv>)
+              : () => {
+                  throw new DataNotFoundError(
+                    "No prerender data found for this route",
+                  );
+                }
+            : isStaticHandler(handler)
+              ? (handler.handler as Handler<any, any, TEnv>)
+              : () => handler;
 
     const entry = {
+      ...emptySegmentBase(),
       id: namespace,
       shortCode: store.getShortCode("route"),
       type: "route" as const,
@@ -193,22 +192,20 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       handler: wrappedHandler,
       // Store the PREFIXED pattern for route matching
       pattern: prefixedPattern,
-      loading: undefined,
-      middleware: [],
-      revalidate: [],
-      errorBoundary: [],
-      notFoundBoundary: [],
-      layout: [],
-      parallel: {},
-      intercept: [],
-      loader: [],
       ...(urlPrefix ? { mountPath: urlPrefix } : {}),
-      ...(isPrerenderHandler(handler)
+      ...(isPassthroughHandler(handler)
         ? {
             isPrerender: true as const,
-            prerenderDef: handler as PrerenderHandlerDefinition,
+            prerenderDef: handler.prerenderDef as PrerenderHandlerDefinition,
+            isPassthrough: true as const,
+            liveHandler: handler.liveHandler as Handler<any, any, TEnv>,
           }
-        : {}),
+        : isPrerenderHandler(handler)
+          ? {
+              isPrerender: true as const,
+              prerenderDef: handler as PrerenderHandlerDefinition,
+            }
+          : {}),
       ...(isStaticHandler(handler)
         ? {
             isStaticPrerender: true as const,
@@ -264,12 +261,15 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       registerSearchSchema(routeName, options.search);
     }
 
-    // Run use callback if provided
-    if (use && typeof use === "function") {
-      const result = store.run(namespace, entry, use)?.flat(3);
-      invariant(
-        Array.isArray(result) && result.every((item) => isValidUseItem(item)),
-        `path() use() callback must return an array of use items [${namespace}]`,
+    // Run merged use callback (handler.use defaults + explicit use) if present
+    if (mergedUse) {
+      const result = runAndValidateUseItems(
+        store,
+        namespace,
+        entry,
+        mergedUse,
+        "path",
+        "use",
       );
       return { name: namespace, type: "route", uses: result } as RouteItem;
     }

package/src/urls/pattern-types.ts

@@ -1,12 +1,19 @@
-import type { ReactNode } from "react";
-import type { Handler, TrailingSlashMode } from "../types.js";
-import type {
-  AllUseItems,
-  RouteUseItem,
-  UrlPatternsBrand,
-} from "../route-types.js";
+import type { TrailingSlashMode } from "../types.js";
+import type { AllUseItems, UrlPatternsBrand } from "../route-types.js";
 import type { SearchSchema } from "../search-params.js";
 import { RESPONSE_TYPE } from "./response-types.js";
+import type { DefaultEnv } from "../types.js";
+import type { PathHelpers } from "./path-helper-types.js";
+
+/**
+ * Builder function accepted by urls() and as a shorthand for routes()/urls option.
+ * When passed directly to routes() or createRouter({ urls }), it is wrapped in urls() automatically.
+ */
+export type UrlBuilder<
+  TEnv = DefaultEnv,
+  TItems extends readonly (AllUseItems | readonly AllUseItems[])[] =
+    readonly AllUseItems[],
+> = (helpers: PathHelpers<TEnv>) => TItems;
 
 /**
  * Sentinel type for unnamed routes.
@@ -42,16 +49,6 @@ export interface PathOptions<
   [RESPONSE_TYPE]?: string;
 }
 
-/**
- * Internal representation of a URL pattern definition
- */
-export interface PathDefinition {
-  pattern: string;
-  name?: string;
-  handler: ReactNode | Handler<any, any, any>;
-  use?: RouteUseItem[];
-}
-
 /**
  * Result of urls() - contains the route definitions
  */
@@ -60,8 +57,6 @@ export interface UrlPatterns<
   TRoutes extends Record<string, any> = Record<string, string>,
   TResponses extends Record<string, unknown> = Record<string, unknown>,
 > {
-  /** Internal: route definitions */
-  readonly definitions: PathDefinition[];
   /** Internal: compiled handler function */
   readonly handler: () => AllUseItems[];
   /** Internal: trailing slash config per route name */
@@ -76,6 +71,40 @@ export interface UrlPatterns<
   readonly _responses?: TResponses;
 }
 
+/**
+ * Extract the phantom env type carried by a UrlPatterns value.
+ */
+export type UrlPatternsEnv<T> =
+  T extends UrlPatterns<infer TEnv, any, any> ? TEnv : never;
+
+/**
+ * Guards `routes()` env compatibility without over-constraining.
+ *
+ * - An env-agnostic block (its env is `unknown` — e.g. a shared urls() module,
+ *   or an app that does not augment `Rango.Env`) attaches to any router.
+ * - A block carrying a concrete env is accepted only when the router env
+ *   (`TRouterEnv`) satisfies it; resolves to `never` otherwise, so a
+ *   `urls<{ DB: D1Database }>()` cannot be mounted on a `createRouter<{}>()`.
+ *
+ * Use as `patterns: T & EnvCompatible<T, TEnv>` so `T` still infers from the
+ * argument — a bare `EnvCompatible<T, TEnv>` parameter sits in a non-inferrable
+ * conditional position and would collapse `T` to its constraint.
+ *
+ * Known limitation: `TRouterEnv extends ...` distributes over a union router env,
+ * so a `urls<A>()` block is accepted on `createRouter<A | B>()` even though the
+ * `B` arm cannot supply `A`'s env. Suppressing distribution with
+ * `[TRouterEnv] extends [...]` would close that edge but breaks the common
+ * generic-`TEnv` call sites (a deferred type parameter can't resolve the tuple
+ * conditional, so the intersection stops reducing to `T`). A router has one env,
+ * so a union env is not a supported pattern; the distributive form is kept.
+ */
+export type EnvCompatible<TPatterns, TRouterEnv> =
+  unknown extends UrlPatternsEnv<TPatterns>
+    ? TPatterns
+    : TRouterEnv extends UrlPatternsEnv<TPatterns>
+      ? TPatterns
+      : never;
+
 /**
  * Options for include()
  */

package/src/urls/response-types.ts

@@ -4,6 +4,8 @@ import type {
   DefaultReverseRouteMap,
   DefaultVars,
 } from "../types/global-namespace.js";
+import type { UseItems, ResponseRouteUseItem } from "../route-types.js";
+import type { RequestScope } from "../types/request-scope.js";
 
 /**
  * Reverse function for response handler contexts.
@@ -30,17 +32,31 @@ 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");
+
+/**
+ * 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.
+ */
+type ResponseHandlerOf<
+  TReturn,
+  TParams = Record<string, string>,
+  TEnv = any,
+> = ((
+  ctx: ResponseHandlerContext<TParams, TEnv>,
+) => 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> = (
-  ctx: ResponseHandlerContext<TParams, TEnv>,
-) => Response | Promise<Response>;
+export type ResponseHandler<
+  TParams = Record<string, string>,
+  TEnv = any,
+> = ResponseHandlerOf<Response, TParams, TEnv>;
 
 /**
  * JSON-serializable value type for auto-wrap support.
@@ -60,9 +76,7 @@ export type JsonValue =
 export type JsonResponseHandler<
   TParams = Record<string, string>,
   TEnv = any,
-> = (
-  ctx: ResponseHandlerContext<TParams, TEnv>,
-) => JsonValue | Response | Promise<JsonValue | Response>;
+> = ResponseHandlerOf<JsonValue | Response, TParams, TEnv>;
 
 /**
  * Handler for text-based response routes (text, html, xml).
@@ -71,9 +85,7 @@ export type JsonResponseHandler<
 export type TextResponseHandler<
   TParams = Record<string, string>,
   TEnv = any,
-> = (
-  ctx: ResponseHandlerContext<TParams, TEnv>,
-) => string | Response | Promise<string | Response>;
+> = ResponseHandlerOf<string | Response, TParams, TEnv>;
 
 /**
  * Lighter handler context for response routes.
@@ -83,19 +95,10 @@ export type TextResponseHandler<
 export interface ResponseHandlerContext<
   TParams = Record<string, string>,
   TEnv = any,
-> {
-  request: Request;
+> extends RequestScope<TEnv> {
   params: TParams;
   /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
   readonly _paramCheck?: (params: TParams) => TParams;
-  /** Platform bindings (DB, KV, secrets, etc.). */
-  env: TEnv;
-  /** Query parameters from the URL (system params like `_rsc*` are filtered). */
-  searchParams: URLSearchParams;
-  /** The full URL object (with system params filtered). */
-  url: URL;
-  /** The pathname portion of the request URL. */
-  pathname: string;
   reverse: ResponseReverseFunction;
   /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
   get: {

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,13 +75,11 @@ 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
@@ -185,14 +123,10 @@ 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
@@ -203,12 +137,8 @@ type ExtractRoutesFromItems<
 /**
  * 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,9 +166,8 @@ 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
         ? {}
@@ -272,46 +201,23 @@ 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
+      ? 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
@@ -362,11 +268,15 @@ export type ResponseEnvelope<T> =
  * type HealthData = RouteResponse<typeof apiPatterns, "health">;
  * // ResponseEnvelope<{ 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>>
+    ? ResponseEnvelope<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,9 +34,6 @@ 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(
@@ -82,7 +79,6 @@ export function urls<
   // 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