@rangojs/router 0.0.0-experimental.22 → 0.0.0-experimental.24

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.22",
+  version: "0.0.0-experimental.24",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.22",
+  "version": "0.0.0-experimental.24",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/router/loader-resolution.ts

@@ -262,7 +262,7 @@ function createLoaderExecutor<TEnv>(
       reverse: ctx.reverse as LoaderContext["reverse"],
     };
 
-    const doneLoader = track(`loader:${loader.$$id}`);
+    const doneLoader = track(`loader:${loader.$$id}`, 2);
     const promise = Promise.resolve(
       loaderFn(loaderCtx as LoaderContext<any, TEnv>),
     ).finally(() => {

package/src/router/match-result.ts

@@ -108,7 +108,7 @@
  */
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
-import { generateServerTiming, logMetrics } from "./metrics.js";
+import { generateServerTiming } from "./metrics.js";
 import { debugLog } from "./logging.js";
 
 /**
@@ -189,7 +189,6 @@ export function buildMatchResult<TEnv>(
   // Output metrics if enabled
   let serverTiming: string | undefined;
   if (ctx.metricsStore) {
-    logMetrics(ctx.request.method, ctx.pathname, ctx.metricsStore);
     serverTiming = generateServerTiming(ctx.metricsStore);
   }
 

package/src/router/metrics.ts

@@ -4,7 +4,56 @@
  * Performance metrics collection and reporting for RSC Router.
  */
 
-import type { MetricsStore } from "../server/context";
+import type { MetricsStore, PerformanceMetric } from "../server/context";
+
+const BASE_INDENT = 2;
+const DEPTH_INDENT = 2;
+const TIMELINE_WIDTH = 40;
+
+function formatMs(value: number): string {
+  return `${value.toFixed(1)}ms`;
+}
+
+function sortMetrics(metrics: PerformanceMetric[]): PerformanceMetric[] {
+  return [...metrics].sort((a, b) => a.startTime - b.startTime);
+}
+
+function renderTimeline(metric: PerformanceMetric, total: number): string {
+  if (TIMELINE_WIDTH <= 0) {
+    return "||";
+  }
+
+  const cells = Array(TIMELINE_WIDTH).fill(".");
+
+  if (!(total > 0)) {
+    cells[0] = "#";
+    return `|${cells.join("")}|`;
+  }
+
+  const start = Math.max(0, metric.startTime);
+  const end = Math.max(start, metric.startTime + metric.duration);
+  const startColumn = Math.min(
+    TIMELINE_WIDTH - 1,
+    Math.floor((start / total) * TIMELINE_WIDTH),
+  );
+  const endColumn = Math.max(
+    startColumn + 1,
+    Math.min(
+      TIMELINE_WIDTH,
+      Math.ceil((Math.min(total, end) / total) * TIMELINE_WIDTH),
+    ),
+  );
+
+  cells.fill("#", startColumn, endColumn);
+  return `|${cells.join("")}|`;
+}
+
+function createTimelineAxis(total: number): string {
+  const totalLabel = formatMs(total);
+  return `0ms${" ".repeat(
+    Math.max(1, TIMELINE_WIDTH - "0ms".length - totalLabel.length),
+  )}${totalLabel}`;
+}
 
 /**
  * Create a metrics store for the request if debugPerformance is enabled
@@ -21,7 +70,44 @@ export function createMetricsStore(
 }
 
 /**
- * Log metrics to console in a formatted way
+ * Append a metric to the request store using an absolute start timestamp.
+ */
+export function appendMetric(
+  metricsStore: MetricsStore | undefined,
+  label: string,
+  start: number,
+  duration: number,
+  depth?: number,
+): void {
+  if (!metricsStore) return;
+  metricsStore.metrics.push({
+    label,
+    duration,
+    startTime: start - metricsStore.requestStart,
+    depth,
+  });
+}
+
+/**
+ * Log the current request metrics and return the corresponding Server-Timing value.
+ * Falls back to an existing header value when no metrics store is active.
+ */
+export function buildMetricsTiming(
+  method: string,
+  pathname: string,
+  metricsStore: MetricsStore | undefined,
+  fallback?: string,
+): string | undefined {
+  if (!metricsStore) {
+    return fallback;
+  }
+  logMetrics(method, pathname, metricsStore);
+  return generateServerTiming(metricsStore) || undefined;
+}
+
+/**
+ * Log metrics to console in a formatted way.
+ * Uses a shared-axis timeline so overlapping work stays visible.
  */
 export function logMetrics(
   method: string,
@@ -30,32 +116,62 @@ export function logMetrics(
 ): 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,
+  const sorted = sortMetrics(metricsStore.metrics);
+  const labels = sorted.map(
+    (m) =>
+      `${" ".repeat(BASE_INDENT + (m.depth ?? 0) * DEPTH_INDENT)}${m.label}`,
+  );
+  const startValues = sorted.map((m) => formatMs(m.startTime));
+  const durationValues = sorted.map((m) => formatMs(m.duration));
+  const startWidth = Math.max(
+    "start".length,
+    ...startValues.map((v) => v.length),
+  );
+  const durationWidth = Math.max(
+    "dur".length,
+    ...durationValues.map((v) => v.length),
+  );
+  const spanWidth = Math.max(
+    "span".length,
+    ...labels.map((label) => label.length),
+    22,
+  );
+  const timelinePadding = " ".repeat(
+    startWidth + 2 + durationWidth + 2 + spanWidth + 2,
   );
 
   console.log(`[RSC Perf] ${method} ${pathname} (${total.toFixed(1)}ms)`);
+  console.log(
+    `${"start".padStart(startWidth)}  ${"dur".padStart(durationWidth)}  ${"span".padEnd(spanWidth)}  timeline`,
+  );
+  console.log(`${timelinePadding}${createTimelineAxis(total)}`);
+
+  for (let index = 0; index < sorted.length; index++) {
+    const metric = sorted[index];
+    const label = labels[index].padEnd(spanWidth);
+    const start = formatMs(metric.startTime).padStart(startWidth);
+    const duration = formatMs(metric.duration).padStart(durationWidth);
 
-  for (const m of metricsStore.metrics) {
-    const paddedLabel = m.label.padEnd(maxLabelLen);
-    console.log(`  ${paddedLabel} ${m.duration.toFixed(1)}ms`);
+    console.log(
+      `${start}  ${duration}  ${label}  ${renderTimeline(metric, total)}`,
+    );
   }
 }
 
 /**
  * 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) => {
       // Convert label to valid Server-Timing name (alphanumeric and hyphens)
-      const name = m.label
+      const base = m.label
         .replace(/:/g, "-")
         .replace(/[^a-zA-Z0-9-]/g, "")
         .toLowerCase();
+      const name = m.depth ? `d${m.depth}-${base}` : base;
       return `${name};dur=${m.duration.toFixed(2)}`;
     })
     .join(", ");

package/src/router/middleware-types.ts

@@ -100,6 +100,18 @@ export interface MiddlewareContext<
    */
   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.
+   *
+   * Must be called **before** `await next()` — the metrics store is
+   * created at the start of route matching inside `next()`, so calling
+   * this after `next()` returns has no effect.
+   */
+  debugPerformance(): void;
+
   /**
    * Generate URLs from route names.
    * - `name` — global route, from the named-routes definition

package/src/router/middleware.ts

@@ -20,6 +20,7 @@ import type {
 } from "./middleware-types.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
+import { appendMetric } from "./metrics.js";
 
 // Re-export types and cookie utilities for backward compatibility
 export type {
@@ -49,6 +50,29 @@ function warnCtxSetBeforeRedirect(handler: Function): void {
   );
 }
 
+const MIDDLEWARE_METRIC_DEPTH = 1;
+
+function getMiddlewareMetricBase<TEnv>(
+  entry: MiddlewareEntry<TEnv>,
+  ordinal: number,
+): string {
+  const handlerName = entry.handler.name?.trim();
+  const scope = entry.pattern ?? "*";
+
+  if (handlerName) {
+    return `${handlerName}@${scope}`;
+  }
+
+  return `${scope}#${ordinal + 1}`;
+}
+
+function getMiddlewareMetricLabel<TEnv>(
+  entry: MiddlewareEntry<TEnv>,
+  ordinal: number,
+): string {
+  return `middleware:${getMiddlewareMetricBase(entry, ordinal)}`;
+}
+
 /** Reset W5 deduplication state (for tests only). */
 export function _resetW5Warnings(): void {
   warnedRedirectMiddleware = new WeakSet();
@@ -227,6 +251,13 @@ export function createMiddlewareContext<TEnv>(
           `ctx.reverse() is not available - route map was not provided to middleware context`,
         );
       }),
+
+    debugPerformance(): void {
+      const reqCtx = _getRequestContext();
+      if (reqCtx) {
+        reqCtx._debugPerformance = true;
+      }
+    },
   };
 }
 
