release: WRNexusJS 0.3.0

packages/router/src/match.ts

@@ -1,10 +1,20 @@
 /**
  * Route compilation + matching.
  *
- * A "route" is a URL pattern compiled to a RegExp. We support static segments
- * and dynamic `[param]` segments, e.g. `/users/[id]` -> `{ id }`.
+ * Supported segments:
+ *   [id]          required parameter
+ *   [id?]         optional parameter
+ *   [[id]]        optional parameter (directory-friendly form)
+ *   [...slug]     required catch-all
+ *   [[...slug]]   optional catch-all
  */
 
+export interface RouteParam {
+  name: string;
+  optional: boolean;
+  catchAll: boolean;
+}
+
 export interface Route {
   /** The human-readable route pattern, e.g. `/users/[id]`. */
   raw: string;
@@ -14,6 +24,8 @@ export interface Route {
   regex: RegExp;
   /** Ordered names of dynamic params captured by `regex`. */
   paramNames: string[];
+  /** Rich parameter metadata. Optional for compatibility with old manifests. */
+  paramMeta?: RouteParam[];
 }
 
 export interface RouteMatch {
@@ -23,52 +35,138 @@ export interface RouteMatch {
 
 const ESCAPE_RE = /[.*+?^${}()|[\]\\]/g;
 
-/** Compile a `/users/[id]` style pattern into a RegExp + param names. */
-export function compileRoutePattern(raw: string): Pick<Route, "regex" | "paramNames"> {
-  if (raw === "/") {
-    return { regex: /^\/$/, paramNames: [] };
+function parseParamSegment(segment: string): RouteParam | null {
+  let inner: string | null = null;
+  let optional = false;
+
+  if (segment.startsWith("[[") && segment.endsWith("]]")) {
+    inner = segment.slice(2, -2);
+    optional = true;
+  } else if (segment.startsWith("[") && segment.endsWith("]")) {
+    inner = segment.slice(1, -1);
+    if (inner.endsWith("?")) {
+      optional = true;
+      inner = inner.slice(0, -1);
+    }
   }
 
-  const paramNames: string[] = [];
-  const parts = raw
+  if (inner === null) return null;
+  const catchAll = inner.startsWith("...");
+  const name = catchAll ? inner.slice(3) : inner;
+  if (!/^[A-Za-z_$][\w$-]*$/.test(name)) {
+    throw new Error(`WRN-ROUTE-PARAM: Invalid route parameter '${segment}'.`);
+  }
+  return { name, optional, catchAll };
+}
+
+/** Return parameter metadata without requiring callers to inspect the regex. */
+export function getRouteParams(raw: string): RouteParam[] {
+  return raw
     .split("/")
     .filter(Boolean)
-    .map((segment) => {
-      const dynamic = segment.match(/^\[(.+)\]$/);
-      if (dynamic) {
-        paramNames.push(dynamic[1]!);
-        return "([^/]+)";
-      }
-      return segment.replace(ESCAPE_RE, "\\$&");
-    });
+    .map(parseParamSegment)
+    .filter((value): value is RouteParam => value !== null);
+}
 
-  // Allow an optional trailing slash.
-  const regex = new RegExp("^/" + parts.join("/") + "/?$");
-  return { regex, paramNames };
+/** Compile a WRNexus route pattern into a RegExp + parameter metadata. */
+export function compileRoutePattern(
+  raw: string,
+): Pick<Route, "regex" | "paramNames" | "paramMeta"> {
+  if (raw === "/") {
+    return { regex: /^\/$/, paramNames: [], paramMeta: [] };
+  }
+
+  const paramMeta: RouteParam[] = [];
+  let source = "^";
+  const segments = raw.split("/").filter(Boolean);
+
+  for (const segment of segments) {
+    const param = parseParamSegment(segment);
+    if (!param) {
+      source += `/${segment.replace(ESCAPE_RE, "\\$&")}`;
+      continue;
+    }
+
+    if (paramMeta.some((existing) => existing.name === param.name)) {
+      throw new Error(
+        `WRN-ROUTE-DUPLICATE-PARAM: Parameter '${param.name}' appears more than once in '${raw}'.`,
+      );
+    }
+    paramMeta.push(param);
+
+    const capture = param.catchAll ? "(.+?)" : "([^/]+)";
+    source += param.optional ? `(?:/${capture})?` : `/${capture}`;
+  }
+
+  source += "/?$";
+  return {
+    regex: new RegExp(source),
+    paramNames: paramMeta.map((param) => param.name),
+    paramMeta,
+  };
+}
+
+function routeSpecificity(route: Route): number[] {
+  const segments = route.raw.split("/").filter(Boolean);
+  let staticCount = 0;
+  let requiredCount = 0;
+  let optionalCount = 0;
+  let catchAllCount = 0;
+  for (const segment of segments) {
+    const param = parseParamSegment(segment);
+    if (!param) staticCount++;
+    else if (param.catchAll) catchAllCount++;
+    else if (param.optional) optionalCount++;
+    else requiredCount++;
+  }
+  return [
+    staticCount,
+    requiredCount,
+    -optionalCount,
+    -catchAllCount,
+    segments.length,
+    route.raw.length,
+  ];
 }
 
 /**
- * Order routes so that static routes win over dynamic ones, and longer/more
- * specific routes win over shorter ones. Sorting once keeps matching simple.
+ * Order routes so static and constrained routes win over optional/catch-all
+ * routes. The ordering remains deterministic for identical specificity.
  */
 export function sortRoutes(routes: Route[]): Route[] {
   return [...routes].sort((a, b) => {
-    if (a.paramNames.length !== b.paramNames.length) {
-      return a.paramNames.length - b.paramNames.length; // fewer params first
+    const as = routeSpecificity(a);
+    const bs = routeSpecificity(b);
+    for (let i = 0; i < as.length; i++) {
+      if (as[i] !== bs[i]) return bs[i]! - as[i]!;
     }
-    return b.raw.length - a.raw.length; // longer/more specific first
+    return a.raw.localeCompare(b.raw) || a.file.localeCompare(b.file);
   });
 }
 
+/** Find duplicate URL patterns before request handling starts. */
+export function findRouteConflicts(routes: Route[]): Array<{ raw: string; files: string[] }> {
+  const grouped = new Map<string, string[]>();
+  for (const route of routes) {
+    const files = grouped.get(route.raw) ?? [];
+    files.push(route.file);
+    grouped.set(route.raw, files);
+  }
+  return [...grouped]
+    .filter(([, files]) => files.length > 1)
+    .map(([raw, files]) => ({ raw, files }));
+}
+
 /** Find the first route whose pattern matches `pathname`. */
 export function matchRoute(routes: Route[], pathname: string): RouteMatch | null {
   for (const route of routes) {
-    const m = route.regex.exec(pathname);
-    if (!m) continue;
+    const match = route.regex.exec(pathname);
+    if (!match) continue;
     const params: Record<string, string> = {};
     try {
-      route.paramNames.forEach((name, i) => {
-        params[name] = decodeURIComponent(m[i + 1]!);
+      route.paramNames.forEach((name, index) => {
+        const value = match[index + 1];
+        if (value !== undefined) params[name] = decodeURIComponent(value);
       });
     } catch {
       // A malformed percent-encoded path is not a valid route match. Treat it