Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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

Node.js Formatting with options

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.

Node.js Domain names and Punycode

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

NODE
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 URL object, 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. Prefer new URL() and set properties on it.
  • url.href and url.toString() always include everything. For safe logging, strip credentials with format(url, { auth: false }) and drop the query with search: false.
  • Punycode appears in url.hostname automatically when you construct a URL; you only need domainToASCII() 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, which http.request(url) also does internally.
  • domainToASCII() and domainToUnicode() have been available since Node.js 7.4 and 8.4 respectively.