From 2c6c303dd05f8369c4cda8a6bd96c19e9d0ebab4 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Wed, 12 May 2021 12:13:16 +0200 Subject: [PATCH 1/2] doc: add ESM code examples in url.md --- doc/api/url.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/doc/api/url.md b/doc/api/url.md index ce528f5f6c8007..65f00db276efc6 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -9,7 +9,10 @@ The `url` module provides utilities for URL resolution and parsing. It can be accessed using: -```js +```mjs +import url from 'url'; +``` +```cjs const url = require('url'); ``` @@ -61,7 +64,12 @@ const myURL = Parsing the URL string using the Legacy API: -```js +```mjs +import url from 'url'; +const myURL = + url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'); +``` +```cjs const url = require('url'); const myURL = url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'); @@ -135,7 +143,11 @@ const myURL = new URL('/foo', 'https://example.org/'); The URL constructor is accessible as a property on the global object. It can also be imported from the built-in url module: -```js +```mjs +import { URL } from 'url'; +console.log(URL === globalThis.URL); // Prints 'true'. +``` +```cjs console.log(URL === require('url').URL); // Prints 'true'. ``` @@ -573,10 +585,6 @@ and [`url.format()`][] methods would produce. The `toString()` method on the `URL` object returns the serialized URL. The value returned is equivalent to that of [`url.href`][] and [`url.toJSON()`][]. -Because of the need for standard compliance, this method does not allow users -to customize the serialization process of the URL. For more flexibility, -[`require('url').format()`][] method might be of interest. - #### `url.toJSON()` * Returns: {string} @@ -932,7 +940,6 @@ 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')); @@ -957,7 +964,6 @@ 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')); @@ -1080,7 +1086,6 @@ This utility function converts a URL object into an ordinary options object as expected by the [`http.request()`][] and [`https.request()`][] APIs. ```js -const { urlToHttpOptions } = require('url'); const myURL = new URL('https://a:b@測試?abc#foo'); console.log(urlToHttpOptions(myUrl)); @@ -1124,8 +1129,8 @@ changes: > Stability: 3 - Legacy: Use the WHATWG URL API instead. -The legacy `urlObject` (`require('url').Url`) is created and returned by the -`url.parse()` function. +The legacy `urlObject` (`require('url').Url` or `import { Url } from 'url'`) is +created and returned by the `url.parse()` function. #### `urlObject.auth` @@ -1499,7 +1504,6 @@ console.log(myURL.origin); [`https.request()`]: https.md#https_https_request_options_callback [`new URL()`]: #url_new_url_input_base [`querystring`]: querystring.md -[`require('url').format()`]: #url_url_format_url_options [`url.domainToASCII()`]: #url_url_domaintoascii_domain [`url.domainToUnicode()`]: #url_url_domaintounicode_domain [`url.format()`]: #url_url_format_urlobject From baac479faa9dc3557679359a3d4eb20daf3dd3bc Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Thu, 13 May 2021 15:38:27 +0200 Subject: [PATCH 2/2] fixup! doc: add ESM code examples in url.md --- doc/api/url.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 52 insertions(+), 3 deletions(-) diff --git a/doc/api/url.md b/doc/api/url.md index 65f00db276efc6..b64bbc405f455e 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -12,6 +12,7 @@ accessed using: ```mjs import url from 'url'; ``` + ```cjs const url = require('url'); ``` @@ -69,6 +70,7 @@ import url from 'url'; const myURL = url.parse('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'); ``` + ```cjs const url = require('url'); const myURL = @@ -147,6 +149,7 @@ It can also be imported from the built-in url module: import { URL } from 'url'; console.log(URL === globalThis.URL); // Prints 'true'. ``` + ```cjs console.log(URL === require('url').URL); // Prints 'true'. ``` @@ -939,7 +942,20 @@ invalid domain, the empty string is returned. It performs the inverse operation to [`url.domainToUnicode()`][]. -```js +```mjs +import url from '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 +``` + +```cjs +const url = require('url'); + console.log(url.domainToASCII('español.com')); // Prints xn--espaol-zwa.com console.log(url.domainToASCII('中文.com')); @@ -963,7 +979,20 @@ domain, the empty string is returned. It performs the inverse operation to [`url.domainToASCII()`][]. -```js +```mjs +import url from '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 +``` + +```cjs +const url = require('url'); + console.log(url.domainToUnicode('xn--espaol-zwa.com')); // Prints español.com console.log(url.domainToUnicode('xn--fiq228c.com')); @@ -1085,7 +1114,27 @@ added: v15.7.0 This utility function converts a URL object into an ordinary options object as expected by the [`http.request()`][] and [`https.request()`][] APIs. -```js +```mjs +import { urlToHttpOptions } from 'url'; +const myURL = new URL('https://a:b@測試?abc#foo'); + +console.log(urlToHttpOptions(myUrl)); +/** +{ + protocol: 'https:', + hostname: 'xn--g6w251d', + hash: '#foo', + search: '?abc', + pathname: '/', + path: '/?abc', + href: 'https://a:b@xn--g6w251d/?abc#foo', + auth: 'a:b' +} +*/ +``` + +```cjs +const { urlToHttpOptions } = require('url'); const myURL = new URL('https://a:b@測試?abc#foo'); console.log(urlToHttpOptions(myUrl));