@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.100

package/src/router/segment-wrappers.ts

@@ -0,0 +1,291 @@
+import type { EntryData, InterceptEntry } from "../server/context";
+import type {
+  HandlerContext,
+  ResolvedSegment,
+  ShouldRevalidateFn,
+} from "../types";
+import type { SegmentResolutionDeps } from "./types.js";
+
+import {
+  resolveAllSegments as _resolveAllSegments,
+  resolveLoadersOnly as _resolveLoadersOnly,
+  resolveLoadersOnlyWithRevalidation as _resolveLoadersOnlyWithRevalidation,
+  buildEntryRevalidateMap as _buildEntryRevalidateMap,
+  resolveAllSegmentsWithRevalidation as _resolveAllSegmentsWithRevalidation,
+} from "./segment-resolution.js";
+
+import {
+  findInterceptForRoute as _findInterceptForRoute,
+  resolveInterceptEntry as _resolveInterceptEntry,
+  resolveInterceptLoadersOnly as _resolveInterceptLoadersOnly,
+} from "./intercept-resolution.js";
+
+import type { InterceptSelectorContext } from "../server/context";
+
+export interface SegmentWrappers<TEnv = any> {
+  resolveAllSegments: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>,
+    options?: { skipLoaders?: boolean },
+  ) => Promise<ResolvedSegment[]>;
+  resolveLoadersOnly: (
+    entries: EntryData[],
+    context: HandlerContext<any, TEnv>,
+  ) => Promise<ResolvedSegment[]>;
+  resolveLoadersOnlyWithRevalidation: (
+    entries: EntryData[],
+    context: HandlerContext<any, TEnv>,
+    clientSegmentIds: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    routeKey: string,
+    actionContext?: {
+      actionId?: string;
+      actionUrl?: URL;
+      actionResult?: any;
+      formData?: FormData;
+    },
+    stale?: boolean,
+  ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
+  buildEntryRevalidateMap: (
+    entries: EntryData[],
+  ) => Map<
+    string,
+    { entry: EntryData; revalidate: ShouldRevalidateFn<any, any>[] }
+  >;
+  resolveAllSegmentsWithRevalidation: (
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    clientSegmentSet: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    loaderPromises: Map<string, Promise<any>>,
+    actionContext:
+      | {
+          actionId?: string;
+          actionUrl?: URL;
+          actionResult?: any;
+          formData?: FormData;
+        }
+      | undefined,
+    interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
+    localRouteName: string,
+    pathname: string,
+  ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
+  findInterceptForRoute: (
+    targetRouteKey: string,
+    fromEntry: EntryData | null,
+    selectorContext?: InterceptSelectorContext | null,
+    isAction?: boolean,
+  ) => { intercept: InterceptEntry; entry: EntryData } | null;
+  resolveInterceptEntry: (
+    interceptEntry: InterceptEntry,
+    parentEntry: EntryData,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    belongsToRoute?: boolean,
+    revalidationContext?: any,
+  ) => Promise<ResolvedSegment[]>;
+  resolveInterceptLoadersOnly: (
+    interceptEntry: InterceptEntry,
+    parentEntry: EntryData,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    belongsToRoute?: boolean,
+    revalidationContext?: any,
+  ) => Promise<{
+    loaderDataPromise: Promise<any[]> | any[];
+    loaderIds: string[];
+  } | null>;
+}
+
+/**
+ * Create thin wrapper functions that bind segmentDeps to extracted
+ * segment resolution and intercept resolution functions.
+ *
+ * These maintain the same signatures as the original inline functions
+ * so that RouterContext and call sites don't need to change.
+ */
+export function createSegmentWrappers<TEnv = any>(
+  segmentDeps: SegmentResolutionDeps<TEnv>,
+): SegmentWrappers<TEnv> {
+  function resolveAllSegments(
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    loaderPromises: Map<string, Promise<any>>,
+    options?: { skipLoaders?: boolean },
+  ): ReturnType<typeof _resolveAllSegments> {
+    return _resolveAllSegments(
+      entries,
+      routeKey,
+      params,
+      context,
+      loaderPromises,
+      segmentDeps,
+      options,
+    );
+  }
+
+  function resolveLoadersOnly(
+    entries: EntryData[],
+    context: HandlerContext<any, TEnv>,
+  ): ReturnType<typeof _resolveLoadersOnly> {
+    return _resolveLoadersOnly(entries, context, segmentDeps);
+  }
+
+  function resolveLoadersOnlyWithRevalidation(
+    entries: EntryData[],
+    context: HandlerContext<any, TEnv>,
+    clientSegmentIds: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    routeKey: string,
+    actionContext?: {
+      actionId?: string;
+      actionUrl?: URL;
+      actionResult?: any;
+      formData?: FormData;
+    },
+    stale?: boolean,
+  ): ReturnType<typeof _resolveLoadersOnlyWithRevalidation> {
+    return _resolveLoadersOnlyWithRevalidation(
+      entries,
+      context,
+      clientSegmentIds,
+      prevParams,
+      request,
+      prevUrl,
+      nextUrl,
+      routeKey,
+      segmentDeps,
+      actionContext,
+      stale,
+    );
+  }
+
+  function buildEntryRevalidateMap(
+    entries: EntryData[],
+  ): ReturnType<typeof _buildEntryRevalidateMap> {
+    return _buildEntryRevalidateMap(entries);
+  }
+
+  function resolveAllSegmentsWithRevalidation(
+    entries: EntryData[],
+    routeKey: string,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    clientSegmentSet: Set<string>,
+    prevParams: Record<string, string>,
+    request: Request,
+    prevUrl: URL,
+    nextUrl: URL,
+    loaderPromises: Map<string, Promise<any>>,
+    actionContext:
+      | {
+          actionId?: string;
+          actionUrl?: URL;
+          actionResult?: any;
+          formData?: FormData;
+        }
+      | undefined,
+    interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
+    localRouteName: string,
+    pathname: string,
+    stale?: boolean,
+  ): ReturnType<typeof _resolveAllSegmentsWithRevalidation> {
+    return _resolveAllSegmentsWithRevalidation(
+      entries,
+      routeKey,
+      params,
+      context,
+      clientSegmentSet,
+      prevParams,
+      request,
+      prevUrl,
+      nextUrl,
+      loaderPromises,
+      actionContext,
+      interceptResult,
+      localRouteName,
+      pathname,
+      segmentDeps,
+      stale,
+    );
+  }
+
+  function findInterceptForRoute(
+    targetRouteKey: string,
+    fromEntry: EntryData | null,
+    selectorContext: InterceptSelectorContext | null = null,
+    isAction: boolean = false,
+  ): ReturnType<typeof _findInterceptForRoute> {
+    return _findInterceptForRoute(
+      targetRouteKey,
+      fromEntry,
+      selectorContext,
+      isAction,
+    );
+  }
+
+  function resolveInterceptEntry(
+    interceptEntry: InterceptEntry,
+    parentEntry: EntryData,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    belongsToRoute: boolean = true,
+    revalidationContext?: any,
+  ): ReturnType<typeof _resolveInterceptEntry> {
+    return _resolveInterceptEntry(
+      interceptEntry,
+      parentEntry,
+      params,
+      context,
+      belongsToRoute,
+      segmentDeps,
+      revalidationContext,
+    );
+  }
+
+  function resolveInterceptLoadersOnly(
+    interceptEntry: InterceptEntry,
+    parentEntry: EntryData,
+    params: Record<string, string>,
+    context: HandlerContext<any, TEnv>,
+    belongsToRoute: boolean = true,
+    revalidationContext: any,
+  ): ReturnType<typeof _resolveInterceptLoadersOnly> {
+    return _resolveInterceptLoadersOnly(
+      interceptEntry,
+      parentEntry,
+      params,
+      context,
+      belongsToRoute,
+      segmentDeps,
+      revalidationContext,
+    );
+  }
+
+  return {
+    resolveAllSegments: resolveAllSegments,
+    resolveLoadersOnly: resolveLoadersOnly,
+    resolveLoadersOnlyWithRevalidation: resolveLoadersOnlyWithRevalidation,
+    buildEntryRevalidateMap: buildEntryRevalidateMap,
+    resolveAllSegmentsWithRevalidation: resolveAllSegmentsWithRevalidation,
+    findInterceptForRoute: findInterceptForRoute,
+    resolveInterceptEntry: resolveInterceptEntry,
+    resolveInterceptLoadersOnly: resolveInterceptLoadersOnly,
+  };
+}

package/src/router/substitute-pattern-params.ts

@@ -0,0 +1,56 @@
+import { encodePathSegment } from "./url-params.js";
+
+/**
+ * Substitute `:param` placeholders in a route pattern with values from
+ * `params`. Two-pass: optional params (`:name?`) first so absent values
+ * collapse cleanly, then required params (throws on missing). Constraint
+ * syntax (`:name(en|gb)`) is stripped from the result. Trailing-slash
+ * patterns like `/blog/` are preserved unless an optional segment was
+ * actually omitted.
+ *
+ * Shared by `ctx.reverse()` (server), `createReverse()` (typed runtime
+ * helper), and `useReverse()` (client hook). The behavior must stay
+ * identical across all three call sites.
+ */
+export function substitutePatternParams(
+  pattern: string,
+  params: Record<string, string | undefined>,
+  routeName: string,
+): string {
+  let result = pattern;
+  let hadOmittedOptional = false;
+
+  result = result.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
+    (_match, key) => {
+      const value = params[key as string];
+      // The matcher omits absent optional params (so `value` is `undefined`
+      // here), but caller-supplied params or `getParams()` shapes may still
+      // pass `""` explicitly. Treat both as the absent form.
+      if (value === undefined || value === "") {
+        hadOmittedOptional = true;
+        return "";
+      }
+      return encodePathSegment(value);
+    },
+  );
+
+  result = result.replace(
+    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(?!\?)/g,
+    (_match, key) => {
+      const value = params[key as string];
+      if (value === undefined) {
+        throw new Error(`Missing param "${key}" for route "${routeName}"`);
+      }
+      return encodePathSegment(value);
+    },
+  );
+
+  if (hadOmittedOptional) {
+    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
+    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+  }
+
+  return result;
+}