@@ -309,14 +340,21 @@ export async function executeMiddleware<TEnv>(
         }
       });
       // Also merge shared RequestContext stub (cookies written via cookies().set()).
-      // Set-Cookie duplication is prevented by createResponseWithMergedHeaders
-      // draining Set-Cookie from ctx.res after merging (helpers.ts).
+      // Dedup Set-Cookie: an inner executeMiddleware (route-level middleware)
+      // may have already merged the same reqCtx cookies into the response.
       const reqCtx = _getRequestContext();
       if (reqCtx) {
+        const stubCookies = reqCtx.res.headers.getSetCookie();
+        if (stubCookies.length > 0) {
+          const existing = new Set(mergedHeaders.getSetCookie());
+          for (const cookie of stubCookies) {
+            if (!existing.has(cookie)) {
+              mergedHeaders.append("set-cookie", cookie);
+            }
+          }
+        }
         reqCtx.res.headers.forEach((value, name) => {
-          if (name.toLowerCase() === "set-cookie") {
-            mergedHeaders.append(name, value);
-          } else if (!mergedHeaders.has(name)) {
+          if (name !== "set-cookie" && !mergedHeaders.has(name)) {
             mergedHeaders.set(name, value);
           }
         });
@@ -332,6 +370,7 @@ export async function executeMiddleware<TEnv>(
       return responseHolder.response;
     }
 
+    const middlewareOrdinal = index;
     const { entry, params } = middlewares[index++];
     const ctx = createMiddlewareContext(
       request,
@@ -341,6 +380,21 @@ export async function executeMiddleware<TEnv>(
       responseHolder,
       reverse,
     );
+    const metricsStore = _getRequestContext()?._metricsStore;
+    const metricStart = performance.now();
+    let middlewareFinished = false;
+    const finishMiddleware = () => {
+      if (!middlewareFinished) {
+        middlewareFinished = true;
+        appendMetric(
+          metricsStore,
+          getMiddlewareMetricLabel(entry, middlewareOrdinal),
+          metricStart,
+          performance.now() - metricStart,
+          MIDDLEWARE_METRIC_DEPTH,
+        );
+      }
+    };
 
     // Track if next() was called and capture its Promise.
     // Guard against double-calling: a second call would re-enter the
@@ -352,6 +406,7 @@ export async function executeMiddleware<TEnv>(
           `[@rangojs/router] Middleware called next() more than once.`,
         );
       }
+      finishMiddleware();
       nextPromise = next();
       return nextPromise;
     };
@@ -366,7 +421,14 @@ export async function executeMiddleware<TEnv>(
       }) as typeof ctx.set;
     }
 
