whatwg-url

• Added parseURLWithValidationErrors(), which records and returns validation errors per the standard's parsing algorithm, often performing additional checks on the input.
• Added isValidURLString(), which checks an input string against the standard's valid URL string predicate.
• Fixed userinfo parsing for astral code points (@spokodev, #333). This was a rare instance of whatwg-url failing to match the specification.

Notably, the new validation code allowed us to make significant progress on whatwg/url#704, and as far as we can tell at this point, the two types of validation agree.

Breaking change: now requires Node.js ^22.14.0 || >=24.0.0.

Updated the domain parser to have an ASCII fallback path, per whatwg/url@a8d5ca3.

Fixed URL.parse() to return a proper URL object, instead of an internal implementation object. This fixes, among other things, URL.parse(x) instanceof URL.

Breaking change: now requires Node.js versions ^20.19.0 || ^22.12.0 || >=24.0.0.

Added encoding support for query string parsing, via the new encoding options to parseURL() and basicURLParse(). (The URL API is not affected, as it always uses UTF-8.) Thanks to @ChALkeR and his excellent @exodus/bytes package for providing the foundation!

Updated our tr46 dependency, which updates our international domain name support to reflect Unicode 17.0.0.

Breaking change: now requires Node.js v20 or later.

Made minor updates to failure cases for "host"/"hostname" and "port" state override parsing, following URL Standard changes https://github.com/whatwg/url/commit/c23aec1a9a7433282abc61c1f21554cd53923b26 and https://github.com/whatwg/url/commit/cc8b776b89a6d92b5cc74581c8d90450d3c1e762. These have no impact on usage of the high-level APIs.

Updated our tr46 dependency, which updates our international domain name support to reflect Unicode 16.0.0. Also includes the related changes to the URL Standard:

• https://github.com/whatwg/url/commit/cd8f1d6c1ad0bab1cc8e40ad8ef6ee6626c57d57
• https://github.com/whatwg/url/commit/a6e4492001454d3d823108a4c48d77a6ad4eead5
• https://github.com/whatwg/url/commit/c3d173f3106e0e557a80e30e828edb369909e17b
• https://github.com/whatwg/url/commit/7f3e3b6866f8ef4d43562545c066e147a3f2a0b1

Added U+005E (^) to the path percent-encode set, per https://github.com/whatwg/url/commit/9bc33c39d4a6cd6a936ea7620b5a69f606ec0d4c.

Ensured opaque paths always roundtrip, per https://github.com/whatwg/url/commit/6c782003a2d53b1feecd072d1006eb8f1d65fb2d.

Improved performance for very long inputs.

Added URL.parse(), per https://github.com/whatwg/url/commit/58acb06dccec3e95a33d842337e61d25195d4b1b.

Breaking change: removed Node.js v16 support.

Breaking change: removed Node.js v14 support.

Added URL.canParse(), per https://github.com/whatwg/url/commit/ae3c28b84e3e7122c2807401c26b8a63cb2ab445.

Added URLSearchParams's size getter, per https://github.com/whatwg/url/commit/12b6f0c456c6df049e2704c92bb3a6d4d1364ec8.

Added optional second value argument to URLSearchParams's has() and delete() methods, per https://github.com/whatwg/url/commit/bfb9157186c237078cb1ac4998607d88242abe35.

Changed the serialization of the origin of blob: URLs whose inner URLs were not http: or https: to be "null", per https://github.com/whatwg/url/commit/eee49fdf4f99d59f717cbeb0bce29fda930196d4.

Updated our tr46 dependency, which brings along several fixes related to international domain names. Such as:

• Empty domain name labels, as in https://xn--4-0bd15808a.../, no longer cause URL parsing to fail.
• Invalid punycode-encoded domain name labels, as in http://xn--ls8h=/, now correctly cause URL parsing to fail.
• Includes support for Unicode 15.0.0.

As part of this, we are now running against the newly-introduced test data derived from the Unicode Consortium-maintained IdnaTestV2.txt file, and passing them all.

Breaking change: removed Node.js v12 support.

Changed the characters allowed in domains vs. generic hosts, per https://github.com/whatwg/url/commit/35e195a2cce7b82694284b8f60caeaf7b43087b4.

Changed the URL API's search and hash setters, as well as the URLSearchParams API, to always ensure the URL is serialize-parse roundtrippable, per https://github.com/whatwg/url/commit/fdaa0e5a3790693a82f578d7373f216d8fef9ac8.

The breaking changes in this release are only to the Low-level URL Standard API. No actual URL parsing or serialization behavior has changed, and users of the URL and URLSearchParams exports are not affected.

These changes follow https://github.com/whatwg/url/commit/fbaa03cb19ee5718953f5f6d179e0339e31f1ede.

• Removed the URL record type's cannotBeABaseURL property.
• Changed the URL record type's path from always being an array of strings, to being either a single string or an array of strings.
• Renamed the "cannot-be-a-base-URL path" parser state (i.e. value for stateOverride) to "opaque path".
• Added the serializePath(urlRecord) export.
• Added the hasAnOpaquePath(urlRecord) export.

The breaking changes in this release are to the API exported by the whatwg-url/webidl2js-wrapper module. In particular it now is based on webidl2js v17, which changes some of the exported function signatures, and changes the realms of any errors thrown on misuse.

Made the host parser reject non-IPv4 domains that end in numbers, per https://github.com/whatwg/url/commit/ab0e820b0b559610b30c731b7f2c1a8094181680.

Breaking changes:

• Removed Node.js v10 support.

• The percentDecode() export was renamed percentDecodeBytes(), and now returns a Uint8Array instead of a Node.js Buffer.

Other changes:

• The package's main module now exports the percentDecodeString() helper.

• The punycode and lodash dependencies were removed.

Make the pathname setter not mess up the URL's path state tracking when given the empty string, per https://github.com/whatwg/url/commit/0672f2e2ef43aca18b59d90abb6dac21712399bb.

Made the hostname setter do nothing if the given string contains a colon, per https://github.com/whatwg/url/commit/ec96993653a70d063843e0198694028c63348db4.

Updated punycode processing to support Unicode v13.

Disallowed | in host parsing, per https://github.com/whatwg/url/commit/40252530f93fe37f092be90583f82e9f337da1ab.

Fixed file: URL parsing cases which would cause different results when serialized-then-reparsed, per https://github.com/whatwg/url/commit/a19495e27ad95154543b46f751d1a1bf25553808.

Updated file: URL path normalization, per https://github.com/whatwg/url/commit/47efa0043d677fb51169cde72b60703bd8de83e3.

Fixed percentDecode to return a Buffer, like it did in v8.1.0, instead of a Uint8Array.

Exported percentDecode again; it went missing in v8.2.0.

Made <, >, and ^ in the host component cause parsing failures, per https://github.com/whatwg/url/commit/302ba419cb3248568243aaf7b5aca9003694d5c3.

Fixed the parsing-then-serializing of non-special URLs to be idempotent, per https://github.com/whatwg/url/commit/83adf0c9ca9a88948e1e5d93374ffded04eec727.

Changed fragment parsing so that U+0000 code points are now percent-encoded, instead of removed, per https://github.com/whatwg/url/commit/3d574017081f6594ce1fa7a5107027c83dbe931f.

Changed file: URL parsing so that if the host ends up empty after the Unicode ToASCII operation, it now result in parsing failure, per https://github.com/whatwg/url/commit/cceb4356cca233b6dfdaabd888263157b2204e44.

The breaking change in this release is raising the minimum Node.js version to v10.

This release introduces the whatwg-url/webidl2js-wrapper module, which can be used to install URL and URLSearchParams constructors on arbitrary global objects. (This is useful for jsdom, after jsdom/jsdom@5e39a4c). Consumers of the default whatwg-url module are not affected.

Removed gopher: special-case parsing and origin computation, per https://github.com/whatwg/url/commit/d589670451a4da9717bad69ed5d5364f93fede33 and https://github.com/whatwg/url/commit/7ae1c691c96f0d82fafa24c33aa1e8df9ffbf2bc.

Changed file: URLs to have an opaque origin, which serializes to "null". Previously all file: URLs shared an origin serialization of "file://". This is underspecified, so either behavior is technically correct, but opaque origins is the more conservative choice.

Improved error messages for invalid input URLs to include those input strings.

Upgraded our webidl2js built-time code-generation dependency from 7.4.x to 9.x; see that package's changelog for details.

Percent-encoded ' characters in the query portion of URLs with special schemes, per https://github.com/whatwg/url/commit/6ef17ebe1220a7e7c0cfff0785017502ee18808b.

Fixed the href setter to update the searchParams of a URL instance. (@TimothyGu, #114)

Changed percent-escaping rules in the query portion of URLs, per https://github.com/whatwg/url/commit/7a3c69f8a1583b33e730c3fea85141a618e7c697.

Fixed Windows drive letter handling when resolving relative to another Windows-drive-letter-containing URL, per https://github.com/whatwg/url/commit/2eef975e989cb5ae2d62467394778fd6778ddec9.

Updated to the new 1.x tr46 package, for fully spec- and tests-compliant host parsing.

Fixed URLSearchParams to remove the "?" from its parent URL if the query becomes empty, per https://github.com/whatwg/url/commit/43158268deb10343057998b8d761a193e9f3dc8a.

Made the scheme setter properly reset the port as appropriate, per https://github.com/whatwg/url/commit/0f53958338bbaec3882f902897873da59ba7e8bd.

Removed unused dependency (stable) from package.json.

Node.js v6 is now required, as we have started using JavaScript language features not present in earlier versions.

Added spec-compliant URLSearchParams support, both as an export and through the searchParams property of URL instances. (@TimothyGu)

Added the percentDecode function to the public API.

Added the cannotHaveAUsernamePasswordPort function to the public API. It was previously documented in the README, but accidentally not exported.

Changed the return value representing failure from the string "failure" to null.

Upgraded our webidl2js and webidl-conversions dependencies, bringing along various edge-case features and fixes, such as a proper Symbol.toStringTag on URL instances and better error messages.

Changed origin serialization to be the ASCII serialization of the origin, instead of the now-no-longer-a-thing Unicode serialization, per https://github.com/whatwg/url/commit/20c3257194db218c47526ba4ef4894a09e3847c9.

This changed the public API by removing serializeURLToUnicodeOrigin and instead exporting serializeURLOrigin.

Fixed Windows drive letter handling with a file: base URL, per https://github.com/whatwg/url/commit/fe6b251739e225555f04319f19c70c031a5d99eb.

Fixed a bug in parsing domains with empty labels, such as http://../.

Changed file URLs to trim leading slashes from their paths, per https://github.com/whatwg/url/commit/6103e0a58eb2460d409056fb2b93b015941b64f2.

Changed the protocol setter to do nothing when a URL has username, password, or port components, per https://github.com/whatwg/url/commit/462fdc14732aae4b0b9c5334f37962d8c235caf9.

Changed the URL record representation to sometimes have an empty string host, instead of a null host, per https://github.com/whatwg/url/commit/5807b28261e44a47e31683230137da395ddc79d8. (This does not impact the URL API, or parsing or serialization, but instead only the low-level URL record structure.)

Trimmed down the published npm package to no longer accidentally include a coverage/ directory and other miscellaneous files.

Changed host parsing to use nontransitional processing when converting to ASCII, per https://github.com/whatwg/url/commit/f4d84a52e67b154b2d11e04889fe0a35a029c833.

Removed a special-case in the hash setter for javascript URLs, per https://github.com/whatwg/url/commit/4bf85a08da18ef367e093426abef776d59e8fb7b.

Changed host parsing for URLs without a special scheme, per https://github.com/whatwg/url/commit/30362553e9ce9fc706d3492bd61886e399fc94e2 and https://github.com/whatwg/url/commit/cdbcce62045b1614695b00cc0427f6fb0fc7ed03.

Changed path parsing for URLs without a special scheme, per https://github.com/whatwg/url/commit/b087fe2ab215caf656a94b067c9a69ae78f03c8f.

Fixed parsing path-less file URLs without a base URL, per https://github.com/whatwg/url/commit/698f3e8f1d7de6d84c78ac81209fd780aca5ab7e.

Changed the URL API's username, password, port, host, and hostname accessors to work more correctly for file and non-special URLs, per https://github.com/whatwg/url/commit/cf616f9d3fca44bd5329e992519a4236a39b0cb7.

Added the toJSON() method to the URL class, per https://github.com/whatwg/url/commit/7dcfe5b5d766fd092b8ce09b6ab47ab2cb2a13f5.

Fixed percent-encoding to work correctly on U+FFFD, instead of dropping such characters.

Returned failure in state override scheme parsing, per https://github.com/whatwg/url/commit/4617e33b27d386bbf1db8c04316961d46aaa1397. (This only impacts consumers of this library using the stateOverride option.)

Disallowed invalid IPv4 addresses in the IPv6 parser, per https://github.com/whatwg/url/commit/a7ae1b846b91d564229faeaafdd28cb7451faa1d.

Fixed a bug where IPv6 address trailing zeros were not being compressed correctly. (#66, @rmisev)

Removed the distinction between null and empty-string passwords, per https://github.com/whatwg/url/commit/5e0b05e95a81fdd539c7b1bf97e69b3df701384f.

Stopped decoding all %2es in the path, per https://github.com/whatwg/url/commit/fbff6834a8a03576261f777d0e0afea5c1bc5a09.

Fixed a regression introduced in v3.1.0 for parsing file URLs relative to file base URLs when the base URL contained a Windows drive letter.

Updated fragment parsing to URL-encode non-ASCII code points, per https://github.com/whatwg/url/commit/373dbedbbf0596f723ce8a195923da98b698aeb0.

Removed the static methods URL.domainToUnicode() and URL.domainToASCII() per https://github.com/whatwg/url/commit/2bd0f59b98024921ab90e628b7a526cca5abcb5f.

Fixed some issues parsing relative URLs containing .. against file base URLs.

Updated the port setter per https://github.com/whatwg/url/commit/05ffaa644bc3cd4c6694ac6db11a072781af449c.

Fixed parsing schemes that have numbers in them.

Parsing failures are now handled differently (and more to-spec):

• new URL() now correctly throws for parsing failures.
• URL setters now ignore parsing failures, leaving the old value in place.
• URL-record-returning functions now will return the string "failure" in case of failure, instead of throwing.

Fixed an issue where the hostname setter would not work, due to a typo.

Updated the search setter per https://github.com/whatwg/url/commit/4f1c2ddbdb866b1150819622ec04a86813294059.

Updated to the latest spec. This includes:

• Removing all tab and newline characters from the input: https://github.com/whatwg/url/commit/7b40216f809c7fe3c9a1680b5c1b06a771c9ebd8#diff-03b21320f26423640f89c447968191e5R1737
• Renaming the "non-relative" flag to the "cannot-be-a-base-URL" flag: https://github.com/jsdom/whatwg-url/commit/4c896e9237ffbdd82f0e9bf0498bab31955e7e52 (a breaking change, since it affects the URL record API and stateOverride value)

Fixed an issue with percent-decoding which was not properly converting %2E into ., even though %2e was processed correctly.

Overhauled API to expose the URL constructor alongside the lower-level algorithms from the URL Standard.