From e4d317e5b4ff694e4d21ba25998fcf617b5c56c4 Mon Sep 17 00:00:00 2001
From: Mert Can Altin <mertgold60@gmail.com>
Date: Wed, 6 May 2026 08:08:49 +0300
Subject: [PATCH 1/2] fs: abort in-flight stat operations

Signed-off-by: Mert Can Altin <mertgold60@gmail.com>
---
 lib/fs.js                                | 25 ++++++++++++++--
 test/parallel/test-fs-stat-abort-test.js | 37 ++++++++++++++----------
 2 files changed, 44 insertions(+), 18 deletions(-)

diff --git a/lib/fs.js b/lib/fs.js
index d63fad8b2a258b..2626e2ac45fba9 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -136,6 +136,7 @@ const {
 const {
   isInt32,
   parseFileMode,
+  validateAbortSignal,
   validateBoolean,
   validateBuffer,
   validateEncoding,
@@ -340,6 +341,25 @@ function checkAborted(signal, callback) {
   return false;
 }
 
+function bindSignalToReq(req, signal, callback) {
+  if (!signal) {
+    req.oncomplete = callback;
+    return;
+  }
+  let aborted = false;
+  const onAbort = () => {
+    aborted = true;
+    callback(new AbortError(undefined, { cause: signal.reason }));
+  };
+  kResistStopPropagation ??= require('internal/event_target').kResistStopPropagation;
+  signal.addEventListener('abort', onAbort, { __proto__: null, [kResistStopPropagation]: true });
+  req.oncomplete = function(err, result) {
+    signal.removeEventListener('abort', onAbort);
+    if (aborted) return;
+    callback(err, result);
+  };
+}
+
 /**
  * Asynchronously reads the entire contents of a file.
  * @param {string | Buffer | URL | number} path
@@ -1635,11 +1655,12 @@ function stat(path, options = { bigint: false, throwIfNoEntry: true }, callback)
   callback = makeStatsCallback(callback);
   path = getValidatedPath(path);
 
+  if (options.signal !== undefined) validateAbortSignal(options.signal, 'options.signal');
   if (checkAborted(options.signal, callback)) return;
 
   const req = new FSReqCallback(options.bigint);
-  req.oncomplete = callback;
-  binding.stat(getValidatedPath(path), options.bigint, req, options.throwIfNoEntry);
+  bindSignalToReq(req, options.signal, callback);
+  binding.stat(path, options.bigint, req, options.throwIfNoEntry);
 }
 
 function statfs(path, options = { bigint: false }, callback) {
diff --git a/test/parallel/test-fs-stat-abort-test.js b/test/parallel/test-fs-stat-abort-test.js
index 2a2b35f8030d7f..1c78f74522e167 100644
--- a/test/parallel/test-fs-stat-abort-test.js
+++ b/test/parallel/test-fs-stat-abort-test.js
@@ -6,29 +6,34 @@ const assert = require('node:assert');
 const fs = require('node:fs');
 const tmpdir = require('../common/tmpdir');
 
-test('fs.stat should throw AbortError when called with an already aborted AbortSignal', async () => {
-  // This test verifies that fs.stat immediately throws an AbortError if the provided AbortSignal
-  // has already been canceled. This approach is used because trying to abort an fs.stat call in flight
-  // is unreliable given that file system operations tend to complete very quickly on many platforms.
-  tmpdir.refresh();
+tmpdir.refresh();
+const filePath = tmpdir.resolve('temp.txt');
+fs.writeFileSync(filePath, 'Test');
 
-  const filePath = tmpdir.resolve('temp.txt');
-  fs.writeFileSync(filePath, 'Test');
-
-  // Create an already aborted AbortSignal.
+test('fs.stat aborts when signal is already aborted', async () => {
   const signal = AbortSignal.abort();
-
   const { promise, resolve, reject } = Promise.withResolvers();
   fs.stat(filePath, { signal }, (err, stats) => {
-    if (err) {
-      return reject(err);
-    }
+    if (err) return reject(err);
     resolve(stats);
   });
+  await assert.rejects(promise, { name: 'AbortError' });
+});
 
-  // Assert that the promise is rejected with an AbortError.
+test('fs.stat aborts in-flight when signal aborts after the call', async () => {
+  const controller = new AbortController();
+  const { promise, resolve, reject } = Promise.withResolvers();
+  fs.stat(filePath, { signal: controller.signal }, (err, stats) => {
+    if (err) return reject(err);
+    resolve(stats);
+  });
+  controller.abort();
   await assert.rejects(promise, { name: 'AbortError' });
+});
 
-  fs.unlinkSync(filePath);
-  tmpdir.refresh();
+test('fs.stat throws ERR_INVALID_ARG_TYPE for invalid signal', () => {
+  assert.throws(
+    () => fs.stat(filePath, { signal: 'not-a-signal' }, () => {}),
+    { code: 'ERR_INVALID_ARG_TYPE' },
+  );
 });

From face7e95e998c1c5ffef326d10d5243e3679e532 Mon Sep 17 00:00:00 2001
From: Mert Can Altin <mertgold60@gmail.com>
Date: Wed, 6 May 2026 08:12:03 +0300
Subject: [PATCH 2/2] fs: extend signal option to lstat, fstat and promises API

Signed-off-by: Mert Can Altin <mertgold60@gmail.com>
---
 doc/api/fs.md                            | 24 +++++++++
 lib/fs.js                                | 20 +++++--
 lib/internal/fs/promises.js              | 63 +++++++++++++++++-----
 test/parallel/test-fs-stat-abort-test.js | 66 ++++++++++++++++++++++++
 4 files changed, 157 insertions(+), 16 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index b2231bd20cc420..dcd5e3e6fe7b39 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/57775
+    description: Accepts an additional `signal` option to allow aborting the
+                 operation.
   - 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,8 @@ changes:
 * `options` {Object}
   * `bigint` {boolean} Whether the numeric values in the returned
     {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `signal` {AbortSignal} An AbortSignal to cancel the operation.
+    **Default:** `undefined`.
 * Returns: {Promise}  Fulfills with the {fs.Stats} object for the given
   symbolic link `path`.
 
@@ -1982,6 +1988,10 @@ Removes files and directories (modeled on the standard POSIX `rm` utility).
 <!-- YAML
 added: v10.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/57775
+    description: Accepts an additional `signal` option to allow aborting the
+                 operation.
   - version: v25.7.0
     pr-url: https://github.com/nodejs/node/pull/61178
     description: Accepts a `throwIfNoEntry` option to specify whether
@@ -1999,6 +2009,8 @@ changes:
   * `throwIfNoEntry` {boolean} Whether an exception will be thrown
     if no file system entry exists, rather than returning `undefined`.
     **Default:** `true`.
+  * `signal` {AbortSignal} An AbortSignal to cancel the operation.
+    **Default:** `undefined`.
 * Returns: {Promise}  Fulfills with the {fs.Stats} object for the
   given `path`.
 
@@ -3309,6 +3321,10 @@ exception are given to the completion callback.
 <!-- YAML
 added: v0.1.95
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/57775
+    description: Accepts an additional `signal` option to allow aborting the
+                 operation.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41678
     description: Passing an invalid callback to the `callback` argument
@@ -3332,6 +3348,8 @@ changes:
 * `options` {Object}
   * `bigint` {boolean} Whether the numeric values in the returned
     {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `signal` {AbortSignal} An AbortSignal to cancel the operation.
+    **Default:** `undefined`.
 * `callback` {Function}
   * `err` {Error}
   * `stats` {fs.Stats}
@@ -3673,6 +3691,10 @@ exception are given to the completion callback.
 <!-- YAML
 added: v0.1.30
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/57775
+    description: Accepts an additional `signal` option to allow aborting the
+                 operation.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41678
     description: Passing an invalid callback to the `callback` argument
@@ -3700,6 +3722,8 @@ changes:
 * `options` {Object}
   * `bigint` {boolean} Whether the numeric values in the returned
     {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `signal` {AbortSignal} An AbortSignal to cancel the operation.
+    **Default:** `undefined`.
 * `callback` {Function}
   * `err` {Error}
   * `stats` {fs.Stats}
diff --git a/lib/fs.js b/lib/fs.js
index 2626e2ac45fba9..a9ca70455c83c7 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -1584,7 +1584,7 @@ function readdirSync(path, options) {
  * Invokes the callback with the `fs.Stats`
  * for the file descriptor.
  * @param {number} fd
- * @param {{ bigint?: boolean; }} [options]
+ * @param {{ bigint?: boolean, signal?: AbortSignal }} [options]
  * @param {(
  *   err?: Error,
  *   stats?: Stats
@@ -1595,11 +1595,16 @@ function fstat(fd, options = { bigint: false }, callback) {
   if (typeof options === 'function') {
     callback = options;
     options = kEmptyObject;
+  } else if (options === null || typeof options !== 'object') {
+    options = kEmptyObject;
   }
   callback = makeStatsCallback(callback);
 
+  if (options.signal !== undefined) validateAbortSignal(options.signal, 'options.signal');
+  if (checkAborted(options.signal, callback)) return;
+
   const req = new FSReqCallback(options.bigint);
-  req.oncomplete = callback;
+  bindSignalToReq(req, options.signal, callback);
   binding.fstat(fd, options.bigint, req);
 }
 
@@ -1607,7 +1612,7 @@ 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, signal?: AbortSignal }} [options]
  * @param {(
  *   err?: Error,
  *   stats?: Stats
@@ -1618,6 +1623,10 @@ function lstat(path, options = { bigint: false }, callback) {
   if (typeof options === 'function') {
     callback = options;
     options = kEmptyObject;
+  } else if (options === null || typeof options !== 'object') {
+    options = kEmptyObject;
+  } else {
+    options = getOptions(options, { bigint: false });
   }
   callback = makeStatsCallback(callback);
   path = getValidatedPath(path);
@@ -1627,8 +1636,11 @@ function lstat(path, options = { bigint: false }, callback) {
     return;
   }
 
+  if (options.signal !== undefined) validateAbortSignal(options.signal, 'options.signal');
+  if (checkAborted(options.signal, callback)) return;
+
   const req = new FSReqCallback(options.bigint);
-  req.oncomplete = callback;
+  bindSignalToReq(req, options.signal, callback);
   binding.lstat(path, options.bigint, req);
 }
 
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 40de890c6eb2d3..adf3423ca44daf 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -14,6 +14,7 @@ const {
   PromiseResolve,
   SafeArrayIterator,
   SafePromisePrototypeFinally,
+  SafePromiseRace,
   Symbol,
   SymbolAsyncDispose,
   SymbolAsyncIterator,
@@ -125,6 +126,7 @@ const kLocked = Symbol('kLocked');
 const kCloseSync = Symbol('kCloseSync');
 
 const { kUsePromises } = binding;
+let kResistStopPropagation;
 const { Interface } = require('internal/readline/interface');
 const {
   kDeserialize, kTransfer, kTransferList, markTransferMode,
@@ -1116,6 +1118,25 @@ function checkAborted(signal) {
     throw new AbortError(undefined, { cause: signal.reason });
 }
 
+async function raceWithSignal(opPromise, signal) {
+  if (!signal) return opPromise;
+  kResistStopPropagation ??= require('internal/event_target').kResistStopPropagation;
+  let onAbort;
+  const abortPromise = new Promise((_, reject) => {
+    onAbort = () => reject(new AbortError(undefined, { cause: signal.reason }));
+    signal.addEventListener('abort', onAbort, {
+      __proto__: null,
+      once: true,
+      [kResistStopPropagation]: true,
+    });
+  });
+  try {
+    return await SafePromiseRace([opPromise, abortPromise]);
+  } finally {
+    signal.removeEventListener('abort', onAbort);
+  }
+}
+
 async function writeFileHandle(filehandle, data, signal, encoding) {
   checkAborted(signal);
   if (isCustomIterable(data)) {
@@ -1654,33 +1675,51 @@ async function symlink(target, path, type) {
 }
 
 async function fstat(handle, options = { bigint: false }) {
-  const result = await PromisePrototypeThen(
-    binding.fstat(handle.fd, options.bigint, kUsePromises),
-    undefined,
-    handleErrorFromBinding,
+  const signal = options?.signal;
+  if (signal !== undefined) validateAbortSignal(signal, 'options.signal');
+  checkAborted(signal);
+  const result = await raceWithSignal(
+    PromisePrototypeThen(
+      binding.fstat(handle.fd, options.bigint, kUsePromises),
+      undefined,
+      handleErrorFromBinding,
+    ),
+    signal,
   );
   return getStatsFromBinding(result);
 }
 
 async function lstat(path, options = { bigint: false }) {
+  const signal = options?.signal;
+  if (signal !== undefined) validateAbortSignal(signal, 'options.signal');
+  checkAborted(signal);
   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),
-    undefined,
-    handleErrorFromBinding,
+  const result = await raceWithSignal(
+    PromisePrototypeThen(
+      binding.lstat(path, options.bigint, kUsePromises),
+      undefined,
+      handleErrorFromBinding,
+    ),
+    signal,
   );
   return getStatsFromBinding(result);
 }
 
 async function stat(path, options = { bigint: false, throwIfNoEntry: true }) {
-  const result = await PromisePrototypeThen(
-    binding.stat(getValidatedPath(path), options.bigint, kUsePromises, options.throwIfNoEntry),
-    undefined,
-    handleErrorFromBinding,
+  const signal = options?.signal;
+  if (signal !== undefined) validateAbortSignal(signal, 'options.signal');
+  checkAborted(signal);
+  const result = await raceWithSignal(
+    PromisePrototypeThen(
+      binding.stat(getValidatedPath(path), options.bigint, kUsePromises, options.throwIfNoEntry),
+      undefined,
+      handleErrorFromBinding,
+    ),
+    signal,
   );
 
   // Binding will resolve undefined if UV_ENOENT or UV_ENOTDIR and throwIfNoEntry is false
diff --git a/test/parallel/test-fs-stat-abort-test.js b/test/parallel/test-fs-stat-abort-test.js
index 1c78f74522e167..e820aaf5565564 100644
--- a/test/parallel/test-fs-stat-abort-test.js
+++ b/test/parallel/test-fs-stat-abort-test.js
@@ -4,6 +4,7 @@ require('../common');
 const test = require('node:test');
 const assert = require('node:assert');
 const fs = require('node:fs');
+const fsPromises = require('node:fs/promises');
 const tmpdir = require('../common/tmpdir');
 
 tmpdir.refresh();
@@ -37,3 +38,68 @@ test('fs.stat throws ERR_INVALID_ARG_TYPE for invalid signal', () => {
     { code: 'ERR_INVALID_ARG_TYPE' },
   );
 });
+
+test('fs.lstat aborts in-flight when signal aborts after the call', async () => {
+  const controller = new AbortController();
+  const { promise, resolve, reject } = Promise.withResolvers();
+  fs.lstat(filePath, { signal: controller.signal }, (err, stats) => {
+    if (err) return reject(err);
+    resolve(stats);
+  });
+  controller.abort();
+  await assert.rejects(promise, { name: 'AbortError' });
+});
+
+test('fs.fstat aborts in-flight when signal aborts after the call', async () => {
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const controller = new AbortController();
+    const { promise, resolve, reject } = Promise.withResolvers();
+    fs.fstat(fd, { signal: controller.signal }, (err, stats) => {
+      if (err) return reject(err);
+      resolve(stats);
+    });
+    controller.abort();
+    await assert.rejects(promise, { name: 'AbortError' });
+  } finally {
+    fs.closeSync(fd);
+  }
+});
+
+test('fsPromises.stat rejects when signal is already aborted', async () => {
+  const signal = AbortSignal.abort();
+  await assert.rejects(fsPromises.stat(filePath, { signal }), { name: 'AbortError' });
+});
+
+test('fsPromises.stat rejects in-flight when signal aborts after the call', async () => {
+  const controller = new AbortController();
+  const p = fsPromises.stat(filePath, { signal: controller.signal });
+  controller.abort();
+  await assert.rejects(p, { name: 'AbortError' });
+});
+
+test('fsPromises.stat rejects with ERR_INVALID_ARG_TYPE for invalid signal', async () => {
+  await assert.rejects(
+    fsPromises.stat(filePath, { signal: 'not-a-signal' }),
+    { code: 'ERR_INVALID_ARG_TYPE' },
+  );
+});
+
+test('fsPromises.lstat rejects in-flight when signal aborts after the call', async () => {
+  const controller = new AbortController();
+  const p = fsPromises.lstat(filePath, { signal: controller.signal });
+  controller.abort();
+  await assert.rejects(p, { name: 'AbortError' });
+});
+
+test('filehandle.stat rejects in-flight when signal aborts after the call', async () => {
+  const fh = await fsPromises.open(filePath, 'r');
+  try {
+    const controller = new AbortController();
+    const p = fh.stat({ signal: controller.signal });
+    controller.abort();
+    await assert.rejects(p, { name: 'AbortError' });
+  } finally {
+    await fh.close();
+  }
+});