GeezerVison is showing github.com — doc: doc and test URLSearchParams discrepancy · nodejs/node@25443fa
File tree
Expand file treeCollapse file tree
Open diff view settings
Expand file treeCollapse file tree
Open diff view settings
Collapse file
Copy file name to clipboardExpand all lines: doc/api/url.md +21-3Lines changed: 21 additions & 3 deletions - Display the source diff
- Display the rich diff
| Original file line number | Diff line number | Diff line change |
|---|
@@ -472,9 +472,27 @@ and [`url.format()`][] methods would produce. |
472 | 472 | * {URLSearchParams} |
473 | 473 |
|
474 | 474 | Gets the [`URLSearchParams`][] object representing the query parameters of the |
475 | | -URL. This property is read-only; to replace the entirety of query parameters of |
476 | | -the URL, use the [`url.search`][] setter. See [`URLSearchParams`][] |
477 | | -documentation for details. |
| 475 | +URL. This property is read-only but the `URLSearchParams` object it provides |
| 476 | +can be used to mutate the URL instance; to replace the entirety of query |
| 477 | +parameters of the URL, use the [`url.search`][] setter. See |
| 478 | +[`URLSearchParams`][] documentation for details. |
| 479 | + |
| 480 | +Use care when using `.searchParams` to modify the `URL` because, |
| 481 | +per the WHATWG specification, the `URLSearchParams` object uses |
| 482 | +different rules to determine which characters to percent-encode. For |
| 483 | +instance, the `URL` object will not percent encode the ASCII tilde (`~`) |
| 484 | +character, while `URLSearchParams` will always encode it: |
| 485 | + |
| 486 | +```js |
| 487 | +const myUrl = new URL('https://example.org/abc?foo=~bar'); |
| 488 | + |
| 489 | +console.log(myUrl.search); // prints ?foo=~bar |
| 490 | + |
| 491 | +// Modify the URL via searchParams... |
| 492 | +myUrl.searchParams.sort(); |
| 493 | + |
| 494 | +console.log(myUrl.search); // prints ?foo=%7Ebar |
| 495 | +``` |
478 | 496 |
|
479 | 497 | #### `url.username` |
480 | 498 |
|
|
Collapse file
Copy file name to clipboardExpand all lines: test/parallel/test-whatwg-url-custom-searchparams-stringifier.js +9Lines changed: 9 additions & 0 deletions | Original file line number | Diff line number | Diff line change |
|---|
@@ -16,3 +16,12 @@ const URLSearchParams = require('url').URLSearchParams; |
16 | 16 | message: 'Value of "this" must be of type URLSearchParams' |
17 | 17 | }); |
18 | 18 | } |
| 19 | + |
| 20 | +// The URLSearchParams stringifier mutates the base URL using |
| 21 | +// different percent-encoding rules than the URL itself. |
| 22 | +{ |
| 23 | + const myUrl = new URL('https://example.org?foo=~bar'); |
| 24 | + assert.strictEqual(myUrl.search, '?foo=~bar'); |
| 25 | + myUrl.searchParams.sort(); |
| 26 | + assert.strictEqual(myUrl.search, '?foo=%7Ebar'); |
| 27 | +} |