Skip to content

Commit 76751fc

Browse files
committed
fix: review follow-ups for #231, #232 and #233
1 parent 1b96970 commit 76751fc

23 files changed

Lines changed: 580 additions & 133 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 guard: counted in `guardConditions`, not the weight, so the emit order doesn't change.
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
- **matchAll** accumulates with `r.push` and one `return r.reverse()`; ordering rules in [matching.md](matching.md#findallroutes-ordering-public-contract).
2626
- Routers without suffix routes, and without a node holding both `""` and method entries, must compile byte-identically (snapshots).
2727

β€Ž.agents/matching.mdβ€Ž

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Node kinds: **static**, **param** (key `*`: `:id`, `*`, `:id(\d+)`, mid-segment
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

@@ -55,16 +55,17 @@ Segments after a `**` match from the **end** of the path; the `**` takes what is
5555

5656
- **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`). `splitRoute()` rewrites a `**<rest>` segment (rest not starting with `:`, `{`, `}`) into `**` + `*<rest>`, so `/**.md` ≑ `/**/*.md` everywhere. A `*` after `**` is required.
5757
- **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)).
58-
- **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".
58+
- **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".
5959
- **Within a suffix trie** (`collectSuffix`): shallower first, then param child, then static child; same-node entries by weight (passing regexes + 1 for `**:name`), ties insertion order.
6060
- **Compiler:** see [compiler.md](compiler.md#suffix-routes).
6161

6262
## Removal
6363

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

66-
- 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`).
67-
- 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`.
66+
- 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`).
67+
- 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.
68+
- 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+)}?/*` on `/a/q/b/z` is `{0:"q", 2:"z"}`, as in URLPattern).
6869
- 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).
6970
- Removal is by registered pattern: `/x/*` does not remove `/x/:id`; `:id(\d+)` and `:x(\d+)` are distinct.
7071
- Suffix routes: `_removeSuffix` walks back from the last segment, prunes empty trie nodes, then `wildcard.suffix`, then the wildcard (`_isEmptyNode` counts `suffix`).

β€Ž.agents/overlap.mdβ€Ž

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Both features are tree-shakeable and never touch the core bundle.
66

77
Files: `src/_overlap.ts` (shape model), `src/_subsume.ts` (subsumption, canonicalization), `src/operations/overlap.ts` (public API, tree traversal).
88

9-
- **Shape** (`RouteShape`): fixed single-segment matchers (`string` literal | `RegExp` | `NON_EMPTY` for a `:name`, which needs a value | `undefined` = any, a `*`) + a tail length range `[tailMin, tailMax]` (`*` β†’ `[0,1]`, `**` / `:x*` β†’ `[0,∞]`, `**:name` β†’ `[1,∞]`, none β†’ `[0,0]`; the tail constrains count only, except `some`: a `**:name`'s one-segment tail can't be `""`) + `suffix`: matchers aligned to the path **end** for segments after `**`. Leading any-value suffix matchers fold into the tail (`/**/*/b` ≑ `/*/**/b`; a `:x` is `NON_EMPTY` and doesn't fold). With a suffix or a `some` tail, overlap/subsumption check each path length position by position (`matcherAt`, which gives the `some` tail's only segment `NON_EMPTY`) up to `stableLength` (max fixed + max suffix, + 2 with `some`), which stands for all longer lengths.
9+
- **Shape** (`RouteShape`): fixed single-segment matchers (`string` literal | `RegExp` | `NON_EMPTY` for a `:name`, which needs a value | `undefined` = any, a `*`) + a tail length range `[tailMin, tailMax]` (`*` β†’ `[0,1]`, `**` β†’ `[0,∞]`, `:x*` β†’ `[0,∞]` with `some`, `**:name` β†’ `[1,∞]`, none β†’ `[0,0]`; the tail constrains count only, except `some`: a `**:name`'s one-segment tail can't be `""`) + `suffix`: matchers aligned to the path **end** for segments after `**`. Leading any-value suffix matchers fold into the tail (`/**/*/b` ≑ `/*/**/b`; a `:x` is `NON_EMPTY` and doesn't fold). With a suffix or a `some` tail, overlap/subsumption check each path length position by position (`matcherAt`, which gives the `some` tail's only segment `NON_EMPTY`) up to `stableLength` (max fixed + max suffix, + 2 with `some`), which stands for all longer lengths.
1010
- Shapes come from tree entries (`shapeOf`, kind-tagged edges so an escaped static `\*` stays distinct from a param), cached per entry in a `WeakMap`. Query patterns go through the real `addRoute` on a throwaway router (`routeToShapes`, memoized per string, cleared at 1024 entries; returned shapes are immutable). A multi-expansion pattern has several shapes; patterns overlap when any pair does.
1111
- **Canonicalization:** trailing any-value matchers fold into the tail (`/a/*/*` β†’ `["a"] [1,2]`), never into a `some` tail (it would move its first segment); shapes with identical fixed prefixes (`_segmentEqual`, strict identity) and contiguous ranges merge (`mergeShapes`; suffixes must be identical; `some` survives only if both ranges' one-segment tails need a value or don't exist). So `/a/:x*` == `/a{/**:y}?` ⊊ `/a/**` and `/a/:x?` ⊊ `/a/*` (`/a//`). Known precision loss: a `NON_EMPTY` `:x` doesn't fold into a tail, so `compareRoutes("/:q*/:x", "/**/b")` is `partial` (true: `superset`); and an in-place optional param is one regex, compared by source only, so `compareRoutes("/a/*-:x?", "/a/*-:x")` is `partial` (true: `superset`) and `("/a/:a:b?", "/a/:id")` is `subset` (true: `equal`). Weaker verdicts, never wrong ones.
1212
- **Overlap** = some concrete path matches both. Static/static and static/regex are exact; any-vs-anything and regex/regex over-approximate to overlap.

0 commit comments

Comments
Β (0)