@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

package/src/urls/path-helper.ts

@@ -0,0 +1,280 @@
+import type { ReactNode } from "react";
+import type { Handler } from "../types.js";
+import type { RouteItem, RouteUseItem, UseItems } from "../route-types.js";
+import {
+  getUrlPrefix,
+  getNamePrefix,
+  getRootScoped,
+  requireDslContext,
+} from "../server/context";
+import { invariant, DataNotFoundError } from "../errors";
+import { validateUserRouteName } from "../route-name.js";
+import {
+  isPrerenderHandler,
+  isPassthroughHandler,
+  type PrerenderHandlerDefinition,
+} from "../prerender.js";
+import {
+  isStaticHandler,
+  type StaticHandlerDefinition,
+} from "../static-handler.js";
+import {
+  registerSearchSchema,
+  registerRouteRootScope,
+} from "../route-map-builder.js";
+import { RESPONSE_TYPE } from "./response-types.js";
+import type { PathOptions } from "./pattern-types.js";
+import type {
+  PathFn,
+  ResponsePathFn,
+  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";
+
+function applyUrlPrefix(prefix: string, pattern: string): string {
+  if (!prefix) return pattern;
+  if (pattern === "/") return prefix;
+  if (prefix.endsWith("/") && pattern.startsWith("/")) {
+    return prefix + pattern.slice(1);
+  }
+  return prefix + pattern;
+}
+
+function applyNamePrefix(prefix: string | undefined, name: string): string {
+  if (!prefix) return name;
+  return `${prefix}.${name}`;
+}
+
+function resolveResponseType(
+  options: PathOptions | undefined,
+): string | undefined {
+  return options?.[RESPONSE_TYPE];
+}
+
+export function createPathHelper<TEnv>(): PathFn<TEnv> {
+  return ((
+    pattern: string,
+    handler: ReactNode | Handler<any, any, TEnv>,
+    optionsOrUse?: PathOptions | (() => UseItems<RouteUseItem>),
+    maybeUse?: () => UseItems<RouteUseItem>,
+  ): RouteItem => {
+    const { store, ctx } = requireDslContext(
+      "path() must be called inside urls()",
+    );
+
+    invariant(
+      !ctx.parent || ctx.parent.type !== "parallel",
+      "path() cannot be used inside parallel()",
+    );
+
+    {
+      let ancestor = ctx.parent;
+      while (ancestor) {
+        invariant(
+          ancestor.type !== "route",
+          "path() cannot be nested inside another path()",
+        );
+        ancestor = ancestor.parent;
+      }
+    }
+
+    let options: PathOptions | undefined;
+    let use: (() => UseItems<RouteUseItem>) | undefined;
+
+    if (typeof optionsOrUse === "function") {
+      // path(pattern, handler, use)
+      use = optionsOrUse as () => UseItems<RouteUseItem>;
+    } else if (typeof optionsOrUse === "object") {
+      // path(pattern, handler, options) or path(pattern, handler, options, use)
+      options = optionsOrUse as PathOptions;
+      use = maybeUse;
+    }
+
+    const handlerUseFn = resolveHandlerUse(handler);
+    const mountSite = resolveResponseType(options) ? "response" : "path";
+    const mergedUse = mergeHandlerUse(handlerUseFn, use, mountSite);
+
+    const urlPrefix = getUrlPrefix();
+    const namePrefix = getNamePrefix();
+
+    const prefixedPattern = applyUrlPrefix(urlPrefix, pattern);
+
+    const localName =
+      options?.name || `$path_${pattern.replace(/[/:*?]/g, "_")}`;
+    if (options?.name) {
+      validateUserRouteName(options.name);
+    }
+    const routeName = applyNamePrefix(namePrefix, localName);
+
+    const namespace = `${ctx.namespace}.${store.getNextIndex("route")}.${routeName}`;
+
+    if (ctx.forRoute && routeName !== ctx.forRoute) {
+      store.getShortCode("route");
+      return { type: "route" } as RouteItem;
+    }
+
+    const wrappedHandler: Handler<any, any, TEnv> =
+      typeof handler === "function"
+        ? (handler as Handler<any, any, TEnv>)
+        : 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,
+      pattern: prefixedPattern,
+      ...(urlPrefix ? { mountPath: urlPrefix } : {}),
+      ...(isPassthroughHandler(handler)
+        ? {
+            isPrerender: true as const,
+            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,
+            ...(handler.$$id ? { staticHandlerId: handler.$$id } : {}),
+          }
+        : {}),
+      ...(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 }
+        : {}),
+    };
+
+    if (isStaticHandler(handler) && handler.$$id && ctx.namePrefix) {
+      (handler as any).$$routePrefix = ctx.namePrefix;
+    }
+
+    invariant(
+      ctx.manifest.get(routeName) === undefined,
+      `Duplicate route name: ${routeName} at ${namespace}`,
+    );
+
+    ctx.manifest.set(routeName, entry);
+
+    registerRouteRootScope(routeName, getRootScoped());
+
+    if (ctx.patterns) {
+      ctx.patterns.set(routeName, prefixedPattern);
+    }
+
+    if (ctx.patternsByPrefix) {
+      const urlPrefix = getUrlPrefix() || "";
+      if (!ctx.patternsByPrefix.has(urlPrefix)) {
+        ctx.patternsByPrefix.set(urlPrefix, new Map());
+      }
+      ctx.patternsByPrefix.get(urlPrefix)!.set(routeName, prefixedPattern);
+    }
+
+    if (options?.trailingSlash && ctx.trailingSlash) {
+      ctx.trailingSlash.set(routeName, options.trailingSlash);
+    }
+
+    if (options?.search) {
+      if (ctx.searchSchemas) {
+        ctx.searchSchemas.set(routeName, options.search);
+      }
+      registerSearchSchema(routeName, options.search);
+    }
+
+    if (mergedUse) {
+      const result = runAndValidateUseItems(
+        store,
+        namespace,
+        entry,
+        mergedUse,
+        "path",
+        "use",
+      );
+      return { name: namespace, type: "route", uses: result } as RouteItem;
+    }
+
+    return { name: namespace, type: "route" } as RouteItem;
+  }) as PathFn<TEnv>;
+}
+
+export function attachPathResponseTags<TEnv>(
+  pathFn: PathFn<TEnv>,
+): PathFn<TEnv> & {
+  json: JsonResponsePathFn<TEnv>;
+  text: TextResponsePathFn<TEnv>;
+  html: TextResponsePathFn<TEnv>;
+  xml: TextResponsePathFn<TEnv>;
+  md: TextResponsePathFn<TEnv>;
+  image: ResponsePathFn<TEnv>;
+  stream: ResponsePathFn<TEnv>;
+  any: ResponsePathFn<TEnv>;
+} {
+  function createTagged(responseType: string): ResponsePathFn<TEnv> {
+    return ((
+      pattern: string,
+      handler: any,
+      optionsOrUse?: any,
+      maybeUse?: any,
+    ) => {
+      let options: PathOptions;
+      let use: (() => any[]) | undefined;
+      if (typeof optionsOrUse === "function") {
+        options = { [RESPONSE_TYPE]: responseType };
+        use = optionsOrUse;
+      } else {
+        options = { ...optionsOrUse, [RESPONSE_TYPE]: responseType };
+        use = maybeUse;
+      }
+
+      return pathFn(pattern, handler, options, use);
+    }) as ResponsePathFn<TEnv>;
+  }
+
+  const extended = pathFn as any;
+  extended.json = createTagged("json");
+  extended.text = createTagged("text");
+  extended.html = createTagged("html");
+  extended.xml = createTagged("xml");
+  extended.md = createTagged("md");
+  extended.image = createTagged("image");
+  extended.stream = createTagged("stream");
+  extended.any = createTagged("any");
+  return extended;
+}

