doc: add basic documentation for WHATWG URL API #10620

jasnell · 2017-01-04T23:44:03Z

Add documentation for the WHATWG URL API

Checklist

documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc,url

sam-github · 2017-01-04T23:46:58Z

doc/api/url.md

@@ -250,7 +250,308 @@ properties of URL objects:
 For example, the ASCII space character (`' '`) is encoded as `%20`. The ASCII
 forward slash (`/`) character is encoded as `%3C`.

+## The WHATWG URL API
+
+The `url` module provides an experimental implementation of the


define experimental, perhaps by including another > Stability: ... stanza here.

sam-github · 2017-01-04T23:49:11Z

doc/api/url.md

+console.log(myURL.href);
+  // Prints http://example.org/foo
+
+myURL.href = 'https://example.com/bar'


What does this actually do? Does it cause all the other properties to be re-evaluated as if the myURL had been constructuted from this new URL string?

sam-github · 2017-01-04T23:49:28Z

doc/api/url.md

+```js
+const myURL = new URL('http://example.org/foo/bar?baz');
+console.log(myURL.origin);
+  // Prints http://exmaple.org


sam-github · 2017-01-04T23:50:13Z

doc/api/url.md

+
+#### url.origin
+
+Gets the read-only Unicode serialization of the URL's origin.


Why is it so specific about Unicode seialization here, and not in the other string properties? This one is different?

That one is specificly pointed out in the spec https://url.spec.whatwg.org/#dom-url-origin

The origin attribute’s getter must return the Unicode serialization of context object’s url’s origin. [HTML]

It returns the Unicode rather than the ASCII serialization for compatibility with HTML’s MessageEvent feature. [HTML]

sam-github · 2017-01-04T23:51:06Z

doc/api/url.md

+
+#### url.port
+
+Gets and sets the port portion of the URL.


if delete url.port, does it become "http://example.org"?

It has no effect.

To be more precise: it has no effect in sloppy mode and throws in strict mode. I think it deserves a note somewhere that to remove writable properties, one must set an empty value.

hmm.. it does not appear to throw in strict mode... always appears to return true but have no effect.

'use strict'; const URL = require('url').URL; const u = new URL('http://example.org:123/abc'); console.log(delete u.port); console.log(u.href);

That's because port is not a property on u, but rather u.[[Prototype]] (i.e. URL.prototype), so delete u.port will not affect the object.

However, since URL.prototype.port is configurable, you can actually delete URL.prototype.port in both strict and sloppy modes.

I see. Sorry for the misunderstanding

sam-github · 2017-01-04T23:51:54Z

doc/api/url.md

+
+#### url.protocol
+
+Gets and sets the protocol portion of the URL.


what if you delete it? actually, for all the properties, what happens if they are deleted?

also, what happens if you assign an invalid value? does it throw, like it does in construction?

Could add a hint about all the attributes of properties https://heycam.github.io/webidl/#es-attributes at the top or somewhere (all enumerable: true and configurable: false for URL properties, writable depends on read-only-ness).

Potentially but we do not typically go into that level of detail for most Node.js properties and the original spec is already pretty well defined.

sam-github · 2017-01-04T23:52:32Z

doc/api/url.md

+
+#### url.search
+
+Gets and sets the serialized querystring portion of the URL.


serialized, as opposed to ...?

As opposed to searchParams

sam-github · 2017-01-04T23:53:11Z

doc/api/url.md

+#### url.searchParams
+
+Gets a `URLSearchParams` object representing the querystring parameters of the
+URL.


should that be linked to the def'n of URLSearchParams?

sam-github · 2017-01-04T23:54:30Z

doc/api/url.md

+exported by the object, they are not considered to be part of the "public"
+API of the object.
+
+*Note*: The origin object and the `require('url').originFor()` API are not part


Why are they here, then, are they going to be deprecated and removed?

same question for the APIs below

No, these are added as part of the new experimental implementation. They are just not part of the standard

jasnell · 2017-01-05T00:20:02Z

Updated to address nits

joyeecheung · 2017-01-05T00:30:23Z

doc/api/url.md

+
+Using the `delete` keyword (e.g. `delete myURL.hash`) has no effect.
+
+Invalid URL characters included in the value assigned to the `hash` property


Maybe worth pointing out that the additional escaped characters in url.parse (e.g. ") are no longer escaped (not necessarily here because that's common to a lot of properties).

joyeecheung · 2017-01-05T00:35:48Z

doc/api/url.md

+  // Prints http://example.org/foo#baz
+```
+
+Using the `delete` keyword (e.g. `delete myURL.hash`) has no effect.


The delete statement would return true even though it has no effect. Could use a hint?

joyeecheung · 2017-01-05T00:41:17Z

doc/api/url.md

+  // Prints http://example.org/foo
+
+myURL.href = 'https://example.com/bar'
+  // Prints https://example.com/bar


Might be worth adding

myURL.href = 'http://你好你好'; // Prints http://xn--6qqa088eba/ // Notice the slash added at the end and the ASCII serialization

