process: deprecate multipleResolves

benjamingr · bengl · commit 5796c3a7ea05 · 2022-02-21T00:37:28.000-05:00
Deprecate the process multipleResolves event to detect when a promise is resolved more than once because it never really worked. Fixes: #41554 PR-URL: #41872 Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com> Reviewed-By: Mestery <mestery@protonmail.com>
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
@@ -3061,6 +3061,20 @@ This method was deprecated because it is not compatible with
 
 Use [`buffer.subarray`][] which does the same thing instead.
 
+### DEPXXXX: `process.on('multipleResolves', handler)`
+
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/41872
+    description: Documentation-only deprecation.
+-->
+
+Type: Documentation-only
+
+This event was deprecated because it did not work with V8 promise combinators
+which diminished its usefulness.
+
 [Legacy URL API]: url.md#legacy-url-api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
diff --git a/doc/api/process.md b/doc/api/process.md
@@ -181,8 +181,11 @@ See [Advanced serialization for `child_process`][] for more details.
 
 <!-- YAML
 added: v10.12.0
+deprecated: REPLACEME
 -->
 
+> Stability: 0 - Deprecated
+
 * `type` {string} The resolution type. One of `'resolve'` or `'reject'`.
 * `promise` {Promise} The promise that resolved or rejected more than once.
 * `value` {any} The value with which the promise was either resolved or
@@ -200,6 +203,9 @@ This is useful for tracking potential errors in an application while using the
 the occurrence of this event does not necessarily indicate an error. For
 example, [`Promise.race()`][] can trigger a `'multipleResolves'` event.
 
+Because of the unreliability of the event in cases like the
+[`Promise.race()`][] example above it has been deprecated.
+
 ```mjs
 import process from 'process';
 
