Repository files navigation

whatwg-url is a full implementation of the WHATWGURL Standard. 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 likejsdom.

whatwg-url is currently up to date with the URL spec up to commit6c78200.

Forfile: URLs, whoseorigin is left unspecified, 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, theencoding override parameter does not exist in our API.

The main API is provided by theURL andURLSearchParams 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 likeHTMLHyperlinkElementUtils. They mostly operate on or return an "internal URL" or"URL record" type.

• URL parser:parseURL(input, { baseURL })
• Basic URL parser:basicURLParse(input, { baseURL, url, stateOverride })
• URL serializer:serializeURL(urlRecord, excludeFragment)
• Host serializer:serializeHost(hostFromURLRecord)
• URL path serializer:serializePath(urlRecord)
• Serialize an integer:serializeInteger(number)
• Originserializer:serializeURLOrigin(urlRecord)
• Set the username:setTheUsername(urlRecord, usernameString)
• Set the password:setThePassword(urlRecord, passwordString)
• Has an opaque path:hasAnOpaquePath(urlRecord)
• Cannot have a username/password/port:cannotHaveAUsernamePasswordPort(urlRecord)
• Percent decode bytes:percentDecodeBytes(uint8Array)
• Percent decode a string:percentDecodeString(string)

ThestateOverride parameter is one of the following strings:

• "scheme start"
• "scheme"
• "no scheme"
• "special relative or authority"
• "path or authority"
• "relative"
• "relative slash"
• "special authority slashes"
• "special authority ignore slashes"
• "authority"
• "host"
• "hostname"
• "port"
• "file"
• "file slash"
• "file host"
• "path start"
• "path"
• "opaque path"
• "query"
• "fragment"

The URL record type has the following API:

• scheme
• username
• password
• host
• port
• path (as an array of strings, or a string)
• query
• fragment

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 ofbasicURLParse 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 parseinput with context object’s url asurl and fragment state asstate override." In between those two steps, a URL record is in an unusable state.

The return value of "failure" in the spec is represented bynull. That is, functions likeparseURL andbasicURLParse can returneither a URL recordornull.

This module exports theURL andURLSearchParamsinterface wrappers API generated bywebidl2js.

First, installNode.js. Then, fetch the dependencies of whatwg-url, by running from this directory:

npm install

To run tests:

npm test

To generate a coverage report:

npm run coverage

To build and run the live viewer:

npm run preparenpm run build-live-viewer

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

The jsdom project (including whatwg-url) is a community-driven project maintained by a team ofvolunteers. You could support us by:

• Getting professional support for whatwg-url as part of a Tidelift subscription. Tidelift helps making open source sustainable for us while giving teams assurances for maintenance, licensing, and security.
• Contributing directly to the project.