Skip to content

Commit

Permalink
doc: clarify url doc
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
jasnell committed Apr 16, 2018
1 parent afb4d55 commit 6d1c3e5
Showing 1 changed file with 29 additions and 1 deletion.
30 changes: 29 additions & 1 deletion doc/api/url.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,9 @@ return `true`.

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

* `input` {string} The input URL to parse
* `input` {string} The absolute or relative input URL to parse. If `input`
is relative, then `base` is required. If `input` is absolute, the `base`
is ignored.
* `base` {string|URL} The base URL to resolve against if the `input` is not
absolute.

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

In cases where it is not known in advance if `input` is an absolute URL
and a `base` is provided, it is advised to validate that the `origin` of
the `URL` object is what is expected.

```js
const { URL } = require('url');

let myURL = new URL('http://anotherExample.org/', 'https://example.org/');
// http://anotherexample.org/

myURL = new URL('https://anotherExample.org/', 'https://example.org/');
// https://anotherexample.org/

myURL = new URL('foo://anotherExample.org/', 'https://example.org/');
// foo://anotherExample.org/

myURL = new URL('http:anotherExample.org/', 'https://example.org/');
// http://anotherexample.org/

myURL = new URL('https:anotherExample.org/', 'https://example.org/');
// https://example.org/anotherExample.org/

myURL = new URL('foo:anotherExample.org/', 'https://example.org/');
// foo:anotherExample.org/
```

#### url.hash

* {string}
Expand Down

0 comments on commit 6d1c3e5

Please sign in to comment.