@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/router/navigation-snapshot.ts

@@ -1,82 +1,41 @@
-/**
- * Navigation Snapshot
- *
- * Pure data type representing the navigation-specific state for partial requests.
- * Consolidates the header parsing, previous-route matching, intercept-context
- * detection, and segment ID filtering that previously lived inline in
- * createMatchContextForPartial (match-api.ts).
- *
- * resolveNavigation() is the factory: given a request + URL + current route key,
- * it returns a NavigationSnapshot (or null if no previous URL).
- */
-
 import type { RouteMatchResult } from "./pattern-matching.js";
 
-/**
- * Snapshot of navigation state for a partial (navigation/action) request.
- *
- * Contains the "where are we coming from?" data: previous route, intercept
- * source, client segment state, and derived flags.
- */
 export interface NavigationSnapshot {
-  /** Previous page URL (from X-RSC-Router-Client-Path or Referer) */
   prevUrl: URL;
-  /** Params from the previous route match */
   prevParams: Record<string, string>;
-  /** Previous route match result (null if prev URL doesn't match any route) */
   prevMatch: RouteMatchResult | null;
 
-  /** URL used as intercept context source */
   interceptContextUrl: URL;
-  /** Route match for the intercept context URL */
   interceptContextMatch: RouteMatchResult | null;
 
-  /** Raw segment IDs the client currently has */
   clientSegmentIds: string[];
-  /** Set version for O(1) lookup */
   clientSegmentSet: Set<string>;
-  /** Segment IDs filtered to remove parallel (.@) and loader (D\d+.) entries */
   filteredSegmentIds: string[];
 
-  /** Whether client considers its cache stale */
   stale: boolean;
 
-  /** Whether the intercept context route is the same as the current route */
   isSameRouteNavigation: boolean;
 
-  /** Effective "from" URL (intercept source URL when present, else prevUrl) */
   effectiveFromUrl: URL;
-  /** Effective "from" match (intercept source match when present, else prevMatch) */
   effectiveFromMatch: RouteMatchResult | null;
 
-  /** Whether an intercept source header was present */
   hasInterceptSource: boolean;
 
-  /** Whether an HMR request header was present */
   isHmr: boolean;
 }
 
 export interface ResolveNavigationDeps {
-  findMatch: (pathname: string) => RouteMatchResult | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult | null | Promise<RouteMatchResult | null>;
 }
 
