Skip to content

TS URLPattern implementation - #8270

Merged
jasnell merged 10 commits into
mainfrom
jasnell/ts-urlpattern
Nov 12, 2026
Merged

jasnell merged 10 commits into
mainfrom
jasnell/ts-urlpattern

Conversation

@jasnell

@jasnell jasnell commented Nov 6, 2026

Copy link
Copy Markdown
Collaborator

Port URLPattern to TS

@jasnell
jasnell added this pull request to stack #8267 November 6, 2026 21:08
@jasnell
jasnell requested review from a team as code owners November 6, 2026 21:08
@jasnell
jasnell requested review from a team and petebacondarwin and removed request for a team November 6, 2026 21:08

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 660f2bf3.

This review, of b2087ddf

💬 Approved with comments — One WARNING: the TS_URL_PATTERN autogate changes observable URLPattern behaviour, and no commit message records a compatibility decision for it. There is also one INFO about the type declarations. Nothing makes the change unsafe to merge while the autogate is off.

Findings: 1 warning · 1 info (2 are inline comments on the diff)

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.

🔧 Fix with your agent

Paste the following into your coding agent to investigate and fix these issues.

Fix the following code review issues found in pull request #8270.

Before making changes, review each issue and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g., the fix would require disproportionate changes
  for minimal ROI, or the finding is factually incorrect), explain why
- If you need to clarify something before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

## WARNING (1)

### [Code Quality] Turning on TS_URL_PATTERN changes behaviour Workers can observe, including on the legacy parser (lone surrogates, init member read order, the three-argument overload, own group properties, global placement, patched exec no longer called), and no commit message records the compatibility decision.
- **File:** src/workerd/util/autogate.h:126

## INFO (1)

### [Code Quality] The shared declaration types `hasRegExpGroups` as always present, but Workers on the legacy parser (`urlpattern_original`) do not have it at runtime.
- **File:** types/defines/urlpattern.d.ts:68

📋 Code Quality: ⚠️ 1 warning · 1 info

The port is solid and well tested. The autogate brings observable behaviour changes with no recorded compatibility decision, and the types over-declare one property.

Recommendation: 📝 Minor Comments

  • [WARNING] Turning on TS_URL_PATTERN changes behaviour Workers can observe, including on the legacy parser (lone surrogates, init member read order, the three-argument overload, own group properties, global placement, patched exec no longer called), and no commit message records the compatibility decision. (src/workerd/util/autogate.h:126)
  • [INFO] The shared declaration types hasRegExpGroups as always present, but Workers on the legacy parser (urlpattern_original) do not have it at runtime. (types/defines/urlpattern.d.ts:68)
View full review

Behaviour changes when TS_URL_PATTERN is on. The parity suite's expectations show these differences from the C++ classes:

  • With the legacy parser, lone surrogates become U+FFFD (conversions.js).
  • Init members are read in WebIDL order, not component order.
  • A three-argument new URLPattern(str, obj, opts) now treats the object as a base URL.
  • Result groups are defined as own data properties.
  • URLPattern is an own property of globalThis.
  • A patched RegExp.prototype.exec is no longer called.

Each change can be defended against the standard, and the suite documents each one. However, the repository's compatibility rules say an autogate does not preserve the API surface existing Workers see, and that the compatibility decision belongs in the commit message. None of this pull request's commit messages records one.

Types. types/defines/urlpattern.d.ts declares hasRegExpGroups for both parsers, but the legacy parser does not have it.


✅ All other checks passed

🔒 Security: ✅ LGTM

No security problems found:

  • The regex provider moved out of the class unchanged, so its out-of-bounds hardening is kept.
  • The bootstrap helpers keep their owning strings alive while ada holds views into them.
  • The TypeScript class uses primordials, null-prototype or data-defined objects, a brand check, and is not cloneable.

📖 AGENTS.md: ✅ LGTM

No issues found.


⚡ Performance: ✅ LGTM

No performance problems found:

  • Patterns are compiled once, when the object is constructed.
  • Matching reuses the cached RegExps and takes ada's fast paths where they exist.
  • Each call into C++ does a bounded amount of work.

📝 Documentation: ✅ LGTM

No issues found.


Reviewed commit: b2087ddf

Comment thread src/workerd/util/autogate.h Resolved
Comment thread types/defines/urlpattern.d.ts Resolved

@piscisaureus piscisaureus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few small things; nothing blocking.

Comment thread types/defines/urlpattern.d.ts Resolved
Comment thread src/tests/urlpattern/results.js Resolved
Comment thread src/tests/urlpattern/pollution.js Resolved

