You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 92a2ee4
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: .agents/compiler.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ Pinned in `test/compiler.test.ts` and `test/types.test-d.ts`.
21
21
-**Wildcard tails** with an all-static prefix → `p.slice(K)`; else `s.slice(i).join('/')`. Valid because the prologue keeps every segment of `p`.
22
22
-**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)).
23
23
-**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`.
25
25
-**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`).
26
26
-**matchAll** accumulates with `r.push` and one `return r.reverse()`; ordering rules in [matching.md](matching.md#findallroutes-ordering-public-contract).
27
27
- Routers without suffix routes, and without a node holding both `""` and method entries, must compile byte-identically (snapshots).
Lookup priority: static > param > wildcard, except on paths a suffix route matches (below).
11
11
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.
13
13
14
14
Guard `index < segments.length` before any `node.static[...]` lookup: `undefined` must never coerce to the key `"undefined"`.
15
15
@@ -59,16 +59,17 @@ Segments after a `**` (or a `*`) match from the **end** of the path; the catch-a
59
59
60
60
-**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`).
61
61
-**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.
64
64
-**Compiler:** see [compiler.md](compiler.md#suffix-routes).
65
65
66
66
## Removal
67
67
68
68
`removeRoute` splices entries by the registration identity `_add` stamps on them (`MethodData.route`), never the whole bucket, so same-node siblings survive.
69
69
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.
72
73
- 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).
73
74
- Removal is by registered pattern: `/x/*` does not remove `/x/:id`; `:id(\d+)` and `:x(\d+)` are distinct.
74
75
- 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
86
87
87
88
## Unnamed captures
88
89
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`).
90
91
91
92
**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).
0 commit comments