feat!: url pattern compatibility (#178)

Author: pi0

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
       - run: corepack enable
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: lts/*
           cache: pnpm
       - run: pnpm install
       - run: pnpm lint

.prettierignore

@@ -0,0 +1 @@
+test/wpt

AGENTS.md

@@ -13,14 +13,17 @@ src/
   types.ts            # TypeScript interfaces & param inference types
   context.ts          # createRouter() factory
   object.ts           # NullProtoObj (null-prototype object constructor)
+  _escape.ts          # URLPattern backslash escape handling (placeholder approach)
+  _group-delimiters.ts# Non-capturing group ({...}) expansion helper
+  _segment-wildcards.ts# Wildcard segment capture handling
   regexp.ts           # routeToRegExp() utility
   compiler.ts         # JIT/AOT compiler (generates optimized match functions)
   operations/
     add.ts            # addRoute() - insert routes into the radix tree
     find.ts           # findRoute() - single-match lookup
     find-all.ts       # findAllRoutes() - multi-match lookup
     remove.ts         # removeRoute() - remove routes from tree
-    _utils.ts         # Shared internal utilities
+    _utils.ts         # Shared utilities (escaping, path splitting, normalization)
 test/
   router.test.ts      # Core router tests
   find.test.ts        # Route matching tests (interpreter vs compiled)
@@ -80,6 +83,33 @@ interface Node<T> {
 - Inlines regex patterns for param validation
 - Compare interpreter vs compiled output in tests
 
+### URLPattern group delimiters
+
+- `src/_group-delimiters.ts` expands non-capturing group delimiters before route insertion/removal/regexp generation.
+- Supported forms: `{...}` and `{...}?` (plus single-segment `{...}+` / `{...}*` converted to `(?:...)+/*` regex fragments).
+- Limitation: `{...}+` / `{...}*` are rejected when group body contains `/` (cross-segment repetition unsupported in radix tree).
+
+### URLPattern backslash escaping
+
+Two separate escape systems handle `\x` in route patterns:
+
+1. **Router escape encoding** (`_utils.ts`): `encodeEscapes()` converts `\:`, `\(`, `\)`, `\{`, `\}` to `\uFFFD` + single-char placeholders (A-E) before segment splitting, preventing these chars from being interpreted as route syntax. `decodeEscaped()` converts them back for static node keys. Other `\x` (like `\*`) are left for existing `segment === "\\*"` handling.
+
+2. **Regex escape handling** (`_escape.ts`): `replaceEscapesOutsideGroups()` replaces `\x` outside `(...)` groups with `\uFFFE` placeholder, preserving regex syntax inside groups (e.g., `\d` in `(\d+)`). `resolveEscapePlaceholders()` then converts placeholders to regex-safe literals. Used by `routeToRegExp()` and `getParamRegexp()` in `add.ts`.
+
+Key invariant: `\uFFFD` (U+FFFD) is used for router-level escaping, `\uFFFE` (U+FFFE) for regex-level escaping — they must not collide.
+
+### Input path normalization
+
+`normalizePath()` in `_utils.ts` resolves `.` and `..` segments in lookup paths (fast-path: skip if no `/.` found). Both `findRoute()` and `findAllRoutes()` normalize before matching. The compiler inlines equivalent logic in generated code.
+
+### Wildcard segment captures
+
+- **Breaking change:** unnamed captures now use URLPattern-style numeric keys (`"0"`, `"1"`, ...) instead of legacy `_0`, `_1`, ...
+- Unescaped `*` inside a segment is treated as an unnamed capture (`"0"`, `"1"`, ...), including mid-pattern forms like `/*.png` and `/file-*-*.png`.
+- Wildcard capture indexing is shared with unnamed regex groups in the same route.
+- `removeRoute()` now treats wildcard-segment patterns as dynamic segments (same classification as add/find/regexp).
+
 ## Build & Scripts
 
 - **Builder:** `obuild` (config in `build.config.mjs`)
@@ -105,6 +135,7 @@ pnpm bench:deno        # Benchmarks (deno)
 - **Snapshots:** Tree structure and compiled code snapshots
 - **Type tests:** `vitest typecheck` via `types.test-d.ts`
 - Run a single test: `pnpm vitest run test/<file>.test.ts`
+- **WPT compat tests:** `test/wpt.test.ts` validates URLPattern compatibility using Web Platform Test data. Known diffs are tracked in `KNOWN_DIFFS`, `REGEXP_ONLY_KNOWN_DIFFS`, and `ROUTER_KNOWN_DIFFS` sets with reason comments.
 
 ## Code Conventions
 

README.md

@@ -94,6 +94,72 @@ findRoute(router, "GET", "/");
 > [!TIP]
 > If you need to register a pattern containing literal `:` or `*`, you can escape them with `\\`. For example, `/static\\:path/\\*\\*` matches only the static `/static:path/**` route.
 
+## Route Patterns
+
+rou3 supports [URLPattern](https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API)-compatible syntax.
+
+| Pattern | Example Match | Params |
+| --- | --- | --- |
+| `/path/to/resource` | `/path/to/resource` | `{}` |
+| `/users/:name` | `/users/foo` | `{ name: "foo" }` |
+| `/path/**` | `/path/foo/bar` | `{}` |
+| `/path/**:rest` | `/path/foo/bar` | `{ rest: "foo/bar" }` |
+| `/files/*.png` | `/files/icon.png` | `{ "0": "icon" }` |
+| `/files/file-*-*.png` | `/files/file-a-b.png` | `{ "0": "a", "1": "b" }` |
+| `/users/:id(\\d+)` | `/users/123` | `{ id: "123" }` |
+| `/files/:ext(png\|jpg)` | `/files/png` | `{ ext: "png" }` |
+| `/path/(\\d+)` | `/path/123` | `{ "0": "123" }` |
+| `/users/:id?` | `/users` or `/users/123` | `{}` or `{ id: "123" }` |
+| `/files/:path+` | `/files/a/b/c` | `{ path: "a/b/c" }` |
+| `/files/:path*` | `/files` or `/files/a/b` | `{}` or `{ path: "a/b" }` |
+| `/book{s}?` | `/book` or `/books` | `{}` |
+| `/blog/:id(\\d+){-:title}?` | `/blog/123` or `/blog/123-my-post` | `{ id: "123" }` or `{ id: "123", title: "my-post" }` |
+
+- **Named params** (`:name`) match a single segment.
+- **Single-segment wildcards** (`*`) capture unnamed params (`0`, `1`, ...) and can be used as full or mid-segment tokens (for example `/*` or `/*.png`).
+- **Wildcards** (`**`) match zero or more segments. Use `**:name` to capture.
+- **Regex constraints** (`:name(regex)`) restrict matching. Constrained and unconstrained params can coexist on the same node (constrained checked first).
+- **Unnamed groups** (`(regex)`) capture into auto-indexed keys `0`, `1`, etc.
+- **Modifiers:** `:name?` (optional), `:name+` (one or more), `:name*` (zero or more). Can combine with regex: `:id(\d+)?`.
+- **Non-capturing groups** (`{...}`): supported with inline (`/foo{bar}`) and optional (`/foo{bar}?`) forms.
+- **Current limitation:** repeating non-capturing groups (`{...}+`, `{...}*`) are supported only within a single segment (no `/` inside the group body).
+- **Backslash escaping** (`\`): escape special characters like `:`, `*`, `(`, `)`, `{`, `}` with a backslash (e.g., `/static\:path` matches literal `/static:path`).
+
+### Differences from URLPattern
+
+rou3 aims for URLPattern-compatible syntax but has intentional differences due to its radix-tree design:
+
+| Feature | URLPattern | rou3 |
+| --- | --- | --- |
+| `*` (single star) | Greedy catch-all `(.*)` across `/` | Single-segment unnamed param `([^/]*)` |
+| `**` (double star) | Literal `**` | Catch-all wildcard (zero or more segments) |
+| `(.*)` in segment | Greedy match across `/` | Segment-scoped (does not cross `/`) |
+| `{...}+` / `{...}*` groups | Cross-segment group repetition | Only supported within a single segment (no `/` in group body) |
+| Path normalization (`.`/`..`) | Resolves `.`/`..` in input paths | Not done by default (opt-in with `{ normalize: true }`) |
+| Case sensitivity | Can be case-insensitive | Always case-sensitive |
+| Non-`/`-prefixed paths | Supported | Paths must start with `/` |
+| Unicode param names | Supports Unicode identifiers | Params use `\w` (ASCII word chars only) |
+| Percent-encoding | Normalizes `%xx` sequences | Does not decode percent-encoded input |
+
+### Path normalization
+
+By default, `findRoute` and `findAllRoutes` do **not** resolve `.`/`..` segments in input paths. If your input paths may contain relative segments, enable normalization:
+
+```js
+findRoute(router, "GET", "/foo/bar/../baz", { normalize: true });
+// Matches "/foo/baz"
+
+findAllRoutes(router, "GET", "/foo/./bar", { normalize: true });
+// Matches "/foo/bar"
+```
+
+The compiled router also supports this via the `normalize` option:
+
+```js
+const match = compileRouter(router, { normalize: true });
+match("GET", "/foo/bar/../baz"); // Matches "/foo/baz"
+```
+
 ## Compiler
 
 <!-- automd:jsdocs src="./src/compiler.ts" -->

src/_escape.ts

@@ -0,0 +1,27 @@
+const _P = "\uFFFE";
+
+export function replaceEscapesOutsideGroups(segment: string): string {
+  let r = "",
+    d = 0;
+  for (let i = 0; i < segment.length; i++) {
+    const c = segment.charCodeAt(i);
+    if (c === 40) d++;
+    else if (c === 41 && d > 0) d--;
+    else if (c === 92 && d === 0 && i + 1 < segment.length) {
+      const n = segment[i + 1];
+      if (n !== ":" && n !== "(" && n !== "*" && n !== "\\") {
+        r += _P + n;
+        i++;
+        continue;
+      }
+    }
+    r += segment[i];
+  }
+  return r;
+}
+
+export function resolveEscapePlaceholders(str: string): string {
+  return str.replace(/\uFFFE(.)/g, (_, c: string) =>
+    /[.*+?^${}()|[\]\\]/.test(c) ? `\\${c}` : c,
+  );
+}

src/_group-delimiters.ts

@@ -0,0 +1,73 @@
+export function expandGroupDelimiters(path: string): string[] | undefined {
+  let i = 0;
+  let depth = 0;
+
+  for (; i < path.length; i++) {
+    const c = path.charCodeAt(i);
+    if (c === 92 /* \\ */) {
+      i++;
+      continue;
+    }
+    if (c === 40 /* ( */) {
+      depth++;
+      continue;
+    }
+    if (c === 41 /* ) */ && depth > 0) {
+      depth--;
+      continue;
+    }
+    if (c === 123 /* { */ && depth === 0) {
+      break;
+    }
+  }
+
+  if (i >= path.length) {
+    return;
+  }
+
+  let j = i + 1;
+  depth = 0;
+
+  for (; j < path.length; j++) {
+    const c = path.charCodeAt(j);
+    if (c === 92 /* \\ */) {
+      j++;
+      continue;
+    }
+    if (c === 40 /* ( */) {
+      depth++;
+      continue;
+    }
+    if (c === 41 /* ) */ && depth > 0) {
+      depth--;
+      continue;
+    }
+    if (c === 125 /* } */ && depth === 0) {
+      break;
+    }
+  }
+
+  if (j >= path.length) {
+    return;
+  }
+
+  const mod = path[j + 1];
+  const hasMod = mod === "?" || mod === "+" || mod === "*";
+  const pre = path.slice(0, i);
+  const body = path.slice(i + 1, j);
+  const suf = path.slice(j + (hasMod ? 2 : 1));
+
+  if (!hasMod) {
+    return [pre + body + suf];
+  }
+
+  if (mod === "?") {
+    return [pre + body + suf, pre + suf];
+  }
+
+  if (body.includes("/")) {
+    throw new Error("unsupported group repetition across segments");
+  }
+
+  return [`${pre}(?:${body})${mod}${suf}`];
+}

