# whatwg-url
whatwg-url is a full implementation of the WHATWG URL 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 like jsdom.
whatwg-url is currently up to date with the URL spec up to commit a62223.
The main API is the URL
export, which follows the spec's behavior in all ways (including e.g. USVString
conversion). Most consumers of this library will want to use this.
The following methods are exported for use by places like jsdom that need to implement things like HTMLHyperlinkElementUtils
. They operate on or return an "internal URL" or "URL record" type.
parseURL(input, { baseURL, encodingOverride })
basicURLParse(input, { baseURL, encodingOverride, url, stateOverride })
serializeURL(urlRecord, excludeFragment)
serializeHost(hostFromURLRecord)
serializeInteger(number)
serializeURLOrigin(urlRecord)
setTheUsername(urlRecord, usernameString)
setThePassword(urlRecord, passwordString)
cannotHaveAUsernamePasswordPort(urlRecord)
The stateOverride
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"
"cannot-be-a-base-URL path"
"query"
"fragment"
The URL record type has the following API:
scheme
username
password
host
port
path
(as an array)query
fragment
cannotBeABaseURL
(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 the string "failure"
. That is, functions like parseURL
and basicURLParse
can return either a URL record or the string "failure"
.