-    const result = await entry.handler(ctx, wrappedNext);
+    let result: Response | void;
+    try {
+      result = await entry.handler(ctx, wrappedNext);
+    } catch (error) {
+      finishMiddleware();
+      throw error;
+    }
+    finishMiddleware();
 
     // Explicit return takes precedence (middleware short-circuit).
     // Merge stub headers (from ctx.header before this point) and
@@ -391,13 +453,22 @@ export async function executeMiddleware<TEnv>(
           mergedHeaders.set(name, value);
         }
       });
-      // Also merge shared RequestContext stub (cookies written via setCookie)
+      // Also merge shared RequestContext stub (cookies written via setCookie).
+      // Dedup Set-Cookie: an inner executeMiddleware (route-level middleware)
+      // may have already merged the same reqCtx cookies into the response.
       const reqCtx = _getRequestContext();
       if (reqCtx) {
+        const stubCookies = reqCtx.res.headers.getSetCookie();
+        if (stubCookies.length > 0) {
+          const existing = new Set(mergedHeaders.getSetCookie());
+          for (const cookie of stubCookies) {
+            if (!existing.has(cookie)) {
+              mergedHeaders.append("set-cookie", cookie);
+            }
+          }
+        }
         reqCtx.res.headers.forEach((value, name) => {
-          if (name.toLowerCase() === "set-cookie") {
-            mergedHeaders.append(name, value);
-          } else if (!mergedHeaders.has(name)) {
+          if (name !== "set-cookie" && !mergedHeaders.has(name)) {
             mergedHeaders.set(name, value);
           }
         });
@@ -459,6 +530,29 @@ export async function executeMiddleware<TEnv>(
     throw new Error("No response generated by middleware chain");
   }
 
+  // Final re-merge: capture any RequestContext stub headers added after the
+  // last merge point (e.g. cookies().set() called after await next()).
+  // The reqCtx stub may have already been partially merged during finalHandler
+  // or early-return paths; only append *new* Set-Cookie entries to avoid dupes.
+  const reqCtx = _getRequestContext();
+  if (reqCtx) {
+    const stubCookies = reqCtx.res.headers.getSetCookie();
+    if (stubCookies.length > 0) {
+      const existingCookies = new Set(finalResponse.headers.getSetCookie());
+      for (const cookie of stubCookies) {
+        if (!existingCookies.has(cookie)) {
+          finalResponse.headers.append("set-cookie", cookie);
+        }
+      }
+    }
+    // Fill in non-cookie headers that aren't already on the response
+    reqCtx.res.headers.forEach((value, name) => {
+      if (name !== "set-cookie" && !finalResponse.headers.has(name)) {
+        finalResponse.headers.set(name, value);
+      }
+    });
+  }
+
   return finalResponse;
 }
 

package/src/router/segment-resolution/fresh.ts

@@ -24,6 +24,7 @@ import {
 } from "./helpers.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
+import { track } from "../../server/context.js";
 
 // ---------------------------------------------------------------------------
 // Streamed handler telemetry
@@ -178,7 +179,9 @@ export async function resolveSegment<TEnv>(
     (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
       entry.shortCode;
 
+    const doneLayoutHandler = track(`handler:${entry.id}`, 2);
     const component = await resolveLayoutComponent(entry, context);
+    doneLayoutHandler();
 
     segments.push({
       id: entry.shortCode,
@@ -241,9 +244,11 @@ export async function resolveSegment<TEnv>(
       entry.shortCode,
     );
     if (component === undefined) {
+      const doneRouteHandler = track(`handler:${entry.id}`, 2);
       if (entry.loading) {
         const result = handleHandlerResult(entry.handler(context));
         if (result instanceof Promise) {
+          result.finally(doneRouteHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: entry.shortCode,
             segmentType: entry.type,
@@ -258,10 +263,12 @@ export async function resolveSegment<TEnv>(
           );
           component = tracked;
         } else {
+          doneRouteHandler();
           component = result;
         }
       } else {
         component = handleHandlerResult(await entry.handler(context));
+        doneRouteHandler();
       }
     }
 
@@ -343,7 +350,9 @@ export async function resolveOrphanLayout<TEnv>(
 
   // Handler-first: orphan layout handler executes before its parallels
   // so that ctx.set() values are visible to parallel children.
+  const doneOrphanHandler = track(`handler:${orphan.id}`, 2);
   const component = await resolveLayoutComponent(orphan, context);
+  doneOrphanHandler();
 
   segments.push({
     id: orphan.shortCode,
@@ -410,12 +419,17 @@ export async function resolveParallelEntry<TEnv>(
     );
 
     if (component === undefined) {
+      const doneParallelHandler = track(
+        `handler:${parallelEntry.id}.${slot}`,
+        2,
+      );
       const hasLoadingFallback =
         parallelEntry.loading !== undefined && parallelEntry.loading !== false;
       if (hasLoadingFallback) {
         const result =
           typeof handler === "function" ? handler(context) : handler;
         if (result instanceof Promise) {
+          result.finally(doneParallelHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: `${parentShortCode}.${slot}`,
             segmentType: "parallel",
@@ -430,11 +444,13 @@ export async function resolveParallelEntry<TEnv>(
           );
           component = tracked as ReactNode;
         } else {
+          doneParallelHandler();
           component = result as ReactNode;
         }
       } else {
         component =
           typeof handler === "function" ? await handler(context) : handler;
+        doneParallelHandler();
       }
     }
 
@@ -499,6 +515,7 @@ export async function resolveAllSegments<TEnv>(
   } catch {}
 
   for (const entry of entries) {
+    const doneEntry = track(`segment:${entry.id}`, 1);
     const resolvedSegments = await resolveWithErrorBoundary(
       entry,
       params,
@@ -518,6 +535,7 @@ export async function resolveAllSegments<TEnv>(
       { request: safeRequest, url: context.url, routeKey, telemetry },
       context.pathname,
     );
+    doneEntry();
     // Deduplicate by segment ID. include() scopes can produce entries that
     // resolve the same shared layout/loader segment. Duplicates in the segment
     // array propagate to the client's matched[] and change the React tree depth.

package/src/router/segment-resolution/revalidation.ts

@@ -37,6 +37,7 @@ import {
 } from "./helpers.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
+import { track } from "../../server/context.js";
 
 // ---------------------------------------------------------------------------
 // Telemetry helpers
@@ -621,20 +622,29 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       return shouldRevalidate;
     },
     async () => {
+      const doneHandler = track(`handler:${entry.id}`, 2);
       (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
         entry.shortCode;
       if (entry.type === "layout" || entry.type === "cache") {
-        return resolveLayoutComponent(entry, context);
+        const layoutComponent = await resolveLayoutComponent(entry, context);
+        doneHandler();
+        return layoutComponent;
       }
       const staticComponent = await tryStaticHandler(entry, entry.shortCode);
-      if (staticComponent !== undefined) return staticComponent;
+      if (staticComponent !== undefined) {
+        doneHandler();
+        return staticComponent;
+      }
       const routeEntry = entry as Extract<EntryData, { type: "route" }>;
       if (!routeEntry.loading) {
-        return handleHandlerResult(await routeEntry.handler(context));
+        const result = handleHandlerResult(await routeEntry.handler(context));
+        doneHandler();
+        return result;
       }
       if (!actionContext) {
         const result = handleHandlerResult(routeEntry.handler(context));
         if (result instanceof Promise) {
+          result.finally(doneHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: entry.shortCode,
             segmentType: entry.type,
@@ -649,15 +659,18 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
           );
           return { content: tracked };
         }
+        doneHandler();
         return { content: result };
       }
       debugLog("segment.action", "resolving action route with awaited value", {
         entryId: entry.id,
       });
+      const actionResult = handleHandlerResult(
+        await routeEntry.handler(context),
+      );
+      doneHandler();
       return {
-        content: Promise.resolve(
-          handleHandlerResult(await routeEntry.handler(context)),
-        ),
+        content: Promise.resolve(actionResult),
       };
     },
     () => null,
@@ -1178,6 +1191,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     }
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
+    const doneEntry = track(`segment:${entry.id}`, 1);
     const resolved = await resolveWithErrorBoundary(
       nonParallelEntry,
       params,
@@ -1204,6 +1218,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
         : undefined,
       pathname,
     );
+    doneEntry();
 
     // Deduplicate segments and matchedIds by ID, matching resolveAllSegments.
     // include() scopes can produce entries that resolve the same shared

package/src/router.ts

@@ -357,8 +357,18 @@ export function createRouter<TEnv = any>(
     return precomputedByPrefix;
   }
 
-  // Wrapper to pass debugPerformance to external createMetricsStore
-  const getMetricsStore = () => createMetricsStore(debugPerformance);
+  // Wrapper to pass debugPerformance to external createMetricsStore.
+  // Also checks per-request flag set by ctx.debugPerformance() in middleware.
+  const getMetricsStore = () => {
+    const reqCtx = _getRequestContext();
+    const enabled = debugPerformance || !!reqCtx?._debugPerformance;
+    if (!enabled) return undefined;
+    if (!reqCtx) {
+      return createMetricsStore(true);
+    }
+    reqCtx._metricsStore ??= createMetricsStore(true);
+    return reqCtx._metricsStore;
+  };
 
   // Wrapper to pass defaults to error/notFound boundary finders
   const findNearestErrorBoundary = (entry: EntryData | null) =>