url: implement URL.prototype.toJSON

PR-URL: https://github.com/nodejs/node/pull/11236
Ref: https://github.com/whatwg/url/pull/229
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>

1 files changed, 23 insertions, 1 deletions

diff --git a/doc/api/url.md b/doc/api/url.md
index 470357e089..8d9483cb12 100644
--- a/doc/api/url.md
+++ b/doc/api/url.md
@@ -652,12 +652,32 @@ and [`url.format()`][] methods would produce.
 * Returns: {String}
 
 The `toString()` method on the `URL` object returns the serialized URL. The
-value returned is equivalent to that of [`url.href`][].
+value returned is equivalent to that of [`url.href`][] and [`url.toJSON()`][].
 
 Because of the need for standard compliance, this method does not allow users
 to customize the serialization process of the URL. For more flexibility,
 [`require('url').format()`][] method might be of interest.
 
+#### url.toJSON()
+
+* Returns: {String}
+
+The `toJSON()` method on the `URL` object returns the serialized URL. The
+value returned is equivalent to that of [`url.href`][] and
+[`url.toString()`][].
+
+This method is automatically called when an `URL` object is serialized
+with [`JSON.stringify()`][].
+
+```js
+const myURLs = [
+  new URL('https://www.example.com'),
+  new URL('https://test.example.org')
+];
+console.log(JSON.stringify(myURLs));
+  // Prints ["https://www.example.com/","https://test.example.org/"]
+```
+
 ### Class: URLSearchParams
 
 The `URLSearchParams` API provides read and write access to the query of a
@@ -1043,3 +1063,5 @@ console.log(myURL.origin);
 [`urlSearchParams.entries()`]: #url_urlsearchparams_entries
 [`urlSearchParams@@iterator()`]: #url_urlsearchparams_iterator
 [stable sorting algorithm]: https://en.wikipedia.org/wiki/Sorting_algorithm#Stability
+[`JSON.stringify()`]: https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
+[`url.toJSON()`]: #url_url_tojson