From 117b3a5f2b6eb3b096f499bad7e3d58a786ce206 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Mon, 4 May 2020 10:33:51 -0700 Subject: [PATCH 1/4] 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 Fixes: https://github.com/nodejs/node/issues/33037 --- doc/api/url.md | 24 ++++++++++++++++--- ...twg-url-custom-searchparams-stringifier.js | 9 +++++++ 2 files changed, 30 insertions(+), 3 deletions(-) diff --git a/doc/api/url.md b/doc/api/url.md index 6950c92f0980c8..af015bc1c5b4c8 100644 --- 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. + +Care must be taken when using `.searchParams` to modify the `URL` because, +per the WHATWG specification, the `URLSearchParams` object uses slightly +different rules to determine which characters should be percent-encoded. 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 index 1fe936f5e293ab..35307fa914975a 100644 --- 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'); +} From 60a40f550240a44b3e1f7c6b1881d66bc81aad56 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 4 May 2020 18:51:33 -0700 Subject: [PATCH 2/4] Update doc/api/url.md --- doc/api/url.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/url.md b/doc/api/url.md index af015bc1c5b4c8..57f391b4dcc86a 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -479,7 +479,7 @@ parameters of the URL, use the [`url.search`][] setter. See Care must be taken when using `.searchParams` to modify the `URL` because, per the WHATWG specification, the `URLSearchParams` object uses slightly -different rules to determine which characters should be percent-encoded. For +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: From fc8aa9d73d238400e60c81081aee00870b3327e3 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 4 May 2020 18:51:39 -0700 Subject: [PATCH 3/4] Update doc/api/url.md --- doc/api/url.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/url.md b/doc/api/url.md index 57f391b4dcc86a..5377f5a9109e77 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -478,7 +478,7 @@ parameters of the URL, use the [`url.search`][] setter. See [`URLSearchParams`][] documentation for details. Care must be taken when using `.searchParams` to modify the `URL` because, -per the WHATWG specification, the `URLSearchParams` object uses slightly +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: From 76b621a426308d9e60b96840578bb01983c2ca38 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Mon, 4 May 2020 18:51:45 -0700 Subject: [PATCH 4/4] Update doc/api/url.md --- doc/api/url.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/url.md b/doc/api/url.md index 5377f5a9109e77..3da8adbe8568d2 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -477,7 +477,7 @@ 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. -Care must be taken when using `.searchParams` to modify the `URL` because, +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 (`~`)