doc: add basic documentation for WHATWG URL API

[jasnell]

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]

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

[sam-github]

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?

[jasnell]

Yes

[sam-github]

"example"

[sam-github]

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

[joyeecheung]

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]

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

[targos]

It has no effect.

[targos]

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.

[jasnell]

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);

[TimothyGu]

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.

[targos]

I see. Sorry for the misunderstanding

[sam-github]

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?

[joyeecheung]

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).

[jasnell]

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]

serialized, as opposed to ...?

[jasnell]

As opposed to searchParams

[sam-github]

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

[sam-github]

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

[sam-github]

same question for the APIs below

[jasnell]

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

[jasnell]

Updated to address nits

[joyeecheung]

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]

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

[joyeecheung]

Might be worth adding

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

[joyeecheung]

Might be worth adding

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

[joyeecheung]

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]

Valid range is [0, 65535].

[joyeecheung]

Has a question mark at the beginning, ?123

[joyeecheung]

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

[joyeecheung]

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]

@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]

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

[jasnell]

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

[joyeecheung]

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

[jasnell]

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

[joyeecheung]

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

[joyeecheung]

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

[jasnell]

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

[TimothyGu]

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

[jasnell]

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]

There are also keys, values, and entries functions.

[TimothyGu]

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

[TimothyGu]

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

[TimothyGu]

Other places of the documentation seem to prefer

* Returns: {Array}

[TimothyGu]

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.

[jasnell]

Yeah, good idea

[TimothyGu]

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]

Updated!

[jasnell]

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

[joyeecheung]

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

[jasnell]

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

[jasnell]

Landed in 0c712b6 and 4757ddc