doc: deprecate calling promisify on a function that returns a promise

PR-URL: #49647 Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: LiviaMedeiros <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]>
nodejs · Sep 28, 2023 · 7b6a731 · 7b6a731
1 parent d316b32
commit 7b6a731
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 0 deletions.
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -3378,6 +3378,20 @@ In a future version of Node.js, [`assert.CallTracker`][],
 will be removed.
 Consider using alternatives such as the [`mock`][] helper function.
 
+### DEP0174: calling `promisify` on a function that returns a `Promise`
+
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/49647
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+Calling [`util.promisify`][] on a function that returns a <Promise> will ignore
+the result of said promise, which can lead to unhandled promise rejections.
+
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
 [RFC 8247 Section 2.4]: https://www.rfc-editor.org/rfc/rfc8247#section-2.4
@@ -3518,6 +3532,7 @@ Consider using alternatives such as the [`mock`][] helper function.
 [`util.isSymbol()`]: util.md#utilissymbolobject
 [`util.isUndefined()`]: util.md#utilisundefinedobject
 [`util.log()`]: util.md#utillogstring
+[`util.promisify`]: util.md#utilpromisifyoriginal
 [`util.types`]: util.md#utiltypes
 [`util`]: util.md
 [`worker.exitedAfterDisconnect`]: cluster.md#workerexitedafterdisconnect

diff --git a/doc/api/util.md b/doc/api/util.md
@@ -1591,6 +1591,11 @@ $ node negate.js --no-logfile --logfile=test.log --color --no-color
 
 <!-- YAML
 added: v8.0.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/49647
+    description: Calling `promisify` on a function that returns a `Promise` is
+                 deprecated.
 -->
 
 * `original` {Function}