From 7ab13f6d8c8e553bfb5435537c32187e0dc09b7b Mon Sep 17 00:00:00 2001 From: Timothy Gu Date: Sun, 12 Feb 2017 12:21:35 -0800 Subject: [PATCH 1/5] tools/doc: add more intrinsic and custom types --- tools/doc/type-parser.js | 40 +++++++++++++++++++++++++++------------- 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js index d8266ab69a4a22..c5c416e2b3bdc2 100644 --- a/tools/doc/type-parser.js +++ b/tools/doc/type-parser.js @@ -16,31 +16,45 @@ const jsGlobalTypes = [ 'Uint16Array', 'Uint32Array', 'Int8Array', 'Int16Array', 'Int32Array', 'Uint8ClampedArray', 'Float32Array', 'Float64Array', 'Date', 'RegExp', 'ArrayBuffer', 'DataView', 'Promise', 'EvalError', 'RangeError', - 'ReferenceError', 'SyntaxError', 'TypeError', 'URIError' + 'ReferenceError', 'SyntaxError', 'TypeError', 'URIError', 'Proxy', 'Map', + 'Set', 'WeakMap', 'WeakSet', 'Generator', 'GeneratorFunction', + 'AsyncFunction', 'SharedArrayBuffer' ]; const typeMap = { + 'Iterable': jsDocPrefix + + 'Reference/Iteration_protocols#The_iterable_protocol', + 'Iterator': jsDocPrefix + + 'Reference/Iteration_protocols#The_iterator_protocol', + 'Buffer': 'buffer.html#buffer_class_buffer', - 'Handle': 'net.html#net_server_listen_handle_backlog_callback', - 'Stream': 'stream.html#stream_stream', - 'stream.Writable': 'stream.html#stream_class_stream_writable', - 'stream.Readable': 'stream.html#stream_class_stream_readable', + 'ChildProcess': 'child_process.html#child_process_class_childprocess', + 'cluster.Worker': 'cluster.html#cluster_class_worker', + 'dgram.Socket': 'dgram.html#dgram_class_dgram_socket', - 'net.Socket': 'net.html#net_class_net_socket', - 'tls.TLSSocket': 'tls.html#tls_class_tls_tlssocket', + 'EventEmitter': 'events.html#events_class_eventemitter', - 'Timer': 'timers.html#timers_timers', + 'http.Agent': 'http.html#http_class_http_agent', 'http.ClientRequest': 'http.html#http_class_http_clientrequest', 'http.IncomingMessage': 'http.html#http_class_http_incomingmessage', 'http.Server': 'http.html#http_class_http_server', 'http.ServerResponse': 'http.html#http_class_http_serverresponse', - 'Iterable': jsDocPrefix + - 'Reference/Iteration_protocols#The_iterable_protocol', - 'Iterator': jsDocPrefix + - 'Reference/Iteration_protocols#The_iterator_protocol', - 'URL': 'url.html#url_the_whatwg_url_api' + + 'Handle': 'net.html#net_server_listen_handle_backlog_callback', + 'net.Socket': 'net.html#net_class_net_socket', + + 'Stream': 'stream.html#stream_stream', + 'stream.Readable': 'stream.html#stream_class_stream_readable', + 'stream.Writable': 'stream.html#stream_class_stream_writable', + + 'tls.TLSSocket': 'tls.html#tls_class_tls_tlssocket', + + 'Timer': 'timers.html#timers_timers', + + 'URL': 'url.html#url_the_whatwg_url_api', + 'URLSearchParams': 'url.html#url_class_urlsearchparams' }; module.exports = { From 658ffccb8690d44c4b28a258919ce8f91eee3f38 Mon Sep 17 00:00:00 2001 From: Timothy Gu Date: Sun, 12 Feb 2017 12:17:03 -0800 Subject: [PATCH 2/5] doc, url: fix file permission --- doc/api/url.md | 0 1 file changed, 0 insertions(+), 0 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 From b5ce33f3847c68812e3af9910fabdf03554a738f Mon Sep 17 00:00:00 2001 From: Timothy Gu Date: Sun, 12 Feb 2017 11:35:16 -0800 Subject: [PATCH 3/5] doc, url: various improvements to WHATWG API --- doc/api/url.md | 227 ++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 188 insertions(+), 39 deletions(-) diff --git a/doc/api/url.md b/doc/api/url.md index d81c31d126dedd..3b8795c88d1139 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -298,6 +298,35 @@ forward slash (`/`) character is encoded as `%3C`. The `url` module provides an *experimental* implementation of the [WHATWG URL Standard][] as an alternative to the existing `url.parse()` API. +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 given. Beneath 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) +``` + ```js const URL = require('url').URL; const myURL = new URL('https://example.org/foo'); @@ -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,14 +643,20 @@ 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 for +customization on the serialization process of the URL. For more flexibility, +[`require('url').format()`][] method might be of interest. ### Class: URLSearchParams @@ -725,36 +820,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 +869,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 +925,7 @@ console.log(params.toString()); * Returns: {String} -Returns the search parameters serialized as a URL-encoded string. +Returns the search parameters serialized as a percent-encoded string. #### urlSearchParams.values() @@ -804,7 +933,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 +941,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 +1023,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 From e55746b02b41ec7ef925c91bd8398b7e3ae69359 Mon Sep 17 00:00:00 2001 From: Timothy Gu Date: Tue, 14 Feb 2017 16:14:12 -0800 Subject: [PATCH 4/5] Address comments --- doc/api/url.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/api/url.md b/doc/api/url.md index 3b8795c88d1139..88b9493dd71142 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -300,8 +300,8 @@ The `url` module provides an *experimental* implementation of the 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 given. Beneath it are properties of a -WHATWG `URL` object. +object returned by `url.parse()` are given. Below it are properties of a WHATWG +`URL` object. *Note*: WHATWG URL's `origin` property includes `protocol` and `host`, but not `username` or `password`. @@ -654,8 +654,8 @@ and [`url.format()`][] methods would produce. The `toString()` method on the `URL` object returns the serialized URL. The value returned is equivalent to that of [`url.href`][]. -Because of the need for standard compliance, this method does not allow for -customization on the serialization process of the URL. For more flexibility, +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 @@ -925,7 +925,8 @@ console.log(params.toString()); * Returns: {String} -Returns the search parameters serialized as a percent-encoded string. +Returns the search parameters serialized as a string, with characters +percent-encoded where necessary. #### urlSearchParams.values() From 424ec4fd9bf65275b6c990b8cf755c144e433357 Mon Sep 17 00:00:00 2001 From: Timothy Gu Date: Tue, 14 Feb 2017 16:25:41 -0800 Subject: [PATCH 5/5] Add reference to querystring --- doc/api/url.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/api/url.md b/doc/api/url.md index 88b9493dd71142..dc4122760b278d 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -660,10 +660,15 @@ to customize the serialization process of the URL. For more flexibility, ### 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');