From 46eebb64cba83f5c4d45acf389249ff4707632cd Mon Sep 17 00:00:00 2001
From: Renegade334 <contact.9a5d6388@renegade334.me.uk>
Date: Mon, 4 May 2026 16:58:26 +0200
Subject: [PATCH 1/2] fs: add throwIfNoEntry option to
 fs.lstat/fs.promises.lstat

Signed-off-by: Renegade334 <contact.9a5d6388@renegade334.me.uk>
---
 doc/api/fs.md                 | 14 ++++++++++++++
 lib/fs.js                     | 17 +++++++++++------
 lib/internal/fs/promises.js   | 12 ++++--------
 src/node_file.cc              | 35 +++++++++++++----------------------
 test/parallel/test-fs-stat.js | 20 +++++++++++++++++---
 5 files changed, 59 insertions(+), 39 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index b2231bd20cc420..e78058f775b40f 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -1478,6 +1478,10 @@ link(2) documentation for more detail.
 <!-- YAML
 added: v10.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63116
+    description: Accepts a `throwIfNoEntry` option to specify whether
+                 an exception should be thrown if the entry does not exist.
   - version: v10.5.0
     pr-url: https://github.com/nodejs/node/pull/20220
     description: Accepts an additional `options` object to specify whether
@@ -1488,6 +1492,9 @@ changes:
 * `options` {Object}
   * `bigint` {boolean} Whether the numeric values in the returned
     {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `throwIfNoEntry` {boolean} Whether an exception will be thrown
+    if no file system entry exists, rather than returning `undefined`.
+    **Default:** `true`.
 * Returns: {Promise}  Fulfills with the {fs.Stats} object for the given
   symbolic link `path`.
 
@@ -3673,6 +3680,10 @@ exception are given to the completion callback.
 <!-- YAML
 added: v0.1.30
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63116
+    description: Accepts a `throwIfNoEntry` option to specify whether
+                 an exception should be thrown if the entry does not exist.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41678
     description: Passing an invalid callback to the `callback` argument
@@ -3700,6 +3711,9 @@ changes:
 * `options` {Object}
   * `bigint` {boolean} Whether the numeric values in the returned
     {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `throwIfNoEntry` {boolean} Whether an exception will be thrown
+    if no file system entry exists, rather than returning `undefined`.
+    **Default:** `true`.
 * `callback` {Function}
   * `err` {Error}
   * `stats` {fs.Stats}
diff --git a/lib/fs.js b/lib/fs.js
index d63fad8b2a258b..f2181aa08cc59d 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -187,9 +187,11 @@ function makeStatsCallback(cb) {
   validateFunction(cb, 'cb');
 
   return (err, stats) => {
-    if (err) return cb(err);
-    if (stats === undefined && err === null) return cb(null, undefined);
-    cb(err, getStatsFromBinding(stats));
+    if (err) {
+      cb(err);
+    } else {
+      cb(null, stats !== undefined ? getStatsFromBinding(stats) : undefined);
+    }
   };
 }
 
@@ -1587,14 +1589,17 @@ function fstat(fd, options = { bigint: false }, callback) {
  * Retrieves the `fs.Stats` for the symbolic link
  * referred to by the `path`.
  * @param {string | Buffer | URL} path
- * @param {{ bigint?: boolean; }} [options]
+ * @param {{
+     bigint?: boolean;
+     throwIfNoEntry?: boolean;
+ * }} [options]
  * @param {(
  *   err?: Error,
  *   stats?: Stats
  *   ) => any} callback
  * @returns {void}
  */
-function lstat(path, options = { bigint: false }, callback) {
+function lstat(path, options = { bigint: false, throwIfNoEntry: true }, callback) {
   if (typeof options === 'function') {
     callback = options;
     options = kEmptyObject;
@@ -1609,7 +1614,7 @@ function lstat(path, options = { bigint: false }, callback) {
 
   const req = new FSReqCallback(options.bigint);
   req.oncomplete = callback;
-  binding.lstat(path, options.bigint, req);
+  binding.lstat(path, options.bigint, req, options.throwIfNoEntry);
 }
 
 /**
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 40de890c6eb2d3..ab810869afd260 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -1662,18 +1662,18 @@ async function fstat(handle, options = { bigint: false }) {
   return getStatsFromBinding(result);
 }
 
-async function lstat(path, options = { bigint: false }) {
+async function lstat(path, options = { bigint: false, throwIfNoEntry: true }) {
   path = getValidatedPath(path);
   if (permission.isEnabled() && !permission.has('fs.read', path)) {
     const resource = pathModule.toNamespacedPath(BufferIsBuffer(path) ? BufferToString(path) : path);
     throw new ERR_ACCESS_DENIED('Access to this API has been restricted', 'FileSystemRead', resource);
   }
   const result = await PromisePrototypeThen(
-    binding.lstat(path, options.bigint, kUsePromises),
+    binding.lstat(path, options.bigint, kUsePromises, options.throwIfNoEntry),
     undefined,
     handleErrorFromBinding,
   );
-  return getStatsFromBinding(result);
+  return result !== undefined ? getStatsFromBinding(result) : undefined;
 }
 
 async function stat(path, options = { bigint: false, throwIfNoEntry: true }) {
@@ -1682,11 +1682,7 @@ async function stat(path, options = { bigint: false, throwIfNoEntry: true }) {
     undefined,
     handleErrorFromBinding,
   );
-
-  // Binding will resolve undefined if UV_ENOENT or UV_ENOTDIR and throwIfNoEntry is false
-  if (!options.throwIfNoEntry && result === undefined) return undefined;
-
-  return getStatsFromBinding(result);
+  return result !== undefined ? getStatsFromBinding(result) : undefined;
 }
 
 async function statfs(path, options = { bigint: false }) {
diff --git a/src/node_file.cc b/src/node_file.cc
index d93f213202ec43..050a3e958c99a0 100644
--- a/src/node_file.cc
+++ b/src/node_file.cc
@@ -1139,7 +1139,7 @@ static void Stat(const FunctionCallbackInfo<Value>& args) {
 
   bool use_bigint = args[1]->IsTrue();
   if (!args[2]->IsUndefined()) {  // stat(path, use_bigint, req,
-                                  // do_not_throw_if_no_entry)
+                                  //      throw_if_no_entry)
     bool do_not_throw_if_no_entry = args[3]->IsFalse();
     FSReqBase* req_wrap_async = GetReqWrap(args, 2, use_bigint);
     CHECK_NOT_NULL(req_wrap_async);
@@ -1150,25 +1150,14 @@ static void Stat(const FunctionCallbackInfo<Value>& args) {
         path.ToStringView());
     FS_ASYNC_TRACE_BEGIN1(
         UV_FS_STAT, req_wrap_async, "path", TRACE_STR_COPY(*path))
-    if (do_not_throw_if_no_entry) {
-      AsyncCall(env,
-                req_wrap_async,
-                args,
-                "stat",
-                UTF8,
-                AfterStatNoThrowIfNoEntry,
-                uv_fs_stat,
-                *path);
-    } else {
-      AsyncCall(env,
-                req_wrap_async,
-                args,
-                "stat",
-                UTF8,
-                AfterStat,
-                uv_fs_stat,
-                *path);
-    }
+    AsyncCall(env,
+              req_wrap_async,
+              args,
+              "stat",
+              UTF8,
+              do_not_throw_if_no_entry ? AfterStatNoThrowIfNoEntry : AfterStat,
+              uv_fs_stat,
+              *path);
   } else {  // stat(path, use_bigint, undefined, do_not_throw_if_no_entry)
     THROW_IF_INSUFFICIENT_PERMISSIONS(
         env, permission::PermissionScope::kFileSystemRead, path.ToStringView());
@@ -1210,7 +1199,9 @@ static void LStat(const FunctionCallbackInfo<Value>& args) {
   ToNamespacedPath(env, &path);
 
   bool use_bigint = args[1]->IsTrue();
-  if (!args[2]->IsUndefined()) {  // lstat(path, use_bigint, req)
+  if (!args[2]->IsUndefined()) {  // lstat(path, use_bigint, req,
+                                  //       throw_if_no_entry)
+    bool do_not_throw_if_no_entry = args[3]->IsFalse();
     FSReqBase* req_wrap_async = GetReqWrap(args, 2, use_bigint);
     CHECK_NOT_NULL(req_wrap_async);
     FS_ASYNC_TRACE_BEGIN1(
@@ -1220,7 +1211,7 @@ static void LStat(const FunctionCallbackInfo<Value>& args) {
               args,
               "lstat",
               UTF8,
-              AfterStat,
+              do_not_throw_if_no_entry ? AfterStatNoThrowIfNoEntry : AfterStat,
               uv_fs_lstat,
               *path);
   } else {  // lstat(path, use_bigint, undefined, throw_if_no_entry)
diff --git a/test/parallel/test-fs-stat.js b/test/parallel/test-fs-stat.js
index 93bf6573a109a7..a0a08e96ab5421 100644
--- a/test/parallel/test-fs-stat.js
+++ b/test/parallel/test-fs-stat.js
@@ -224,9 +224,23 @@ fs.lstat(__filename, undefined, common.mustCall());
 
 {
   // Test that the throwIfNoEntry option works and returns undefined
+  const path = 'does_not_exist';
   const opts = { throwIfNoEntry: false };
-  assert.ok(!(fs.statSync('./wont_exists', opts)));
-  fs.stat('./wont_exists', opts, common.mustSucceed((err, stats) => {
+
+  assert.strictEqual(fs.statSync(path, opts), undefined);
+  assert.strictEqual(fs.lstatSync(path, opts), undefined);
+
+  /* eslint-disable node-core/must-call-assert */
+
+  const assertResult = (stats) => {
     assert.strictEqual(stats, undefined);
-  }));
+  };
+
+  fs.stat(path, opts, common.mustSucceed(assertResult));
+  fs.lstat(path, opts, common.mustSucceed(assertResult));
+
+  fs.promises.stat(path, opts).then(common.mustCall(assertResult));
+  fs.promises.lstat(path, opts).then(common.mustCall(assertResult));
+
+  /* eslint-enable node-core/must-call-assert */
 }

From 10413d61b11b31dea2e848dd9909d157a192f538 Mon Sep 17 00:00:00 2001
From: Renegade334 <contact.9a5d6388@renegade334.me.uk>
Date: Mon, 4 May 2026 17:57:11 +0200
Subject: [PATCH 2/2] fixup! fs: add throwIfNoEntry option to
 fs.lstat/fs.promises.lstat

honey, I broke the linter
---
 test/parallel/test-fs-stat.js | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/test/parallel/test-fs-stat.js b/test/parallel/test-fs-stat.js
index a0a08e96ab5421..a1a9c394365abd 100644
--- a/test/parallel/test-fs-stat.js
+++ b/test/parallel/test-fs-stat.js
@@ -227,20 +227,17 @@ fs.lstat(__filename, undefined, common.mustCall());
   const path = 'does_not_exist';
   const opts = { throwIfNoEntry: false };
 
-  assert.strictEqual(fs.statSync(path, opts), undefined);
-  assert.strictEqual(fs.lstatSync(path, opts), undefined);
-
-  /* eslint-disable node-core/must-call-assert */
-
   const assertResult = (stats) => {
+    // eslint-disable-next-line node-core/must-call-assert
     assert.strictEqual(stats, undefined);
   };
 
+  assertResult(fs.statSync(path, opts));
+  assertResult(fs.lstatSync(path, opts));
+
   fs.stat(path, opts, common.mustSucceed(assertResult));
   fs.lstat(path, opts, common.mustSucceed(assertResult));
 
-  fs.promises.stat(path, opts).then(common.mustCall(assertResult));
-  fs.promises.lstat(path, opts).then(common.mustCall(assertResult));
-
-  /* eslint-enable node-core/must-call-assert */
+  fs.promises.stat(path, opts).then(assertResult).then(common.mustCall());
+  fs.promises.lstat(path, opts).then(assertResult).then(common.mustCall());
 }