joyeecheung · 2017-01-05T00:43:04Z

doc/api/url.md

+```js
+const myURL = new URL('http://example.org/foo/bar?baz');
+console.log(myURL.origin);
+  // Prints http://example.org


Might be worth adding

const idnURL = new URL('http://你好你好'); console.log(idnURL.origin); // Prints http://你好你好

joyeecheung · 2017-01-05T00:49:54Z

doc/api/url.md

+
+```js
+const myURL = new URL('http://example.org:8888');
+console.log(myURL.port);


Worth pointing out it returns a string, not a number. Also setting it to the protocol's default port would result in a '' returned, that's different from what url.parse would do.

joyeecheung · 2017-01-05T01:01:01Z

doc/api/url.md

+
+Using the `delete` keyword (e.g. `delete myURL.port`) has no effect.
+
+Invalid URL port values assigned to the `port` property are ignored.


Valid range is [0, 65535].

joyeecheung · 2017-01-05T01:07:51Z

doc/api/url.md

+```js
+const myURL = new URL('http://example.org/abc?123');
+console.log(myURL.search);
+  // Prints 123


Has a question mark at the beginning, ?123

joyeecheung · 2017-01-05T01:10:32Z

doc/api/url.md

+
+#### url.toString([unicode])
+
+* `unicode` {Boolean} `true` to serialize Unicode characters in the URL


Could use a tip about it returning the same result as #href

joyeecheung · 2017-01-05T01:19:14Z

Overall I think we should document the behaviors different from url.parse for people who want to migrate to this new API. That doesn't have to happen all at once in this PR though.

jasnell · 2017-01-05T03:06:22Z

@joyeecheung ... definitely think that would be helpful but perhaps a guide would be better for that? In the meantime, I've address some of your comments! PTAL!

joyeecheung · 2017-01-05T03:12:45Z

doc/api/url.md

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


Any reason this comment is indented (and others below)?

Just a style I generally prefer (and have used in other docs that show the expected output

joyeecheung · 2017-01-05T03:14:09Z

doc/api/url.md

+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`.
+
+### require('url').originFor(url)


Not very sure about these, if they are not part of the public API, maybe we should avoid documenting them?

They are not part of the WHATWG specification. They will be part of the Node.js API, however.

joyeecheung · 2017-01-05T03:16:08Z

doc/api/url.md

+
+#### url.port
+
+Gets and sets the port portion of the URL as a String.


Gets as a string, sets as either a string or a number.

joyeecheung · 2017-01-05T03:21:23Z

@jasnell Yeah a guide would definitely be more suitable for this. I've submitted another review, if resolved then LGTM.

jasnell · 2017-01-05T03:54:51Z

I've added some specific details about the pct-encoding in the new implementation

TimothyGu · 2017-01-05T04:07:22Z

doc/api/url.md

+Remove any existing name-value pairs whose name is `name` and append a new
+name-value pair.
+
+#### urlSearchParams[Symbol.iterator]()


Perhaps the @@iterator notation used in ES spec would be more concise? Or is this notation already used in the documentation?

I don't believe there is much (or any) precedence for documenting @@iterator in our current docs given that few (if any) of our core APIs make use of it.

TimothyGu · 2017-01-05T04:09:03Z

doc/api/url.md

+
+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`.


There are also keys, values, and entries functions.

TimothyGu · 2017-01-05T04:09:45Z

doc/api/url.md

+
+* `name` {String}
+* `value` {String}
+* Returns `undefined`


I don't think "Returns undefined" needs to be explicitly stated…

TimothyGu · 2017-01-05T04:10:11Z

doc/api/url.md

+#### urlSearchParams.get(name)
+
+* `name` {String}
+* Returns a string or `undefined`


Actually, it returns null when the param cannot be found.

TimothyGu · 2017-01-05T04:11:09Z

doc/api/url.md

+#### urlSearchParams.getAll(name)
+
+* `name` {String}
+* Returns a JavaScript Array


Other places of the documentation seem to prefer

* Returns: {Array}

TimothyGu · 2017-01-05T06:24:50Z

doc/api/url.md

+
+#### urlSearchParams.entries()
+
+* Returns: ES6 Iterator


While at it, why don't you add an MDN link for the Iterator type to tools/doc/type-parser.js ? Then, you will be able to use {Iterator} with automatic linking.

Yeah, good idea

TimothyGu · 2017-01-05T06:28:14Z

doc/api/url.md

+
+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`.


I'd explicitly mention that by definition, urlSearchParams[@@iterator] === urlSearchParams.entries. You can completely replace this description with the aliasing information (which has the benefit of not going out of sync), or make that info an additional paragraph – either is fine with me.

jasnell · 2017-01-17T00:39:29Z

Updated!

jasnell · 2017-01-17T00:47:15Z

Will land this tomorrow if there are further objections or comments.

joyeecheung · 2017-01-23T17:48:27Z

