@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.120

package/src/urls/path-helper.ts

@@ -0,0 +1,329 @@
+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";
+
+/**
+ * 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;
+  if (prefix.endsWith("/") && pattern.startsWith("/")) {
+    return prefix + pattern.slice(1);
+  }
+  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,
+    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()",
+    );
+
+    // 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) {
+        invariant(
+          ancestor.type !== "route",
+          "path() cannot be nested inside another path()",
+        );
+        ancestor = ancestor.parent;
+      }
+    }
+
+    // Determine options and use based on argument types
+    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;
+    }
+
+    // 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();
+
+    // 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)
+    // 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>)
+        : 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,
+      ...(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) }
+        : {}),
+    };
+
+    // 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)) {
+        ctx.patternsByPrefix.set(urlPrefix, new Map());
+      }
+      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);
+      }
+      registerSearchSchema(routeName, options.search);
+    }
+
+    // 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;
+    }
+
+    return { name: namespace, type: "route" } as RouteItem;
+  }) 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> & {
+  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,124 @@
+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
+ */
+export interface PathOptions<
+  TName extends string = string,
+  TSearch extends SearchSchema = {},
+> {
+  /** Route name for href() lookups */
+  name?: TName;
+  /** 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;
+}