@rangojs/router 0.0.0-experimental.21 → 0.0.0-experimental.23

package/src/index.ts

@@ -115,25 +115,32 @@ export type {
 // Middleware context types
 export type { MiddlewareContext, CookieOptions } from "./router/middleware.js";
 
+function serverOnlyStubError(name: string): Error {
+  return new Error(
+    `${name}() is only available from "@rangojs/router" in a react-server/RSC environment. ` +
+      `For client hooks and components, import from "@rangojs/router/client".`,
+  );
+}
+
 /**
  * Error-throwing stub for server-only `urls` function.
  */
 export function urls(): never {
-  throw new Error("urls() is server-only and requires RSC context.");
+  throw serverOnlyStubError("urls");
 }
 
 /**
  * Error-throwing stub for server-only `createRouter` function.
  */
 export function createRouter(): never {
-  throw new Error("createRouter() is server-only and requires RSC context.");
+  throw serverOnlyStubError("createRouter");
 }
 
 /**
  * Error-throwing stub for server-only `redirect` function.
  */
 export function redirect(): never {
-  throw new Error("redirect() is server-only and requires RSC context.");
+  throw serverOnlyStubError("redirect");
 }
 
 // Handle API (universal - works on both server and client)
@@ -149,102 +156,94 @@ export { nonce } from "./rsc/nonce.js";
  * Error-throwing stub for server-only `Prerender` function.
  */
 export function Prerender(): never {
-  throw new Error("Prerender() is server-only and requires RSC context.");
+  throw serverOnlyStubError("Prerender");
 }
 
 /**
  * Error-throwing stub for server-only `Static` function.
  */
 export function Static(): never {
-  throw new Error("Static() is server-only and requires RSC context.");
+  throw serverOnlyStubError("Static");
 }
 
 /**
  * Error-throwing stub for server-only `getRequestContext` function.
  */
 export function getRequestContext(): never {
-  throw new Error(
-    "getRequestContext() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("getRequestContext");
 }
 
 /**
  * Error-throwing stub for server-only `cookies` function.
  */
 export function cookies(): never {
-  throw new Error("cookies() is server-only and requires RSC context.");
+  throw serverOnlyStubError("cookies");
 }
 
 /**
  * Error-throwing stub for server-only `headers` function.
  */
 export function headers(): never {
-  throw new Error("headers() is server-only and requires RSC context.");
+  throw serverOnlyStubError("headers");
 }
 
 /**
  * Error-throwing stub for server-only `createReverse` function.
  */
 export function createReverse(): never {
-  throw new Error("createReverse() is server-only and requires RSC context.");
+  throw serverOnlyStubError("createReverse");
 }
 
 /**
  * Error-throwing stub for server-only `enableMatchDebug` function.
  */
 export function enableMatchDebug(): never {
-  throw new Error(
-    "enableMatchDebug() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("enableMatchDebug");
 }
 
 /**
  * Error-throwing stub for server-only `getMatchDebugStats` function.
  */
 export function getMatchDebugStats(): never {
-  throw new Error(
-    "getMatchDebugStats() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("getMatchDebugStats");
 }
 
 // Error-throwing stubs for server-only route helpers
 export function layout(): never {
-  throw new Error("layout() is server-only and requires RSC context.");
+  throw serverOnlyStubError("layout");
 }
 export function cache(): never {
-  throw new Error("cache() is server-only and requires RSC context.");
+  throw serverOnlyStubError("cache");
 }
 export function middleware(): never {
-  throw new Error("middleware() is server-only and requires RSC context.");
+  throw serverOnlyStubError("middleware");
 }
 export function revalidate(): never {
-  throw new Error("revalidate() is server-only and requires RSC context.");
+  throw serverOnlyStubError("revalidate");
 }
 export function loader(): never {
-  throw new Error("loader() is server-only and requires RSC context.");
+  throw serverOnlyStubError("loader");
 }
 export function loading(): never {
-  throw new Error("loading() is server-only and requires RSC context.");
+  throw serverOnlyStubError("loading");
 }
 export function parallel(): never {
-  throw new Error("parallel() is server-only and requires RSC context.");
+  throw serverOnlyStubError("parallel");
 }
 export function intercept(): never {
-  throw new Error("intercept() is server-only and requires RSC context.");
+  throw serverOnlyStubError("intercept");
 }
 export function when(): never {
-  throw new Error("when() is server-only and requires RSC context.");
+  throw serverOnlyStubError("when");
 }
 export function errorBoundary(): never {
-  throw new Error("errorBoundary() is server-only and requires RSC context.");
+  throw serverOnlyStubError("errorBoundary");
 }
 export function notFoundBoundary(): never {
-  throw new Error(
-    "notFoundBoundary() is server-only and requires RSC context.",
-  );
+  throw serverOnlyStubError("notFoundBoundary");
 }
 export function transition(): never {
-  throw new Error("transition() is server-only and requires RSC context.");
+  throw serverOnlyStubError("transition");
 }
 
 // Request context type (safe for client)

package/src/route-definition/index.ts

@@ -1,6 +1,3 @@
-// Route definition
-export { route, type RouteDefinitionResult } from "./route-function.js";
-
 // Type definitions
 export type { RouteHelpers } from "./helpers-types.js";
 export type {

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/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,8 @@ export function createMetricsStore(
 }
 
 /**
- * Log metrics to console in a formatted way
+ * 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 +80,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

@@ -227,6 +227,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 +316,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);
           }
         });
@@ -391,13 +405,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 +482,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/router-options.ts

@@ -239,7 +239,7 @@ export interface RSCRouterOptions<TEnv = any> {
    *
    * @example Static config
    * ```typescript
-   * import { MemorySegmentCacheStore } from "rsc-router/rsc";
+   * import { MemorySegmentCacheStore } from "@rangojs/router/cache";
    *
    * const router = createRouter({
    *   cache: {

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,12 @@ 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 = () =>
+    createMetricsStore(
+      debugPerformance || !!_getRequestContext()?._debugPerformance,
+    );
 
   // Wrapper to pass defaults to error/notFound boundary finders
   const findNearestErrorBoundary = (entry: EntryData | null) =>

package/src/rsc/index.ts

@@ -29,28 +29,8 @@ export type {
   NonceProvider,
 } from "./types.js";
 
-// Re-export HandleStore types for consumers who need custom handling
-export {
-  createHandleStore,
-  type HandleStore,
-  type HandleData,
-} from "../server/handle-store.js";
-
 // Re-export request context utilities for server-side access to env/request/params
 export {
   getRequestContext,
   requireRequestContext,
-  setRequestContextParams,
 } from "../server/request-context.js";
-
-// Re-export cache store types and implementations
-export type {
-  SegmentCacheStore,
-  CachedEntryData,
-  CachedEntryResult,
-  SegmentCacheProvider,
-  SegmentHandleData,
-} from "../cache/types.js";
-
-export { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
-export { CFCacheStore, type CFCacheStoreOptions } from "../cache/cf/index.js";