package/src/urls/pattern-types.ts

@@ -0,0 +1,189 @@
+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.
+ * Using a branded string instead of `never` prevents TypeScript from
+ * widening array type inference when mixing named and unnamed routes.
+ */
+export type UnnamedRoute = "$unnamed";
+
+/**
+ * Sentinel type for include() mounts that stay local to the mounted module.
+ * This keeps child route names out of the parent/global type map while still
+ * allowing the mounted module to use its own local route names internally.
+ *
+ * Branded with a symbol key so it cannot be accidentally produced by user code.
+ */
+declare const LOCAL_ONLY_BRAND: unique symbol;
+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[];
+  /**
+   * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
+   * inside the shell entry. The snapshot duplicates every cache-store value
+   * the capture pinned, so a page over a large cache() segment can push the
+   * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
+   * Over the cap the snapshot is skipped: the shell is still stored and
+   * served, but pinned reads fall back to the live store, so drifted cached
+   * content can hydration-mismatch and be repaired client-side (the
+   * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in MILLISECONDS (default 15000). Bounds the whole
+   * background capture: the wait for deferred shell material — top-level
+   * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
+   * are AWAITED and their settled values baked into the stored shell — AND
+   * the fizz prerender deadline. Declare it to tighten the budget below the
+   * default or when a route's shell material takes longer than 15s to
+   * settle. A budget that expires with pushes still pending REFUSES the
+   * capture (the route stays MISS with the once-per-key warning) — a shell
+   * with missing head material is never stored. Capture is background work
+   * (waitUntil), so a longer budget costs latency-to-HIT only, never a served
+   * response; the platform waitUntil lifetime (workerd: ~30s past response
+   * completion) is the physical ceiling — the default's derivation lives in
+   * docs/design/ppr-shell-resume.md (Cost model). Build-time captures
+   * (Prerender+ppr, producer B) honor the same budget with no platform
+   * ceiling. Non-finite or sub-1ms values fall back to the default.
+   */
+  captureTimeout?: number;
+}
+
+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) */
+  trailingSlash?: TrailingSlashMode;
+  /** Response type marker (set by path.json(), etc.) */
+  [RESPONSE_TYPE]?: string;
+}
+
+/**
+ * Result of urls() - contains the route definitions
+ */
+export interface UrlPatterns<
+  TEnv = any,
+  TRoutes extends Record<string, any> = Record<string, string>,
+  TResponses extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /** Internal: compiled handler function */
+  readonly handler: () => AllUseItems[];
+  /** Internal: trailing slash config per route name */
+  readonly trailingSlash: Record<string, TrailingSlashMode>;
+  /** Brand for type checking */
+  readonly [UrlPatternsBrand]: void;
+  /** Environment type brand (phantom) */
+  readonly _env?: TEnv;
+  /** Routes type brand (phantom) - carries route name -> pattern mapping */
+  readonly _routes?: TRoutes;
+  /** Responses type brand (phantom) - carries route name -> response data type mapping */
+  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()
+ */
+export interface IncludeOptions<TNamePrefix extends string = string> {
+  /**
+   * Name prefix for all routes in this pattern set.
+   *
+   * - `{ name: "blog" }` — children become `blog.index`, `blog.detail`, etc.
+   *   Visible in generated route types and resolvable globally via `reverse("blog.index")`.
+   * - `{ name: "" }` — children merge into the parent namespace with no prefix.
+   *   Equivalent to defining the routes inline at the include site.
+   * - Omitted — children live in a private local scope, hidden from the
+   *   generated route map and global reverse resolution. Only dot-local
+   *   reverse (e.g. `reverse(".child")`) works from inside the module.
+   */
+  name?: TNamePrefix;
+}

