URL and URLSearchParams

// URL is a global — no import needed (WHATWG URL, same as browsers)
const u = new URL("https://user:pw@api.example.com:8443/v1/items?q=node&page=2#top");

u.href       // full string back
u.origin     // "https://api.example.com:8443"
u.protocol   // "https:"
u.host       // "api.example.com:8443"
u.hostname   // "api.example.com"
u.port       // "8443"
u.pathname   // "/v1/items"
u.search     // "?q=node&page=2"
u.searchParams  // URLSearchParams instance
u.hash       // "#top"
u.username   // "user"
u.password   // "pw"

// Throws TypeError on invalid input — validate without try/catch:
URL.canParse("not a url");            // false (Node 19.9+)
URL.parse("not a url");               // null instead of throwing (Node 22+)

// Resolve relative to a base
new URL("../users", "https://api.example.com/v1/items");
// → https://api.example.com/users

// Mutate parts — href updates automatically
u.pathname = "/v2/items";
u.searchParams.set("page", "3");
u.toString();

const params = new URLSearchParams("q=node&tag=js&tag=backend");

// Also constructable from object or entry pairs
new URLSearchParams({ q: "node", page: "2" });
new URLSearchParams([["tag", "js"], ["tag", "backend"]]);

params.get("q");          // "node" (first value or null)
params.getAll("tag");     // ["js", "backend"]
params.has("q");          // true
params.has("tag", "js");  // value-specific check (Node 20+)

params.set("page", "2");  // replace all values for key
params.append("tag", "web"); // add another value
params.delete("tag");        // remove all
params.delete("tag", "js");  // remove one value (Node 20+)

params.sort();               // stable sort by key (cache-key normalization)
params.size;                 // number of entries (Node 19+)
params.toString();           // "q=node&page=2" — percent-encoded

// Iterate
for (const [key, value] of params) { ... }
[...params.keys()]; [...params.values()]; [...params.entries()];

// → plain object (single-valued params only)
Object.fromEntries(params);

import http from "node:http";

http.createServer((req, res) => {
  // req.url is path + query only — supply the host as base
  const url = new URL(req.url, `http://${req.headers.host}`);
  const page = Number(url.searchParams.get("page") ?? 1);
  res.end(JSON.stringify({ path: url.pathname, page }));
}).listen(3000);

import { fileURLToPath, pathToFileURL } from "node:url";

fileURLToPath("file:///Users/me/app%20dir/index.js");
// "/Users/me/app dir/index.js" — handles percent-encoding + Windows drives

pathToFileURL("/Users/me/app dir/index.js").href;
// "file:///Users/me/app%20dir/index.js"

// Standard ESM idiom — path of the current module:
const selfPath = fileURLToPath(import.meta.url);
// or, Node 21.2+:
import.meta.filename; import.meta.dirname;

// Resolve a sibling file (works regardless of cwd)
new URL("./data.json", import.meta.url);

encodeURIComponent("a b&c");   // "a%20b%26c" — for individual values
decodeURIComponent("a%20b");   // "a b"
encodeURI("https://x.com/a b"); // encodes only what a full URL can't contain

// URLSearchParams encodes spaces as "+" (form encoding); components as %20
new URLSearchParams({ q: "a b" }).toString();  // "q=a+b"

// Punycode / IDN handled automatically
new URL("https://bücher.example").hostname;    // "xn--bcher-kva.example"

// domainToASCII / domainToUnicode for hostnames outside a URL
import { domainToASCII } from "node:url";
domainToASCII("español.com");   // "xn--espaol-zwa.com"