diff --git a/doc/api/url.md b/doc/api/url.md index 934e65fabc664f..1356e7c038374f 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -131,6 +131,56 @@ The `slashes` property is a `boolean` with a value of `true` if two ASCII forward-slash characters (`/`) are required following the colon in the `protocol`. +## url.domainToASCII(domain) + + +> Stability: 1 - Experimental + +* `domain` {string} +* Returns: {string} + +Returns the [Punycode][] ASCII serialization of the `domain`. If `domain` is an +invalid domain, the empty string is returned. + +It performs the inverse operation to [`url.domainToUnicode()`][]. + +```js +const url = require('url'); +console.log(url.domainToASCII('español.com')); + // Prints xn--espaol-zwa.com +console.log(url.domainToASCII('中文.com')); + // Prints xn--fiq228c.com +console.log(url.domainToASCII('xn--iñvalid.com')); + // Prints an empty string +``` + +## url.domainToUnicode(domain) + + +> Stability: 1 - Experimental + +* `domain` {string} +* Returns: {string} + +Returns the Unicode serialization of the `domain`. If `domain` is an invalid +domain, the empty string is returned. + +It performs the inverse operation to [`url.domainToASCII()`][]. + +```js +const url = require('url'); +console.log(url.domainToUnicode('xn--espaol-zwa.com')); + // Prints español.com +console.log(url.domainToUnicode('xn--fiq228c.com')); + // Prints 中文.com +console.log(url.domainToUnicode('xn--iñvalid.com')); + // Prints an empty string +``` + ## url.format(urlObject) > Stability: 1 - Experimental @@ -210,7 +263,7 @@ The formatting process operates as follows: fragment, `false` otherwise. Defaults to `true`. * `search` {boolean} `true` if the serialized URL string should include the search query, `false` otherwise. Defaults to `true`. - * `unicode` (Boolean) `true` if Unicode characters appearing in the host + * `unicode` {boolean} `true` if Unicode characters appearing in the host component of the URL string should be encoded directly as opposed to being Punycode encoded. Defaults to `false`. @@ -308,6 +361,9 @@ For example, the ASCII space character (`' '`) is encoded as `%20`. The ASCII forward slash (`/`) character is encoded as `%3C`. ## The WHATWG URL API + > Stability: 1 - Experimental @@ -695,6 +751,9 @@ console.log(JSON.stringify(myURLs)); ``` ### Class: URLSearchParams + The `URLSearchParams` API provides read and write access to the query of a `URL`. The `URLSearchParams` class can also be used standalone with one of the @@ -767,6 +826,9 @@ console.log(params.toString()); ``` #### Constructor: new URLSearchParams(obj) + * `obj` {Object} An object representing a collection of key-value pairs @@ -790,6 +852,9 @@ console.log(params.toString()); ``` #### Constructor: new URLSearchParams(iterable) + * `iterable` {Iterable} An iterable object whose elements are key-value pairs @@ -949,6 +1014,9 @@ console.log(params.toString()); ``` #### urlSearchParams.sort() + Sort all existing name-value pairs in-place by their names. Sorting is done with a [stable sorting algorithm][], so relative order between name-value pairs @@ -997,52 +1065,6 @@ for (const [name, value] of params) { // xyz baz ``` -### require('url').domainToASCII(domain) - -* `domain` {string} -* Returns: {string} - -Returns the [Punycode][] ASCII serialization of the `domain`. If `domain` is an -invalid domain, the empty string is returned. - -It performs the inverse operation to [`require('url').domainToUnicode()`][]. - -```js -const url = require('url'); -console.log(url.domainToASCII('español.com')); - // Prints xn--espaol-zwa.com -console.log(url.domainToASCII('中文.com')); - // Prints xn--fiq228c.com -console.log(url.domainToASCII('xn--iñvalid.com')); - // Prints an empty string -``` - -*Note*: The `require('url').domainToASCII()` method is introduced as part of -the new `URL` implementation but is not part of the WHATWG URL standard. - -### require('url').domainToUnicode(domain) - -* `domain` {string} -* Returns: {string} - -Returns the Unicode serialization of the `domain`. If `domain` is an invalid -domain, the empty string is returned. - -It performs the inverse operation to [`require('url').domainToASCII()`][]. - -```js -const url = require('url'); -console.log(url.domainToUnicode('xn--espaol-zwa.com')); - // Prints español.com -console.log(url.domainToUnicode('xn--fiq228c.com')); - // Prints 中文.com -console.log(url.domainToUnicode('xn--iñvalid.com')); - // Prints an empty string -``` - -*Note*: The `require('url').domainToUnicode()` API is introduced as part of the -the new `URL` implementation but is not part of the WHATWG URL standard. - ### Percent-Encoding in the WHATWG URL Standard @@ -1092,6 +1114,8 @@ console.log(myURL.origin); [`TypeError`]: errors.html#errors_class_typeerror [WHATWG URL Standard]: https://url.spec.whatwg.org/ [examples of parsed URLs]: https://url.spec.whatwg.org/#example-url-parsing +[`url.domainToASCII()`]: #url_url_domaintoascii_domain +[`url.domainToUnicode()`]: #url_url_domaintounicode_domain [`url.parse()`]: #url_url_parse_urlstring_parsequerystring_slashesdenotehost [`url.format()`]: #url_url_format_urlobject [`require('url').format()`]: #url_url_format_url_options @@ -1107,8 +1131,6 @@ console.log(myURL.origin); [`URLSearchParams`]: #url_class_urlsearchparams [`urlSearchParams.entries()`]: #url_urlsearchparams_entries [`urlSearchParams@@iterator()`]: #url_urlsearchparams_iterator -[`require('url').domainToASCII()`]: #url_require_url_domaintoascii_domain -[`require('url').domainToUnicode()`]: #url_require_url_domaintounicode_domain [stable sorting algorithm]: https://en.wikipedia.org/wiki/Sorting_algorithm#Stability [`JSON.stringify()`]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [`url.toJSON()`]: #url_url_tojson