package/src/router/telemetry-otel.ts

@@ -0,0 +1,299 @@
+/**
+ * OpenTelemetry Adapter for Router Telemetry
+ *
+ * Maps internal TelemetrySink events to OTel spans. The core router
+ * remains OTel-agnostic — this adapter bridges the gap by accepting
+ * a standard OTel Tracer and producing spans/events from it.
+ *
+ * Usage:
+ *   import { trace } from "@opentelemetry/api";
+ *   import { createOTelSink } from "@rangojs/router";
+ *
+ *   const router = createRouter({
+ *     telemetry: createOTelSink(trace.getTracer("my-app")),
+ *   });
+ */
+
+import type { TelemetrySink, TelemetryEvent } from "./telemetry.js";
+
+// ---------------------------------------------------------------------------
+// Minimal OTel-compatible types (structurally typed, no import needed)
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal Span interface compatible with @opentelemetry/api Span.
+ * Only the methods used by the adapter are declared.
+ */
+export interface OTelSpan {
+  setAttribute(key: string, value: string | number | boolean): OTelSpan | void;
+  addEvent(
+    name: string,
+    attributes?: Record<string, string | number | boolean>,
+  ): OTelSpan | void;
+  setStatus(status: { code: number; message?: string }): OTelSpan | void;
+  recordException(exception: Error): void;
+  end(): void;
+}
+
+/**
+ * Minimal Tracer interface compatible with @opentelemetry/api Tracer.
+ */
+export interface OTelTracer {
+  startSpan(
+    name: string,
+    options?: {
+      attributes?: Record<string, string | number | boolean>;
+    },
+  ): OTelSpan;
+}
+
+// OTel SpanStatusCode constants (mirrors @opentelemetry/api values)
+const STATUS_OK = 1;
+const STATUS_ERROR = 2;
+
+// ---------------------------------------------------------------------------
+// Span correlation helpers
+// ---------------------------------------------------------------------------
+
+// Build correlation keys using requestId.
+// getRequestId() always returns a value (generated internally when no
+// header is present), so concurrent requests to the same path each get
+// their own correlation key and never mis-correlate.
+
+function requestKey(event: {
+  requestId?: string;
+  pathname: string;
+  transaction: string;
+}): string {
+  return `${event.requestId ?? ""}:${event.pathname}:${event.transaction}`;
+}
+
+function loaderKey(event: {
+  requestId?: string;
+  segmentId: string;
+  loaderName: string;
+  pathname: string;
+}): string {
+  return `${event.requestId ?? ""}:${event.segmentId}:${event.loaderName}:${event.pathname}`;
+}
+
+function pushSpan(
+  map: Map<string, OTelSpan[]>,
+  key: string,
+  span: OTelSpan,
+): void {
+  let stack = map.get(key);
+  if (!stack) {
+    stack = [];
+    map.set(key, stack);
+  }
+  stack.push(span);
+}
+
+function popSpan(
+  map: Map<string, OTelSpan[]>,
+  key: string,
+): OTelSpan | undefined {
+  const stack = map.get(key);
+  if (!stack || stack.length === 0) return undefined;
+  const span = stack.pop()!;
+  if (stack.length === 0) map.delete(key);
+  return span;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a TelemetrySink that maps router lifecycle events to OTel spans.
+ *
+ * Span mapping:
+ *   - request.start / request.end / request.error  → "rango.request" span
+ *   - loader.start / loader.end / loader.error      → "rango.loader" span
+ *   - handler.error                                  → "rango.handler.error" instant span
+ *   - cache.decision                                 → "rango.cache.decision" instant span
+ *   - revalidation.decision                          → "rango.revalidation.decision" instant span
+ *
+ * Attributes use the `rango.*` namespace for router-specific data and
+ * `http.method` / `http.route` for HTTP semantics.
+ */
+export function createOTelSink(tracer: OTelTracer): TelemetrySink {
+  const requestSpans = new Map<string, OTelSpan[]>();
+  const loaderSpans = new Map<string, OTelSpan[]>();
+
+  return {
+    emit(event: TelemetryEvent): void {
+      switch (event.type) {
+        // -----------------------------------------------------------------
+        // Request lifecycle
+        // -----------------------------------------------------------------
+
+        case "request.start": {
+          const span = tracer.startSpan("rango.request", {
+            attributes: {
+              "http.method": event.method,
+              "http.route": event.pathname,
+              "rango.transaction": event.transaction,
+              "rango.is_partial": event.isPartial,
+            },
+          });
+          pushSpan(requestSpans, requestKey(event), span);
+          break;
+        }
+
+        case "request.end": {
+          const span = popSpan(requestSpans, requestKey(event));
+          if (span) {
+            span.setAttribute("rango.duration_ms", event.durationMs);
+            span.setAttribute("rango.segment_count", event.segmentCount);
+            span.setAttribute("rango.cache.hit", event.cacheHit);
+            span.setStatus({ code: STATUS_OK });
+            span.end();
+          }
+          break;
+        }
+
+        case "request.error": {
+          const span = popSpan(requestSpans, requestKey(event));
+          if (span) {
+            span.setAttribute("rango.duration_ms", event.durationMs);
+            span.setAttribute("rango.phase", event.phase);
+            span.recordException(event.error);
+            span.setStatus({
+              code: STATUS_ERROR,
+              message: event.error.message,
+            });
+            span.end();
+          }
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Loader lifecycle
+        // -----------------------------------------------------------------
+
+        case "loader.start": {
+          const span = tracer.startSpan("rango.loader", {
+            attributes: {
+              "rango.segment_id": event.segmentId,
+              "rango.loader_name": event.loaderName,
+              "http.route": event.pathname,
+            },
+          });
+          pushSpan(loaderSpans, loaderKey(event), span);
+          break;
+        }
+
+        case "loader.end": {
+          const key = loaderKey(event);
+          const span = popSpan(loaderSpans, key);
+          if (span) {
+            span.setAttribute("rango.duration_ms", event.durationMs);
+            span.setAttribute("rango.loader.ok", event.ok);
+            span.setStatus({ code: event.ok ? STATUS_OK : STATUS_ERROR });
+            span.end();
+          }
+          break;
+        }
+
+        case "loader.error": {
+          const key = loaderKey(event);
+          const span = popSpan(loaderSpans, key);
+          if (span) {
+            span.setAttribute(
+              "rango.handled_by_boundary",
+              event.handledByBoundary,
+            );
+            span.recordException(event.error);
+            span.setStatus({
+              code: STATUS_ERROR,
+              message: event.error.message,
+            });
+            span.end();
+          } else {
+            // No matching start — create a standalone error span
+            const errorSpan = tracer.startSpan("rango.loader", {
+              attributes: {
+                "rango.segment_id": event.segmentId,
+                "rango.loader_name": event.loaderName,
+                "http.route": event.pathname,
+                "rango.handled_by_boundary": event.handledByBoundary,
+              },
+            });
+            errorSpan.recordException(event.error);
+            errorSpan.setStatus({
+              code: STATUS_ERROR,
+              message: event.error.message,
+            });
+            errorSpan.end();
+          }
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Handler errors (instant span)
+        // -----------------------------------------------------------------
+
+        case "handler.error": {
+          const attrs: Record<string, string | number | boolean> = {
+            "rango.handled_by_boundary": event.handledByBoundary,
+          };
+          if (event.segmentId) attrs["rango.segment_id"] = event.segmentId;
+          if (event.segmentType)
+            attrs["rango.segment_type"] = event.segmentType;
+          if (event.pathname) attrs["http.route"] = event.pathname;
+          if (event.routeKey) attrs["rango.route_key"] = event.routeKey;
+          if (event.params) {
+            attrs["rango.params"] = JSON.stringify(event.params);
+          }
+
+          const span = tracer.startSpan("rango.handler.error", {
+            attributes: attrs,
+          });
+          span.recordException(event.error);
+          span.setStatus({ code: STATUS_ERROR, message: event.error.message });
+          span.end();
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Cache decision (instant span)
+        // -----------------------------------------------------------------
+
+        case "cache.decision": {
+          const attrs: Record<string, string | number | boolean> = {
+            "http.route": event.pathname,
+            "rango.route_key": event.routeKey,
+            "rango.cache.hit": event.hit,
+            "rango.cache.should_revalidate": event.shouldRevalidate,
+          };
+          if (event.source) attrs["rango.cache.source"] = event.source;
+
+          const span = tracer.startSpan("rango.cache.decision", {
+            attributes: attrs,
+          });
+          span.end();
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Revalidation decision (instant span)
+        // -----------------------------------------------------------------
+
+        case "revalidation.decision": {
+          const span = tracer.startSpan("rango.revalidation.decision", {
+            attributes: {
+              "rango.segment_id": event.segmentId,
+              "http.route": event.pathname,
+              "rango.route_key": event.routeKey,
+              "rango.revalidate": event.shouldRevalidate,
+            },
+          });
+          span.end();
+          break;
+        }
+      }
+    },
+  };
+}