workerd / urlpattern
AGENTS.md9.2k starsChanged 8 months agoApache-2.0View on GitHub
An informal specification of URLPattern as implemented in workerd, kept in lockstep with the test suite in this directory. The tests are the normative artifact. The cells run the same modules (urlpattern-modules.capnp) against the C++ implementations and the TypeScript one: which-impl.js reads the flags; a cell's USING_TS_IMPL binding says which implementation it means to run. enable_fast_jsg_struct is not pinned: the @ and @all-compat-flags variants run each cell with it off and on. The TypeScript implementation honors the dated flags above…
Trending
More talk lately.about the whole repository
Who's talking about cloudflare/workerd
- A Hacker News story“OS Workerd, Cloudflare's JavaScript/WASM Runtime”Hacker News · Sep 27, 2022 · 27 points
- withastro/astro“Cloudflare adapter returning [object Object]”GitHub · Oct 10, 2025 · 18 reactions
- supabase/supabase-js“The 'cache' field on 'RequestInitializerDict' is not implemented - Cloudflare Workers”GitHub · Mar 28, 2024 · 16 reactions
- NixOS/nixpkgs“Package request: workerd”GitHub · Nov 12, 2024 · 13 reactions
- nodejs/node“src: improve buffer.transcode performance”GitHub · Aug 1, 2024 · 13 reactions
The biggest 5 of 39 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 39
Talked about on GitHub, Bluesky, Hacker News and Stack Overflow (39 times).
On GitHub · 32
- Oct 10, 2025Cloudflare adapter returning [object Object] — withastro/astro18 reactions · 15 comments
- Mar 28, 2024The 'cache' field on 'RequestInitializerDict' is not implemented - Cloudflare Workers — supabase/supabase-js16 reactions · 24 comments
- Nov 12, 2024Package request: workerd — NixOS/nixpkgs13 reactions · 10 comments
- Aug 1, 2024src: improve buffer.transcode performance — nodejs/node13 reactions · 26 comments
- Feb 19, 2024Add Curve25519 — w3c/webcrypto9 reactions · 16 comments
27 more on GitHub
- Nov 3, 2025Optimize TextEncoder::encode — nodejs/performance7 reactions · 33 comments
- Oct 23, 2023🐛 BUG: pages dev output is unnecessarily verbose — cloudflare/workers-sdk7 reactions · 7 comments
- Nov 24, 2025util: improve textencoder encodeInto performance — nodejs/node6 reactions · 8 comments
- Aug 8, 2024Fix fetch adapter in cloudflare workers — axios/axios6 reactions · 1 comment
- May 25, 2024Partially fix #3160 by properly handling resultsFormat query — cloudflare/workers-sdk6 reactions · 12 comments
- Jan 23, 2026src: improve textEncoder encode performance with simdutf — nodejs/node5 reactions · 8 comments
- Jan 19, 2024Implement Vitest testing environment for Miniflare 3 — cloudflare/workers-sdksays it tested it5 reactions · 7 comments
- Nov 28, 2024src,lib: remove the cost of encoding parameter serialization — nodejs/node4 reactions · 3 comments
- Aug 8, 2026deps: bump the npm group in /kanarek-companion with 2 updates — trvny/trvny3 reactions · 4 comments
- Aug 8, 2026deps: bump the npm group in /weather-feed with 3 updates — trvny/trvny3 reactions · 4 comments
- Aug 8, 2026deps: bump the npm group in /mcp/status-mcp with 2 updates — trvny/trvny3 reactions · 4 comments
- Jan 24, 2026build(deps-dev): bump @cloudflare/workers-types from 4.20260123.0 to 4.20260124.0 — magicappdev/magicappdev3 reactions · 5 comments
- Nov 15, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261112.1 — paglaai/PaglaROUTER2 reactions · 2 comments
- Nov 8, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261104.1 — paglaai/PaglaROUTER2 reactions · 3 comments
- Nov 1, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261029.1 — paglaai/PaglaROUTER2 reactions · 3 comments
- Oct 25, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261022.1 — paglaai/PaglaROUTER2 reactions · 3 comments
- Oct 18, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261015.1 — paglaai/PaglaROUTER2 reactions · 3 comments
- Oct 11, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261008.1 — paglaai/PaglaROUTER2 reactions · 4 comments
- Oct 4, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20261001.1 — paglaai/PaglaROUTER2 reactions · 4 comments
- Sep 27, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20260924.1 — paglaai/PaglaROUTER2 reactions · 4 comments
- Sep 20, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20260917.1 — paglaai/PaglaROUTER2 reactions · 3 comments
- Sep 16, 2026[wrangler] Add Analytics SQL binding support — cloudflare/workers-sdk2 reactions · 4 comments
- Sep 13, 2026chore(deps-dev): bump @cloudflare/workers-types from 5.20260821.1 to 5.20260910.1 — paglaai/PaglaROUTER2 reactions · 4 comments
- Apr 21, 2026build(deps-dev): Bump @cloudflare/workers-types from 4.20260411.1 to 4.20260421.1 in /workers/auth-api — Trancendos/infinity-adminOS2 reactions · 4 comments
- Apr 14, 2026build(deps-dev): Bump @cloudflare/workers-types from 4.20260411.1 to 4.20260414.1 in /workers/ai-api — Trancendos/infinity-adminOS2 reactions · 4 comments
- Apr 14, 2026build(deps-dev): Bump @cloudflare/workers-types from 4.20260411.1 to 4.20260414.1 in /workers/files-api — Trancendos/infinity-adminOS2 reactions · 4 comments
- Jan 24, 2026build(deps-dev): bump @cloudflare/workers-types from 4.20260123.0 to 4.20260124.0 — magicappdev/templates2 reactions · 2 comments
On Bluesky · 4
- Mar 24, 2026workerd : le runtime JavaScript/Wasm open source de Cloudflare Workers — @news.humancoders.com4 likes and reposts
- Aug 22, 2026Current status: trying to build github.com/cloudflare/w... on various sandbox providers — @jeremymorrell.dev1 likes and repost
- Mar 24, 2026workerd : le runtime JavaScript/Wasm qui propulse Cloudflare Workers est maintenant open source. Basé sur les standards web, il permet… — @humancoders.com1 likes and repost
- Nov 5, 2024Technically workers are open source github.com/cloudflare/w... — @userops.bsky.social1 likes and repost
On Hacker News · 2
- Sep 27, 2022OS Workerd, Cloudflare's JavaScript/WASM Runtime27 points · 2 comments
- Oct 5, 2023Cloudflare workers is adopting Ada URL parser2 points
On Stack Overflow · 1
- Oct 1, 2024How to user KV in cloudflare workers?1 vote
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository84 other files it gives its agents.
- AGENTS.mdAGENTS.md
- build/AGENTS.mdAGENTS.md
- src/bench/streams/AGENTS.mdAGENTS.md
- src/bench/streams/body/AGENTS.mdAGENTS.md
- src/bench/streams/compression/AGENTS.mdAGENTS.md
- src/bench/streams/digest/AGENTS.mdAGENTS.md
- src/bench/streams/encoding/AGENTS.mdAGENTS.md
- src/bench/streams/identity/AGENTS.mdAGENTS.md
- src/bench/streams/piping/AGENTS.mdAGENTS.md
- src/bench/streams/readable/AGENTS.mdAGENTS.md
- src/bench/streams/readable-byte/AGENTS.mdAGENTS.md
- src/bench/streams/strategies/AGENTS.mdAGENTS.md
- src/bench/streams/transform/AGENTS.mdAGENTS.md
- src/bench/streams/writable/AGENTS.mdAGENTS.md
- src/cloudflare/AGENTS.mdAGENTS.md
- src/node/AGENTS.mdAGENTS.md
- src/per_isolate/AGENTS.mdAGENTS.md
- src/per_isolate/crypto/AGENTS.mdAGENTS.md
- src/per_isolate/events/AGENTS.mdAGENTS.md
- src/per_isolate/url/AGENTS.mdAGENTS.md
- src/per_isolate/urlpattern/AGENTS.mdAGENTS.md
- src/per_isolate/webfs/AGENTS.mdAGENTS.md
- src/per_isolate/webstreams/AGENTS.mdAGENTS.md
- src/pyodide/AGENTS.mdAGENTS.md
- src/rust/AGENTS.mdAGENTS.md
- src/rust/cxx/AGENTS.mdAGENTS.md
- src/tests/dom-exception/AGENTS.mdAGENTS.md
- src/tests/events/AGENTS.mdAGENTS.md
- src/tests/events/eventsource/AGENTS.mdAGENTS.md
- src/tests/events/messagechannel/AGENTS.mdAGENTS.md
- src/tests/node/AGENTS.mdAGENTS.md
- src/tests/node/http-client/AGENTS.mdAGENTS.md
- src/tests/node/http-server/AGENTS.mdAGENTS.md
- src/tests/node/net/AGENTS.mdAGENTS.md
- src/tests/node/stream/AGENTS.mdAGENTS.md
- src/tests/streams/AGENTS.mdAGENTS.md
- src/tests/streams/cache/AGENTS.mdAGENTS.md
- src/tests/streams/compression/AGENTS.mdAGENTS.md
- src/tests/streams/digest/AGENTS.mdAGENTS.md
- src/tests/streams/encoding/AGENTS.mdAGENTS.md
- src/tests/streams/formdata/AGENTS.mdAGENTS.md
- src/tests/streams/htmlrewriter/AGENTS.mdAGENTS.md
- src/tests/streams/identity/AGENTS.mdAGENTS.md
- src/tests/streams/inspect/AGENTS.mdAGENTS.md
- src/tests/streams/iocontext/AGENTS.mdAGENTS.md
- src/tests/streams/piping/AGENTS.mdAGENTS.md
- src/tests/streams/r2-patterns/AGENTS.mdAGENTS.md
- src/tests/streams/readable/AGENTS.mdAGENTS.md
- src/tests/streams/readable-byte/AGENTS.mdAGENTS.md
- src/tests/streams/scaling/AGENTS.mdAGENTS.md
- src/tests/streams/sockets/AGENTS.mdAGENTS.md
- src/tests/streams/strategies/AGENTS.mdAGENTS.md
- src/tests/streams/transform/AGENTS.mdAGENTS.md
- src/tests/streams/writable/AGENTS.mdAGENTS.md
- src/tests/url/AGENTS.mdAGENTS.md
- src/workerd/api/AGENTS.mdAGENTS.md
- src/workerd/api/crypto/AGENTS.mdAGENTS.md
- src/workerd/api/node/AGENTS.mdAGENTS.md
- src/workerd/api/streams/AGENTS.mdAGENTS.md
- src/workerd/io/AGENTS.mdAGENTS.md
- The first 60 shown.
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 35
Errors: every standard failure is TypeError: Failed to construct URLPattern (or Failed to exec URLPattern / Failed to test URLPattern).
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
URLPattern
An informal specification of URLPattern as implemented in workerd, kept in
lockstep with the test suite in this directory. The tests are the
normative artifact. The cells run the same modules
(urlpattern-modules.capnp) against the C++ implementations and the
TypeScript one:
| Cell | Implementation | Flags the suite branches on |
urlpattern-standard-cpp | api/urlpattern-standard.{h,c++} (ada) | urlpattern_standard, set_tostring_tag |
urlpattern-legacy-cpp | api/urlpattern.{h,c++} (jsg::UrlPattern) | urlpattern_original, do_not_set_tostring_tag |
urlpattern-opt-in-cpp | standard, with the dateless WebIDL opt-ins | standard + spec_compliant_property_attributes, immutable_api_prototypes (--experimental) |
urlpattern-standard-ts, urlpattern-legacy-ts | src/per_isolate/urlpattern/, under the TS_URL_PATTERN autogate | as the C++ cell of the same name |
which-impl.js reads the flags; a cell's USING_TS_IMPL binding says which
implementation it means to run. enable_fast_jsg_struct is not pinned: the
@ and @all-compat-flags variants run each cell with it off and on.
The TypeScript implementation honors the dated flags above and is otherwise
WebIDL-conformant, so it differs from the C++ only toward the spec, in the
rows of the ledger below. Each row is pinned on both sides with a
usingTsImpl branch. The C++ cells disable the @all-autogates variant,
which would run the TypeScript implementation under them.
Core semantics
- Parsing: the standard parser is ada, the legacy one
jsg::UrlPattern; their patterns, quirks included, are pinned as they are (construction.js). In a pattern string:starts a named group and?makes the part before it optional. The standard parser leaves the components after the last one a string names as*, and against a baseURL the credentials too; the legacy one makes them'', and takes a baseURL's search and hash as well. - Errors: every standard failure is
TypeError: Failed to construct URLPattern(orFailed to exec URLPattern/Failed to test URLPattern); the legacy parser's messages say what failed. - RegExp flags:
v(standard) andu(legacy), plusiunderignoreCase. - Construction and
RegExp.prototype.exec: the standard parser asks a protocol pattern that compiles to a RegExp (not*or an exact protocol) whether it matches each special scheme, through the currentRegExp.prototype.exec, in both implementations. What a patchedexecreturns decides whether the pathname compiles as an opaque path's, and what it throws escapes the constructor (pollution.js). The legacy parser calls nothing while it compiles. - Inputs: an object,
nullorundefinedis aURLPatternInit(a URL included, read through its getters); anything else a string. A string input is parsed as a URL; one that does not parse, or a baseURL that does not, does not match. An init input is processed as URL components; when that fails the standard parser does not match and the legacy one throws its message. An init with a baseURL throws. - Results:
inputsholds the string input and baseURL, or a copy of the init. Groups are named by the pattern's names, wildcards and regexp groups numbered; an unmatched optional group isundefined(standard) or''(legacy). - Constructor overloads: with two arguments, a second that is an
object,
nullorundefinedis the options, anything else the baseURL. - Serialization: a URLPattern throws
DataCloneError: Could not serialize object of type "<constructor>".; results are plain objects.
Ledger
| # | Area | C++ | TypeScript | Test |
| 1 | Standard string input that does not parse, no baseURL | ada resolves it against an empty URL: test('nope') is true | no match | matching.js |
| 2 | Standard group order | ada's std::unordered_map order | the pattern's | results.js |
| 3 | URLPatternInit read order | declared (protocol … hash, baseURL) | lexicographic | conversions.js |
| 4 | Result and inputs copy member order | declared (inputs, protocol …; input, groups) | lexicographic | results.js |
| 5 | Patched RegExp.prototype.exec while matching | called for each component ada's fast paths do not cover; legacy all eight | not called | pollution.js |
| 6 | Legacy lone surrogates | WTF-8 | U+FFFD | conversions.js |
| 7 | Three arguments | an object or undefined second argument is the options (undefined: no baseURL); the third is read and ignored | the second is the baseURL (ToUSVString) | construction.js, conversions.js |
| 8 | Accessor names, constructor prototype, Symbol.toStringTag, global | JSG: anonymous, writable, writable, on the global's prototype (WebIDL under the opt-ins but the tag) | WebIDL | api-surface.js |
| 9 | Calling without new | JSG's TypeError message | the language's | construction.js |
| 10 | Object.prototype setters | groups always set, so a setter takes them; without enable_fast_jsg_struct results assigned too | data properties | pollution.js |
| 11 | inputs copy of an init under enable_fast_jsg_struct | every member, those absent undefined | the members present | results.js |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

