Tracking Issue: Legacy URL deprecation

[jasnell]

The legacy url API (url.parse(), url.format(), and url.resolve()) have been docs-only deprecated.

Following the Node.js 11.0.0 release, I plan to open a PR that upgrades that to a pending runtime-deprecation (requires --pending-deprecation for the warning to appear). That would land in master but would not go into a release until 12.0.0 (April 2019)

Following the 12.0.0 release, I plan to on a PR that upgrades that to a full run-time deprecation that would last in master but would not go into a release until 13.0.0 (October 2019).

After the 13.0.0 release, I would like to move the legacy url API to End-of-Life, allowing us to remove it.

To support existing code that is still using the legacy URL, the implementation can be moved into a separate standalone module published on npm (similar to the existing node-url module).

[Trott]

@nodejs/url

[mattiasrunge]

Hi,
From what I understand from the docs there is no way to use the new URL-object to create a url from scratch since the URL constructor requires a string argument. Though it is possible to change the parameters and construct a new URL by inputting some dummy url, ex:

const url = new URL("http://example.com");
url.protocol = "https";
url.toString(); // --> 'https://example.com/'

Using the legacy API it is possible to construct an url with url.format. What is the way to do this going forward?

Using a dummy url to be allowed to create a URL object seems like a hack but will probably be easier than taking in an extra npm package to implement it. Or have I completely missed how to do this in the docs? :)

Thank you for your time,
Mattias

[domenic]

I think something closer to what you're looking for would be

Object.assign(new URL("about:blank"), {
  protocol: "https",
  hostname: "example.com",
  pathname: "/path/to/thing",
  hash: "somehash"
});

[TimothyGu]

@domenic That wouldn’t work because about is non-special, while https is a special scheme. Something that would probably work is

Object.assign(new URL("https://abc.def/"), {
  protocol: "https",
  hostname: "example.com",
  pathname: "/path/to/thing",
  hash: "somehash"
});

[mattiasrunge]

Thank you for the response! Seems like pretty easy solutions but still a bit hackish to have to enter a dummy url. Would it be possible to remove the requirement for giving an initial url or would that break the spec?

[lukechilds]

The legacy url API (url.parse(), url.format(), and url.resolve()) have been docs-only deprecated.

url.parse() is still mentioned in http.request() docs in numerous places:
https://nodejs.org/api/http.html#http_http_request_url_options_callback

Seems like either:

1. http.request() should be updated to use pathname and search (looks like it already accepts a URL object) and the docs should be updated to show using new url.URL() directly

2. Docs should be changed to show how to build a compatible url object with non (soon to be) depricated APIs

[sindresorhus]

http.request() should be updated to use pathname and search and the docs should be updated to show using new url.URL() directly

👍

[guybedford]

As it is related I wanted to mention the suggestion at whatwg/url#421 for URL.relative, which can always be done in Node without a URL spec. If more people show interest now it could be worthwhile to line up though.

[l1bbcsg]

http.md and http2.md still have plenty of references to url.parse including some that do not have a trivial replacement in WHATWG api, i.e.:

require('url').parse('/status?name=ryan')

Related: #12682

[developit]

I'm hoping we might have just published something that helps with this. @janicklas-ralph put a bunch of time into porting (in spirit) Node's url implementation to work atop the URL API, and the result is now available as native-url.

It contains a number of fixes for the cases noted by @l1bbcsg and others elsewhere.

[rpuls]

Hey, this was working with legacy url
url.parse('/some/image.png');
returns:

Url {
  protocol: null,
  slashes: null,
  auth: null,
  host: null,
  port: null,
  hostname: null,
  hash: null,
  search: null,
  query: null,
  pathname: '/some/image.png',
  path: '/some/image.png',
  href: '/some/image.png'
}

This throws a type error
new URL('/some/image.png');

TypeError [ERR_INVALID_URL] [ERR_INVALID_URL]: Invalid URL: /some/image.png

What to do ?

[rob4629]

Similarly to @rpuls, I'm able to use url.parse('relative/uri') but not new URL('relative/uri')... Is there a way we can skip/override the validation for the URL?

[jasnell]

The WHATWG URL parser does not work with relative URL without specifying a base. We cannot deviate from that as it's mandated by the standard.

The way to address this is: new URL('relative/uri', 'http://example.com/') where the second argument is an absolute base URL against which the first argument will be resolved.

[rob4629]

The WHATWG URL parser does not work with relative URL without specifying a base. We cannot deviate from that as it's mandated by the standard.

Ahh, ok, sorry I misunderstood the significance of that. Thanks for clarifying.

[jfoclpf]

How would you replace url.format in this case?

const url = nodeUrl.format({
  protocol: 'https',
  host: 'example.com',
  pathname: 'somepath' // or '/somepath'
})

By this?

const buildUrl = (url) => new URL(url.pathname, url.protocol + '://' + url.host)

[jfoclpf]

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

const urlFrom = (urlObject) => String(Object.assign(new URL("https://site.example"), urlObject))

Test it here