URL Parser

The anatomy of a URL, component by component

Every absolute URL is built from the same skeleton. The table below dissects one fully-loaded example so you can see exactly where each delimiter ends and the next component begins. The sample URL:

https://api:s3cr3t@shop.example.com:8443/v2/orders?status=open&status=paid#summary

The fragment never leaves the browser. It is not in the HTTP request line, so server logs, analytics backends, and CDNs never see it — which is why single-page apps historically used #/route for client-side routing.

Percent-encoding: when a character must be escaped

A URL may only contain a restricted set of ASCII characters. Anything outside that set — spaces, most punctuation, non-ASCII letters — must be percent-encoded: replaced by a % followed by the byte's two-digit hex value (UTF-8 for multi-byte characters). The catch is that reserved characters have a structural meaning, so whether they need encoding depends on where they appear. The table below lists the reserved characters and their codes.

The unreserved set — A–Z a–z 0–9 - _ . ~ — is never encoded and never needs to be. Encoding it anyway is legal but pointless, and some servers compare paths byte-for-byte, so %2D and - can be treated as different.

encodeURI vs encodeURIComponent: the one that bites everyone

JavaScript ships two encoders, and picking the wrong one is the single most common URL bug. The rule: use encodeURI on a whole URL, and encodeURIComponent on a single piece you are about to drop into one.

• encodeURI assumes its input is already a complete URL, so it leaves the structural characters : / ? # & = alone. It only escapes spaces and other illegal characters.
• encodeURIComponent assumes its input is just data, so it escapes : / ? # & = too — exactly what you want when that data could itself contain a slash, ampersand, or equals sign.

const term = "rock & roll/50%";

// WRONG — the & ends the parameter early, server sees q=rock
"/search?q=" + encodeURI(term)
//   ->  /search?q=rock%20&%20roll/50%25

// RIGHT — the whole value is escaped as one opaque chunk
"/search?q=" + encodeURIComponent(term)
//   ->  /search?q=rock%20%26%20roll%2F50%25

In modern code you usually skip both: build the query with URLSearchParams and it encodes each value for you. Note one historical quirk — URLSearchParams encodes a space as +, while encodeURIComponent uses %20. Both decode back to a space.

How repeated query keys are handled (and why it varies)

The URL spec does not define what ?tag=red&tag=bluemeans — that is left to the server. Different stacks resolve the same string differently, which is a frequent source of "it works in Postman but not in prod" bugs:

This parser shows every occurrence in order, so you can see the raw truth before your framework collapses it. When you genuinely need a list, prefer an explicit convention your backend documents — PHP and Rails expect tag[]=red&tag[]=blue.

Questions developers actually search for