diff --git a/doc/api/url.md b/doc/api/url.md index 1063baefc849bb..27b3b69e4447d2 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -1012,18 +1012,37 @@ added: v10.12.0 This function ensures the correct decodings of percent-encoded characters as well as ensuring a cross-platform valid absolute path string. -```js -new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/ -fileURLToPath('file:///C:/path/'); // Correct: C:\path\ (Windows) +```mjs +import { fileURLToPath } from 'url'; + +const __filename = fileURLToPath(import.meta.url); + +new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/ +fileURLToPath('file:///C:/path/'); // Correct: C:\path\ (Windows) + +new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt +fileURLToPath('file://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows) + +new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt +fileURLToPath('file:///你好.txt'); // Correct: /你好.txt (POSIX) + +new URL('file:///hello world').pathname; // Incorrect: /hello%20world +fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX) +``` + +```cjs +const { fileURLToPath } = require('url'); +new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/ +fileURLToPath('file:///C:/path/'); // Correct: C:\path\ (Windows) -new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt -fileURLToPath('file://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows) +new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt +fileURLToPath('file://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows) -new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt -fileURLToPath('file:///你好.txt'); // Correct: /你好.txt (POSIX) +new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt +fileURLToPath('file:///你好.txt'); // Correct: /你好.txt (POSIX) -new URL('file:///hello world').pathname; // Incorrect: /hello%20world -fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX) +new URL('file:///hello world').pathname; // Incorrect: /hello%20world +fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX) ``` ### `url.format(URL[, options])` @@ -1052,7 +1071,22 @@ string serializations of the URL. These are not, however, customizable in any way. The `url.format(URL[, options])` method allows for basic customization of the output. -```js +```mjs +import url from 'url'; +const myURL = new URL('https://a:b@測試?abc#foo'); + +console.log(myURL.href); +// Prints https://a:b@xn--g6w251d/?abc#foo + +console.log(myURL.toString()); +// Prints https://a:b@xn--g6w251d/?abc#foo + +console.log(url.format(myURL, { fragment: false, unicode: true, auth: false })); +// Prints 'https://測試/?abc' +``` + +```cjs +const url = require('url'); const myURL = new URL('https://a:b@測試?abc#foo'); console.log(myURL.href); @@ -1076,17 +1110,28 @@ added: v10.12.0 This function ensures that `path` is resolved absolutely, and that the URL control characters are correctly encoded when converting into a File URL. -```js -new URL(__filename); // Incorrect: throws (POSIX) -new URL(__filename); // Incorrect: C:\... (Windows) -pathToFileURL(__filename); // Correct: file:///... (POSIX) -pathToFileURL(__filename); // Correct: file:///C:/... (Windows) +```mjs +import { pathToFileURL } from 'url'; + +new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1 +pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX) + +new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c +pathToFileURL('/some/path%.c'); // Correct: file:///some/path%25.c (POSIX) +``` + +```cjs +const { pathToFileURL } = require('url'); +new URL(__filename); // Incorrect: throws (POSIX) +new URL(__filename); // Incorrect: C:\... (Windows) +pathToFileURL(__filename); // Correct: file:///... (POSIX) +pathToFileURL(__filename); // Correct: file:///C:/... (Windows) -new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1 -pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX) +new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1 +pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX) -new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c -pathToFileURL('/some/path%.c'); // Correct: file:///some/path%25.c (POSIX) +new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c +pathToFileURL('/some/path%.c'); // Correct: file:///some/path%25.c (POSIX) ``` ### `url.urlToHttpOptions(url)` @@ -1317,6 +1362,7 @@ The `url.format()` method returns a formatted URL string derived from `urlObject`. ```js +const url = require('url'); url.format({ protocol: 'https', hostname: 'example.com',