From 18599fc3d738afb2155d9bd1e6cc9f59c6ef84a9 Mon Sep 17 00:00:00 2001 From: Timothy Gu Date: Sun, 12 Feb 2017 12:17:03 -0800 Subject: [PATCH] doc/url: various improvements to WHATWG API Also remove executable bit from doc/api/url.md's mode. Backport-of: https://github.com/nodejs/node/pull/11330 Fixes: 84e2ff373841175 "doc: add basic documentation for WHATWG URL API" --- doc/api/url.md | 235 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 195 insertions(+), 40 deletions(-) mode change 100755 => 100644 doc/api/url.md diff --git a/doc/api/url.md b/doc/api/url.md old mode 100755 new mode 100644 index fa92cbb1413e82..61d27c5b68a15e --- a/doc/api/url.md +++ b/doc/api/url.md @@ -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 +// 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/ + myURL.port = 1234; +console.log(myURL.port); + // Prints 1234 console.log(myURL.href); - // Prints https://example.org:1234 + // 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,20 +643,31 @@ 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 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 = require('url').URL; const myURL = new URL('https://example.org/?abc=123'); @@ -609,36 +709,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) @@ -653,13 +758,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() @@ -680,7 +814,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() @@ -688,7 +823,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} @@ -696,7 +831,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) @@ -767,6 +913,15 @@ 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 [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