@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

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,40 +30,15 @@ import type {
   JsonResponsePathFn,
   TextResponsePathFn,
 } from "./path-helper-types.js";
+import {
+  resolveHandlerUse,
+  mergeHandlerUse,
+} from "../route-definition/resolve-handler-use.js";
+import {
+  emptySegmentBase,
+  runAndValidateUseItems,
+} from "../route-definition/dsl-helpers.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))
-  );
-};
-
-/**
- * Apply URL prefix to a pattern
- * Handles edge cases like "/" patterns and double slashes
- */
 function applyUrlPrefix(prefix: string, pattern: string): string {
   if (!prefix) return pattern;
   if (pattern === "/") return prefix;
@@ -77,29 +48,17 @@ function applyUrlPrefix(prefix: string, pattern: string): string {
   return prefix + pattern;
 }
 
-/**
- * Apply name prefix to a route name
- */
 function applyNamePrefix(prefix: string | undefined, name: string): string {
   if (!prefix) return name;
   return `${prefix}.${name}`;
 }
 
-/**
- * Resolve response type from path options (set by path.json(), path.text(), etc.)
- */
 function resolveResponseType(
   options: PathOptions | undefined,
 ): string | undefined {
   return options?.[RESPONSE_TYPE];
 }
 
-/**
- * Create path() helper
- *
- * The path() function is the key new feature - it combines URL pattern
- * with handler at the definition site.
- */
 export function createPathHelper<TEnv>(): PathFn<TEnv> {
   return ((
     pattern: string,
@@ -107,17 +66,15 @@ 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",
       "path() cannot be used inside parallel()",
     );
 
-    // Walk the parent chain to prevent path() nested under another path(),
-    // even when separated by intermediate layouts (e.g. path(layout(path())))
     {
       let ancestor = ctx.parent;
       while (ancestor) {
@@ -129,7 +86,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       }
     }
 
-    // Determine options and use based on argument types
     let options: PathOptions | undefined;
     let use: (() => UseItems<RouteUseItem>) | undefined;
 
@@ -142,73 +98,74 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       use = maybeUse;
     }
 
-    // Get prefixes from context (set by include())
+    const handlerUseFn = resolveHandlerUse(handler);
+    const mountSite = resolveResponseType(options) ? "response" : "path";
+    const mergedUse = mergeHandlerUse(handlerUseFn, use, mountSite);
+
     const urlPrefix = getUrlPrefix();
     const namePrefix = getNamePrefix();
 
-    // Apply URL prefix to pattern
     const prefixedPattern = applyUrlPrefix(urlPrefix, pattern);
 
-    // Generate route name - use provided name or generate from pattern
     const localName =
       options?.name || `$path_${pattern.replace(/[/:*?]/g, "_")}`;
     if (options?.name) {
       validateUserRouteName(options.name);
     }
-    // Apply name prefix if set (from include())
     const routeName = applyNamePrefix(namePrefix, localName);
 
     const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${routeName}`;
 
-    // Per-request pruning: skip registration for routes that won't be rendered.
-    // forRoute is set by loadManifest() to the matched route name. During
-    // evaluateLazyEntry() (route matching), forRoute is unset so all routes
-    // register normally. We still increment counters to keep shortCodes stable
-    // across different routes (needed for segment reconciliation on navigation).
-    //
-    // include() does not need its own forRoute pruning. include() creates lazy
-    // entries that defer handler execution until route matching. When the lazy
-    // handler eventually runs inside loadManifest(), this path() check already
-    // covers all routes defined inside the include.
     if (ctx.forRoute && routeName !== ctx.forRoute) {
       store.getShortCode("route");
       return { type: "route" } as RouteItem;
     }
 
-    // Ensure handler is always a function (wrap ReactNode or extract from prerender/static def)
     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,
       parent: ctx.parent,
       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,
@@ -218,31 +175,30 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       ...(resolveResponseType(options)
         ? { responseType: resolveResponseType(options) }
         : {}),
+      // PPR shell-caching opt-in (document-level). Stored raw; the integrated
+      // serve path normalizes it via resolvePprConfig (rsc/shell-serve.ts).
+      ...(options?.ppr !== undefined && options.ppr !== false
+        ? { ppr: options.ppr }
+        : {}),
     };
 
-    // Capture namespace prefix on static handler for build-time reverse() resolution
     if (isStaticHandler(handler) && handler.$$id && ctx.namePrefix) {
       (handler as any).$$routePrefix = ctx.namePrefix;
     }
 
-    // Check for duplicate route names (TypeScript should catch this, but runtime check too)
     invariant(
       ctx.manifest.get(routeName) === undefined,
       `Duplicate route name: ${routeName} at ${namespace}`,
     );
 
-    // Register route entry with prefixed name
     ctx.manifest.set(routeName, entry);
 
-    // Register root-scope flag for dot-local reverse resolution
     registerRouteRootScope(routeName, getRootScoped());
 
-    // Also store pattern in a separate map for URL generation
     if (ctx.patterns) {
       ctx.patterns.set(routeName, prefixedPattern);
     }
 
-    // Store pattern grouped by URL prefix for separate entry creation
     if (ctx.patternsByPrefix) {
       const urlPrefix = getUrlPrefix() || "";
       if (!ctx.patternsByPrefix.has(urlPrefix)) {
@@ -251,12 +207,10 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
       ctx.patternsByPrefix.get(urlPrefix)!.set(routeName, prefixedPattern);
     }
 
-    // Store trailing slash config if specified
     if (options?.trailingSlash && ctx.trailingSlash) {
       ctx.trailingSlash.set(routeName, options.trailingSlash);
     }
 
-    // Store search schema if specified
     if (options?.search) {
       if (ctx.searchSchemas) {
         ctx.searchSchemas.set(routeName, options.search);
@@ -264,12 +218,14 @@ 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}]`,
+    if (mergedUse) {
+      const result = runAndValidateUseItems(
+        store,
+        namespace,
+        entry,
+        mergedUse,
+        "path",
+        "use",
       );
       return { name: namespace, type: "route", uses: result } as RouteItem;
     }
@@ -278,10 +234,6 @@ export function createPathHelper<TEnv>(): PathFn<TEnv> {
   }) as PathFn<TEnv>;
 }
 
