Skip to content

Commit bb90ef2

Browse files
Renegade334aduh95
authored andcommitted
doc: document url.format(urlString) as deprecated under DEP0169
Refs: #55017 PR-URL: #61644 Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
1 parent 513df82 commit bb90ef2

File tree

2 files changed

+47
-3
lines changed

2 files changed

+47
-3
lines changed

doc/api/deprecations.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3770,6 +3770,9 @@ Type: Application (non-`node_modules` code only)
37703770
have security implications. Use the [WHATWG URL API][] instead. CVEs are not
37713771
issued for `url.parse()` vulnerabilities.
37723772

3773+
Passing a string argument to [`url.format()`][] invokes `url.parse()`
3774+
internally, and is therefore also covered by this deprecation.
3775+
37733776
### DEP0170: Invalid port when using `url.parse()`
37743777

37753778
<!-- YAML

doc/api/url.md

Lines changed: 44 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1739,9 +1739,8 @@ changes:
17391739
times.
17401740
-->
17411741
1742-
* `urlObject` {Object|string} A URL object (as returned by `url.parse()` or
1743-
constructed otherwise). If a string, it is converted to an object by passing
1744-
it to `url.parse()`.
1742+
* `urlObject` {Object} A URL object (as returned by `url.parse()` or
1743+
constructed otherwise).
17451744
17461745
The `url.format()` method returns a formatted URL string derived from
17471746
`urlObject`.
@@ -1822,6 +1821,48 @@ An automated migration is available ([source](https://github.com/nodejs/userland
18221821
npx codemod@latest @nodejs/node-url-to-whatwg-url
18231822
```
18241823
1824+
### `url.format(urlString)`
1825+
1826+
<!-- YAML
1827+
added: v0.1.25
1828+
changes:
1829+
- version:
1830+
- v24.0.0
1831+
pr-url: https://github.com/nodejs/node/pull/55017
1832+
description: Application deprecation.
1833+
-->
1834+
1835+
> Stability: 0 - Deprecated: Use the WHATWG URL API instead.
1836+
1837+
* `urlString` {string} A string that will be passed to `url.parse()` and then
1838+
formatted.
1839+
1840+
`url.format(urlString)` is shorthand for `url.format(url.parse(urlString))`.
1841+
1842+
Because it invokes the deprecated [`url.parse()`][], passing a string argument
1843+
to `url.format()` is itself deprecated.
1844+
1845+
Canonicalizing a URL string can be performed using the WHATWG URL API, by
1846+
constructing a new URL object and calling [`url.toString()`][].
1847+
1848+
```mjs
1849+
import { URL } from 'node:url';
1850+
1851+
const unformatted = 'http://[fe80:0:0:0:0:0:0:1]:/a/b?a=b#abc';
1852+
const formatted = new URL(unformatted).toString();
1853+
1854+
console.log(formatted); // Prints: http://[fe80::1]/a/b?a=b#abc
1855+
```
1856+
1857+
```cjs
1858+
const { URL } = require('node:url');
1859+
1860+
const unformatted = 'http://[fe80:0:0:0:0:0:0:1]:/a/b?a=b#abc';
1861+
const formatted = new URL(unformatted).toString();
1862+
1863+
console.log(formatted); // Prints: http://[fe80::1]/a/b?a=b#abc
1864+
```
1865+
18251866
### `url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`
18261867
18271868
<!-- YAML

0 commit comments

Comments
 (0)