fs: add signal option to fs.stat()

Author: mertcanaltin

doc/api/fs.md

@@ -622,15 +622,17 @@ Read from a file and write to an array of {ArrayBufferView}s
 <!-- YAML
 added: v10.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/57775
+    description: Now accepts an additional `signal` property 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
-                 the numeric values returned should be bigint.
+    description: Accepts an additional `options` object to specify whether the numeric values returned should be bigint.
 -->
 
 * `options` {Object}
-  * `bigint` {boolean} Whether the numeric values in the returned
-    {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `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 an {fs.Stats} for the file.
 
 #### `filehandle.sync()`

lib/fs.js

@@ -73,6 +73,7 @@ const {
   codes: {
     ERR_ACCESS_DENIED,
     ERR_FS_FILE_TOO_LARGE,
+    ERR_INVALID_ARG_TYPE,
     ERR_INVALID_ARG_VALUE,
   },
 } = require('internal/errors');
@@ -1620,22 +1621,57 @@ function lstat(path, options = { bigint: false }, callback) {
 /**
  * Asynchronously gets the stats of a file.
  * @param {string | Buffer | URL} path
- * @param {{ bigint?: boolean; }} [options]
+ * @param {{ bigint?: boolean, signal?: AbortSignal }} [options]
  * @param {(
  *   err?: Error,
  *   stats?: Stats
  *   ) => any} callback
  * @returns {void}
  */
-function stat(path, options = { bigint: false }, callback) {
+function stat(path, options = { __proto__: null, bigint: false, signal: undefined }, callback) {
   if (typeof options === 'function') {
     callback = options;
     options = kEmptyObject;
+  } else if (options === null || typeof options !== 'object') {
+    options = kEmptyObject;
+  } else {
+    options = getOptions(options, { __proto__: null, bigint: false, signal: undefined });
+  }
+
+  if (typeof callback !== 'function') {
+    throw new ERR_INVALID_ARG_TYPE('callback', 'Function', callback);
   }
-  callback = makeStatsCallback(callback);
 
+  const originalCallback = callback;
   const req = new FSReqCallback(options.bigint);
-  req.oncomplete = callback;
+
+  if (options.signal?.aborted) {
+    const abortErr = new AbortError('The operation was aborted', { __proto__: null, cause: options.signal.reason });
+    return process.nextTick(() => originalCallback(abortErr));
+  }
+
+  let aborted = false;
+  const onAbort = () => {
+    aborted = true;
+    originalCallback(new AbortError(undefined, { __proto__: null, cause: options.signal.reason }));
+  };
+
+  if (options.signal) {
+    options.signal.addEventListener('abort', onAbort, { __proto__: null, once: true });
+  }
+
+  req.oncomplete = (err, stats) => {
+    if (options.signal) {
+      options.signal.removeEventListener('abort', onAbort);
+    }
+
+    if (aborted) return;
+
+    const wrappedCallback = makeStatsCallback(originalCallback);
+
+    wrappedCallback(err, stats);
+  };
+
   binding.stat(getValidatedPath(path), options.bigint, req);
 }
 

test/parallel/test-fs-stat-abort-test.js

@@ -0,0 +1,25 @@
+'use strict';
+
+require('../common');
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+
+const filePath = './temp.txt';
+fs.writeFileSync(filePath, 'Test');
+
+test('fs.stat should throw AbortError when abort signal is triggered', async () => {
+  const signal = AbortSignal.abort();
+
+  const { promise, resolve, reject } = Promise.withResolvers();
+  fs.stat(filePath, { signal }, (err, stats) => {
+    if (err) {
+      return reject(err);
+    }
+    resolve(stats);
+  });
+
+  await assert.rejects(promise, { name: 'AbortError' });
+
+  fs.unlinkSync(filePath);
+});