@piscisaureus piscisaureus left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM but see comments

@jasnell
jasnell force-pushed the jasnell/ts-urlpattern branch from b2087dd to 660f2bf Compare November 7, 2026 00:50

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 5a14a9b0.

This review, of 660f2bf3

💬 Approved with comments — The earlier compatibility WARNING is resolved: commit 66edb4a now records the decision to accept the risk. One INFO note remains, about hasRegExpGroups being typed for the legacy parser.

Findings: 1 info

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📋 Code Quality: 💬 1 info

One INFO note: hasRegExpGroups is declared as always present.

Recommendation: 💬 Optional Nits

  • [INFO] hasRegExpGroups is declared as always present, but Workers on the legacy parser (urlpattern_original) have no such property at runtime. (types/defines/urlpattern.d.ts:68)
View full review
  • Compatibility decision (resolved): commit 66edb4a now records the decision to accept the risk, and it lists each change Workers can observe when TS_URL_PATTERN is on.
  • hasRegExpGroups (INFO): types/defines/urlpattern.d.ts declares hasRegExpGroups as always present. Workers on the legacy parser (urlpattern_original) have no such property at runtime: the TypeScript implementation deletes it from the prototype for that parser. The file's header comment documents this, but the type does not express it.
  • Generated snapshots: they match the new declaration file, and groups is now Record<string, string | undefined>.

✅ All other checks passed

🔒 Security: ✅ LGTM

No security problems found:

  • The regex provider moved out of the class unchanged, so its out-of-bounds hardening is kept.
  • The bootstrap helpers check input types and keep their owning strings alive while ada holds views into them.

📖 AGENTS.md: ✅ LGTM

No issues found.


⚡ Performance: ✅ LGTM

No performance problems found:

  • Patterns are compiled once, in the constructor.
  • Matching reuses the cached RegExps and takes ada's fast paths for wildcard, exact and empty components.

📝 Documentation: ✅ LGTM

No issues found.


Reviewed commit: 660f2bf3

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of 6c825a7a.

This review, of 5a14a9b0

💬 Approved with comments — The only change since the last review is an include-path fix, and nothing new turned up. One INFO note about how hasRegExpGroups is typed is still open.

Findings: 1 info

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


📋 Code Quality: 💬 1 info

No new problems. One INFO note from the last review is still open: hasRegExpGroups is typed as always present.

Recommendation: 💬 Optional Nits

  • [INFO] hasRegExpGroups is typed as always present, but Workers on the legacy parser (urlpattern_original) have no such property at runtime. (types/defines/urlpattern.d.ts:68)
View full review
  • hasRegExpGroups typing (INFO, still open): types/defines/urlpattern.d.ts:68 declares get hasRegExpGroups(): boolean; with no condition. Under the legacy parser, src/per_isolate/urlpattern/urlpattern.ts deletes the property from the prototype. Type-checked code on a legacy-parser Worker can therefore read undefined where the type promises boolean. The header comment of the file mentions this, but the type does not.
  • The change since the last review (the full-path include in urlpattern-standard.h) is correct.
  • The generated snapshots match types/defines/urlpattern.d.ts, and groups is Record<string, string | undefined>.

✅ All other checks passed

🔒 Security: ✅ LGTM

  • The include-path change has no security effect.
  • The regex provider keeps its out-of-bounds hardening.
  • The bootstrap helpers check their input types and keep the strings that own the data alive for as long as ada holds views into them.

📖 AGENTS.md: ✅ LGTM

No issues found.


⚡ Performance: ✅ LGTM

No runtime path changed since the last review.


📝 Documentation: ✅ LGTM

No issues found.


Reviewed commit: 5a14a9b0

@petebacondarwin petebacondarwin left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving from a typings perspective.
It would be good for the PR description to have more context here. It is currently just one line with no explanation of why this has been implemented. 😢

Base automatically changed from jasnell/ts-url to main November 11, 2026 19:05
@jasnell
jasnell force-pushed the jasnell/ts-urlpattern branch from 5a14a9b to 6c825a7 Compare November 11, 2026 19:48

@clanky-the-clanker clanky-the-clanker Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by the review of a81a7267.

This review, of 6c825a7a

✅ Approved — Nothing new turned up since the last review. The include-path fix is correct, and the commit messages record the compatibility decision for the TS_URL_PATTERN switch.

Not opened by the correctness review: 3 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

  • The regex provider keeps its out-of-bounds hardening.
  • The bootstrap helpers check their input types. The strings that own the data stay alive for as long as ada holds views into them.
  • The TypeScript class uses private-field brand checks and null-prototype records, and does not depend on a patched RegExp.prototype.exec.
  • User patterns still run in V8's RegExp, so the change adds no new regex denial-of-service exposure.

