Skip to content

Commit 92a2ee4

Browse files
committed
merge: main (#236, #238, #239) into fix/greedy-star
join slot moves to 5 (main uses 3/4 for `plain` / `inPlace`); fixtures, tests and docs follow the greedy `*`.
2 parents 37cc1e8 + cccc995 commit 92a2ee4

30 files changed

Lines changed: 1469 additions & 239 deletions

‎.agents/compiler.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Pinned in `test/compiler.test.ts` and `test/types.test-d.ts`.
2121
- **Wildcard tails** with an all-static prefix → `p.slice(K)`; else `s.slice(i).join('/')`. Valid because the prologue keeps every segment of `p`.
2222
- **Values:** a `:name` / `**:name` (also `:name+` / `:name*`) needs one (see [matching.md](matching.md#empty-segments-and-normalization)): `nonEmptyGuard()` adds `s[i]` (truthy: not `""`) per `:name`, and `(l>c+n+1||s[c])` per `**:name` (two segments or more, or one that is not empty; `n` segments after it). A `*` (`empty`) and a bare `**` get none. A `:name`'s guard is counted in `guardConditions`, not the weight, so the emit order doesn't change; a catch-all's counts, so a `**:name` outweighs a `*` on their node (see [matching.md](matching.md#same-node-siblings)).
2323
- **Bare `**` over zero segments** is unset (see [matching.md](matching.md#unnamed-captures)): `compileFinalMatch` emits `l>c?{…,params:{…,"N":_w=tail,_:_w}}:{…,params:{…}}` (`_` is the deprecated alias; `_w` is declared once with the regex temps when `ctx.starStarTemp`), with the `suffixGuard` (`l>c+j`) as the condition in a suffix trie. The only matchers whose result object is a ternary.
24-
- **Regex params:** `scanRegExpGroups()` resolves group names at compile time → direct `.groups.<name>` reads with one `exec` into a `_mN` temp (declared via `ctx.regexTemps`). A whole-segment `^(?<name>…)$` uses `.test()` + `params:{name:seg}`. An in-place optional param (source ending `))?$`, the last group name) is spread in only when set, `...(_m0.groups.x!==void 0&&{x:…})`, so an absent one has no key, as in the interpreter. Unparseable names fall back to exec + spread + runtime `_normalizeGroups`.
24+
- **Regex params:** `scanRegExpGroups()` resolves group names at compile time → direct `.groups.<name>` reads with one `exec` into a `_mN` temp (declared via `ctx.regexTemps`). A whole-segment `^(?<name>…)$` uses `.test()` + `params:{name:seg}`. An in-place optional param (its name flagged by `getParamRegexp`, `paramsMap` entry's fifth element) is spread in only when set, `...(_m0.groups.x!==void 0&&{x:…})`, so an absent one has no key, as in the interpreter. Unparseable names fall back to exec + spread + runtime `_normalizeGroups`.
2525
- **A `*` inside a segment** (see [matching.md](matching.md#greedy-)): its pieces (the `pre*` / `*post` regex groups and the `join` `**`'s tail) are one property, placed where the first piece is (`\0` in `paramsCode`) and filled after the loop: `pre+(nonEmpty?"/"+tail:"")+"/"+post`, the `**`'s only where it has a segment (`l>c`, or the `suffixGuard`).
2626
- **matchAll** accumulates with `r.push` and one `return r.reverse()`; ordering rules in [matching.md](matching.md#findallroutes-ordering-public-contract).
2727
- Routers without suffix routes, and without a node holding both `""` and method entries, must compile byte-identically (snapshots).

‎.agents/matching.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Node kinds: **static**, **param** (key `*`: `:id`, `:id(\d+)`, mixed segments li
99

1010
Lookup priority: static > param > wildcard, except on paths a suffix route matches (below).
1111

12-
**Results** are fresh `{ data, params? }` objects, never the stored `MethodData` (one shared object per route). Static matches and `params: false` have no `params` key; interpreter params are null-proto. An absent optional param has no key, also an in-place one (`*-:x?`: its group is unset, `getMatchParams` skips `undefined`). `addRoute` stores `data ?? null`, so falsy data round-trips.
12+
**Results** are fresh `{ data, params? }` objects, never the stored `MethodData` (one shared object per route). Static matches and `params: false` have no `params` key; interpreter params are null-proto. An absent optional param (`:x?`, `:x*`, `{…}?`) has no key (the expansion without it matched), nor does an absent in-place one (`*-:x?`: its group is unset, `getMatchParams` skips `undefined`). Not so a trailing optional `*` that takes no segment: its key stays, `undefined` (`/a/*` on `/a` gives `{"0": undefined}`), and a bare `**` gives `_: ""`. `addRoute` stores `data ?? null`, so falsy data round-trips.
1313

1414
Guard `index < segments.length` before any `node.static[...]` lookup: `undefined` must never coerce to the key `"undefined"`.
1515

@@ -59,16 +59,17 @@ Segments after a `**` (or a `*`) match from the **end** of the path; the catch-a
5959

6060
- **Syntax:** one catch-all per route (`*`, `**`, `:x+`, `:x*`); `_add` throws `rou3: a route can have only one ...` quoting the input as written (threaded through expansion as `input`).
6161
- **Params:** `MethodData.suffix = [wildcard index w, suffix length n]`; a param at route index `k` after the `**` maps to `index - w - 1 + (n - k)` at match time (`getMatchParams`, `collectSuffix`, compiled `s[l-j]`). A bare `**` between them over zero segments is unset (see [Unnamed captures](#unnamed-captures)).
62-
- **Ranking** (`rankFromEnd`, `operations/_suffix.ts`): when a suffix route matches (`hasSuffixMatch`, pruned by `hasSuffix`), `findRoute` collects all matches (`_findAll(…, reverse = true)`) and stable-sorts comparing from the last segment backwards: literal 3 > regex param 2 > plain param or `**`-covered 0 (a plain param must be 0, or `/**/:y` beats the narrower `/b/**`). `kindAt` returns a covered segment as `~start` of its `**`, so comparisons jump over ranges both `**` cover (cost ∝ segments around the `**`, not path length). Ties keep tree order; `reverse` makes the last match the first-registered. `findAllRoutes` applies the same sort when a suffix route is among its matches. Paths no suffix route matches are untouched. Known (README): the from-end ranking also applies between non-suffix routes on those paths. Pinned by the `suffix.test.ts` sweep "never picks a strictly broader route".
63-
- **Within a suffix trie** (`collectSuffix`): shallower first, then param child, then static child; same-node entries by weight (passing regexes, + 1 for a `*`, + 2 for a `**:name`), ties insertion order.
62+
- **Ranking** (`rankFromEnd`, `operations/_suffix.ts`): when a suffix route matches (`hasSuffixMatch`, pruned by `hasSuffix`), `findRoute` collects all matches (`_findAll(…, reverse = true)`) and stable-sorts comparing from the last segment backwards: literal 3 > regex param 2 > plain param or `**`-covered 0 (a plain param must be 0, or `/**/:y` beats the narrower `/b/**`; so must a regex that restricts no more, `paramsMap`'s `plain`: `:a:b?`, `*:x?`). `kindAt` returns a covered segment as `~start` of its `**`, so comparisons jump over ranges both `**` cover (cost ∝ segments around the `**`, not path length). Ties keep tree order; `reverse` makes the last match the first-registered. `findAllRoutes` applies the same sort when a suffix route is among its matches. Paths no suffix route matches are untouched. Known (README): the from-end ranking also applies between non-suffix routes on those paths. Pinned by the `suffix.test.ts` sweep "never picks a strictly broader route".
63+
- **Within a suffix trie** (`collectSuffix`): shallower first, then param child, then static child; same-node entries by weight (+ 2 per passing regex, + 1 for a `*`, + 2 for a `**:name`), ties insertion order.
6464
- **Compiler:** see [compiler.md](compiler.md#suffix-routes).
6565

6666
## Removal
6767

6868
`removeRoute` splices entries by the registration identity `_add` stamps on them (`MethodData.route`), never the whole bucket, so same-node siblings survive.
6969

70-
- Plain pattern: identity = the rewritten segment join (static keys via `segmentKey`, suffix included), the same string `ctx.static` is keyed by. Spellings the tree can't distinguish remove each other (`/a/` ≡ `/a`, `\)` ≡ `)`, `/**.md` ≡ `/*.md`). A `*` inside a segment is removed through the same `splitStar` routes.
71-
- Expanding pattern (groups, modifiers): every entry gets the pre-expansion text normalized by `expandedRouteId()`, so the `/admin` entry of `/admin/:page?` never collides with a separately registered `/admin`.
70+
- Plain pattern: identity = the rewritten segment join (static keys via `segmentKey`, dynamic segments as written, suffix included), the same string `ctx.static` is keyed by. Spellings the tree can't distinguish remove each other (`/a/` ≡ `/a`, `\)` ≡ `)`, `/**.md` ≡ `/*.md`, `/café-:id` ≡ `/caf%C3%A9-:id`). A `*` inside a segment is removed through the same `splitStar` routes.
71+
- Identities are compared canonically (`routeId`: each segment through `dynamicKey`, which percent-encodes a dynamic segment's literal text like `getParamRegexp`, outside constraints, `?{}` kept as syntax, and is a no-op on a static key), in `removeRoute` and `findOverlappingRoutes`' dedupe, so both spellings alias; a constraint is regex and stays distinct (`:x(é)` vs `:x(%C3%A9)`). Escapes are not canonicalized (`/:x-a` vs `/:x-\a` stay distinct): a missed alias, never a wrong one. The canonical form is computed where identities are compared, not stamped by `addRoute`, so the core bundle (routers that never remove) doesn't carry it.
72+
- Expanding pattern (groups, modifiers): every entry gets the pre-expansion text normalized by `expandedRouteId()` (static segments via `segmentKey`), so the `/admin` entry of `/admin/:page?` never collides with a separately registered `/admin`. A group that expands to a single route (`/a/*-{:x}?` is `/a/*-:x?`, `/a{b}` is `/ab`) is that route: it takes the rewritten route's identity (both `_add` and `_removeRoute` skip `expandedRouteId` there). `expandGroupDelimiters` returns that rewrite alone, also next to another group, so the next group is expanded from the rewritten text: its identity is `expandedRouteId` of `/*-:x?/b{.json}?` for `/*-{:x}?/b{.json}?` too, and `skipGroup` renumbers the right group (`/a/*{:x}?/b{/(\d+)}?/(\w+)` on `/a/q/b/z` is `{0:"q", 2:"z"}`, as in URLPattern). A pattern starting with a group (no `/` in front, see [syntax.md](syntax.md#leading-)) is read after a `/` (the split drops a path's first piece) and marked with a leading `{`: read after a `/`, `{a}?/b` is the text of `/{a}?/b`, and both register `/a/b`. A malformed `{…` removes nothing.
7273
- All entries with that identity go (duplicates together). An emptied static node deletes its `ctx.static` key via the join accumulated during the walk (no value scan).
7374
- Removal is by registered pattern: `/x/*` does not remove `/x/:id`; `:id(\d+)` and `:x(\d+)` are distinct.
7475
- Suffix routes: `_removeSuffix` walks back from the last segment, prunes empty trie nodes, then `wildcard.suffix`, then the wildcard (`_isEmptyNode` counts `suffix`).
@@ -86,7 +87,7 @@ Segments after a `**` (or a `*`) match from the **end** of the path; the catch-a
8687

8788
## Unnamed captures
8889

89-
An unescaped `*` (`/*`, `/*.png`, `/file-*`), a bare `**` and an unnamed regex group are unnamed captures keyed `"0"`, `"1"`, … in pattern order over the **whole pattern** (URLPattern, which reads `**` as `*` with a `*` modifier): `/(\d+)/x/**` gives `0` and `1`, `/(\d+)-*` gives the group `0` and the `*` `1`, and the pieces a `*` inside a segment is split into share its key (`/**.md` is `/*.md`: one `0`). A left-out optional group uses up the numbers of its captures (`/a{/(\d+)}?/**` keys the `**` `1` on `/a/x/y` too), so a capture has one key in every route a pattern registers (`findAllRoutes` and the regex can't disagree per expansion). `_add` counts a route's captures (`_unnamedParamIndex`, also through `getParamRegexp`, and returns the count) and maps each through `unnamed` (identity for a plain pattern); for the expansion without a `{…}?` group, `skipGroup()` (`add.ts`) shifts the captures after it by the group's count, which `_add` itself counts on the text before the group with and without its body (no second parser). Early bails keep plain groups at their old cost: a pattern without `*` / `(` skips `skipGroup`, and a group body without them (not extending a catch-all) skips the counting. `routeToRegExp` threads the same `unnamed` (`toRegExp` → `inlineOptionalGroup` / `routeToRegExpSegments`, emitting `_N`), so both expansions of an inline group line up. Modifier expansions drop no unnamed capture. A param name can't collide with them (a name can't start with a digit; `:_0` is the key `_0`).
90+
An unescaped `*` (`/*`, `/*.png`, `/file-*`), a bare `**` and an unnamed regex group are unnamed captures keyed `"0"`, `"1"`, … in pattern order over the **whole pattern** (URLPattern, which reads `**` as `*` with a `*` modifier): `/(\d+)/x/**` gives `0` and `1`, `/(\d+)-*` gives the group `0` and the `*` `1`, and the pieces a `*` inside a segment is split into share its key (`/**.md` is `/*.md`: one `0`). A left-out optional group uses up the numbers of its captures (`/a{/(\d+)}?/**` keys the `**` `1` on `/a/x/y` too), so a capture has one key in every route a pattern registers (`findAllRoutes` and the regex can't disagree per expansion). `_add` counts a route's captures (`_unnamedParamIndex`, also through `getParamRegexp`, and returns the count) and maps each through `unnamed` (identity for a plain pattern); for the expansion without a `{…}?` group, `skipGroup()` (`add.ts`) shifts the captures after it by the group's count, which `_add` itself counts on the text before the group with and without its body, joined like `expandGroupDelimiters` (`joinGroup`: in `/:a{(\d+)}?/*` the group holds an unnamed `(\d+)`, so the `*` is `1` in both routes; no second parser). Early bails keep plain groups at their old cost: a pattern without `*` / `(` skips `skipGroup`, and a group body without them (not extending a catch-all) skips the counting. `routeToRegExp` threads the same `unnamed` (`toRegExp` → `inlineOptionalGroup` / `routeToRegExpSegments`, emitting `_N`), so both expansions of an inline group line up. Modifier expansions drop no unnamed capture. A param name can't collide with them (a name can't start with a digit; `:_0` is the key `_0`).
9091

9192
**Deprecated `_` alias** (0.x compatibility): the router also reports a bare `**` capture as `_`. `getMatchParams` sets it next to the numbered key (`index < 0 && optional && !join` is only a bare `**`, not the one a `*` inside a segment is split around); the compiler writes the tail once into the temp `_w` (`"N":_w=tail,_:_w`, declared with the regex temps when `ctx.starStarTemp`), so routes without a bare `**` pay nothing. `_add` records `_` as a taken name for a bare `**` (`addName`), so `/:_/**` and `/**/:_` throw a duplicate name. Types add `_?: string` with `@deprecated` (`DoubleStarAlias`). `routeToRegExp` keeps only the `_N` group (no regex can capture one group under two names); tests comparing router params with regex groups or URLPattern drop the alias (`routerCaptures` in `regexp.test.ts`, `withoutAlias` in `test/_utils.ts`, which also accepts a split `*`'s key without it).
9293

0 commit comments

Comments
 (0)