@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/router/metrics.ts

@@ -1,9 +1,3 @@
-/**
- * Router Metrics Utilities
- *
- * Performance metrics collection and reporting for Rango.
- */
-
 import type { MetricsStore, PerformanceMetric } from "../server/context";
 
 const BASE_INDENT = 2;
@@ -16,7 +10,6 @@ function formatMs(value: number): string {
 
 function sortMetrics(metrics: PerformanceMetric[]): PerformanceMetric[] {
   return [...metrics].sort((a, b) => {
-    // handler:total always goes last (it wraps everything)
     if (a.label === "handler:total") return 1;
     if (b.label === "handler:total") return -1;
     return a.startTime - b.startTime;
@@ -68,11 +61,6 @@ function createTimelineAxis(total: number): string {
   )}${totalLabel}`;
 }
 
-/**
- * Create a metrics store for the request if debugPerformance is enabled.
- * An optional `requestStart` timestamp can anchor the store to an earlier
- * point (e.g. handler start) so that handler:total has startTime=0.
- */
 export function createMetricsStore(
   debugPerformance: boolean,
   requestStart?: number,
@@ -85,9 +73,6 @@ export function createMetricsStore(
   };
 }
 
-/**
- * Append a metric to the request store using an absolute start timestamp.
- */
 export function appendMetric(
   metricsStore: MetricsStore | undefined,
   label: string,
@@ -104,9 +89,6 @@ export function appendMetric(
   });
 }
 
-/**
- * Log the current request metrics and return the corresponding Server-Timing value.
- */
 export function buildMetricsTiming(
   method: string,
   pathname: string,
@@ -117,7 +99,6 @@ export function buildMetricsTiming(
   return generateServerTiming(metricsStore) || undefined;
 }
 
-/** Display row produced by merging :pre/:post metric pairs. */
 interface DisplayRow {
   label: string;
   startTime: number;
@@ -126,12 +107,7 @@ interface DisplayRow {
   spans: Span[];
 }
 
-/**
- * Build display rows from sorted metrics, merging :pre/:post pairs into
- * a single row with disjoint timeline segments.
- */
 function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
-  // Index :pre and :post metrics by their base label
   const preMap = new Map<string, PerformanceMetric>();
   const postMap = new Map<string, PerformanceMetric>();
   const consumed = new Set<PerformanceMetric>();
@@ -211,11 +187,6 @@ function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
   return rows;
 }
 
-/**
- * Log metrics to console in a formatted way.
- * Uses a shared-axis timeline so overlapping work stays visible.
- * Merges :pre/:post pairs onto one row with disjoint timeline segments.
- */
 export function logMetrics(
   method: string,
   pathname: string,
@@ -267,11 +238,6 @@ export function logMetrics(
   }
 }
 
-/**
- * Generate Server-Timing header value from metrics
- * Format: metric-name;dur=X.XX
- * Depth is encoded as a "d{N}-" prefix for nested metrics.
- */
 export function generateServerTiming(metricsStore: MetricsStore): string {
   return metricsStore.metrics
     .map((m) => {

package/src/router/middleware-cookies.ts

@@ -1,14 +1,5 @@
-/**
- * Cookie Utilities
- *
- * Parsing and serialization for HTTP cookies used by middleware context.
- */
-
 import type { CookieOptions } from "./middleware-types.js";
 
-/**
- * Parse cookies from Cookie header
- */
 export function parseCookies(
   cookieHeader: string | null,
 ): Record<string, string> {
@@ -24,7 +15,6 @@ export function parseCookies(
       try {
         cookies[name] = decodeURIComponent(raw);
       } catch {
-        // Malformed percent-encoded value (e.g. %zz) - fall back to raw value
         cookies[name] = raw;
       }
     }
@@ -33,9 +23,6 @@ export function parseCookies(
   return cookies;
 }
 
-/**
- * Serialize a cookie for Set-Cookie header
- */
 export function serializeCookie(
   name: string,
   value: string,

package/src/router/middleware-types.ts

@@ -1,10 +1,3 @@
-/**
- * Middleware Types
- *
- * Type definitions and interfaces for the middleware system.
- * Separated from execution logic for cleaner imports.
- */
-
 import type { ContextVar } from "../context-var.js";
 import type {
   DefaultReverseRouteMap,
@@ -16,17 +9,11 @@ import type { Theme } from "../theme/types.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RequestScope } from "../types/request-scope.js";
 
-/**
- * Get variable function type
- */
 type GetVariableFn = {
   <T>(contextVar: ContextVar<T>): T | undefined;
   <K extends keyof DefaultVars>(key: K): DefaultVars[K];
 };
 
-/**
- * Set variable function type
- */
 type SetVariableFn = {
   <T>(contextVar: ContextVar<T>, value: T, options?: { cache?: boolean }): void;
   <K extends keyof DefaultVars>(
@@ -36,9 +23,6 @@ type SetVariableFn = {
   ): void;
 };
 
-/**
- * Cookie options for setting cookies
- */
 export interface CookieOptions {
   domain?: string;
   path?: string;
@@ -49,109 +33,36 @@ export interface CookieOptions {
   sameSite?: "strict" | "lax" | "none";
 }
 
-/**
- * Context passed to middleware
- *
- * @template TEnv - Environment type (bindings, variables) - defaults to any for internal flexibility
- * @template TParams - URL params type (typed for route middleware,
- *   `Record<string, string | undefined>` for global middleware — absent
- *   optional segments are omitted from the params record at runtime, so
- *   the index signature must include `undefined`)
- */
 export interface MiddlewareContext<
   TEnv = any,
   TParams = Record<string, string | undefined>,
 > extends RequestScope<TEnv> {
-  /** URL params extracted from route/middleware pattern */
   params: TParams;
 
-  /**
-   * Response headers.
-   * Before `next()`, returns headers from the shared response stub.
-   * After `next()`, returns headers from the downstream response.
-   */
   readonly headers: Headers;
 
-  /** Get a context variable (shared with route handlers) */
   get: GetVariableFn;
 
-  /** Set a context variable (shared with route handlers) */
   set: SetVariableFn;
 
-  /**
-   * Set a response header - can be called before or after `next()`.
-   *
-   * When called before `next()`, headers are queued and merged into the final response.
-   * When called after `next()`, headers are set directly on the response.
-   */
   header(name: string, value: string): void;
 
-  /**
-   * The matched route name, if available and the route has an explicit name.
-   * Undefined for global middleware (runs before route matching) or unnamed routes.
-   */
   routeName?: DefaultRouteName;
 
-  /**
-   * Enable performance metrics for this request.
-   * When called, granular timing breakdown is logged to console and
-   * included in the Server-Timing response header, regardless of the
-   * router-level `debugPerformance` option.
-   *
-   * Call **before** `await next()` so the metrics store exists when
-   * downstream phases (route matching, rendering, SSR) record their
-   * spans. Calling after `next()` returns still emits `handler:total`
-   * but misses all upstream metrics.
-   */
   debugPerformance(): void;
 
-  /**
-   * Current theme (from cookie or default).
-   * Only available when theme is enabled in router config.
-   */
   theme?: Theme;
 
-  /**
-   * Set the theme (only available when theme is enabled in router config).
-   * Sets a cookie with the new theme value.
-   */
   setTheme?: (theme: Theme) => void;
 
-  /**
-   * Attach location state entries to this response.
-   * State is delivered to the client via history.pushState and accessible
-   * through the useLocationState() hook.
-   */
   setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
 
-  /**
-   * Generate URLs from route names.
-   * - `name` — global route, from the named-routes definition
-   */
   reverse: ScopedReverseFunction<
     Record<string, string>,
     DefaultReverseRouteMap
   >;
 }
 
-/**
- * Middleware function signature
- *
- * @template TEnv - Environment type - defaults to any for internal flexibility
- * @template TParams - URL params type (typed for route middleware)
- *
- * When using middleware with global augmentation (Rango.Env), explicitly
- * annotate your middleware functions, or the types will be inferred from context:
- *
- * @example
- * ```typescript
- * // With explicit annotation (recommended for reusable middleware)
- * const authMiddleware: MiddlewareFn<AppEnv> = async (ctx, next) => {...}
- *
- * // Types inferred from router.use() call
- * router.use((ctx, next) => {...}) // ctx is typed from router's TEnv
- * ```
- */
 export type MiddlewareFn<
   TEnv = any,
   TParams = Record<string, string | undefined>,
@@ -160,50 +71,24 @@ export type MiddlewareFn<
   next: () => Promise<Response>,
 ) => Response | void | Promise<Response | void>;
 
-/**
- * Stored middleware entry with pattern matching info
- * @internal - uses any for internal flexibility
- */
 export interface MiddlewareEntry<TEnv = any> {
-  /** Original pattern string */
   pattern: string | null;
-
-  /** Compiled regex for matching */
   regex: RegExp | null;
-
-  /** Param names extracted from pattern */
   paramNames: string[];
-
-  /** The middleware function */
   handler: MiddlewareFn<TEnv>;
-
-  /** Mount prefix this middleware is scoped to (null = global) */
   mountPrefix: string | null;
 }
 
-/**
- * Mutable response holder - tracks the current response through the middleware chain.
- */
 export interface ResponseHolder {
   response: Response | null;
 }
 
-/**
- * Entry type for middleware collection
- * Matches the shape of EntryData used in router.ts
- */
 export interface MiddlewareCollectableEntry {
   middleware?: MiddlewareFn<any, any>[];
   layout?: MiddlewareCollectableEntry[];
 }
 
-/**
- * Collected route middleware with params
- */
 export interface CollectedMiddleware {
   handler: MiddlewareFn<any, any>;
-  // Internal shape only. The user-facing `MiddlewareContext.params` is
-  // typed `Record<string, string | undefined>` to reflect that absent
-  // optional segments are omitted from the params record at runtime.
   params: Record<string, string>;
 }

package/src/router/middleware.ts

@@ -1,13 +1,4 @@
 /// <reference types="vite/types/importMeta.d.ts" />
-/**
- * Middleware Execution
- *
- * True middleware that wraps the entire RSC handler.
- * - `await next()` returns actual Response
- * - Can modify response headers
- * - Can catch errors from RSC rendering
- * - Forgiving API: if middleware doesn't return, original response is used
- */
 
 import { contextGet, contextSet } from "../context-var.js";
 import { safeDecodeURIComponent } from "./url-params.js";
@@ -26,23 +17,20 @@ import { appendMetric, createMetricsStore } from "./metrics.js";
 import { stripInternalParams } from "./handler-context.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
-// Re-export types and cookie utilities for backward compatibility
+// Re-export types and cookie utilities consumed through this module's path.
 export type {
   CookieOptions,
-  CollectedMiddleware,
   MiddlewareCollectableEntry,
   MiddlewareContext,
   MiddlewareEntry,
   MiddlewareFn,
-  ResponseHolder,
 } from "./middleware-types.js";
 export { parseCookies, serializeCookie } from "./middleware-cookies.js";
 
 const MIDDLEWARE_METRIC_DEPTH = 1;
-/** Ignore post-next() durations below this threshold (measurement noise). */
 const POST_METRIC_MIN_DURATION_MS = 0.01;
 
-function getMiddlewareMetricBase<TEnv>(
+function getMiddlewareMetricLabel<TEnv>(
   entry: MiddlewareEntry<TEnv>,
   ordinal: number,
 ): string {
@@ -50,23 +38,12 @@ function getMiddlewareMetricBase<TEnv>(
   const scope = entry.pattern ?? "*";
 
   if (handlerName) {
-    return `${handlerName}@${scope}`;
+    return `middleware:${handlerName}@${scope}`;
   }
 
-  return `${scope}#${ordinal + 1}`;
+  return `middleware:${scope}#${ordinal + 1}`;
 }
 
-function getMiddlewareMetricLabel<TEnv>(
-  entry: MiddlewareEntry<TEnv>,
-  ordinal: number,
-): string {
-  return `middleware:${getMiddlewareMetricBase(entry, ordinal)}`;
-}
-
-/**
- * Parse a route pattern into regex and param names
- * Supports: *, /path, /path/*, /path/:param, /path/:param/*
- */
 export function parsePattern(pattern: string): {
   regex: RegExp;
   paramNames: string[];
@@ -355,7 +332,7 @@ function mergeReqCtxStub(
  * - `ctx.headers` available before and after `await next()`
  * - `ctx.header()` shorthand for setting a single header
  * - Forgiving: if middleware doesn't return, uses the downstream response
- * - Short-circuit: return Response to stop chain
+ * - Short-circuit: return OR throw a Response to stop chain
  * - Error catching: try/catch around `next()` works
  */
 export async function executeMiddleware<TEnv>(
@@ -490,7 +467,7 @@ export async function executeMiddleware<TEnv>(
 
     // Explicit return takes precedence (middleware short-circuit).
     // Merge stub headers (from ctx.header before this point) and
-    // RequestContext stub headers (from ctx.setCookie) into the
+    // RequestContext stub headers (from cookies().set()) into the
     // returned Response so they are not lost.
     if (result instanceof Response) {
       if (isWebSocketUpgradeResponse(result)) {
@@ -564,7 +541,7 @@ export async function executeMiddleware<TEnv>(
  *
  * Intercepts use a shared stubResponse from the request context. This function:
  * - Runs middleware in sequence with a simple next() chain
- * - Returns Response if any middleware short-circuits (returns Response or redirects BEFORE next())
+ * - Returns Response if any middleware short-circuits (returns OR throws a Response, or redirects, BEFORE next())
  * - Returns null if all middleware calls next() - headers set after next() remain on stubResponse
  *
  * @param middlewares - Array of middleware functions

package/src/router/navigation-snapshot.ts

@@ -1,58 +1,26 @@
-/**
- * Navigation Snapshot
- *
- * Pure data type representing the navigation-specific state for partial requests.
- * Consolidates the header parsing, previous-route matching, intercept-context
- * detection, and segment ID filtering that previously lived inline in
- * createMatchContextForPartial (match-api.ts).
- *
- * resolveNavigation() is the factory: given a request + URL + current route key,
- * it returns a NavigationSnapshot (or null if no previous URL).
- */
-
 import type { RouteMatchResult } from "./pattern-matching.js";
 
-/**
- * Snapshot of navigation state for a partial (navigation/action) request.
- *
- * Contains the "where are we coming from?" data: previous route, intercept
- * source, client segment state, and derived flags.
- */
 export interface NavigationSnapshot {
-  /** Previous page URL (from X-RSC-Router-Client-Path or Referer) */
   prevUrl: URL;
-  /** Params from the previous route match */
   prevParams: Record<string, string>;
-  /** Previous route match result (null if prev URL doesn't match any route) */
   prevMatch: RouteMatchResult | null;
 
-  /** URL used as intercept context source */
   interceptContextUrl: URL;
-  /** Route match for the intercept context URL */
   interceptContextMatch: RouteMatchResult | null;
 
-  /** Raw segment IDs the client currently has */
   clientSegmentIds: string[];
-  /** Set version for O(1) lookup */
   clientSegmentSet: Set<string>;
-  /** Segment IDs filtered to remove parallel (.@) and loader (D\d+.) entries */
   filteredSegmentIds: string[];
 
-  /** Whether client considers its cache stale */
   stale: boolean;
 
-  /** Whether the intercept context route is the same as the current route */
   isSameRouteNavigation: boolean;
 
-  /** Effective "from" URL (intercept source URL when present, else prevUrl) */
   effectiveFromUrl: URL;
-  /** Effective "from" match (intercept source match when present, else prevMatch) */
   effectiveFromMatch: RouteMatchResult | null;
 
-  /** Whether an intercept source header was present */
   hasInterceptSource: boolean;
 
-  /** Whether an HMR request header was present */
   isHmr: boolean;
 }
 
@@ -60,23 +28,12 @@ export interface ResolveNavigationDeps {
   findMatch: (pathname: string) => RouteMatchResult | null;
 }
 
-/**
- * Resolve navigation state from a partial request.
- *
- * Returns null if no previous URL is available (required for partial navigation).
- *
- * @param request - The incoming HTTP request
- * @param url - Parsed URL of the request
- * @param currentRouteKey - Route key of the current (target) route match
- * @param deps - Dependencies (findMatch)
- */
 export function resolveNavigation(
   request: Request,
   url: URL,
   currentRouteKey: string,
   deps: ResolveNavigationDeps,
 ): NavigationSnapshot | null {
-  // Parse client state from RSC request params/headers
   const clientSegmentIds =
     url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
   const stale = url.searchParams.get("_rsc_stale") === "true";
@@ -92,7 +49,6 @@ export function resolveNavigation(
     return null;
   }
 
-  // Parse previous URL
   let prevUrl: URL;
   try {
     prevUrl = new URL(previousUrl, url.origin);
@@ -100,7 +56,6 @@ export function resolveNavigation(
     return null;
   }
 
-  // Parse intercept context URL
   let interceptContextUrl: URL;
   try {
     interceptContextUrl = interceptSourceUrl
@@ -110,14 +65,12 @@ export function resolveNavigation(
     interceptContextUrl = prevUrl;
   }
 
-  // Match previous and intercept context routes
   const prevMatch = deps.findMatch(prevUrl.pathname);
   const prevParams = prevMatch?.params || {};
   const interceptContextMatch = interceptSourceUrl
     ? deps.findMatch(interceptContextUrl.pathname)
     : prevMatch;
 
-  // Derived state
   const isSameRouteNavigation = !!(
     interceptContextMatch && interceptContextMatch.routeKey === currentRouteKey
   );
@@ -128,7 +81,6 @@ export function resolveNavigation(
     ? interceptContextMatch
     : prevMatch;
 
-  // Filter segment IDs: remove parallel (.@) and loader (D\d+.) entries
   const filteredSegmentIds = clientSegmentIds.filter((id) => {
     if (id.includes(".@")) return false;
     if (/D\d+\./.test(id)) return false;
@@ -155,9 +107,6 @@ export function resolveNavigation(
   };
 }
 
-/**
- * Test helper: create a NavigationSnapshot with sensible defaults and overrides.
- */
 export function createNavigationSnapshot(
   overrides?: Partial<NavigationSnapshot>,
 ): NavigationSnapshot {

package/src/router/params-util.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared route-param comparison helpers.
+ */
+
+/**
+ * Shallow equality for two route-param records. Same-reference is a fast path;
+ * otherwise compares key count then each value.
+ */
+export function paramsEqual(
+  a: Record<string, string>,
+  b: Record<string, string>,
+): boolean {
+  if (a === b) return true;
+
+  const keysA = Object.keys(a);
+  if (keysA.length !== Object.keys(b).length) return false;
+
+  for (const key of keysA) {
+    if (a[key] !== b[key]) return false;
+  }
+
+  return true;
+}