Repository navigation
WhatWG URL provides no suitable replacement for url.format() #25099
Description
Activity
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.
Reacted by Adrien BecchisRelated discussion to relative URL in WHATWG: whatwg/url#421
Reacted by StevenI do not agree that deprecating
url.format()with no such API alternative is acceptable.
The deprecation was done in #22715I'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?
Reacted by Tao, Samuel Torres, Rick, ascii, flo7842, João Pimentel Ferreira, Emma Troxell and Rahul ShamkuwarThe 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.Reacted by Daijiro Wachi and Juan José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
Reacted by Juan José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).
26 remaining items
This is not concerned with the exact semantics of
url.format()but rather the general things it is used for.@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
URLobject from parts is not straightforward. - Getting the string from a
URLobject is non-obvious. This is probably just documentation if anything. Maybe it's better than in 2018.
- The larger issue, that building a
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?
Reacted by Rick and Wes RobertsExamples 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.
- added a commit that references this issue
on Mar 24, 2021 - added a commit that references this issue
on May 1, 2021 If this is documented appropriately and if the old url api is no longer deprecated, feel free to close this.
Reacted by James M SnellWe 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.
another thing I'd like to point out is that
url.formathandles 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
Reacted by Jared Dobson and Noel Llevares- added a commit that references this issue
on May 22, 2026
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:
I do not agree that deprecating
url.format()with no such API alternative is acceptable.The deprecation was done in #22715