-/**
- * Resolve navigation state from a partial request.
- *
- * Returns null if no previous URL is available (required for partial navigation).
- *
- * @param request - The incoming HTTP request
- * @param url - Parsed URL of the request
- * @param currentRouteKey - Route key of the current (target) route match
- * @param deps - Dependencies (findMatch)
- */
-export function resolveNavigation(
+export async function resolveNavigation(
   request: Request,
   url: URL,
   currentRouteKey: string,
   deps: ResolveNavigationDeps,
-): NavigationSnapshot | null {
-  // Parse client state from RSC request params/headers
+): Promise<NavigationSnapshot | null> {
   const clientSegmentIds =
     url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
   const stale = url.searchParams.get("_rsc_stale") === "true";
@@ -92,7 +51,6 @@ export function resolveNavigation(
     return null;
   }
 
-  // Parse previous URL
   let prevUrl: URL;
   try {
     prevUrl = new URL(previousUrl, url.origin);
@@ -100,7 +58,6 @@ export function resolveNavigation(
     return null;
   }
 
-  // Parse intercept context URL
   let interceptContextUrl: URL;
   try {
     interceptContextUrl = interceptSourceUrl
@@ -110,14 +67,12 @@ export function resolveNavigation(
     interceptContextUrl = prevUrl;
   }
 
-  // Match previous and intercept context routes
-  const prevMatch = deps.findMatch(prevUrl.pathname);
+  const prevMatch = await deps.findMatch(prevUrl.pathname);
   const prevParams = prevMatch?.params || {};
   const interceptContextMatch = interceptSourceUrl
-    ? deps.findMatch(interceptContextUrl.pathname)
+    ? await deps.findMatch(interceptContextUrl.pathname)
     : prevMatch;
 
-  // Derived state
   const isSameRouteNavigation = !!(
     interceptContextMatch && interceptContextMatch.routeKey === currentRouteKey
   );
@@ -128,7 +83,6 @@ export function resolveNavigation(
     ? interceptContextMatch
     : prevMatch;
 
-  // Filter segment IDs: remove parallel (.@) and loader (D\d+.) entries
   const filteredSegmentIds = clientSegmentIds.filter((id) => {
     if (id.includes(".@")) return false;
     if (/D\d+\./.test(id)) return false;
@@ -155,9 +109,6 @@ export function resolveNavigation(
   };
 }
 
-/**
- * Test helper: create a NavigationSnapshot with sensible defaults and overrides.
- */
 export function createNavigationSnapshot(
   overrides?: Partial<NavigationSnapshot>,
 ): NavigationSnapshot {

package/src/router/params-util.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared route-param comparison helpers.
+ */
+
+/**
+ * Shallow equality for two route-param records. Same-reference is a fast path;
+ * otherwise compares key count then each value.
+ */
+export function paramsEqual(
+  a: Record<string, string>,
+  b: Record<string, string>,
+): boolean {
+  if (a === b) return true;
+
+  const keysA = Object.keys(a);
+  if (keysA.length !== Object.keys(b).length) return false;
+
+  for (const key of keysA) {
+    if (a[key] !== b[key]) return false;
+  }
+
+  return true;
+}

package/src/router/parse-pattern.ts

@@ -0,0 +1,115 @@
+/**
+ * Route pattern parsing (grammar only).
+ *
+ * Deliberately dependency-free so it is safe to bundle into the CLIENT — the
+ * reverse helper (`substitute-pattern-params.ts` -> `use-reverse`) needs it, and
+ * pulling it from `pattern-matching.ts` would drag that module's server-only
+ * transitive imports (`node:async_hooks` via `logging.ts`) into the browser.
+ * `pattern-matching.ts` re-exports these so existing importers are unaffected.
+ */
+
+/**
+ * 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"]
+  suffix?: string; // literal text after param in same segment (e.g., ".html")
+  /**
+   * Named catch-all repeat modifier. On a `wildcard` segment whose `value` is a
+   * param name (`:name+` / `:name*`), `true` marks one-or-more (`+`, rejects the
+   * zero-segment case); absent/false marks zero-or-more (`*`, and the bare `/*`).
+   */
+  oneOrMore?: boolean;
+}
+
+/**
+ * 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: /*
+ * - Named catch-all: /:slug* (zero-or-more), /:path+ (one-or-more)
+ */
+export function parsePattern(pattern: string): ParsedSegment[] {
+  const segments: ParsedSegment[] = [];
+  // The `([+*])?` group peels a trailing `+`/`*` off a `:name` BEFORE the
+  // literal-suffix group `([^/]*)` so it can be inspected. Whether it is a
+  // catch-all MODIFIER or a literal suffix character is decided below — a bare
+  // trailing `+`/`*` is the named catch-all of issue #634; any other combination
+  // is folded back into the literal suffix so previously-valid patterns are
+  // unaffected. It sits after `(\?)?` so `:name?*` is seen as `?` + suffix `*`.
+  const segmentRegex =
+    /\/(:([a-zA-Z_][a-zA-Z0-9_]*)(\(([^)]+)\))?(\?)?([+*])?([^/]*)|(\*)|([^/]+))/g;
+
+  let match;
+  while ((match = segmentRegex.exec(pattern)) !== null) {
+    const [
+      ,
+      ,
+      paramName,
+      ,
+      constraint,
+      optional,
+      repeat,
+      suffix,
+      wildcard,
+      staticText,
+    ] = match;
+
+    if (wildcard) {
+      // Bare `/*`: zero-or-more, captured under "*".
+      segments.push({ type: "wildcard", value: "*", optional: false });
+    } else if (paramName) {
+      // A trailing `+`/`*` is a named catch-all ONLY when it stands alone on the
+      // param — no `?`, no constraint, no literal suffix after it. In any other
+      // combination it is the start of a literal suffix, exactly as before this
+      // feature existed, so `:version+build` still matches `/…/v1+build` and
+      // never throws at registration.
+      if (repeat && !suffix && optional !== "?" && !constraint) {
+        segments.push({
+          type: "wildcard",
+          value: paramName,
+          optional: false,
+          oneOrMore: repeat === "+",
+        });
+      } else {
+        segments.push({
+          type: "param",
+          value: paramName,
+          optional: optional === "?",
+          constraint: constraint ? constraint.split("|") : undefined,
+          // Fold a non-modifier `+`/`*` back into the literal suffix.
+          suffix: (repeat ?? "") + (suffix ?? "") || undefined,
+        });
+      }
+    } else if (staticText) {
+      segments.push({ type: "static", value: staticText, optional: false });
+    }
+  }
+
+  // A named catch-all consumes the remainder, so it only makes sense as the final
+  // segment. If it isn't last, it isn't really a catch-all: restore the literal
+  // parse (`:name` + literal `+`/`*` suffix) rather than error, so a pattern like
+  // `/docs/:slug+/edit` keeps its pre-feature behavior (matches `/docs/x+/edit`).
+  // Bare `/*` keeps its historical mid-pattern leniency and is left untouched.
+  for (let i = 0; i < segments.length - 1; i++) {
+    const s = segments[i];
+    if (s.type === "wildcard" && s.value !== "*") {
+      segments[i] = {
+        type: "param",
+        value: s.value,
+        optional: false,
+        suffix: s.oneOrMore ? "+" : "*",
+      };
+    }
+  }
+
+  return segments;
+}