doc: document url.format(urlString) as deprecated under DEP0169

Renegade334 · aduh95 · commit bb90ef2356ce · 2026-02-08T10:10:44.000+01:00
Refs: #55017 PR-URL: #61644 Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -3770,6 +3770,9 @@ Type: Application (non-`node_modules` code only)
 have security implications. Use the [WHATWG URL API][] instead. CVEs are not
 issued for `url.parse()` vulnerabilities.
 
+Passing a string argument to [`url.format()`][] invokes `url.parse()`
+internally, and is therefore also covered by this deprecation.
+
 ### DEP0170: Invalid port when using `url.parse()`
 
 <!-- YAML
diff --git a/doc/api/url.md b/doc/api/url.md
@@ -1739,9 +1739,8 @@ changes:
                  times.
 -->
 
-* `urlObject` {Object|string} A URL object (as returned by `url.parse()` or
-  constructed otherwise). If a string, it is converted to an object by passing
-  it to `url.parse()`.
+* `urlObject` {Object} A URL object (as returned by `url.parse()` or
+  constructed otherwise).
 
 The `url.format()` method returns a formatted URL string derived from
 `urlObject`.
@@ -1822,6 +1821,48 @@ An automated migration is available ([source](https://github.com/nodejs/userland
 npx codemod@latest @nodejs/node-url-to-whatwg-url
 ```
 
+### `url.format(urlString)`
+
+<!-- YAML
+added: v0.1.25
+changes:
+  - version:
+      - v24.0.0
+    pr-url: https://github.com/nodejs/node/pull/55017
+    description: Application deprecation.
+-->
+
+> Stability: 0 - Deprecated: Use the WHATWG URL API instead.
+
+* `urlString` {string} A string that will be passed to `url.parse()` and then
+  formatted.
+
+`url.format(urlString)` is shorthand for `url.format(url.parse(urlString))`.
+
+Because it invokes the deprecated [`url.parse()`][], passing a string argument
+to `url.format()` is itself deprecated.
+
+Canonicalizing a URL string can be performed using the WHATWG URL API, by
+constructing a new URL object and calling [`url.toString()`][].
+
+```mjs
+import { URL } from 'node:url';
+
+const unformatted = 'http://[fe80:0:0:0:0:0:0:1]:/a/b?a=b#abc';
+const formatted = new URL(unformatted).toString();
+
+console.log(formatted); // Prints: http://[fe80::1]/a/b?a=b#abc
+```
+
+```cjs
+const { URL } = require('node:url');
+
+const unformatted = 'http://[fe80:0:0:0:0:0:0:1]:/a/b?a=b#abc';
+const formatted = new URL(unformatted).toString();
+
+console.log(formatted); // Prints: http://[fe80::1]/a/b?a=b#abc
+```
+
 ### `url.parse(urlString[, parseQueryString[, slashesDenoteHost]])`
 
 <!-- YAML
