url: expose the WHATWG URL API globally

Install URL and URLSearchParams on the global object, like they can be
found in browser environments.

PR-URL: #18281
Reviewed-By: Anatoli Papirovski <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Daijiro Wachi <[email protected]>
Reviewed-By: Tiancheng "Timothy" Gu <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Joyee Cheung <[email protected]>
Reviewed-By: Ben Noordhuis <[email protected]>
Reviewed-By: Evan Lucas <[email protected]>
Reviewed-By: James M Snell <[email protected]>

Author: targos

doc/api/errors.md

@@ -1204,7 +1204,6 @@ A Node.js API function was called with an incompatible `this` value.
 Example:
 
 ```js
-const { URLSearchParams } = require('url');
 const urlSearchParams = new URLSearchParams('foo=bar&baz=new');
 
 const buf = Buffer.alloc(1);

doc/api/esm.md

@@ -143,7 +143,6 @@ rules with only JS file extension and Node builtin modules support could
 be written:
 
 ```js
-import url from 'url';
 import path from 'path';
 import process from 'process';
 import Module from 'module';
@@ -164,7 +163,7 @@ export function resolve(specifier, parentModuleURL/*, defaultResolve */) {
     throw new Error(
       `imports must begin with '/', './', or '../'; '${specifier}' does not`);
   }
