@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20

package/src/router/match-middleware/intercept-resolution.ts

@@ -105,6 +105,7 @@ import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
+import { debugLog } from "../logging.js";
 
 /**
  * Creates intercept resolution middleware
@@ -117,11 +118,14 @@ import type { GeneratorMiddleware } from "./cache-lookup.js";
  */
 export function withInterceptResolution<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): GeneratorMiddleware<ResolvedSegment> {
   return async function* (
-    source: AsyncGenerator<ResolvedSegment>
+    source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
+    const pipelineStart = performance.now();
+    const ms = ctx.metricsStore;
+
     // First, yield all segments from the source (main segment resolution or cache)
     const segments: ResolvedSegment[] = [];
     for await (const segment of source) {
@@ -131,6 +135,13 @@ export function withInterceptResolution<TEnv>(
 
     // Skip intercept resolution for full match (document requests don't have intercepts)
     if (ctx.isFullMatch) {
+      if (ms) {
+        ms.metrics.push({
+          label: "pipeline:intercept",
+          duration: performance.now() - pipelineStart,
+          startTime: pipelineStart - ms.requestStart,
+        });
+      }
       return;
     }
 
@@ -149,6 +160,13 @@ export function withInterceptResolution<TEnv>(
       if (ctx.interceptResult && state.cacheHit && ctx.isIntercept) {
         await handleCacheHitIntercept(ctx, state, segments);
       }
+      if (ms) {
+        ms.metrics.push({
+          label: "pipeline:intercept",
+          duration: performance.now() - pipelineStart,
+          startTime: pipelineStart - ms.requestStart,
+        });
+      }
       return;
     }
 
@@ -156,9 +174,10 @@ export function withInterceptResolution<TEnv>(
     const { resolveInterceptEntry } = getRouterContext<TEnv>();
 
     const slotName = ctx.interceptResult!.intercept.slotName;
-    console.log(
-      `[Router.matchPartial] Found intercept for "${ctx.localRouteName}" -> slot "${slotName}"`
-    );
+    debugLog("matchPartial.intercept", "intercept resolved", {
+      routeName: ctx.localRouteName,
+      slotName,
+    });
 
     // Resolve intercept entry (middleware, loaders, handler)
     const Store = ctx.Store;
@@ -178,8 +197,8 @@ export function withInterceptResolution<TEnv>(
           routeKey: ctx.routeKey,
           actionContext: ctx.actionContext,
           stale: ctx.stale,
-        }
-      )
+        },
+      ),
     );
 
     // Update state
@@ -193,6 +212,14 @@ export function withInterceptResolution<TEnv>(
     for (const segment of interceptSegments) {
       yield segment;
     }
+
+    if (ms) {
+      ms.metrics.push({
+        label: "pipeline:intercept",
+        duration: performance.now() - pipelineStart,
+        startTime: pipelineStart - ms.requestStart,
+      });
+    }
   };
 }
 
