1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc/url: various improvements to WHATWG API

Browse Source 
Also remove executable bit from doc/api/url.md's mode.

PR-URL: https://github.com/nodejs/node/pull/11330
Fixes: 4757ddcce10af04 "doc: add basic documentation for WHATWG URL API"
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
This commit is contained in:
Timothy Gu 2017-02-12 12:17:03 -08:00
parent 6cea5dd39f
commit bd07c8fc12
1 changed files with 196 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

237
doc/api/url.md Executable file → Normal file
View File

@ -311,6 +311,35 @@ console.log(myURL.pathname); // /foo
*Note*: Using the `delete` keyword (e.g. `delete myURL.protocol`,
`delete myURL.pathname`, etc) has no effect but will still return `true`.
A comparison between this API and `url.parse()` is given below. Above the URL
`'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`, properties of an
object returned by `url.parse()` are shown. Below it are properties of a WHATWG
`URL` object.
*Note*: WHATWG URL's `origin` property includes `protocol` and `host`, but not
`username` or `password`.
```txt
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ href │
├──────────┬──┬─────────────────────┬─────────────────┬───────────────────────────┬───────┤
│ protocol │ │ auth │ host │ path │ hash │
│ │ │ ├──────────┬──────┼──────────┬────────────────┤ │
│ │ │ │ hostname │ port │ pathname │ search │ │
│ │ │ │ │ │ ├─┬──────────────┤ │
│ │ │ │ │ │ │ │ query │ │
" http: // user : pass @ host.com : 8080 /p/a/t/h ? query=string #hash "
│ │ │ │ │ hostname │ port │ │ │ │
│ │ │ │ ├──────────┴──────┤ │ │ │
│ protocol │ │ username │ password │ host │ │ │ │
├──────────┴──┼──────────┴──────────┼─────────────────┤ │ │ │
│ origin │ │ origin │ pathname │ search │ hash │
├─────────────┴─────────────────────┴─────────────────┴──────────┴────────────────┴───────┤
│ href │
└─────────────────────────────────────────────────────────────────────────────────────────┘
(all spaces in the "" line should be ignored -- they are purely for formatting)
```
### Class: URL
#### Constructor: new URL(input[, base])
@ -340,13 +369,15 @@ automatically converted to ASCII using the [Punycode][] algorithm.
```js
const myURL = new URL('https://你好你好');
// https://xn--6qqa088eba
// https://xn--6qqa088eba/
```
Additional [examples of parsed URLs][] may be found in the WHATWG URL Standard.
#### url.hash
* {String}
Gets and sets the fragment portion of the URL.
```js
@ -360,12 +391,14 @@ console.log(myURL.href);
```
Invalid URL characters included in the value assigned to the `hash` property
are [percent-encoded](#whatwg-percent-encoding). Note that the selection of
which characters to percent-encode may vary somewhat from what the
[`url.parse()`][] and [`url.format()`][] methods would produce.
are [percent-encoded][]. Note that the selection of which characters to
percent-encode may vary somewhat from what the [`url.parse()`][] and
[`url.format()`][] methods would produce.
#### url.host
* {String}
Gets and sets the host portion of the URL.
```js
@ -382,6 +415,8 @@ Invalid host values assigned to the `host` property are ignored.
#### url.hostname
* {String}
Gets and sets the hostname portion of the URL. The key difference between
`url.host` and `url.hostname` is that `url.hostname` does *not* include the
port.
@ -400,6 +435,8 @@ Invalid hostname values assigned to the `hostname` property are ignored.
#### url.href
* {String}
Gets and sets the serialized URL.
```js
@ -411,15 +448,20 @@ myURL.href = 'https://example.com/bar'
// Prints https://example.com/bar
```
Setting the value of the `href` property to a new value is equivalent to
creating a new `URL` object using `new URL(value)`. Each of the `URL` object's
properties will be modified.
Getting the value of the `href` property is equivalent to calling
[`url.toString()`][].
Setting the value of this property to a new value is equivalent to creating a
new `URL` object using [`new URL(value)`][`new URL()`]. Each of the `URL`
object's properties will be modified.
If the value assigned to the `href` property is not a valid URL, a `TypeError`
will be thrown.
#### url.origin
* {String}
Gets the read-only serialization of the URL's origin. Unicode characters that
may be contained within the hostname will be encoded as-is without [Punycode][]
encoding.
@ -441,6 +483,8 @@ console.log(idnURL.hostname);
#### url.password
* {String}
Gets and sets the password portion of the URL.
```js
@ -454,12 +498,14 @@ console.log(myURL.href);
```
Invalid URL characters included in the value assigned to the `password` property
are [percent-encoded](#whatwg-percent-encoding). Note that the selection of
which characters to percent-encode may vary somewhat from what the
[`url.parse()`][] and [`url.format()`][] methods would produce.
are [percent-encoded][]. Note that the selection of which characters to
percent-encode may vary somewhat from what the [`url.parse()`][] and
[`url.format()`][] methods would produce.
#### url.pathname
* {String}
Gets and sets the path portion of the URL.
```js
@ -473,23 +519,54 @@ console.log(myURL.href);
```
Invalid URL characters included in the value assigned to the `pathname`
property are [percent-encoded](#whatwg-percent-encoding). Note that the
selection of which characters to percent-encode may vary somewhat from what the
[`url.parse()`][] and [`url.format()`][] methods would produce.
property are [percent-encoded][]. Note that the selection of which characters
to percent-encode may vary somewhat from what the [`url.parse()`][] and
[`url.format()`][] methods would produce.
#### url.port
Gets and sets the port portion of the URL. When getting the port, the value
is returned as a String.
* {String}
Gets and sets the port portion of the URL.
```js
const myURL = new URL('https://example.org:8888');
console.log(myURL.port);
// Prints 8888
myURL.port = 1234;
// Default ports are automatically transformed to the empty string
// (HTTPS protocol's default port is 443)
myURL.port = '443';
console.log(myURL.port);
// Prints the empty string
console.log(myURL.href);
// Prints https://example.org:1234
// Prints https://example.org/
myURL.port = 1234;
console.log(myURL.port);
// Prints 1234
console.log(myURL.href);
// Prints https://example.org:1234/
// Completely invalid port strings are ignored
myURL.port = 'abcd';
console.log(myURL.port);
// Prints 1234
// Leading numbers are treated as a port number
myURL.port = '5678abcd';
console.log(myURL.port);
// Prints 5678
// Non-integers are truncated
myURL.port = 1234.5678;
console.log(myURL.port);
// Prints 1234
// Out-of-range numbers are ignored
myURL.port = 1e10;
console.log(myURL.port);
// Prints 1234
```
The port value may be set as either a number or as a String containing a number
@ -497,10 +574,14 @@ in the range `0` to `65535` (inclusive). Setting the value to the default port
of the `URL` objects given `protocol` will result in the `port` value becoming
the empty string (`''`).
Invalid URL port values assigned to the `port` property are ignored.
If an invalid string is assigned to the `port` property, but it begins with a
number, the leading number is assigned to `port`. Otherwise, or if the number
lies outside the range denoted above, it is ignored.
#### url.protocol
* {String}
Gets and sets the protocol portion of the URL.
```js
@ -517,6 +598,8 @@ Invalid URL protocol values assigned to the `protocol` property are ignored.
#### url.search
* {String}
Gets and sets the serialized query portion of the URL.
```js
@ -530,17 +613,23 @@ console.log(myURL.href);
```
Any invalid URL characters appearing in the value assigned the `search`
property will be [percent-encoded](#whatwg-percent-encoding). Note that the
selection of which characters to percent-encode may vary somewhat from what the
[`url.parse()`][] and [`url.format()`][] methods would produce.
property will be [percent-encoded][]. Note that the selection of which
characters to percent-encode may vary somewhat from what the [`url.parse()`][]
and [`url.format()`][] methods would produce.
#### url.searchParams
Gets a [`URLSearchParams`](#url_class_urlsearchparams) object representing the
query parameters of the URL.
* {URLSearchParams}
Gets the [`URLSearchParams`][] object representing the query parameters of the
URL. This property is read-only; to replace the entirety of query parameters of
the URL, use the [`url.search`][] setter. See [`URLSearchParams`][]
documentation for details.
#### url.username
* {String}
Gets and sets the username portion of the URL.
```js
@ -554,21 +643,32 @@ console.log(myURL.href);
```
Any invalid URL characters appearing in the value assigned the `username`
property will be [percent-encoded](#whatwg-percent-encoding). Note that the
selection of which characters to percent-encode may vary somewhat from what the
[`url.parse()`][] and [`url.format()`][] methods would produce.
property will be [percent-encoded][]. Note that the selection of which
characters to percent-encode may vary somewhat from what the [`url.parse()`][]
and [`url.format()`][] methods would produce.
#### url.toString()
* Returns: {String}
The `toString()` method on the `URL` object returns the serialized URL. The
value returned is equivalent to that of `url.href`.
value returned is equivalent to that of [`url.href`][].
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.
### Class: URLSearchParams
The `URLSearchParams` object provides read and write access to the query of a
The `URLSearchParams` API provides read and write access to the query of a
`URL`. The `URLSearchParams` class can also be used standalone with one of the
four following constructors.
The WHATWG `URLSearchParams` interface and the [`querystring`][] module have
similar purpose, but the purpose of the [`querystring`][] module is more
general, as it allows the customization of delimiter characters (`&` and `=`).
On the other hand, this API is designed purely for URL query strings.
```js
const { URL, URLSearchParams } = require('url');
@ -725,36 +825,41 @@ Returns an ES6 Iterator over each of the name-value pairs in the query.
Each item of the iterator is a JavaScript Array. The first item of the Array
is the `name`, the second item of the Array is the `value`.
Alias for `urlSearchParams\[\@\@iterator\]()`.
Alias for [`urlSearchParams[@@iterator]()`][`urlSearchParams@@iterator()`].
#### urlSearchParams.forEach(fn)
#### urlSearchParams.forEach(fn[, thisArg])
* `fn` {Function} Function invoked for each name-value pair in the query.
* `thisArg` {Object} Object to be used as `this` value for when `fn` is called
Iterates over each name-value pair in the query and invokes the given function.
```js
const URL = require('url').URL;
const myURL = new URL('https://example.org/?a=b&c=d');
myURL.searchParams.forEach((value, name) => {
console.log(name, value);
myURL.searchParams.forEach((value, name, searchParams) => {
console.log(name, value, myURL.searchParams === searchParams);
});
// Prints:
// a b true
// c d true
```
#### urlSearchParams.get(name)
* `name` {String}
* Returns: {String} or `null` if there is no name-value pair with the given
`name`.
* Returns: {String | Null}
Returns the value of the first name-value pair whose name is `name`.
Returns the value of the first name-value pair whose name is `name`. If there
are no such pairs, `null` is returned.
#### urlSearchParams.getAll(name)
* `name` {String}
* Returns: {Array}
Returns the values of all name-value pairs whose name is `name`.
Returns the values of all name-value pairs whose name is `name`. If there are
no such pairs, an empty array is returned.
#### urlSearchParams.has(name)
@ -769,13 +874,42 @@ Returns `true` if there is at least one name-value pair whose name is `name`.
Returns an ES6 Iterator over the names of each name-value pair.
```js
const { URLSearchParams } = require('url');
const params = new URLSearchParams('foo=bar&foo=baz');
for (const name of params.keys()) {
console.log(name);
}
// Prints:
// foo
// foo
```
#### urlSearchParams.set(name, value)
* `name` {String}
* `value` {String}
Remove any existing name-value pairs whose name is `name` and append a new
name-value pair.
Sets the value in the `URLSearchParams` object associated with `name` to
`value`. If there are any pre-existing name-value pairs whose names are `name`,
set the first such pair's value to `value` and remove all others. If not,
append the name-value pair to the query string.
```js
const { URLSearchParams } = require('url');
const params = new URLSearchParams();
params.append('foo', 'bar');
params.append('foo', 'baz');
params.append('abc', 'def');
console.log(params.toString());
// Prints foo=bar&foo=baz&abc=def
params.set('foo', 'def');
params.set('xyz', 'opq');
console.log(params.toString());
// Prints foo=def&abc=def&xyz=opq
```
#### urlSearchParams.sort()
@ -796,7 +930,8 @@ console.log(params.toString());
* Returns: {String}
Returns the search parameters serialized as a URL-encoded string.
Returns the search parameters serialized as a string, with characters
percent-encoded where necessary.
#### urlSearchParams.values()
@ -804,7 +939,7 @@ Returns the search parameters serialized as a URL-encoded string.
Returns an ES6 Iterator over the values of each name-value pair.
#### urlSearchParams\[\@\@iterator\]()
#### urlSearchParams\[@@iterator\]()
* Returns: {Iterator}
@ -812,7 +947,18 @@ Returns an ES6 Iterator over each of the name-value pairs in the query string.
Each item of the iterator is a JavaScript Array. The first item of the Array
is the `name`, the second item of the Array is the `value`.
Alias for `urlSearchParams.entries()`.
Alias for [`urlSearchParams.entries()`][].
```js
const { URLSearchParams } = require('url');
const params = new URLSearchParams('foo=bar&xyz=baz');
for (const [name, value] of params) {
console.log(name, value);
}
// Prints:
// foo bar
// xyz baz
```
### require('url').domainToAscii(domain)
@ -883,8 +1029,17 @@ console.log(myURL.origin);
[examples of parsed URLs]: https://url.spec.whatwg.org/#example-url-parsing
[`url.parse()`]: #url_url_parse_urlstring_parsequerystring_slashesdenotehost
[`url.format()`]: #url_url_format_urlobject
[`require('url').format()`]: #url_url_format_url_options
[`url.toString()`]: #url_url_tostring
[Punycode]: https://tools.ietf.org/html/rfc5891#section-4.4
[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
[`array.toString()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString
[WHATWG URL]: #url_the_whatwg_url_api
[`new URL()`]: #url_constructor_new_url_input_base
[`url.href`]: #url_url_href
[`url.search`]: #url_url_search
[percent-encoded]: #whatwg-percent-encoding
[`URLSearchParams`]: #url_class_urlsearchparams
[`urlSearchParams.entries()`]: #url_urlsearchparams_entries
[`urlSearchParams@@iterator()`]: #url_urlsearchparams_iterator
[stable sorting algorithm]: https://en.wikipedia.org/wiki/Sorting_algorithm#Stability