An implementation of the WHATWG URL Standard's URL API and parsing machinery. 

An implementation of the WHATWG URL Standard's URL API and parsing machinery

timothygu

tmpvar

domenic

sebmaster

joris-van-der-wel

zirro

whatwg-url

const { utf8DecodeWithoutBOM } = require("./encoding");

const { percentDecodeString, utf8PercentEncodeCodePoint, utf8PercentEncodeString, isC0ControlPercentEncode,

  isFragmentPercentEncode, isQueryPercentEncode, isSpecialQueryPercentEncode, isPathPercentEncode,

  isUserinfoPercentEncode } = require("./percent-encoding");

  return isNaN(c) ? undefined : String.fromCodePoint(c);

  return buffer === "." || buffer.toLowerCase() === "%2e";

  return buffer === ".." || buffer === "%2e." || buffer === ".%2e" || buffer === "%2e%2e";

function isWindowsDriveLetterCodePoints(cp1, cp2) {

  return infra.isASCIIAlpha(cp1) && (cp2 === 58 || cp2 === 124);

function isWindowsDriveLetterString(string) {

  return string.length === 2 && infra.isASCIIAlpha(string.codePointAt(0)) && (string[1] === ":" || string[1] === "|");

function isNormalizedWindowsDriveLetterString(string) {

  return string.length === 2 && infra.isASCIIAlpha(string.codePointAt(0)) && string[1] === ":";

function containsForbiddenHostCodePoint(string) {

  return string.search(/\u0000|\u0009|\u000A|\u000D|\u0020|#|%|\/|:|<|>|\?|@|\[|\\|\]|\^|\|/) !== -1;

function containsForbiddenHostCodePointExcludingPercent(string) {

  return string.search(/\u0000|\u0009|\u000A|\u000D|\u0020|#|\/|:|<|>|\?|@|\[|\\|\]|\^|\|/) !== -1;

  return specialSchemes[scheme] !== undefined;

  if (input.length >= 2 && input.charAt(0) === "0" && input.charAt(1).toLowerCase() === "x") {

  } else if (input.length >= 2 && input.charAt(0) === "0") {

    if (this.stateOverride === "hostname") {

    const host = parseHost(this.buffer, isNotSpecial(this.url));

  } else if (isNaN(c) || c === 47 || c === 63 || c === 35 ||

             (isSpecial(this.url) && c === 92)) {

    if (isSpecial(this.url) && this.buffer === "") {

    } else if (this.stateOverride && this.buffer === "" &&

               (includesCredentials(this.url) || this.url.port !== null)) {

URLStateMachine.prototype["parse port"] = function parsePort(c, cStr) {

             (isSpecial(this.url) && c === 92) ||

      const port = parseInt(this.buffer);

      this.url.port = port === defaultPort(this.url.scheme) ? null : port;

const fileOtherwiseCodePoints = new Set([47, 92, 63, 35]);

function startsWithWindowsDriveLetter(input, pointer) {

    isWindowsDriveLetterCodePoints(input[pointer], input[pointer + 1]) &&

    (length === 2 || fileOtherwiseCodePoints.has(input[pointer + 2]));

URLStateMachine.prototype["parse file"] = function parseFile(c) {

  } else if (this.base !== null && this.base.scheme === "file") {

    this.url.path = this.base.path.slice();

      if (!startsWithWindowsDriveLetter(this.input, this.pointer)) {

  "description": "An implementation of the WHATWG URL Standard's URL API and parsing machinery",

  "author": "Sebastian Mayr <github@smayr.name>",

    "prepare": "node scripts/transform.js",

    "pretest": "node scripts/get-latest-platform-tests.js && node scripts/transform.js",

    "build-live-viewer": "browserify index.js --standalone whatwgURL > live-viewer/whatwg-url.js",

      "^<rootDir>/test/web-platform-tests/"

whatwg-url is a full implementation of the WHATWG [URL Standard](https://url.spec.whatwg.org/). It can be used standalone, but it also exposes a lot of the internal algorithms that are useful for integrating a URL parser into a project like [jsdom](https://github.com/jsdom/jsdom).

whatwg-url is currently up to date with the URL spec up to commit [0915d88](https://github.com/whatwg/url/commit/0915d886bbf409331857f56e6d2bfd0cb5e01de7).

whatwg-url is currently up to date with the URL spec up to commit [6d4669a](https://github.com/whatwg/url/commit/6d4669a9a8cc90582bdb1e3cdb758e45242812b0).

For `file:` URLs, whose [origin is left unspecified](https://url.spec.whatwg.org/#concept-url-origin), whatwg-url chooses to use a new opaque origin (which serializes to `"null"`).

whatwg-url does not yet implement any encoding handling beyond UTF-8. That is, the _encoding override_ parameter does not exist in our API.

### The `URL` and `URLSearchParams` classes

The main API is provided by the [`URL`](https://url.spec.whatwg.org/#url-class) and [`URLSearchParams`](https://url.spec.whatwg.org/#interface-urlsearchparams) exports, which follows the spec's behavior in all ways (including e.g. `USVString` conversion). Most consumers of this library will want to use these.

The following methods are exported for use by places like jsdom that need to implement things like [`HTMLHyperlinkElementUtils`](https://html.spec.whatwg.org/#htmlhyperlinkelementutils). They mostly operate on or return an "internal URL" or ["URL record"](https://url.spec.whatwg.org/#concept-url) type.

- [URL parser](https://url.spec.whatwg.org/#concept-url-parser): `parseURL(input, { baseURL })`

- [Basic URL parser](https://url.spec.whatwg.org/#concept-basic-url-parser): `basicURLParse(input, { baseURL, url, stateOverride })`

- [URL serializer](https://url.spec.whatwg.org/#concept-url-serializer): `serializeURL(urlRecord, excludeFragment)`

- [Host serializer](https://url.spec.whatwg.org/#concept-host-serializer): `serializeHost(hostFromURLRecord)`

- [Serialize an integer](https://url.spec.whatwg.org/#serialize-an-integer): `serializeInteger(number)`

- [Origin](https://url.spec.whatwg.org/#concept-url-origin) [serializer](https://html.spec.whatwg.org/multipage/origin.html#ascii-serialisation-of-an-origin): `serializeURLOrigin(urlRecord)`

- [Set the username](https://url.spec.whatwg.org/#set-the-username): `setTheUsername(urlRecord, usernameString)`

- [Set the password](https://url.spec.whatwg.org/#set-the-password): `setThePassword(urlRecord, passwordString)`

- [Cannot have a username/password/port](https://url.spec.whatwg.org/#cannot-have-a-username-password-port): `cannotHaveAUsernamePasswordPort(urlRecord)`

- [Percent decode](https://url.spec.whatwg.org/#percent-decode): `percentDecode(buffer)`

The `stateOverride` parameter is one of the following strings:

- [`"scheme start"`](https://url.spec.whatwg.org/#scheme-start-state)

- [`"scheme"`](https://url.spec.whatwg.org/#scheme-state)

- [`"no scheme"`](https://url.spec.whatwg.org/#no-scheme-state)

- [`"special relative or authority"`](https://url.spec.whatwg.org/#special-relative-or-authority-state)

- [`"path or authority"`](https://url.spec.whatwg.org/#path-or-authority-state)

- [`"relative"`](https://url.spec.whatwg.org/#relative-state)

- [`"relative slash"`](https://url.spec.whatwg.org/#relative-slash-state)

- [`"special authority slashes"`](https://url.spec.whatwg.org/#special-authority-slashes-state)

- [`"special authority ignore slashes"`](https://url.spec.whatwg.org/#special-authority-ignore-slashes-state)

- [`"authority"`](https://url.spec.whatwg.org/#authority-state)

- [`"host"`](https://url.spec.whatwg.org/#host-state)

- [`"hostname"`](https://url.spec.whatwg.org/#hostname-state)

- [`"port"`](https://url.spec.whatwg.org/#port-state)

- [`"file"`](https://url.spec.whatwg.org/#file-state)

- [`"file slash"`](https://url.spec.whatwg.org/#file-slash-state)

- [`"file host"`](https://url.spec.whatwg.org/#file-host-state)

- [`"path start"`](https://url.spec.whatwg.org/#path-start-state)

- [`"path"`](https://url.spec.whatwg.org/#path-state)

- [`"cannot-be-a-base-URL path"`](https://url.spec.whatwg.org/#cannot-be-a-base-url-path-state)

- [`"query"`](https://url.spec.whatwg.org/#query-state)

- [`"fragment"`](https://url.spec.whatwg.org/#fragment-state)

The URL record type has the following API:

- [`scheme`](https://url.spec.whatwg.org/#concept-url-scheme)

- [`username`](https://url.spec.whatwg.org/#concept-url-username)

- [`password`](https://url.spec.whatwg.org/#concept-url-password)

- [`host`](https://url.spec.whatwg.org/#concept-url-host)

- [`port`](https://url.spec.whatwg.org/#concept-url-port)

- [`path`](https://url.spec.whatwg.org/#concept-url-path) (as an array)

- [`query`](https://url.spec.whatwg.org/#concept-url-query)

- [`fragment`](https://url.spec.whatwg.org/#concept-url-fragment)

- [`cannotBeABaseURL`](https://url.spec.whatwg.org/#url-cannot-be-a-base-url-flag) (as a boolean)

These properties should be treated with care, as in general changing them will cause the URL record to be in an inconsistent state until the appropriate invocation of `basicURLParse` is used to fix it up. You can see examples of this in the URL Standard, where there are many step sequences like "4. Set context object’s url’s fragment to the empty string. 5. Basic URL parse _input_ with context object’s url as _url_ and fragment state as _state override_." In between those two steps, a URL record is in an unusable state.

The return value of "failure" in the spec is represented by `null`. That is, functions like `parseURL` and `basicURLParse` can return _either_ a URL record _or_ `null`.

### `whatwg-url/webidl2js-wrapper` module

This module exports the `URL` and `URLSearchParams` [interface wrappers API](https://github.com/jsdom/webidl2js#for-interfaces) generated by [webidl2js](https://github.com/jsdom/webidl2js).

First, install [Node.js](https://nodejs.org/). Then, fetch the dependencies of whatwg-url, by running from this directory:

Serve the contents of the `live-viewer` directory using any web server.

The jsdom project (including whatwg-url) is a community-driven project maintained by a team of [volunteers](https://github.com/orgs/jsdom/people). You could support us by:

- [Getting professional support for whatwg-url](https://tidelift.com/subscription/pkg/npm-whatwg-url?utm_source=npm-whatwg-url&utm_medium=referral&utm_campaign=readme) as part of a Tidelift subscription. Tidelift helps making open source sustainable for us while giving teams assurances for maintenance, licensing, and security.

		@@ -759,2 +759,6 @@ "use strict";

		if (this.stateOverride === "hostname") {
		return false;
		}

		const host = parseHost(this.buffer, isNotSpecial(this.url));
		@@ -768,5 +772,2 @@ if (host === failure) {
		this.state = "port";
		if (this.stateOverride === "hostname") {
		return false;
		}
		} else if (isNaN(c) \|\| c === 47 \|\| c === 63 \|\| c === 35 \|\|
		@@ -773,0 +774,0 @@ (isSpecial(this.url) && c === 92)) {

		{
		"name": "whatwg-url",
		"version": "8.5.0",
		"version": "8.6.0",
		"description": "An implementation of the WHATWG URL Standard's URL API and parsing machinery",
		@@ -16,3 +16,3 @@ "main": "index.js",
		"lodash": "^4.7.0",
		"tr46": "^2.0.2",
		"tr46": "^2.1.0",
		"webidl-conversions": "^6.1.0"
		@@ -23,6 +23,6 @@ },
		"domexception": "^2.0.1",
		"eslint": "^7.20.0",
		"glob": "^7.1.6",
		"got": "^11.8.1",
		"jest": "^26.6.3",
		"eslint": "^7.28.0",
		"glob": "^7.1.7",
		"got": "^11.8.2",
		"jest": "^27.0.4",
		"recast": "^0.20.4",
		@@ -29,0 +29,0 @@ "webidl2js": "^16.2.0"

Improved metrics

Dependency changes

		@@ -7,3 +7,3 @@ # whatwg-url

		whatwg-url is currently up to date with the URL spec up to commit [0915d88](https://github.com/whatwg/url/commit/0915d886bbf409331857f56e6d2bfd0cb5e01de7).
		whatwg-url is currently up to date with the URL spec up to commit [6d4669a](https://github.com/whatwg/url/commit/6d4669a9a8cc90582bdb1e3cdb758e45242812b0).

		@@ -10,0 +10,0 @@ For `file:` URLs, whose [origin is left unspecified](https://url.spec.whatwg.org/#concept-url-origin), whatwg-url chooses to use a new opaque origin (which serializes to `"null"`).