@@ -204,7 +231,7 @@ export function withInterceptResolution<TEnv>(
 async function handleCacheHitIntercept<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
-  segments: ResolvedSegment[]
+  segments: ResolvedSegment[],
 ): Promise<void> {
   if (!ctx.interceptResult) return;
 
@@ -214,7 +241,7 @@ async function handleCacheHitIntercept<TEnv>(
 
   // Find intercept segments from cached segments (namespace starts with "intercept:")
   const interceptSegments = segments.filter((s) =>
-    s.namespace?.startsWith("intercept:")
+    s.namespace?.startsWith("intercept:"),
   );
   state.interceptSegments = interceptSegments;
 
@@ -238,25 +265,36 @@ async function handleCacheHitIntercept<TEnv>(
           routeKey: ctx.routeKey,
           actionContext: ctx.actionContext,
           stale: ctx.stale,
-        }
-      )
+        },
+      ),
     );
 
     // Update intercept segment's loaderDataPromise with fresh data
     if (freshLoaderResult) {
       const interceptMainSegment = interceptSegments.find(
-        (s) => s.type === "parallel" && s.slot
+        (s) => s.type === "parallel" && s.slot,
       );
       if (interceptMainSegment) {
-        interceptMainSegment.loaderDataPromise = freshLoaderResult.loaderDataPromise;
+        interceptMainSegment.loaderDataPromise =
+          freshLoaderResult.loaderDataPromise;
         interceptMainSegment.loaderIds = freshLoaderResult.loaderIds;
-        console.log(
-          `[Router.matchPartial] Cache HIT + fresh loaders for intercept "${ctx.localRouteName}" -> slot "${slotName}"`
+        debugLog(
+          "matchPartial.intercept",
+          "cache hit with fresh intercept loaders",
+          {
+            routeName: ctx.localRouteName,
+            slotName,
+          },
         );
       }
     } else {
-      console.log(
-        `[Router.matchPartial] Cache HIT for intercept "${ctx.localRouteName}" -> slot "${slotName}" (no loader revalidation)`
+      debugLog(
+        "matchPartial.intercept",
+        "cache hit without intercept loader revalidation",
+        {
+          routeName: ctx.localRouteName,
+          slotName,
+        },
       );
     }
   }

package/src/router/match-middleware/segment-resolution.ts

@@ -99,11 +99,14 @@ import type { GeneratorMiddleware } from "./cache-lookup.js";
  */
 export function withSegmentResolution<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): GeneratorMiddleware<ResolvedSegment> {
   return async function* (
-    source: AsyncGenerator<ResolvedSegment>
+    source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
+    const pipelineStart = performance.now();
+    const ms = ctx.metricsStore;
+
     // IMPORTANT: Always iterate source first to give cache-lookup a chance
     // to run and set state.cacheHit. Without this, cache-lookup never executes!
     for await (const segment of source) {
@@ -112,6 +115,13 @@ export function withSegmentResolution<TEnv>(
 
     // If cache hit, segments were already yielded by cache lookup
     if (state.cacheHit) {
+      if (ms) {
+        ms.metrics.push({
+          label: "pipeline:segment-resolve",
+          duration: performance.now() - pipelineStart,
+          startTime: pipelineStart - ms.requestStart,
+        });
+      }
       return;
     }
 
@@ -128,8 +138,8 @@ export function withSegmentResolution<TEnv>(
           ctx.routeKey,
           ctx.matched.params,
           ctx.handlerContext,
-          ctx.loaderPromises
-        )
+          ctx.loaderPromises,
+        ),
       );
 
       // Update state with resolved segments
@@ -157,8 +167,8 @@ export function withSegmentResolution<TEnv>(
           ctx.actionContext,
           ctx.interceptResult,
           ctx.localRouteName,
-          ctx.pathname
-        )
+          ctx.pathname,
+        ),
       );
 
       // Update state with resolved segments
@@ -170,5 +180,13 @@ export function withSegmentResolution<TEnv>(
         yield segment;
       }
     }
+
+    if (ms) {
+      ms.metrics.push({
+        label: "pipeline:segment-resolve",
+        duration: performance.now() - pipelineStart,
+        startTime: pipelineStart - ms.requestStart,
+      });
+    }
   };
 }

package/src/router/match-pipelines.ts

@@ -86,19 +86,14 @@
  *     -> output: cached segments + fresh loader data
  *
  *
