URL and URLPattern

Owners: @nodejs/url.

Purpose

Implement the WHATWG URL and URLPattern standards as fast, spec-compliant primitives. URL is used everywhere — by import, by fetch, by http, by tests — so its parser performance materially affects boot time and request throughput. URLPattern is the newer pattern matcher used by routers and the customization-hooks resolver.

Directory layout

lib/
  url.js                    // legacy + WHATWG URL exports
  internal/url.js           // URL/URLSearchParams class implementations
src/
  node_url.{cc,h}            // C++ binding bridging ada
  node_url_pattern.{cc,h}    // URLPattern binding
deps/
  ada/                       // ada-url, vendored URL parser (C++)

Key abstractions

Type / file	Role
URL (lib/internal/url.js)	Spec-compliant URL class with caching of parsed components.
URLSearchParams (lib/internal/url.js)	Iterable searchParams object; mutates parent URL on update.
URLPattern (lib/internal/url.js)	Spec-compliant pattern matcher; thin shim over the C++ binding.
node_url::Parse (src/node_url.cc)	Calls ada::parse and returns parsed components to JS.
URLPatternData (src/node_url_pattern.cc)	Pattern object lifetime + match.

How URL parsing works

graph LR
    JS[new URL(input, base)] --> Cls[URL class]
    Cls --> Bind[internalBinding('url').domainTo* / parse]
    Bind --> Ada[ada::parse]
    Ada --> Parts[components: scheme, host, ...]
    Parts --> Cache[on the URL instance]
    Cls -- get .pathname etc. --> Cache

The hot path is C++-only: ada returns parsed components directly into a Uint32Array slice that the JS class uses to lazily expose getters. ada itself was written specifically as a high-performance WHATWG URL parser; the integration replaces a much older hand-rolled JavaScript parser.

Legacy url.parse API

url.parse(str) (the pre-WHATWG, callable API) is in lib/url.js. It is documented as "Legacy" in doc/api/url.md. Internally it still calls into the same parser but presents the older shape ({ protocol, host, port, pathname, search, hash, ... }).

URLPattern

URLPattern exposes spec-compliant pattern matching for resolution / routing:

const pat = new URLPattern({ pathname: '/users/:id' });
pat.exec('https://example.com/users/42'); // { groups: { id: '42' }, ... }

The match implementation lives in src/node_url_pattern.cc; it uses ada::url_pattern_*. The customization-hooks resolver uses URLPattern internally to express scoped resolution rules.

Integration points

• ESM resolver: the resolver in lib/internal/modules/esm/resolve.js accepts URLs and uses URLPattern for some package.json exports patterns.
• fetch / undici: Request, Response, fetch URL parsing all go through the same parser.
• Inspector / source maps: source URLs are normalized through URL.
• WPT tests: test/wpt/url/ and test/fixtures/wpt/url/ mirror the upstream URL test suite.

Entry points for modification

• Bug in URL parsing? Reproduce against the WPT suite (test/wpt/url/). The fix usually goes upstream to ada-url/ada and is bumped via tools/dep_updaters/update-ada.sh.
• JS-side getter behaviour? lib/internal/url.js.
• New URLPattern feature? Mirror in src/node_url_pattern.cc and lib/internal/url.js.