package/src/urls/response-types.ts

@@ -0,0 +1,109 @@
+import type { ContextVar } from "../context-var.js";
+import type { ReverseFunction } from "../reverse.js";
+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.
+ * Global names get autocomplete and param validation from the generated route map.
+ * Local `.name` calls are accepted but not validated (scope unknown at type level).
+ */
+type ResponseReverseFunction = [DefaultReverseRouteMap] extends [
+  Record<string, string>,
+]
+  ? (
+      name: string,
+      params?: Record<string, string>,
+      search?: Record<string, unknown>,
+    ) => string
+  : ReverseFunction<DefaultReverseRouteMap> & {
+      (
+        name: `.${string}`,
+        params?: Record<string, string>,
+        search?: Record<string, unknown>,
+      ): string;
+    };
+
+/**
+ * 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");
+
+/**
+ * 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,
+> = ResponseHandlerOf<Response, TParams, TEnv>;
+
+/**
+ * JSON-serializable value type for auto-wrap support.
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * Handler for JSON response routes.
+ * Can return a plain JSON-serializable value (auto-wrapped) or Response (pass-through).
+ */
+export type JsonResponseHandler<
+  TParams = Record<string, string>,
+  TEnv = any,
+> = ResponseHandlerOf<JsonValue | Response, TParams, TEnv>;
+
+/**
+ * Handler for text-based response routes (text, html, xml).
+ * Can return a string (auto-wrapped) or Response (pass-through).
+ */
+export type TextResponseHandler<
+  TParams = Record<string, string>,
+  TEnv = any,
+> = ResponseHandlerOf<string | Response, TParams, TEnv>;
+
+/**
+ * Lighter handler context for response routes.
+ * No ctx.use() (no loaders). Supports setting response headers via ctx.header().
+ * Use the standalone cookies() function for cookie mutations.
+ */
+export interface ResponseHandlerContext<
+  TParams = Record<string, string>,
+  TEnv = any,
+> extends RequestScope<TEnv> {
+  params: TParams;
+  /** @internal Phantom property for params type invariance. Prevents mounting handlers on wrong routes. */
+  readonly _paramCheck?: (params: TParams) => TParams;
+  reverse: ResponseReverseFunction;
+  /** Read a variable set by middleware via ctx.set(key, value) or ctx.set(ContextVar, value). */
+  get: {
+    <T>(contextVar: ContextVar<T>): T | undefined;
+  } & (<K extends keyof DefaultVars>(key: K) => DefaultVars[K]);
+  /** Set a response header. Merged into the auto-wrapped or pass-through Response. */
+  header: (name: string, value: string) => void;
+}