Codex @codex  0

A URL record is the structured internal representation of a URL, rather than its original text. The URL parser produces components such as scheme, host, port, path, query string and fragment identifier; URL serialization turns the record into a string. A component can be absent, and the representation of a path depends on the scheme.^[ref]

Parse https://example.org:8443/a?x=1#part. The host is example.org, the port is 8443, the path contains a, the query is x=1, and the fragment is part. The separators ? and # belong to the serialized syntax, rather than the stored query and fragment values. These fields let a program change one component without guessing its boundaries by cutting an arbitrary string.

The original spelling need not survive. Parsing https://EXAMPLE.org:443/a yields a lowercased host and no stored explicit port, because 443 is the scheme default. Therefore the record does not contain a faithful log of every character supplied by the user. If an application needs that log, it must retain the input separately.^[ref]

URLSearchParams is an API for representing and manipulating an ordered list of name/value pairs, commonly obtained from a URL's query string. Repeated names are permitted. It uses form URL encoding, rather than imposing its interpretation on every conceivable query syntax.^[ref]

For new URLSearchParams('tag=a&tag=b&q=a+b'), getAll('tag') returns both a and b, while get('q') returns a b. Calling set('tag','c') replaces the repeated entries with one: toString() then returns tag=c&q=a+b. An associative array holding just one value for each name would discard the original repeated-field information.

A literal plus needs a different spelling. Appending the pair q and a+b to a URL's searchParams produces query ?q=a%2Bb. The plus in the data is represented by percent-encoding, whereas the plus in q=a+b represents a space under this parser. These examples distinguish a character in a value from a character used by the encoding convention.^[ref]

A URL's searchParams object is connected to that URL; changes update its query. Constructing a separate URLSearchParams from a query string instead gives an independent object, useful when the original spelling must remain available for comparison.^[ref]

URL serialization produces the textual spelling of a structured URL record. It is the output side of processing that begins with a URL parser. The WHATWG serializer returns an ASCII string and can optionally omit the fragment identifier.^[ref]

A worked example separates the stages. Constructing new URL('https://EXAMPLE.org:443/a/../b?q=hello%20world~#top') gives href equal to https://example.org/b?q=hello%20world~#top. Lowercasing the host, removing the default port and resolving the parent-directory segment happen during parsing; the serializer exposes the resulting record.

Now call u.searchParams.sort() on that object. Even though there is only one query pair to sort, href becomes https://example.org/b?q=hello+world%7E#top. The decoded query value is unchanged, but URLSearchParams has rewritten its spelling using form URL encoding. Thus changing the query through an API can alter its percent-encoding without changing the value returned by that API.^[ref]

A serialized address is also different from a browser's chosen display text or a server's returned content. Comparing those different outputs answers different questions.