@rangojs/router 0.0.0-experimental.10

package/src/router/pattern-matching.ts

@@ -0,0 +1,407 @@
+/**
+ * Router Pattern Matching
+ *
+ * Route pattern compilation and matching utilities.
+ */
+
+import type { RouteEntry, TrailingSlashMode } from "../types";
+import type { EntryData } from "../server/context";
+
+/**
+ * Parsed segment info
+ */
+export interface ParsedSegment {
+  type: "static" | "param" | "wildcard";
+  value: string; // static text, param name, or "*"
+  optional: boolean;
+  constraint?: string[]; // enum values like ["en", "gb"]
+}
+
+/**
+ * Parse a route pattern into segments
+ *
+ * Supports:
+ * - Static: /blog, /about
+ * - Params: /:slug, /:id
+ * - Optional: /:locale?, /:page?
+ * - Constrained: /:locale(en|gb), /:type(post|page)
+ * - Optional + Constrained: /:locale(en|gb)?
+ * - Wildcard: /*
+ */
+export function parsePattern(pattern: string): ParsedSegment[] {
+  const segments: ParsedSegment[] = [];
+  // Match: /segment where segment can be:
+  // - static text
+  // - :param
+  // - :param?
+  // - :param(a|b)
+  // - :param(a|b)?
+  // - *
+  const segmentRegex = /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?|(\*)|([^/]+))/g;
+
+  let match;
+  while ((match = segmentRegex.exec(pattern)) !== null) {
+    const [, , paramName, , constraint, optional, wildcard, staticText] = match;
+
+    if (wildcard) {
+      segments.push({ type: "wildcard", value: "*", optional: false });
+    } else if (paramName) {
+      segments.push({
+        type: "param",
+        value: paramName,
+        optional: optional === "?",
+        constraint: constraint ? constraint.split("|") : undefined,
+      });
+    } else if (staticText) {
+      segments.push({ type: "static", value: staticText, optional: false });
+    }
+  }
+
+  return segments;
+}
+
+/**
+ * Compile a route pattern to regex
+ *
+ * Supports:
+ * - Static segments: /blog, /about
+ * - Dynamic params: /:slug, /:id
+ * - Optional params: /:locale?, /:page?
+ * - Constrained params: /:locale(en|gb)
+ * - Optional + constrained: /:locale(en|gb)?
+ * - Wildcard: /*
+ *
+ * @example
+ * compilePattern("/blog/:slug")           // matches /blog/hello
+ * compilePattern("/:locale?/blog")        // matches /blog or /en/blog
+ * compilePattern("/:locale(en|gb)/blog")  // matches /en/blog or /gb/blog
+ * compilePattern("/:locale(en|gb)?/blog") // matches /blog, /en/blog, or /gb/blog
+ */
+export function compilePattern(pattern: string): {
+  regex: RegExp;
+  paramNames: string[];
+  optionalParams: Set<string>;
+  hasTrailingSlash: boolean;
+} {
+  // Detect if pattern has trailing slash (but not just "/")
+  const hasTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+  // Remove trailing slash for parsing (we'll add it back to regex if needed)
+  const normalizedPattern = hasTrailingSlash ? pattern.slice(0, -1) : pattern;
+
+  const segments = parsePattern(normalizedPattern);
+  const paramNames: string[] = [];
+  const optionalParams = new Set<string>();
+
+  let regexPattern = "";
+
+  for (const segment of segments) {
+    if (segment.type === "wildcard") {
+      paramNames.push("*");
+      regexPattern += "/(.*)";
+    } else if (segment.type === "param") {
+      paramNames.push(segment.value);
+      const valuePattern = segment.constraint
+        ? `(${segment.constraint.join("|")})`
+        : "([^/]+)";
+
+      if (segment.optional) {
+        optionalParams.add(segment.value);
+        // Optional: make the whole /segment optional
+        regexPattern += `(?:/${valuePattern})?`;
+      } else {
+        regexPattern += `/${valuePattern}`;
+      }
+    } else {
+      // Static segment
+      regexPattern += `/${escapeRegex(segment.value)}`;
+    }
+  }
+
+  // Handle root path
+  if (regexPattern === "") {
+    regexPattern = "/";
+  }
+
+  // Add trailing slash to regex if pattern has one
+  if (hasTrailingSlash) {
+    regexPattern += "/";
+  }
+
+  return {
+    regex: new RegExp(`^${regexPattern}$`),
+    paramNames,
+    optionalParams,
+    hasTrailingSlash,
+  };
+}
+
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegex(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Extract the static prefix from a route pattern.
+ * Returns everything before the first param/wildcard.
+ *
+ * Called ONCE at registration time, not at match time.
+ *
+ * Examples:
+ * - "/api" → "/api"
+ * - "/site/:locale" → "/site"
+ * - "/:locale" → ""
+ * - "/admin/users/:id" → "/admin/users"
+ * - "/api/*" → "/api"
+ */
+export function extractStaticPrefix(pattern: string): string {
+  if (!pattern || pattern === "/") return "";
+
+  // Find the first occurrence of : or *
+  const paramIndex = pattern.indexOf(":");
+  const wildcardIndex = pattern.indexOf("*");
+
+  let cutIndex = -1;
+  if (paramIndex !== -1 && wildcardIndex !== -1) {
+    cutIndex = Math.min(paramIndex, wildcardIndex);
+  } else if (paramIndex !== -1) {
+    cutIndex = paramIndex;
+  } else if (wildcardIndex !== -1) {
+    cutIndex = wildcardIndex;
+  }
+
+  if (cutIndex === -1) {
+    // No params or wildcards - entire pattern is static
+    return pattern;
+  }
+
+  if (cutIndex === 0) {
+    // Pattern starts with : or * - no static prefix
+    return "";
+  }
+
+  // Find the last / before the param
+  const lastSlash = pattern.lastIndexOf("/", cutIndex - 1);
+  if (lastSlash === -1 || lastSlash === 0) {
+    return "";
+  }
+
+  return pattern.slice(0, lastSlash);
+}
+
+/**
+ * Match a pathname against registered routes
+ *
+ * Note: Optional params that are absent in the path will have empty string value.
+ * Use the pattern definition to determine if a param is optional.
+ *
+ * Trailing slash handling (priority order):
+ * 1. Per-route `trailingSlash` config from route()
+ * 2. Pattern-based detection (pattern ending with `/`)
+ *
+ * Modes:
+ * - "never": Redirect to no trailing slash
+ * - "always": Redirect to with trailing slash
+ * - "ignore": Match both, no redirect
+ */
+/**
+ * Result of a route match
+ */
+export interface RouteMatchResult<TEnv = any> {
+  entry: RouteEntry<TEnv>;
+  routeKey: string;
+  params: Record<string, string>;
+  optionalParams: Set<string>;
+  redirectTo?: string;
+  /** Ancestry shortCodes for layout pruning (from trie match) */
+  ancestry?: string[];
+  /** Route has pre-rendered data available (from trie) */
+  pr?: true;
+  /** Passthrough: handler kept for live fallback on unknown params (from trie) */
+  pt?: true;
+  /** Response type for non-RSC routes (json, text, image, any) */
+  responseType?: string;
+  /** Negotiate variants: response-type routes sharing this path */
+  negotiateVariants?: Array<{ routeKey: string; responseType: string }>;
+  /** RSC-first: RSC route was defined before response-type variants */
+  rscFirst?: true;
+}
+
+/**
+ * Result when a lazy entry needs evaluation before matching
+ */
+export interface LazyEvaluationNeeded<TEnv = any> {
+  lazyEntry: RouteEntry<TEnv>;
+}
+
+/**
+ * Type guard to check if result is a lazy evaluation needed response
+ */
+export function isLazyEvaluationNeeded<TEnv>(
+  result: RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null
+): result is LazyEvaluationNeeded<TEnv> {
+  return result !== null && "lazyEntry" in result;
+}
+
+// Debug stats type for exports
+interface MatchDebugStats {
+  entriesChecked: number;
+  entriesSkipped: number;
+  routesChecked: number;
+}
+
+// Debug stats for route matching (only in debug mode)
+let debugEnabled = false;
+let debugStats = { entriesChecked: 0, entriesSkipped: 0, routesChecked: 0 };
+
+export function enableMatchDebug(enabled: boolean): void {
+  debugEnabled = enabled;
+}
+
+export function getMatchDebugStats(): MatchDebugStats {
+  return { entriesChecked: debugStats.entriesChecked, entriesSkipped: debugStats.entriesSkipped, routesChecked: debugStats.routesChecked };
+}
+
+export function findMatch<TEnv>(
+  pathname: string,
+  routesEntries: RouteEntry<TEnv>[]
+): RouteMatchResult<TEnv> | LazyEvaluationNeeded<TEnv> | null {
+  if (debugEnabled) {
+    debugStats = { entriesChecked: 0, entriesSkipped: 0, routesChecked: 0 };
+    console.log(`[findMatch] pathname="${pathname}", entries=${routesEntries.length}`);
+    for (const e of routesEntries) {
+      console.log(`  entry: prefix="${e.prefix}", staticPrefix="${e.staticPrefix}", routes=${Object.keys(e.routes).length}`);
+    }
+  }
+
+  const pathnameHasTrailingSlash = pathname.length > 1 && pathname.endsWith("/");
+  // Try alternate pathname for redirect matching
+  const alternatePathname = pathnameHasTrailingSlash
+    ? pathname.slice(0, -1)
+    : pathname + "/";
+
+  for (const entry of routesEntries) {
+    // Short-circuit: skip entry if pathname doesn't start with static prefix
+    // staticPrefix is pre-computed at registration time, so this is O(1)
+    if (entry.staticPrefix && !pathname.startsWith(entry.staticPrefix)) {
+      if (debugEnabled) {
+        debugStats.entriesSkipped++;
+        console.log(`  SKIP entry prefix="${entry.prefix}" (staticPrefix="${entry.staticPrefix}" doesn't match)`);
+      }
+      continue;
+    }
+
+    // Check if this is a lazy entry that needs evaluation
+    // When staticPrefix matches but routes are not yet populated, signal caller to evaluate
+    if (entry.lazy && !entry.lazyEvaluated) {
+      if (debugEnabled) {
+        console.log(`  LAZY entry needs evaluation: staticPrefix="${entry.staticPrefix}"`);
+      }
+      return { lazyEntry: entry };
+    }
+
+    if (debugEnabled) {
+      debugStats.entriesChecked++;
+    }
+
+    const routeEntries = Object.entries(entry.routes);
+
+    for (const [routeKey, pattern] of routeEntries) {
+      if (debugEnabled) {
+        debugStats.routesChecked++;
+      }
+
+      // Join prefix and pattern, handling edge cases
+      let fullPattern: string;
+      if (entry.prefix === "" || entry.prefix === "/") {
+        fullPattern = pattern;
+      } else if (pattern === "/" || pattern === "") {
+        fullPattern = entry.prefix;
+      } else {
+        fullPattern = entry.prefix + pattern;
+      }
+
+      const { regex, paramNames, optionalParams, hasTrailingSlash } = compilePattern(fullPattern);
+
+      // Get trailing slash mode for this route (per-route config or pattern-based)
+      const trailingSlashMode: TrailingSlashMode | undefined = entry.trailingSlash?.[routeKey];
+
+
+      // Try exact match first
+      const match = regex.exec(pathname);
+      if (match) {
+        const params: Record<string, string> = {};
+        paramNames.forEach((name, index) => {
+          params[name] = match[index + 1] ?? "";
+        });
+
+        if (debugEnabled) {
+          console.log(`  MATCH: routeKey="${routeKey}", pattern="${fullPattern}"`);
+          console.log(`  Stats: entriesChecked=${debugStats.entriesChecked}, entriesSkipped=${debugStats.entriesSkipped}, routesChecked=${debugStats.routesChecked}`);
+        }
+
+        // Check if trailing slash mode requires redirect even on exact match
+        if (trailingSlashMode === "always" && !pathnameHasTrailingSlash && pathname !== "/") {
+          // Mode says always have trailing slash, but pathname doesn't have it
+          return { entry, routeKey, params, optionalParams, redirectTo: pathname + "/" };
+        } else if (trailingSlashMode === "never" && pathnameHasTrailingSlash) {
+          // Mode says never have trailing slash, but pathname has it
+          return { entry, routeKey, params, optionalParams, redirectTo: pathname.slice(0, -1) };
+        }
+
+        return { entry, routeKey, params, optionalParams };
+      }
+
+      // Try alternate pathname (opposite trailing slash)
+      const altMatch = regex.exec(alternatePathname);
+      if (altMatch) {
+        const params: Record<string, string> = {};
+        paramNames.forEach((name, index) => {
+          params[name] = altMatch[index + 1] ?? "";
+        });
+
+        // Determine redirect behavior based on mode
+        if (trailingSlashMode === "ignore") {
+          // Match without redirect
+          return { entry, routeKey, params, optionalParams };
+        } else if (trailingSlashMode === "never") {
+          // Redirect to no trailing slash
+          if (pathnameHasTrailingSlash) {
+            return { entry, routeKey, params, optionalParams, redirectTo: alternatePathname };
+          }
+          return { entry, routeKey, params, optionalParams };
+        } else if (trailingSlashMode === "always") {
+          // Redirect to with trailing slash
+          if (!pathnameHasTrailingSlash) {
+            return { entry, routeKey, params, optionalParams, redirectTo: alternatePathname };
+          }
+          return { entry, routeKey, params, optionalParams };
+        } else {
+          // No explicit mode - use pattern-based detection
+          // Redirect to canonical form (what the pattern defines)
+          const canonicalPath = hasTrailingSlash ? alternatePathname : pathname.slice(0, -1);
+          return { entry, routeKey, params, optionalParams, redirectTo: canonicalPath };
+        }
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Traverse from entry to bottom to top, yielding each EntryData
+ * e.g. {child -> parent -> grandparent ...}
+ */
+export function* traverseBack(entry: EntryData): Generator<EntryData> {
+  let current: EntryData | null = entry;
+  const items = [] as EntryData[];
+  while (current !== null) {
+    items.push(current); // Move up to next parent
+    current = current.parent;
+  }
+  for (let i = items.length - 1; i >= 0; i--) {
+    yield items[i];
+  }
+}

package/src/router/revalidation.ts

@@ -0,0 +1,190 @@
+/**
+ * Router Revalidation Logic
+ *
+ * Evaluates whether segments should revalidate based on params, actions, and custom functions.
+ */
+
+import type { ResolvedSegment, HandlerContext } from "../types";
+import type { ActionContext } from "./types";
+
+/**
+ * Options for revalidation evaluation
+ */
+interface EvaluateRevalidationOptions<TEnv> {
+  /** Current segment to evaluate */
+  segment: ResolvedSegment;
+  /** Previous route params (from route match, not segment) */
+  prevParams: Record<string, string>;
+  /** Lazy function to get previous segment if needed */
+  getPrevSegment: (() => Promise<ResolvedSegment | undefined>) | null;
+  /** Current request */
+  request: Request;
+  /** Previous URL */
+  prevUrl: URL;
+  /** Next URL */
+  nextUrl: URL;
+  /** Custom revalidation functions */
+  revalidations: Array<{ name: string; fn: any }>;
+  /** Current route key */
+  routeKey: string;
+  /** Handler context */
+  context: HandlerContext<any, TEnv>;
+  /** Action context if triggered by action */
+  actionContext?: ActionContext;
+  /** If true, this is a stale cache revalidation request */
+  stale?: boolean;
+}
+
+/**
+ * Evaluate if a segment should revalidate using soft/hard decision pattern
+ * Optimized to use prevParams directly and avoid building previous segments
+ */
+export async function evaluateRevalidation<TEnv>(
+  options: EvaluateRevalidationOptions<TEnv>
+): Promise<boolean> {
+  const {
+    segment,
+    prevParams,
+    getPrevSegment,
+    request,
+    prevUrl,
+    nextUrl,
+    revalidations,
+    routeKey,
+    context,
+    actionContext,
+    stale,
+  } = options;
+  const nextParams = segment.params || {};
+  const paramsChanged =
+    Object.keys(nextParams).length !== Object.keys(prevParams).length ||
+    Object.keys(nextParams).some(
+      (key) => nextParams[key] !== prevParams[key]
+    );
+
+  // Calculate default revalidation based on segment type and request method
+  let defaultShouldRevalidate: boolean;
+
+  if (request.method === "POST") {
+    // Actions: revalidate segments that belong to the route, skip parent chain
+    if (segment.type === "route") {
+      // Route segment always revalidates on actions
+      defaultShouldRevalidate = true;
+    } else if (segment.type === "loader") {
+      // Loaders always revalidate on actions - they often contain action-sensitive data
+      // (e.g., cart count after add-to-cart action)
+      defaultShouldRevalidate = true;
+    } else if (segment.belongsToRoute) {
+      // Segment belongs to route (orphan layouts/parallels) - revalidate
+      defaultShouldRevalidate = true;
+    } else {
+      // Parent chain segment (shared layouts/parallels) - don't revalidate
+      defaultShouldRevalidate = false;
+    }
+  } else {
+    // Navigation (GET): Conservative defaults to minimize unnecessary revalidations
+    // Only the route segment revalidates by default - all others require explicit opt-in
+
+    if (segment.type === "route") {
+      // Route segments revalidate when params change
+      // Routes are the primary param-dependent content and always need updates
+      defaultShouldRevalidate = paramsChanged;
+      if (paramsChanged) {
+        console.log(
+          `[Router.evaluateRevalidation] ${segment.id}: ROUTE - params changed, revalidating`
+        );
+      }
+    } else {
+      // Layouts and parallels default to no revalidation
+      // Cannot assume these segments depend on params without explicit declaration
+      // Use custom revalidation functions to opt-in when needed
+      defaultShouldRevalidate = false;
+      console.log(
+        `[Router.evaluateRevalidation] ${
+          segment.id
+        }: ${segment.type.toUpperCase()} segment - skipping (override with custom revalidation if needed)`
+      );
+    }
+  }
+
+  // No custom revalidations defined - return default behavior without prev segment
+  if (revalidations.length === 0) {
+    if (defaultShouldRevalidate) {
+      console.log(
+        `[Router.evaluateRevalidation] ${segment.id}: PARAMS CHANGED (default) - revalidating`,
+        { prev: prevParams, next: nextParams }
+      );
+    } else {
+      console.log(
+        `[Router.evaluateRevalidation] ${segment.id}: UNCHANGED (default) - skipping`
+      );
+    }
+    return defaultShouldRevalidate;
+  }
+
+  // Custom revalidations exist - may need full prev segment
+  // Lazy load prev segment only if getPrevSegment provided
+  const prevSegment = getPrevSegment ? await getPrevSegment() : null;
+
+  // Execute revalidation functions with soft/hard decision pattern
+  let currentSuggestion = defaultShouldRevalidate;
+
+  for (const { name, fn } of revalidations) {
+    const result = fn({
+      currentParams: prevSegment?.params || prevParams, // Use segment params if available, else route params
+      currentUrl: prevUrl,
+      nextParams,
+      nextUrl,
+      defaultShouldRevalidate: currentSuggestion,
+      context,
+      // Segment metadata (which segment is being evaluated)
+      segmentType: segment.type,
+      layoutName: segment.layoutName,
+      slotName: segment.slot,
+      // Action context (only populated when triggered by server action)
+      actionId: actionContext?.actionId,
+      actionUrl: actionContext?.actionUrl,
+      actionResult: actionContext?.actionResult,
+      formData: actionContext?.formData,
+      method: request.method, // GET for navigation, POST for actions
+      routeName: routeKey, // User-friendly route name (e.g., "products.detail")
+      // Stale cache context (only true for background revalidation after stale cache render)
+      stale,
+    });
+
+    // Check return type:
+    // - boolean: hard decision, short-circuit immediately
+    // - { defaultShouldRevalidate: boolean }: soft decision, update suggestion and continue
+    // - null/undefined: use default behavior (equivalent to returning { defaultShouldRevalidate })
+    if (typeof result === "boolean") {
+      // Hard decision - short-circuit
+      console.log(
+        `[Router.evaluateRevalidation] ${segment.id}: REVALIDATE (${name}) HARD: ${result}`
+      );
+      return result;
+    } else if (
+      result &&
+      typeof result === "object" &&
+      "defaultShouldRevalidate" in result
+    ) {
+      // Soft decision - update suggestion and continue
+      currentSuggestion = result.defaultShouldRevalidate;
+      console.log(
+        `[Router.evaluateRevalidation] ${segment.id}: REVALIDATE (${name}) SOFT: ${currentSuggestion}`
+      );
+    } else if (result === null || result === undefined) {
+      // Defer to default - equivalent to { defaultShouldRevalidate: currentSuggestion }
+      // This means "I don't care, use whatever the default is"
+      console.log(
+        `[Router.evaluateRevalidation] ${segment.id}: REVALIDATE (${name}) DEFER to default: ${currentSuggestion}`
+      );
+      // currentSuggestion stays the same, continue to next function
+    }
+  }
+
+  // All revalidators completed - use final suggestion
+  console.log(
+    `[Router.evaluateRevalidation] ${segment.id}: Final decision: ${currentSuggestion}`
+  );
+  return currentSuggestion;
+}