-/**
- * Attach response type tag methods (.json, .text, .html, .xml, .md, .image, .stream, .any) to a path helper.
- * Each tag wraps the original path() call with the RESPONSE_TYPE option set.
- */
 export function attachPathResponseTags<TEnv>(
   pathFn: PathFn<TEnv>,
 ): PathFn<TEnv> & {
@@ -303,7 +255,6 @@ export function attachPathResponseTags<TEnv>(
     ) => {
       let options: PathOptions;
       let use: (() => any[]) | undefined;
-
       if (typeof optionsOrUse === "function") {
         options = { [RESPONSE_TYPE]: responseType };
         use = optionsOrUse;

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.
@@ -28,12 +35,48 @@ export type LocalOnlyInclude = string & { [LOCAL_ONLY_BRAND]: void };
 /**
  * Options for path() function
  */
+/**
+ * Options for the `ppr` path option (PPR shell caching — Axis 2, see
+ * docs/design/ppr-shell-resume.md and the /ppr skill). Declaring
+ * `ppr: true | PartialPrerenderProps` on a page route opts that DOCUMENT into
+ * shell capture: the rendered HTML shell (everything that is not a live hole) is
+ * cached and, on a later GET, flushed immediately while fizz resumes only the
+ * holes. Serving is integral to the router — there is no middleware to mount;
+ * the shell store is the app-level `createRouter({ cache })` store (which must
+ * implement the `getShell`/`putShell` family).
+ */
+export interface PartialPrerenderProps {
+  /**
+   * Shell time-to-live in seconds. Defaults to 300 (`ppr: true` uses the same
+   * default).
+   */
+  ttl?: number;
+  /**
+   * Stale-while-revalidate window in seconds: a stale shell is still served
+   * while a background recapture refreshes it.
+   */
+  swr?: number;
+  /**
+   * Operational tags attached to the captured shell entry for
+   * `updateTag()`/`revalidateTag()`-driven eviction. UNIONED with the tags the
+   * capture render auto-collects (the shell's own non-loader request tags).
+   */
+  tags?: string[];
+}
+
 export interface PathOptions<
   TName extends string = string,
   TSearch extends SearchSchema = {},
 > {
   /** Route name for href() lookups */
   name?: TName;
+  /**
+   * PPR shell caching opt-in for this page route (document-level). `true` uses
+   * the default policy (ttl 300); an object sets ttl/swr/tags. See
+   * {@link PartialPrerenderProps}. Routes without this option are pure axis 1 —
+   * no capture, no store reads, no logs.
+   */
+  ppr?: boolean | PartialPrerenderProps;
   /** Search param schema for typed query parameters */
   search?: TSearch;
   /** Trailing slash behavior: "never" (redirect /path/ to /path), "always" (redirect /path to /path/), "ignore" (match both) */
@@ -42,16 +85,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 +93,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 +107,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: {