This haven't moved for a while. Pinging @Fishrock123 , are you OK with landing this now?

jasnell · 2017-01-23T17:52:49Z

Yeah, I intentionally left it open just in case. I'm planning on landing it today.

PR-URL: #10620 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Michal Zasso <targos@protonmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com>

jasnell · 2017-01-23T17:59:27Z

Landed in 0c712b6 and 4757ddc

PR-URL: nodejs#10620 Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Michal Zasso <targos@protonmail.com> Reviewed-By: Timothy Gu <timothygu99@gmail.com>

Notable changes: * crypto: * ability to select cert store at runtime (Adam Majer) #8334 * Use system CAs instead of using bundled ones (Adam Majer) #8334 * deps: * upgrade npm to 4.1.2 (Kat Marchán) #11020 * upgrade openssl sources to 1.0.2k (Shigeki Ohtsu) #11021 * doc: add basic documentation for WHATWG URL API (James M Snell) #10620 * process: add NODE_NO_WARNINGS environment variable (cjihrig) #10842 * url: allow use of URL with http.request and https.request (James M Snell) #10638 PR-URL: #11062

nodejs-github-bot added doc Issues and PRs related to the documentations. url Issues and PRs related to the legacy built-in url module. lts-watch-v6.x labels Jan 4, 2017

sam-github suggested changes Jan 4, 2017

View reviewed changes

mscdex removed the lts-watch-v6.x label Jan 5, 2017

jasnell force-pushed the url-documentation branch from 232d199 to d3adc47 Compare January 5, 2017 00:19

nodejs-github-bot added the lts-watch-v6.x label Jan 5, 2017

joyeecheung reviewed Jan 5, 2017

View reviewed changes

joyeecheung requested changes Jan 5, 2017

View reviewed changes

nodejs-github-bot added the lts-watch-v6.x label Jan 5, 2017

joyeecheung mentioned this pull request Jan 5, 2017

meta, url: track WHATWG URL implementation in GitHub project #10625

Closed

TimothyGu reviewed Jan 5, 2017

View reviewed changes

jasnell force-pushed the url-documentation branch from 76ca474 to 91d64d9 Compare January 5, 2017 04:26

nodejs-github-bot added the lts-watch-v6.x label Jan 5, 2017

jasnell force-pushed the url-documentation branch from 91d64d9 to b836c24 Compare January 5, 2017 04:30

nodejs-github-bot added the lts-watch-v6.x label Jan 5, 2017

TimothyGu reviewed Jan 5, 2017

View reviewed changes

joyeecheung approved these changes Jan 5, 2017

View reviewed changes

joyeecheung added the whatwg-url Issues and PRs related to the WHATWG URL implementation. label Jan 5, 2017

jasnell force-pushed the url-documentation branch from b836c24 to 6b6c374 Compare January 5, 2017 16:27

nodejs-github-bot added the lts-watch-v6.x label Jan 17, 2017

TimothyGu approved these changes Jan 17, 2017

View reviewed changes

jasnell closed this Jan 23, 2017

italoacasas mentioned this pull request Jan 25, 2017

Proposal to update v7.x-staging #10989

Closed

italoacasas mentioned this pull request Jan 29, 2017

v7.5.0 proposal #11062

Merged

TimothyGu mentioned this pull request Jan 29, 2017

url: track status of a spec-compliant URLSearchParams #10821

Closed

11 tasks

gibfahn mentioned this pull request Apr 24, 2017

Potential Semver Minor Backports nodejs/Release#188

Closed

31 tasks

MylesBorins added dont-land-on-v4.x and removed lts-watch-v6.x labels May 15, 2017


		#### url.origin

		Gets the read-only Unicode serialization of the URL's origin.


		#### url.protocol

		Gets and sets the protocol portion of the URL.


		#### url.search

		Gets and sets the serialized querystring portion of the URL.


		Using the `delete` keyword (e.g. `delete myURL.hash`) has no effect.

		Invalid URL characters included in the value assigned to the `hash` property


		Using the `delete` keyword (e.g. `delete myURL.port`) has no effect.

		Invalid URL port values assigned to the `port` property are ignored.


		#### url.toString([unicode])

		* `unicode` {Boolean} `true` to serialize Unicode characters in the URL


		#### url.port

		Gets and sets the port portion of the URL as a String.

doc: add basic documentation for WHATWG URL API #10620

doc: add basic documentation for WHATWG URL API #10620

Conversation

jasnell commented Jan 4, 2017

Checklist

Affected core subsystem(s)

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell Jan 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Jan 5, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung commented Jan 5, 2017

jasnell commented Jan 5, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung commented Jan 5, 2017

jasnell commented Jan 5, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TimothyGu Jan 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Jan 17, 2017

jasnell commented Jan 17, 2017

joyeecheung commented Jan 23, 2017

jasnell commented Jan 23, 2017

jasnell commented Jan 23, 2017

jasnell Jan 5, 2017 •

edited

Loading

TimothyGu Jan 5, 2017 •

edited

Loading