Skip to content

Commit 5553be3

Browse files
fiskerdanielleadams
authored andcommitted
doc: update code examples for node:url module
There are many things called `url` in this page including `url` module, `URL` instances, etc. The original example was not clear where these methods come from. PR-URL: #38645 Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent a98d631 commit 5553be3

File tree

1 file changed

+65
-19
lines changed

1 file changed

+65
-19
lines changed

doc/api/url.md

+65-19
Original file line numberDiff line numberDiff line change
@@ -1012,18 +1012,37 @@ added: v10.12.0
10121012
This function ensures the correct decodings of percent-encoded characters as
10131013
well as ensuring a cross-platform valid absolute path string.
10141014

1015-
```js
1016-
new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/
1017-
fileURLToPath('file:///C:/path/'); // Correct: C:\path\ (Windows)
1015+
```mjs
1016+
import { fileURLToPath } from 'url';
1017+
1018+
const __filename = fileURLToPath(import.meta.url);
1019+
1020+
new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/
1021+
fileURLToPath('file:///C:/path/'); // Correct: C:\path\ (Windows)
1022+
1023+
new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt
1024+
fileURLToPath('file://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows)
1025+
1026+
new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
1027+
fileURLToPath('file:///你好.txt'); // Correct: /你好.txt (POSIX)
1028+
1029+
new URL('file:///hello world').pathname; // Incorrect: /hello%20world
1030+
fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX)
1031+
```
1032+
1033+
```cjs
1034+
const { fileURLToPath } = require('url');
1035+
new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/
1036+
fileURLToPath('file:///C:/path/'); // Correct: C:\path\ (Windows)
10181037

1019-
new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt
1020-
fileURLToPath('file://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows)
1038+
new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt
1039+
fileURLToPath('file://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows)
10211040

1022-
new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
1023-
fileURLToPath('file:///你好.txt'); // Correct: /你好.txt (POSIX)
1041+
new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
1042+
fileURLToPath('file:///你好.txt'); // Correct: /你好.txt (POSIX)
10241043

1025-
new URL('file:///hello world').pathname; // Incorrect: /hello%20world
1026-
fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX)
1044+
new URL('file:///hello world').pathname; // Incorrect: /hello%20world
1045+
fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX)
10271046
```
10281047
10291048
### `url.format(URL[, options])`
@@ -1052,7 +1071,22 @@ string serializations of the URL. These are not, however, customizable in
10521071
any way. The `url.format(URL[, options])` method allows for basic customization
10531072
of the output.
10541073
1055-
```js
1074+
```mjs
1075+
import url from 'url';
1076+
const myURL = new URL('https://a:b@測試?abc#foo');
1077+
1078+
console.log(myURL.href);
1079+
// Prints https://a:b@xn--g6w251d/?abc#foo
1080+
1081+
console.log(myURL.toString());
1082+
// Prints https://a:b@xn--g6w251d/?abc#foo
1083+
1084+
console.log(url.format(myURL, { fragment: false, unicode: true, auth: false }));
1085+
// Prints 'https://測試/?abc'
1086+
```
1087+
1088+
```cjs
1089+
const url = require('url');
10561090
const myURL = new URL('https://a:b@測試?abc#foo');
10571091

10581092
console.log(myURL.href);
@@ -1076,17 +1110,28 @@ added: v10.12.0
10761110
This function ensures that `path` is resolved absolutely, and that the URL
10771111
control characters are correctly encoded when converting into a File URL.
10781112
1079-
```js
1080-
new URL(__filename); // Incorrect: throws (POSIX)
1081-
new URL(__filename); // Incorrect: C:\... (Windows)
1082-
pathToFileURL(__filename); // Correct: file:///... (POSIX)
1083-
pathToFileURL(__filename); // Correct: file:///C:/... (Windows)
1113+
```mjs
1114+
import { pathToFileURL } from 'url';
1115+
1116+
new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1
1117+
pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX)
1118+
1119+
new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c
1120+
pathToFileURL('/some/path%.c'); // Correct: file:///some/path%25.c (POSIX)
1121+
```
1122+
1123+
```cjs
1124+
const { pathToFileURL } = require('url');
1125+
new URL(__filename); // Incorrect: throws (POSIX)
1126+
new URL(__filename); // Incorrect: C:\... (Windows)
1127+
pathToFileURL(__filename); // Correct: file:///... (POSIX)
1128+
pathToFileURL(__filename); // Correct: file:///C:/... (Windows)
10841129

1085-
new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1
1086-
pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX)
1130+
new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1
1131+
pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX)
10871132

1088-
new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c
1089-
pathToFileURL('/some/path%.c'); // Correct: file:///some/path%25.c (POSIX)
1133+
new URL('/some/path%.c', 'file:'); // Incorrect: file:///some/path%.c
1134+
pathToFileURL('/some/path%.c'); // Correct: file:///some/path%25.c (POSIX)
10901135
```
10911136
10921137
### `url.urlToHttpOptions(url)`
@@ -1306,6 +1351,7 @@ The `url.format()` method returns a formatted URL string derived from
13061351
`urlObject`.
13071352
13081353
```js
1354+
const url = require('url');
13091355
url.format({
13101356
protocol: 'https',
13111357
hostname: 'example.com',

0 commit comments

Comments
 (0)