@rangojs/router 0.0.0-experimental.ce770c9a → 0.0.0-experimental.d5d3070a

package/src/router/metrics.ts

@@ -1,9 +1,3 @@
-/**
- * Router Metrics Utilities
- *
- * Performance metrics collection and reporting for RSC Router.
- */
-
 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-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,
@@ -14,26 +7,22 @@ import type {
 import type { ScopedReverseFunction } from "../reverse.js";
 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): void;
-  <K extends keyof DefaultVars>(key: K, value: DefaultVars[K]): void;
+  <T>(contextVar: ContextVar<T>, value: T, options?: { cache?: boolean }): void;
+  <K extends keyof DefaultVars>(
+    key: K,
+    value: DefaultVars[K],
+    options?: { cache?: boolean },
+  ): void;
 };
 
-/**
- * Cookie options for setting cookies
- */
 export interface CookieOptions {
   domain?: string;
   path?: string;
@@ -44,178 +33,60 @@ 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> for global middleware)
- */
 export interface MiddlewareContext<
   TEnv = any,
-  TParams = Record<string, string>,
-> {
-  /** Original request */
-  request: Request;
-
-  /** Parsed URL (with internal `_rsc*` params stripped) */
-  url: URL;
-
-  /**
-   * The original request URL with all parameters intact, including
-   * internal `_rsc*` transport params.
-   */
-  originalUrl: URL;
-
-  /** URL pathname */
-  pathname: string;
-
-  /** URL search params */
-  searchParams: URLSearchParams;
-
-  /** Platform bindings (Cloudflare, etc.) */
-  env: TEnv;
-
-  /** URL params extracted from route/middleware pattern */
+  TParams = Record<string, string | undefined>,
+> extends RequestScope<TEnv> {
   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;
 
-  /**
-   * Middleware-injected variables.
-   * Same shared dictionary as `ctx.get()`/`ctx.set()`.
-   */
-  var: DefaultVars;
-
-  /**
-   * 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 (RSCRouter.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>> = (
+export type MiddlewareFn<
+  TEnv = any,
+  TParams = Record<string, string | undefined>,
+> = (
   ctx: MiddlewareContext<TEnv, TParams>,
   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>;
   params: Record<string, string>;