-  const resolved = new url.URL(specifier, parentModuleURL);
+  const resolved = new URL(specifier, parentModuleURL);
   const ext = path.extname(resolved.pathname);
   if (!JS_EXTENSIONS.has(ext)) {
     throw new Error(

doc/api/fs.md

@@ -173,7 +173,6 @@ are supported.
 
 ```js
 const fs = require('fs');
-const { URL } = require('url');
 const fileUrl = new URL('file:///tmp/hello');
 
 fs.readFileSync(fileUrl);

doc/api/globals.md

@@ -138,6 +138,24 @@ added: v0.0.1
 
 [`setTimeout`] is described in the [timers][] section.
 
+## URL
+<!-- YAML
+added: REPLACEME
+-->
+
+<!-- type=global -->
+
+The WHATWG `URL` class. See the [`URL`][] section.
+
+## URLSearchParams
+<!-- YAML
+added: REPLACEME
+-->
+
+<!-- type=global -->
+
+The WHATWG `URLSearchParams` class. See the [`URLSearchParams`][] section.
+
 [`__dirname`]: modules.html#modules_dirname
 [`__filename`]: modules.html#modules_filename
 [`clearImmediate`]: timers.html#timers_clearimmediate_immediate
@@ -151,6 +169,8 @@ added: v0.0.1
 [`setImmediate`]: timers.html#timers_setimmediate_callback_args
 [`setInterval`]: timers.html#timers_setinterval_callback_delay_args
 [`setTimeout`]: timers.html#timers_settimeout_callback_delay_args
+[`URL`]: url.html#url_class_url
+[`URLSearchParams`]: url.html#url_class_urlsearchparams
 [buffer section]: buffer.html
 [built-in objects]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects
 [module system documentation]: modules.html

doc/api/http.md

@@ -1871,8 +1871,6 @@ There are a few special headers that should be noted.
 Example using a [`URL`][] as `options`:
 
 ```js
-const { URL } = require('url');
-
 const options = new URL('http://abc:[email protected]');
 
 const req = http.request(options, (res) => {

doc/api/http2.md

@@ -2186,7 +2186,6 @@ An HTTP/2 CONNECT proxy:
 const http2 = require('http2');
 const { NGHTTP2_REFUSED_STREAM } = http2.constants;
 const net = require('net');
-const { URL } = require('url');
 
 const proxy = http2.createServer();
 proxy.on('stream', (stream, headers) => {

doc/api/https.md

@@ -242,8 +242,6 @@ const req = https.request(options, (res) => {
 Example using a [`URL`][] as `options`:
 
 ```js
-const { URL } = require('url');
-
 const options = new URL('https://abc:[email protected]');
 
 const req = https.request(options, (res) => {

doc/api/url.md

@@ -57,15 +57,10 @@ properties of a WHATWG `URL` object.
 Parsing the URL string using the WHATWG API:
 
 ```js
-const { URL } = require('url');
 const myURL =
   new URL('https://user:[email protected]:8080/p/a/t/h?query=string#hash');
 ```
 
-*Note*: In Web Browsers, the WHATWG `URL` class is a global that is always
-available. In Node.js, however, the `URL` class must be accessed via
-`require('url').URL`.
-
 Parsing the URL string using the Legacy API:
 
 ```js
@@ -75,14 +70,19 @@ const myURL =
 ```
 
 ## The WHATWG URL API
+
+### Class: URL
 <!-- YAML
 added: v7.0.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/18281
+    description: The class is now available on the global object.
 -->
 
-### Class: URL
-
 Browser-compatible `URL` class, implemented by following the WHATWG URL
 Standard. [Examples of parsed URLs][] may be found in the Standard itself.
+The `URL` class is also available on the global object.
 
 *Note*: In accordance with browser conventions, all properties of `URL` objects
 are implemented as getters and setters on the class prototype, rather than as
@@ -101,7 +101,6 @@ Creates a new `URL` object by parsing the `input` relative to the `base`. If
 `base` is passed as a string, it will be parsed equivalent to `new URL(base)`.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('/foo', 'https://example.org/');
 // https://example.org/foo
 ```
@@ -111,7 +110,6 @@ that an effort will be made to coerce the given values into strings. For
 instance:
 
 ```js
-const { URL } = require('url');
 const myURL = new URL({ toString: () => 'https://example.org/' });
 // https://example.org/
 ```
@@ -120,7 +118,6 @@ Unicode characters appearing within the hostname of `input` will be
 automatically converted to ASCII using the [Punycode][] algorithm.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://你好你好');
 // https://xn--6qqa088eba/
 ```
@@ -135,7 +132,6 @@ with [ICU][] enabled. If not, the domain names are passed through unchanged.
 Gets and sets the fragment portion of the URL.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://example.org/foo#bar');
 console.log(myURL.hash);
 // Prints #bar
@@ -157,7 +153,6 @@ percent-encode may vary somewhat from what the [`url.parse()`][] and
 Gets and sets the host portion of the URL.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://example.org:81/foo');
 console.log(myURL.host);
 // Prints example.org:81
@@ -178,7 +173,6 @@ Gets and sets the hostname portion of the URL. The key difference between
 port.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://example.org:81/foo');
 console.log(myURL.hostname);
 // Prints example.org
@@ -197,7 +191,6 @@ Invalid hostname values assigned to the `hostname` property are ignored.
 Gets and sets the serialized URL.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://example.org/foo');
 console.log(myURL.href);
 // Prints https://example.org/foo
@@ -224,14 +217,12 @@ will be thrown.
 Gets the read-only serialization of the URL's origin.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://example.org/foo/bar?baz');
 console.log(myURL.origin);
 // Prints https://example.org
 ```
 
 ```js
-const { URL } = require('url');
 const idnURL = new URL('https://你好你好');
 console.log(idnURL.origin);
 // Prints https://xn--6qqa088eba
@@ -247,7 +238,6 @@ console.log(idnURL.hostname);
 Gets and sets the password portion of the URL.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://abc:[email protected]');
 console.log(myURL.password);
 // Prints xyz
@@ -269,7 +259,6 @@ percent-encode may vary somewhat from what the [`url.parse()`][] and
 Gets and sets the path portion of the URL.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://example.org/abc/xyz?123');
 console.log(myURL.pathname);
 // Prints /abc/xyz
@@ -291,7 +280,6 @@ to percent-encode may vary somewhat from what the [`url.parse()`][] and
 Gets and sets the port portion of the URL.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://example.org:8888');
 console.log(myURL.port);
 // Prints 8888
@@ -347,7 +335,6 @@ lies outside the range denoted above, it is ignored.
 Gets and sets the protocol portion of the URL.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://example.org');
 console.log(myURL.protocol);
 // Prints https:
@@ -366,7 +353,6 @@ Invalid URL protocol values assigned to the `protocol` property are ignored.
 Gets and sets the serialized query portion of the URL.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://example.org/abc?123');
 console.log(myURL.search);
 // Prints ?123
@@ -397,7 +383,6 @@ documentation for details.
 Gets and sets the username portion of the URL.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://abc:[email protected]');
 console.log(myURL.username);
 // Prints abc
@@ -435,7 +420,6 @@ This method is automatically called when an `URL` object is serialized
 with [`JSON.stringify()`][].
 
 ```js
-const { URL } = require('url');
 const myURLs = [
   new URL('https://www.example.com'),
   new URL('https://test.example.org')
@@ -447,20 +431,23 @@ console.log(JSON.stringify(myURLs));
 ### Class: URLSearchParams
 <!-- YAML
 added: v7.5.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/18281
+    description: The class is now available on the global object.
 -->
 
 The `URLSearchParams` API provides read and write access to the query of a
 `URL`. The `URLSearchParams` class can also be used standalone with one of the
 four following constructors.
+The `URLSearchParams` class is also available on the global object.
 
 The WHATWG `URLSearchParams` interface and the [`querystring`][] module have
 similar purpose, but the purpose of the [`querystring`][] module is more
 general, as it allows the customization of delimiter characters (`&` and `=`).
 On the other hand, this API is designed purely for URL query strings.
 
 ```js
-const { URL, URLSearchParams } = require('url');
-
 const myURL = new URL('https://example.org/?abc=123');
 console.log(myURL.searchParams.get('abc'));
 // Prints 123
@@ -505,7 +492,6 @@ Parse the `string` as a query string, and use it to instantiate a new
 `URLSearchParams` object. A leading `'?'`, if present, is ignored.
 
 ```js
-const { URLSearchParams } = require('url');
 let params;
 
 params = new URLSearchParams('user=abc&query=xyz');
@@ -534,7 +520,6 @@ values are not allowed. Arrays are stringified using [`array.toString()`][],
 which simply joins all array elements with commas.
 
 ```js
-const { URLSearchParams } = require('url');
 const params = new URLSearchParams({
   user: 'abc',
   query: ['first', 'second']
@@ -562,7 +547,6 @@ themselves be any iterable object.
 Duplicate keys are allowed.
 
 ```js
-const { URLSearchParams } = require('url');
 let params;
 
 // Using an array
@@ -631,7 +615,6 @@ Alias for [`urlSearchParams[@@iterator]()`][`urlSearchParams@@iterator()`].
 Iterates over each name-value pair in the query and invokes the given function.
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://example.org/?a=b&c=d');
 myURL.searchParams.forEach((value, name, searchParams) => {
   console.log(name, value, myURL.searchParams === searchParams);
@@ -672,7 +655,6 @@ Returns `true` if there is at least one name-value pair whose name is `name`.
 Returns an ES6 Iterator over the names of each name-value pair.
 
 ```js
-const { URLSearchParams } = require('url');
 const params = new URLSearchParams('foo=bar&foo=baz');
 for (const name of params.keys()) {
   console.log(name);
@@ -693,8 +675,6 @@ set the first such pair's value to `value` and remove all others. If not,
 append the name-value pair to the query string.
 
 ```js
-const { URLSearchParams } = require('url');
-
 const params = new URLSearchParams();
 params.append('foo', 'bar');
 params.append('foo', 'baz');
@@ -720,7 +700,6 @@ with the same name is preserved.
 This method can be used, in particular, to increase cache hits.
 
 ```js
-const { URLSearchParams } = require('url');
 const params = new URLSearchParams('query[]=abc&type=search&query[]=123');
 params.sort();
 console.log(params.toString());
@@ -751,7 +730,6 @@ is the `name`, the second item of the Array is the `value`.
 Alias for [`urlSearchParams.entries()`][].
 
 ```js
-const { URLSearchParams } = require('url');
 const params = new URLSearchParams('foo=bar&xyz=baz');
 for (const [name, value] of params) {
   console.log(name, value);
@@ -835,7 +813,6 @@ of the output.
 For example:
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://a:b@你好你好?abc#foo');
 
 console.log(myURL.href);
@@ -1135,7 +1112,6 @@ using the [Punycode][] algorithm. Note, however, that a hostname *may* contain
 *both* Punycode encoded and percent-encoded characters. For example:
 
 ```js
-const { URL } = require('url');
 const myURL = new URL('https://%CF%80.com/foo');
 console.log(myURL.href);
 // Prints https://xn--1xa.com/foo

lib/internal/bootstrap_node.js

@@ -72,6 +72,7 @@
     if (browserGlobals) {
       setupGlobalTimeouts();
       setupGlobalConsole();
+      setupGlobalURL();
     }
 
     // Ensure setURLConstructor() is called before the native
@@ -372,6 +373,24 @@
     setupInspector(originalConsole, wrappedConsole, Module);
   }
 
+  function setupGlobalURL() {
+    const { URL, URLSearchParams } = NativeModule.require('internal/url');
+    Object.defineProperties(global, {
+      URL: {
+        value: URL,
+        writable: true,
+        configurable: true,
+        enumerable: false
+      },
+      URLSearchParams: {
+        value: URLSearchParams,
+        writable: true,
+        configurable: true,
+        enumerable: false
+      }
+    });
+  }
+
   function setupInspector(originalConsole, wrappedConsole, Module) {
     if (!process.config.variables.v8_enable_inspector) {
       return;