Skip to content

Commit 6d1c3e5

Browse files
committed
doc: clarify url doc
Indicate that `base` is ignored if `input` is absolute. PR-URL: #19899 Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
1 parent afb4d55 commit 6d1c3e5

File tree

1 file changed

+29
-1
lines changed

1 file changed

+29
-1
lines changed

doc/api/url.md

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,9 @@ return `true`.
9393

9494
#### Constructor: new URL(input[, base])
9595

96-
* `input` {string} The input URL to parse
96+
* `input` {string} The absolute or relative input URL to parse. If `input`
97+
is relative, then `base` is required. If `input` is absolute, the `base`
98+
is ignored.
9799
* `base` {string|URL} The base URL to resolve against if the `input` is not
98100
absolute.
99101

@@ -125,6 +127,32 @@ const myURL = new URL('https://你好你好');
125127
This feature is only available if the `node` executable was compiled with
126128
[ICU][] enabled. If not, the domain names are passed through unchanged.
127129

130+
In cases where it is not known in advance if `input` is an absolute URL
131+
and a `base` is provided, it is advised to validate that the `origin` of
132+
the `URL` object is what is expected.
133+
134+
```js
135+
const { URL } = require('url');
136+
137+
let myURL = new URL('http://anotherExample.org/', 'https://example.org/');
138+
// http://anotherexample.org/
139+
140+
myURL = new URL('https://anotherExample.org/', 'https://example.org/');
141+
// https://anotherexample.org/
142+
143+
myURL = new URL('foo://anotherExample.org/', 'https://example.org/');
144+
// foo://anotherExample.org/
145+
146+
myURL = new URL('http:anotherExample.org/', 'https://example.org/');
147+
// http://anotherexample.org/
148+
149+
myURL = new URL('https:anotherExample.org/', 'https://example.org/');
150+
// https://example.org/anotherExample.org/
151+
152+
myURL = new URL('foo:anotherExample.org/', 'https://example.org/');
153+
// foo:anotherExample.org/
154+
```
155+
128156
#### url.hash
129157

130158
* {string}

0 commit comments

Comments
 (0)