From d8a9ada4523b5337b1f103fb02750d268a136635 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Sat, 5 Sep 2026 01:38:28 +0000
Subject: [PATCH] src,lib: add util.markPromiseAsHandled

Signed-off-by: James M Snell <jasnell@gmail.com>
---
 doc/api/util.md                            | 11 ++++++++++
 lib/util.js                                |  8 +++++++
 src/node_util.cc                           | 23 ++++++++++++++++++++
 test/parallel/test-mark-promise-handled.js | 25 ++++++++++++++++++++++
 4 files changed, 67 insertions(+)
 create mode 100644 test/parallel/test-mark-promise-handled.js

diff --git a/doc/api/util.md b/doc/api/util.md
index f9bfed5b5998..52e2c06b09ff 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -1691,6 +1691,17 @@ console.log(util.isDeepStrictEqual(foo, bar, true));
 See [`assert.deepStrictEqual()`][] for more information about deep strict
 equality.
 
+## `util.markPromiseAsHandled(promise)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `promise` {promise} The promise to mark as handled
+
+Marks a promise as handled so that unhandled rejections are ignored and are not
+reported to the `'unhandledrejection'` event.
+
 ## Class: `util.MIMEType`
 
 <!-- YAML
diff --git a/lib/util.js b/lib/util.js
index 7a9c06e8bdbb..d238a620e59a 100644
--- a/lib/util.js
+++ b/lib/util.js
@@ -588,6 +588,13 @@ function deprecate(fn, msg, code, { modifyPrototype } = kEmptyObject) {
   return internalDeprecate(fn, msg, code, undefined, modifyPrototype);
 }
 
+function markPromiseAsHandled(promise) {
+  if (!types.isPromise(promise)) {
+    throw new ERR_INVALID_ARG_TYPE('promise', 'Promise', promise);
+  }
+  binding.markPromiseAsHandled(promise);
+}
+
 // Keep the `exports =` so that various functions can still be monkeypatched
 module.exports = {
   _errnoException,
@@ -618,6 +625,7 @@ module.exports = {
     }
     return internalDeepEqual(a, b, skipPrototype);
   },
+  markPromiseAsHandled,
   promisify,
   stripVTControlCharacters,
   toUSVString(input) {
diff --git a/src/node_util.cc b/src/node_util.cc
index 6d3373caae6c..ab74b2e8d375 100644
--- a/src/node_util.cc
+++ b/src/node_util.cc
@@ -18,15 +18,18 @@ using v8::CFunction;
 using v8::Context;
 using v8::DictionaryTemplate;
 using v8::External;
+using v8::Function;
 using v8::FunctionCallbackInfo;
 using v8::IndexFilter;
 using v8::Integer;
 using v8::Isolate;
 using v8::KeyCollectionMode;
+using v8::kPromiseHandlerAddedAfterReject;
 using v8::Local;
 using v8::LocalVector;
 using v8::MaybeLocal;
 using v8::Name;
+using v8::Number;
 using v8::Object;
 using v8::ObjectTemplate;
 using v8::ONLY_CONFIGURABLE;
@@ -467,6 +470,26 @@ void MarkPromiseAsHandled(const FunctionCallbackInfo<Value>& args) {
   Local<Promise> promise = args[0].As<Promise>();
   promise->MarkAsHandled();
   promise->MarkAsSilent();
+
+  // If the promise is already rejected, then it may have already been
+  // reported to the unhandled rejection handler. Marking it as handled
+  // above does not trigger the v8 callback that updates it's status.
+  // So to avoid the notification we call out manually.
+  if (promise->State() == v8::Promise::kRejected) {
+    Environment* env = Environment::GetCurrent(args);
+    Local<Function> callback = env->promise_reject_callback();
+    CHECK(!callback.IsEmpty());
+
+    Local<Value> type =
+        Number::New(env->isolate(), kPromiseHandlerAddedAfterReject);
+    Local<Value> vargs[] = {type, promise, Undefined(env->isolate())};
+
+    USE(callback->Call(
+        env->context(), Undefined(env->isolate()), arraysize(vargs), vargs));
+
+    // Note that if callback->Call throws here, we go ahead and let that
+    // propagate.
+  }
 }
 
 void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
diff --git a/test/parallel/test-mark-promise-handled.js b/test/parallel/test-mark-promise-handled.js
new file mode 100644
index 000000000000..62158c4d6212
--- /dev/null
+++ b/test/parallel/test-mark-promise-handled.js
@@ -0,0 +1,25 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('node:assert');
+const { markPromiseAsHandled } = require('node:util');
+
+process.on('unhandledrejection', common.mustNotCall());
+
+markPromiseAsHandled(Promise.reject(123));
+
+{
+  const { promise, reject } = Promise.withResolvers();
+  markPromiseAsHandled(promise);
+  reject(123);
+}
+
+{
+  const { promise, reject } = Promise.withResolvers();
+  reject(123);
+  markPromiseAsHandled(promise);
+}
+
+assert.throws(() => markPromiseAsHandled(123), {
+  code: 'ERR_INVALID_ARG_TYPE',
+});