WhatWG URL provides no suitable replacement for url.format()

Users have used url.format() for as long as I can remember. It is useful, reasonably ergonomic, has has existed for public use for over 7 years...

The WhatWG url alternative is absolutely not ergonomic or obvious:

String(Object.assign(new URL('<a url>'), {pathname: '/foo'}))

I do not agree that deprecating url.format() with no such API alternative is acceptable.
The deprecation was done in #22715

fwiw, URL purposely doesn't expose ways to create relative urls, so there isn't really any way to represent the example you posted with a URL. i'd be interested in a version of the api which builds absolute urls though.

Tagging tsc-agenda @nodejs/tsc

It seems premature to me to have the discussion brought up to the TSC before it happened here.

Yeah, this really isn't that big of an issue. It's trivial to wrap the non-eronomic bits into a utility function that is easier to use. Alternatively, we could go ask the WHATWG for a new function.

Related discussion to relative URL in WHATWG: whatwg/url#421

I do not agree that deprecating url.format() with no such API alternative is acceptable.
The deprecation was done in #22715

I'm also not a fan of deprecating useful APIs with no alternatives. Is there a way to better prevent this kind of thing in the future?

The idea that there is no alternative in this case is incorrect. There is an alternative, it's just not as simple to use out of the box (although, it's relatively trivial to build a utility wrapper around that can sit out in userland) and some folks are unhappy with the alternative. Also, it would be relatively straightforward to submit a proposal to add a URL.format() utility function to the standard if someone wished to do so.

Also, keep in mind that the deprecation of url.format() is docs only and is expected to remain docs-only for quite some time.

The idea that there is no alternative in this case is incorrect. There is an alternative, it's just not as simple to use out of the box

I should have clarified. I'm meant no core API alternatives. I see this happen in Node when deprecating/removing chunks of functionality. Occasionally useful APIs get caught up in the cleanup. Is there a way to better prevent this kind of thing in the future?

I should have clarified. I'm meant no core API alternatives. I see this happen in Node when deprecating/removing chunks of functionality. Occasionally useful APIs get caught up in the cleanup. Is there a way to better prevent this kind of thing in the future?

I don't think so, being useful always depends on the implementation or requirement.

Some ideas.

API review board for any added or removed APIs
Require usage estimates and roadmapped migration plans for removed APIs

The following suggestion would be big effort, might not be possible, but if we're brainstorming and it's all about idea quantity and not (yet) about quality, here it is: Get CITGM to the point where it's green on master. Run it nightly. Back out changes that break things and fix the issue in the ecosystem, then re-land on master.

However, that will only impact runtime deprecations and breaking changes. Issues with doc-only deprecations obviously wouldn't be caught by that. But is that really that much of a problem? Undoing a doc-only deprecation is pretty simple (minus the politics, which I guess is kinda the point).

This is not concerned with the exact semantics of url.format() but rather the general things it is used for.

@Fishrock123

@Fishrock123 is the expectation of general usage that it always outputs a valid URL (including the protocol)?

Ok I'll tease the issue apart more, there are two issues:

The larger issue, that building a URL object from parts is not straightforward.
Getting the string from a URL object is non-obvious. This is probably just documentation if anything. Maybe it's better than in 2018.

The larger issue, that building a URL object from parts is not straightforward.

const u = new URL('http://example.org');
u.host = 'example.org';
u.port = 80;
u.pathname = '/a/b/c';
u.search = '?d=e';
u.hash = '#fgh';

Alternatively...

const host = 'example.org';
const port = 80;
const pathname = '/a/b/c';
const search = '?d=e';
const hash = '#fgh';
const u = new URL(`https://${host}:${port}${pathname}${search}${hash}`);

Getting the string from a URL object is non-obvious...

console.log(u.href);

Is this just a documentation issue then?

Examples showing how to use the WHAT-WG URL parser to build a URL from components and how to get the serialized URL string have been added to the documentation.

doc: revoke deprecation of legacy url, change status to legacy

If this is documented appropriately and if the old url api is no longer deprecated, feel free to close this.

A fully adaptable one-liner replacer for url.format(urlObject) would be

URL.from = (urlObject) => String(Object.assign(new URL("http://a.org"), urlObject))

Test it here

We can't attach a new static member to the URL class itself unless it's added to the spec. But adding something like this to the url module would be ok.

@jasnell

@jasnell it makes perfect sense, yes, please do kindly add a method to the node url module

another thing I'd like to point out is that url.format handles ipv6 hosts correctly, whereas none of the other alternatives do:

const obj = { hostname: '2001:db8::1', port: 8080, protocol: 'http' };

url.format(obj) === 'http://[2001:db8::1]:8080'; // correct
String(Object.assign(new URL("http://a.org"), obj)) === 'http://a.org:8080/'; // incorrect
`${obj.protocol}://${obj.host}:${obj.port}` === 'http://2001:db8::1:8080'; //incorrect

doc: revoke deprecation of legacy url, change status to legacy

Navigation Menu

Repository navigation

WhatWG URL provides no suitable replacement for `url.format()` #25099

26 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

WhatWG URL provides no suitable replacement for url.format() #25099

Description

Activity

devsnek commented on Dec 18, 2018

mcollina commented on Dec 18, 2018

targos commented on Dec 18, 2018

jasnell commented on Dec 18, 2018

watilde commented on Dec 18, 2018

jdalton commented on Dec 20, 2018

jasnell commented on Dec 20, 2018

jdalton commented on Dec 20, 2018

juanarbol commented on Dec 29, 2018

jdalton commented on Dec 29, 2018

Trott commented on Dec 29, 2018

26 remaining items

Fishrock123 commented on Mar 19, 2021

bmeck commented on Mar 19, 2021

Fishrock123 commented on Mar 19, 2021

jasnell commented on Mar 19, 2021

jasnell commented on Mar 22, 2021

Fishrock123 commented on May 25, 2021

jfoclpf commented on Dec 12, 2021

jasnell commented on Dec 12, 2021

jfoclpf commented on Dec 13, 2021

clhuang commented on Sep 16, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

WhatWG URL provides no suitable replacement for `url.format()` #25099