📖 AGENTS.md: ✅ LGTM

No issues found.


📋 Code Quality: ✅ LGTM

  • The native helpers, the TypeScript URLPattern, the autogate wiring and the test cells show no correctness defect.
  • Overload resolution follows WebIDL.
  • Matching uses RegExpPrototypeExec on null-prototype internals.
  • The legacy parser removes hasRegExpGroups.
  • The regex provider moves over unchanged, out-of-bounds hardening included.
  • The compatibility changes visible under TS_URL_PATTERN are accepted explicitly in the commit message of 7cd3dc7, with each one listed against the ledger.
  • The full-path include of urlpattern-regex.h is correct.

⚡ Performance: ✅ LGTM

No issues found.


📝 Documentation: ✅ LGTM

No issues found.


Reviewed commit: 6c825a7a

The same test modules run under a cell per C++ implementation and
flag combination: standard (ada), legacy (jsg::UrlPattern), and
standard with the dateless WebIDL opt-ins. They pin the shape,
the constructor's overloads and patterns, conversions, matching,
results, inspection, serialization, and what patched builtins
reach.

The suite also holds the expectations of a TypeScript
implementation to come, in usingTsImpl branches, and AGENTS.md
the ledger of where those depart from the C++, toward the
URLPattern standard and WebIDL. Among them: with no baseURL, the
standard C++ matches a string input that does not parse, because
ada resolves it against an empty URL; its groups come out in
std::unordered_map order; and both C++ implementations call a
patched RegExp.prototype.exec.
Construction from an init, a string and a string with a baseURL;
test() and exec() on string and init inputs; and a small router,
on the standard path, against the C++ implementation.
URLPattern::URLPatternRegexEngine becomes UrlPatternRegexProvider in
api/urlpattern-regex.h, unchanged, so that code other than the C++
URLPattern can compile patterns with ada.
Four stateless utils members for a URLPattern implemented in the
per-isolate bootstrap, in api/urlpattern-bootstrap.h:

- urlPatternCompile() compiles a pattern with ada and returns, for
  each component, its pattern string, RegExp, group names and ada's
  fast-path type and exact value, so that the bootstrap can match
  without calling back into C++.
- urlPatternProcessInit() processes an init input into the URL
  components matching compares, as ada's match() does.
- legacyUrlPatternCompile() and legacyUrlPatternProcessInit() do
  the same with jsg::UrlPattern, throwing its TypeErrors.

Nothing uses them yet.
One implementation for both parsers, in the per-isolate bootstrap.
The parser the urlpattern_standard flag selects compiles the
pattern through utils (api/urlpattern-bootstrap.h), ada or
jsg::UrlPattern, and so decides every pattern, the components an
init input processes to, the RegExp flags and the errors.
Everything else is in TypeScript and follows the URLPattern
standard and WebIDL: the conversions and constructor overloads,
matching, the results and the class shape.

Matching uses ada's fast paths where it has them and the builtin
RegExp exec otherwise, so a string input costs one native call, to
parse it as a URL, and a patched RegExp.prototype.exec is never
called. primordials gains RegExpPrototypeExec for it.

Nothing loads the module yet.
The new autogate makes the per-isolate bootstrap install the
TypeScript URLPattern as an own property of the global, and
global-scope.h then leaves out both C++ classes. It is independent
of TS_URL, so either can be rolled back alone.

The URLPattern suite gains a TypeScript cell for each parser,
which the ledger's usingTsImpl branches already described. WPT's
urlpattern tests run against it with each parser: the legacy
config's lone-surrogate expected failure passes there, since the
pattern is converted to a USVString. The search-OOB regression
test, a C++ memory-safety test, expects the patched exec to be
reached only by the C++ implementation.