- * TWO PIPELINE VARIANTS
- * =====================
- *
- * 1. createMatchPipeline (Full Match)
- *    - Used for document requests (initial page load)
- *    - No revalidation logic (no previous state to compare)
- *    - Simpler segment resolution
- *
- * 2. createMatchPartialPipeline (Partial Match)
- *    - Used for client-side navigation
- *    - Includes revalidation for SWR
- *    - Compares with previous params/URL
- *    - Supports intercepts (soft navigation modals)
+ * PIPELINE VARIANT
+ * ================
+ *
+ * createMatchPartialPipeline handles both full (document) and partial
+ * (navigation) requests. The middleware steps adapt based on ctx.isFullMatch:
+ * - cache-lookup/store work for both
+ * - background-revalidation is a no-op for full matches (no stale state)
+ * - intercept-resolution is a no-op for full matches (no previous navigation)
  */
 import type { ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
@@ -163,7 +158,7 @@ export async function* empty<T>(): AsyncGenerator<T> {
  */
 export function createMatchPartialPipeline<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): AsyncGenerator<ResolvedSegment> {
   // Build the middleware chain
   const pipeline = compose<ResolvedSegment>(
@@ -176,39 +171,9 @@ export function createMatchPartialPipeline<TEnv>(
     // Resolves segments on cache miss
     withSegmentResolution(ctx, state),
     // Innermost - checks cache first
-    withCacheLookup(ctx, state)
+    withCacheLookup(ctx, state),
   );
 
   // Start with empty source - cache lookup or segment resolution will produce segments
   return pipeline(empty());
 }
-
-/**
- * Create the full match pipeline (simpler, no revalidation)
- *
- * Used for document requests (initial page load) where we don't need
- * revalidation logic since there's no previous state to compare against.
- */
-export function createMatchPipeline<TEnv>(
-  ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
-): AsyncGenerator<ResolvedSegment> {
-  // For full match, we only need:
-  // 1. Cache lookup
-  // 2. Segment resolution (without revalidation)
-  // 3. Intercept resolution
-  // 4. Cache store
-
-  // Note: Full match uses different resolution logic (resolveAllSegments instead of
-  // resolveAllSegmentsWithRevalidation). This will be handled by the segment resolution
-  // middleware checking ctx.isFullMatch or similar flag.
-
-  const pipeline = compose<ResolvedSegment>(
-    withCacheStore(ctx, state),
-    withInterceptResolution(ctx, state),
-    withSegmentResolution(ctx, state),
-    withCacheLookup(ctx, state)
-  );
-
-  return pipeline(empty());
-}

package/src/router/match-result.ts

@@ -109,12 +109,13 @@
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
 import { generateServerTiming, logMetrics } from "./metrics.js";
+import { debugLog } from "./logging.js";
 
 /**
  * Collect all segments from an async generator
  */
 export async function collectSegments(
-  generator: AsyncGenerator<ResolvedSegment>
+  generator: AsyncGenerator<ResolvedSegment>,
 ): Promise<ResolvedSegment[]> {
   const segments: ResolvedSegment[] = [];
   for await (const segment of generator) {
@@ -129,17 +130,30 @@ export async function collectSegments(
 export function buildMatchResult<TEnv>(
   allSegments: ResolvedSegment[],
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): MatchResult {
-  const logPrefix = ctx.isFullMatch ? "[Router.match]" : "[Router.matchPartial]";
+  const logPrefix = ctx.isFullMatch
+    ? "[Router.match]"
+    : "[Router.matchPartial]";
 
   let allIds: string[];
   let segmentsToRender: ResolvedSegment[];
 
   if (ctx.isFullMatch) {
     // Full match (document request) - all segments are rendered
-    allIds = allSegments.map((s) => s.id);
-    segmentsToRender = allSegments;
+    // Deduplicate by segment ID (defense-in-depth). The primary dedup is in
+    // resolveAllSegments, but this guards against any path that bypasses it.
+    // include() scopes can produce entries that resolve the same shared layout,
+    // and duplicate IDs change the client's React tree depth causing remounts.
+    const seen = new Set<string>();
+    segmentsToRender = [];
+    for (const s of allSegments) {
+      if (!seen.has(s.id)) {
+        seen.add(s.id);
+        segmentsToRender.push(s);
+      }
+    }
+    allIds = segmentsToRender.map((s) => s.id);
   } else {
     // Partial match (navigation) - filter and handle intercepts
     // When intercepting, tell browser to keep its current segments + add modal
@@ -151,25 +165,26 @@ export function buildMatchResult<TEnv>(
         : allSegments.map((s) => s.id) // Use actual segments, not matchedIds
       : [...state.matchedIds, ...state.interceptSegments.map((s) => s.id)];
 
+    // Deduplicate allIds (defense-in-depth for partial match path)
+    allIds = [...new Set(allIds)];
+
     // Filter out segments with null components (client already has them)
     // BUT always include loader segments - they carry data even with null component
     segmentsToRender = allSegments.filter(
-      (s) => s.component !== null || s.type === "loader"
+      (s) => s.component !== null || s.type === "loader",
     );
   }
 
-  if (process.env.NODE_ENV === "development") {
-    console.log(
-      `${logPrefix} All segments:`,
-      allSegments
-        .map((s) => `${s.id}(${s.type}, component=${s.component !== null})`)
-        .join(", ")
-    );
-    console.log(
-      `${logPrefix} Segments to render:`,
-      segmentsToRender.map((s) => s.id).join(", ")
-    );
-  }
+  debugLog(logPrefix, "all segments", {
+    segments: allSegments.map((s) => ({
+      id: s.id,
+      type: s.type,
+      hasComponent: s.component !== null,
+    })),
+  });
+  debugLog(logPrefix, "segments to render", {
+    segmentIds: segmentsToRender.map((s) => s.id),
+  });
 
   // Output metrics if enabled
   let serverTiming: string | undefined;
@@ -184,7 +199,6 @@ export function buildMatchResult<TEnv>(
     diff: segmentsToRender.map((s) => s.id),
     params: ctx.matched.params,
     routeName: ctx.routeKey,
-    routeMap: ctx.routeMap,
     serverTiming,
     slots: Object.keys(state.slots).length > 0 ? state.slots : undefined,
     routeMiddleware:
@@ -201,7 +215,7 @@ export function buildMatchResult<TEnv>(
 export async function collectMatchResult<TEnv>(
   pipeline: AsyncGenerator<ResolvedSegment>,
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): Promise<MatchResult> {
   const allSegments = await collectSegments(pipeline);
 

package/src/router/metrics.ts

@@ -10,7 +10,7 @@ import type { MetricsStore } from "../server/context";
  * Create a metrics store for the request if debugPerformance is enabled
  */
 export function createMetricsStore(
-  debugPerformance: boolean
+  debugPerformance: boolean,
 ): MetricsStore | undefined {
   if (!debugPerformance) return undefined;
   return {
@@ -26,14 +26,14 @@ export function createMetricsStore(
 export function logMetrics(
   method: string,
   pathname: string,
-  metricsStore: MetricsStore
+  metricsStore: MetricsStore,
 ): void {
   const total = performance.now() - metricsStore.requestStart;
 
   // Find max label length for alignment
   const maxLabelLen = Math.max(
     ...metricsStore.metrics.map((m) => m.label.length),
-    20
+    20,
   );
 
   console.log(`[RSC Perf] ${method} ${pathname} (${total.toFixed(1)}ms)`);

package/src/router/middleware-cookies.ts

@@ -0,0 +1,55 @@
+/**
+ * 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> {
+  if (!cookieHeader) return {};
+
+  const cookies: Record<string, string> = {};
+  const pairs = cookieHeader.split(";");
+
+  for (const pair of pairs) {
+    const [name, ...rest] = pair.trim().split("=");
+    if (name) {
+      const raw = rest.join("=");
+      try {
+        cookies[name] = decodeURIComponent(raw);
+      } catch {
+        // Malformed percent-encoded value (e.g. %zz) - fall back to raw value
+        cookies[name] = raw;
+      }
+    }
+  }
+
+  return cookies;
+}
+
+/**
+ * Serialize a cookie for Set-Cookie header
+ */
+export function serializeCookie(
+  name: string,
+  value: string,
+  options: CookieOptions = {},
+): string {
+  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+
+  if (options.domain) cookie += `; Domain=${options.domain}`;
+  if (options.path) cookie += `; Path=${options.path}`;
+  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`;
+  if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
+  if (options.httpOnly) cookie += "; HttpOnly";
+  if (options.secure) cookie += "; Secure";
+  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`;
+
+  return cookie;
+}

package/src/router/middleware-types.ts

@@ -0,0 +1,179 @@
+/**
+ * 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,
+  DefaultRouteName,
+  DefaultVars,
+} from "../types/global-namespace.js";
+import type { ScopedReverseFunction } from "../reverse.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;
+};
+
+/**
+ * Cookie options for setting cookies
+ */
+export interface CookieOptions {
+  domain?: string;
+  path?: string;
+  maxAge?: number;
+  expires?: Date;
+  httpOnly?: boolean;
+  secure?: boolean;
+  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 */
+  url: URL;
+
+  /** URL pathname */
+  pathname: string;
+
+  /** URL search params */
+  searchParams: URLSearchParams;
+
+  /** Platform bindings (Cloudflare, etc.) */
+  env: TEnv;
+
+  /** URL params extracted from route/middleware pattern */
+  params: TParams;
+
+  /**
+   * Response stub (read-only). Before `next()`, returns the shared response stub
+   * where headers and cookies accumulate. After `next()`, returns the downstream response.
+   *
+   * Use `ctx.header()` to set response headers, or `cookies()` for cookie mutations.
+   * To replace the response entirely, return a new `Response` from the middleware.
+   */
+  readonly res: Response;
+
+  /** 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.
+   * Shorthand for `ctx.res.headers.set()`.
+   */
+  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;
+
+  /**
+   * 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>> = (
+  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 - allows ctx.res to be updated after next() is called
+ */
+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>;
+}