doc: doc and test URLSearchParams discrepancy

The WHATWG URL spec is not going to change this behavior so let's document it Signed-off-by: James M Snell <jasnell@gmail.com> Fixes: #33037 PR-URL: #33236 Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Zeyu Yang <himself65@outlook.com>
nodejs · Jun 7, 2020 · ea3a68f74f2041207caa30496d9371e2f82cb74a · ea3a68f
1 parent c054834
commit ea3a68f74f2041207caa30496d9371e2f82cb74a
Showing with 30 additions and 3 deletions.

+21 −3 doc/api/url.md

+9 −0 test/parallel/test-whatwg-url-custom-searchparams-stringifier.js
diff --git a/doc/api/url.md b/doc/api/url.md
@@ -472,9 +472,27 @@ and [`url.format()`][] methods would produce.
 * {URLSearchParams}
 
 Gets the [`URLSearchParams`][] object representing the query parameters of the
-URL. This property is read-only; to replace the entirety of query parameters of
-the URL, use the [`url.search`][] setter. See [`URLSearchParams`][]
-documentation for details.
+URL. This property is read-only but the `URLSearchParams` object it provides
+can be used to mutate the URL instance; to replace the entirety of query
+parameters of the URL, use the [`url.search`][] setter. See
+[`URLSearchParams`][] documentation for details.
+
+Use care when using `.searchParams` to modify the `URL` because,
+per the WHATWG specification, the `URLSearchParams` object uses
+different rules to determine which characters to percent-encode. For
+instance, the `URL` object will not percent encode the ASCII tilde (`~`)
+character, while `URLSearchParams` will always encode it:
+
+```js
+const myUrl = new URL('https://example.org/abc?foo=~bar');
+
+console.log(myUrl.search);  // prints ?foo=~bar
+
+// Modify the URL via searchParams...
+myUrl.searchParams.sort();
+
+console.log(myUrl.search);  // prints ?foo=%7Ebar
+```
 
 #### `url.username`
 

diff --git a/test/parallel/test-whatwg-url-custom-searchparams-stringifier.js b/test/parallel/test-whatwg-url-custom-searchparams-stringifier.js
@@ -16,3 +16,12 @@ const URLSearchParams = require('url').URLSearchParams;
     message: 'Value of "this" must be of type URLSearchParams'
   });
 }
+
+// The URLSearchParams stringifier mutates the base URL using
+// different percent-encoding rules than the URL itself.
+{
+  const myUrl = new URL('https://example.org?foo=~bar');
+  assert.strictEqual(myUrl.search, '?foo=~bar');
+  myUrl.searchParams.sort();
+  assert.strictEqual(myUrl.search, '?foo=%7Ebar');
+}