workerd / url
AGENTS.md9.2k starsChanged 8 months agoApache-2.0View on GitHub
An informal specification of URL and URLSearchParams 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 (url-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…
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/urlpattern/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
2 rules. About 0 are common, 0 are distinctive, and 2 are 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 36
Setters: only href throws (Failed to set the 'href' property on 'URL': ...).
- Very specific: line 52
Serialization: every URL, URLSearchParams and iterator throws DataCloneError: Could not serialize object of type "<constructor>".
≈ “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
URL and URLSearchParams
An informal specification of URL and URLSearchParams 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
(url-modules.capnp) against the C++ implementations and the TypeScript
one:
| Cell | Implementation | Flags the suite branches on |
url-standard-cpp | api/url-standard.{h,c++} (ada) | url_standard, urlsearchparams_delete_has_value_arg, set_tostring_tag |
url-standard-legacy-flags-cpp | the same | url_standard, no_urlsearchparams_delete_has_value_arg, do_not_set_tostring_tag |
url-legacy-cpp | api/url.{h,c++} (kj::Url) | url_original, workers_api_getters_setters_on_prototype, set_tostring_tag, urlsearchparams_delete_has_value_arg |
url-legacy-instance-cpp | the same, attributes on each instance | url_original, workers_api_getters_setters_on_instance, do_not_set_tostring_tag, no_urlsearchparams_delete_has_value_arg |
url-opt-in-cpp | standard, with the dateless WebIDL opt-ins | standard + spec_compliant_property_attributes, immutable_api_prototypes (--experimental) |
url-standard-ts, url-standard-legacy-flags-ts, url-legacy-ts, url-legacy-instance-ts | src/per_isolate/url/, under the TS_URL 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 backend is ada; the legacy backend is
kj::Url, whose results, quirks included, are pinned as they are (setters.js,construction.js, and the URL test datakj::Urlpasses inlegacy-conformance.js). Legacy constructor errors distinguishInvalid base URL string.; the standard one saysInvalid URL string.for everything. - Setters: only
hrefthrows (Failed to set the 'href' property on 'URL': ...); the others leave the URL unchanged on a value they reject. The legacyhost,hostnameandportsetters do not validate. A hostkj::Urlcannot stringify, or a path whose%2Eit decoded, makeshref,toString(),toJSON()and theprotocol,usernameandpasswordsetters throwInvalid hostname when stringifying URL.orInvalid pathname when stringifying URL. - searchParams is the same object for the URL's lifetime. The
hrefandsearchsetters reach it, and every mutator, even one that changes nothing, reserializes the URL's query (?a=b%20cbecomes?a=b+c). - Arguments: a missing required argument is a TypeError; an explicit
undefinedconverts to"undefined",nullto"null". The standard path converts to USVStrings (a lone surrogate becomes U+FFFD); the legacy one keeps the WTF-8 bytes. - Iteration is live by index: deleting the current entry skips the next,
appended entries are visited, and
doneis not sticky. - Serialization: every URL, URLSearchParams and iterator throws
DataCloneError: Could not serialize object of type "<constructor>".
Ledger
| # | Area | C++ | TypeScript | Test |
| 1 | Legacy instance layout | 12 own native data properties, reverse WebIDL order | own accessors, same order | api-surface.js |
| 2 | Constructors' prototype | writable unless immutable_api_prototypes | non-writable | api-surface.js |
| 3 | Calling without new | JSG's TypeError message | the language's | construction.js |
| 4 | Serialization message | names the constructor | the same | serialization.js |
| 4a | Iterator serialization message | EntryIterator, ... | follows #6 | serialization.js |
| 5 | Member order | standard: origin first, searchParams after hash; legacy: WebIDL attributes, toString before toJSON | WebIDL | api-surface.js, inspect.js |
| 6 | Iterators | three prototypes and tags (EntryIterator, ...), @@iterator !== entries | one URLSearchParams Iterator prototype, @@iterator === entries | iteration.js, api-surface.js, illegal-invocation.js |
| 9 | Iterator results and Object.prototype setters | without enable_fast_jsg_struct, made by assignment: done/value setters run | object literals | pollution.js |
| 13 | Function lengths, accessor names | 0 and anonymous, unless spec_compliant_property_attributes | WebIDL | api-surface.js |
| 14 | Globals | on the global's prototype; also own under spec_compliant_property_attributes | own only | api-surface.js |
| 15 | Legacy statics | none | canParse, parse, createObjectURL, revokeObjectURL | api-surface.js, construction.js |
| 16 | Legacy initializer | arrays and dicts: a Map or other iterable is a dict of its own properties | WebIDL union | search-params.js |
| 17 | Legacy lone surrogates | WTF-8 | U+FFFD | conversions.js |
| 18 | forEach(cb, null) receiver | undefined | null | iteration.js |
| 20 | Symbol.toStringTag | writable | non-writable | api-surface.js |
| 21 | Initializer with a non-callable @@iterator | a record | TypeError | search-params.js |
| 22 | Legacy-instance URL.prototype | toString, toJSON only | the accessors too | api-surface.js |
| 23 | Legacy delete/has value under urlsearchparams_delete_has_value_arg | ignored | honored | search-params.js |
| 24 | Iterator result shape | { done, value }; without enable_fast_jsg_struct the last lacks value | { value, done } | iteration.js |
| 25 | Record initializer read order | every key's descriptor, then every value | each key's descriptor, then its value | search-params.js |
| 26 | Record initializer with an enumerable Symbol key | skipped | TypeError, as WPT's headers-record.any.js requires of records | search-params.js |
| 27 | Standard sequence initializer's final iterator result | its value is appended, a generator's return value included | ignored | search-params.js |
Rows the plan keeps but no test here covers: #7 and #11 (now matches), #8 and #19 (WPT), #10 (RPC; with the TS cells) and #12 (heap snapshots).
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.

