Node.js Reference · path, os and url
Node.js url.format() and domainToASCII()
Reference for url.format() with WHATWG URL options, plus domainToASCII() and domainToUnicode() for internationalized domain names and urlToHttpOptions().
url.format() turns a URL object into a string, and unlike url.href it lets you leave parts out: credentials, the query string, the fragment. That makes it useful for logging, where you want to print where a request went without leaking a password or a token in the query.
The same module has two helpers for internationalized domain names (IDN). domainToASCII() converts a Unicode host name to its Punycode form (xn--...), the form used on the wire, and domainToUnicode() converts back. Both return an empty string for a domain that is not valid.
import { format } from 'node:url'; const url = new URL('https://user:[email protected]/a?token=1#top'); format(url, { auth: false, search: false, fragment: false }); // 'https://example.com/a'
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
url.format(URL[, options]) url.format(urlObject) // legacy object form url.format(urlString) // legacy string form url.domainToASCII(domain) url.domainToUnicode(domain) url.urlToHttpOptions(url)
| Name | Description |
|---|---|
URL |
A WHATWG URL object. |
options.auth |
Keep the user:password@ part. Default true. |
options.fragment |
Keep the #hash part. Default true. |
options.search |
Keep the ?query part. Default true. |
options.unicode |
Show the host in Unicode instead of Punycode. Default false. |
domain |
A host name string, for the two domainTo... functions. |
Returns: a string. domainToASCII() and domainToUnicode() return '' when the input is not a valid domain.
Errors: format() with a first argument of an unsupported type throws ERR_INVALID_ARG_TYPE.
Usage notes
- With a
URLobject,format()never mutates it and honors only the four options above. - The legacy forms (a plain object with
protocol,host,pathname,query, or a string that is parsed first) still work but are deprecated along with the legacy parser. Prefernew URL()and set properties on it. url.hrefandurl.toString()always include everything. For safe logging, strip credentials withformat(url, { auth: false })and drop the query withsearch: false.- Punycode appears in
url.hostnameautomatically when you construct aURL; you only needdomainToASCII()for host names that are not part of a full URL, such as DNS or TLS options. - The result of
domainToASCII()follows the WHATWG URL host rules, which lower-case the name and reject forbidden characters. urlToHttpOptions()returns a plain object (protocol,hostname,port,path,auth,search,hash,href). It decodes credentials and strips IPv6 brackets, whichhttp.request(url)also does internally.domainToASCII()anddomainToUnicode()have been available since Node.js 7.4 and 8.4 respectively.