src/_segment-wildcards.ts

@@ -0,0 +1,80 @@
+export const UNNAMED_GROUP_PREFIX = "__rou3_unnamed_";
+const _unnamedGroupPrefixLength = UNNAMED_GROUP_PREFIX.length;
+
+export function hasSegmentWildcard(segment: string): boolean {
+  let depth = 0;
+
+  for (let i = 0; i < segment.length; i++) {
+    const ch = segment.charCodeAt(i);
+    if (ch === 92 /* \\ */) {
+      i++;
+      continue;
+    }
+    if (ch === 40 /* ( */) {
+      depth++;
+      continue;
+    }
+    if (ch === 41 /* ) */ && depth > 0) {
+      depth--;
+      continue;
+    }
+    if (ch === 42 /* * */ && depth === 0) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function replaceSegmentWildcards(
+  segment: string,
+  unnamedStart: number,
+  toGroupKey: (index: number) => string = toUnnamedGroupKey,
+): [string, number] {
+  let depth = 0;
+  let nextIndex = unnamedStart;
+  let replaced = "";
+
+  for (let i = 0; i < segment.length; i++) {
+    const ch = segment.charCodeAt(i);
+
+    if (ch === 92 /* \\ */) {
+      replaced += segment[i];
+      if (i + 1 < segment.length) {
+        replaced += segment[++i];
+      }
+      continue;
+    }
+
+    if (ch === 40 /* ( */) {
+      depth++;
+      replaced += segment[i];
+      continue;
+    }
+
+    if (ch === 41 /* ) */ && depth > 0) {
+      depth--;
+      replaced += segment[i];
+      continue;
+    }
+
+    if (ch === 42 /* * */ && depth === 0) {
+      replaced += `(?<${toGroupKey(nextIndex++)}>[^/]*)`;
+      continue;
+    }
+
+    replaced += segment[i];
+  }
+
+  return [replaced, nextIndex];
+}
+
+export function toUnnamedGroupKey(index: number): string {
+  return `${UNNAMED_GROUP_PREFIX}${index}`;
+}
+
+export function normalizeUnnamedGroupKey(key: string): string {
+  return key.startsWith(UNNAMED_GROUP_PREFIX)
+    ? key.slice(_unnamedGroupPrefixLength)
+    : key;
+}

src/compiler.ts

@@ -1,7 +1,9 @@
+import { UNNAMED_GROUP_PREFIX } from "./_segment-wildcards.ts";
 import type { MatchedRoute, MethodData, Node, RouterContext } from "./types.ts";
 
 export interface RouterCompilerOptions<T = any> {
   matchAll?: boolean;
+  normalize?: boolean;
   serialize?: (data: T) => string;
 }
 
@@ -106,7 +108,15 @@ function compileRouteMatch(ctx: CompilerContext): string {
     return ctx.opts?.matchAll ? `return [];` : "";
   }
 
-  return `${ctx.opts?.matchAll ? `let r=[];` : ""}if(p.charCodeAt(p.length-1)===47)p=p.slice(0,-1)||"/";${code}${ctx.opts?.matchAll ? "return r;" : ""}`;
+  const normalizeHelper = code.includes("_normalizeGroups(")
+    ? `const _prefix=${JSON.stringify(UNNAMED_GROUP_PREFIX)},_prefixLen=${UNNAMED_GROUP_PREFIX.length};const _normalizeGroups=(g)=>{if(!g)return g;for(const k in g){if(k.startsWith(_prefix)){g[k.slice(_prefixLen)]=g[k];delete g[k]}}return g;};`
+    : "";
+
+  const normalizePathHelper = ctx.opts?.normalize
+    ? `if(p.includes("/.")){let _r=[];for(let _v of p.split("/")){if(_v===".")continue;_v===".."&&_r.length>1?_r.pop():_r.push(_v)}p=_r.join("/")||"/"}`
+    : "";
+
+  return `${ctx.opts?.matchAll ? `let r=[];` : ""}${normalizeHelper}${normalizePathHelper}if(p.charCodeAt(p.length-1)===47)p=p.slice(0,-1)||"/";${code}${ctx.opts?.matchAll ? "return r;" : ""}`;
 }
 
 function compileMethodMatch(
@@ -166,7 +176,7 @@ function compileFinalMatch(
       ret +=
         typeof map[1] === "string"
           ? `${JSON.stringify(map[1])}:${params[i]},`
-          : `...(${map[1].toString()}.exec(${params[i]}))?.groups,`;
+          : `..._normalizeGroups((${map[1].toString()}.exec(${params[i]}))?.groups),`;
     }
     ret += "}";
   }