Compatibility: we accept the risk rather than adding a compatibility
flag. Turning TS_URL_PATTERN on changes what every Worker can
observe, those on urlpattern_original included, each change toward
the URLPattern standard and WebIDL, as the ledger in
src/tests/urlpattern/AGENTS.md lists:
- With the legacy parser, lone surrogates become U+FFFD (#6).
- URLPatternInit members are read in lexicographic order, so getters
  run in a different order (#3), and results and init copies list
  their members in that order (#4).
- new URLPattern(input, object, options) takes the object as the
  baseURL (#7).
- Groups and results are own data properties, so Object.prototype
  setters no longer take them (#10), and under enable_fast_jsg_struct
  an init copy has only the members present (#11).
- URLPattern is an own property of the global, with WebIDL accessor
  names and a non-writable prototype and Symbol.toStringTag (#8);
  calling it without `new` throws the language's TypeError (#9).
- Matching no longer calls a patched RegExp.prototype.exec (#5).
- With the standard parser, a string input that does not parse,
  without a baseURL, no longer matches (#1), and groups are in the
  pattern's order (#2).
The URLPattern benchmarks gain a config that runs them against the
TypeScript implementation, with the standard parser.

Per 16 calls, C++ against TypeScript on this machine: test(url)
18.4 against 13.5 us, exec(url) 144 against 50.4, exec(init) 160
against 85.5, an eight-route router 205 against 155; construction
143 against 164 from an init.
URLPattern's declarations move from the C++ classes' RTTI to a
hand-written types/defines/urlpattern.d.ts, so that they do not
depend on which implementation runs: the TypeScript one under
TS_URL_PATTERN has no RTTI. Both C++ classes, and the standard
one's four structs, override their declarations to `never`.

The declarations are the snapshot's, unchanged, so the snapshot
only moves them to the end, after a comment. A type test pins
their shape.
An optional group that does not match is an own property of groups
whose value, with the standard parser, is undefined, so
URLPatternComponentResult's groups is now
Record<string, string | undefined>. The type test pins it: reading
such a group's length no longer type-checks.

The URLPattern suite gains:
- namedFullWildcard: a named group whose regexp is `.*` keeps its
  name, though the standard parser matches it on ada's full-wildcard
  fast path, without a RegExp.
- String inputs beyond ordinary special URLs: opaque, an empty host,
  not special, an IPv6 host, and an empty query and fragment. The
  TypeScript implementation slices them out of ada's serialization,
  which the URL WPTs cover only when TS_URL is on too.
- constructionCallsPatchedExecForProtocol: compiling a protocol
  pattern that needs a RegExp, such as `http{s}?`, the standard
  parser asks it whether it matches each special scheme through the
  current RegExp.prototype.exec, in both implementations. What a
  patched exec returns decides whether the pathname compiles as an
  opaque path's, and what it throws escapes the constructor. Core
  semantics now describes this, and ledger #5 is about matching.
urlpattern-standard.h included urlpattern-regex.h, which is in
another target, by a quoted relative path. Where Bazel copies a
target's headers into _virtual_includes, as on macOS and Windows,
that path resolves next to the copy and is not found.
@jasnell
jasnell force-pushed the jasnell/ts-urlpattern branch from 6c825a7 to a81a726 Compare November 11, 2026 23:51

@clanky-the-clanker clanky-the-clanker Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Approved — Nothing new turned up since the last review. The include-path fix is correct, and the commit messages record the compatibility decision for the TS_URL_PATTERN switch.

Not opened by the correctness review: 3 changed files it was meant to read
  • types/generated-snapshot/experimental/index.d.ts
  • types/generated-snapshot/experimental/index.ts
  • types/generated-snapshot/index.ts

The decision is advisory: this review is a comment and never approves, blocks or requests changes on the pull request.


✅ All checks passed

🔒 Security: ✅ LGTM

  • The regex provider keeps its out-of-bounds hardening.
  • The bootstrap helpers check their input types. The strings that own the data stay alive for as long as ada holds views into them.
  • The TypeScript class uses private-field brand checks and null-prototype records, and does not depend on a patched RegExp.prototype.exec.
  • User patterns still run in V8's RegExp, so the change adds no new regex denial-of-service exposure.

📖 AGENTS.md: ✅ LGTM

No issues found.


📋 Code Quality: ✅ LGTM

  • The native helpers, the TypeScript URLPattern, the autogate wiring and the test cells show no correctness defect.
  • Overload resolution follows WebIDL.
  • Matching uses RegExpPrototypeExec on null-prototype internals.
  • The legacy parser removes hasRegExpGroups.
  • The regex provider moves over unchanged, out-of-bounds hardening included.
  • The compatibility changes visible under TS_URL_PATTERN are accepted explicitly in the commit message of 7cd3dc7, with each one listed against the ledger.
  • The full-path include of urlpattern-regex.h is correct.

⚡ Performance: ✅ LGTM

No issues found.


📝 Documentation: ✅ LGTM

No issues found.


Reviewed commit: a81a7267 — same changes as 6c825a7a, so this is that commit's review (no new review was run; line numbers are as of 6c825a7a)

@jasnell
jasnell merged commit 26b83c5 into main Nov 12, 2026
23 of 24 checks passed
@jasnell
jasnell deleted the jasnell/ts-urlpattern branch November 12, 2026 01:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants