fs: add signal option to fs.stat()

PR-URL: #57775
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Jason Zhang <xzha4350@gmail.com>
Reviewed-By: Edy Silva <edigleyssonsilva@gmail.com>
Reviewed-By: Aviv Keller <me@aviv.sh>
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>

Author: mertcanaltin

doc/api/fs.md

@@ -628,15 +628,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

@@ -1652,7 +1652,7 @@ 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
@@ -1663,8 +1663,16 @@ function stat(path, options = { bigint: false, throwIfNoEntry: true }, callback)
 if(typeofoptions==='function'){
 callback=options;
 options=kEmptyObject;
+}elseif(options===null||typeofoptions!=='object'){
+options=kEmptyObject;
+}else{
+options=getOptions(options,{bigint: false});
 }
+
 callback=makeStatsCallback(callback);
+path=getValidatedPath(path);
+
+if(checkAborted(options.signal,callback))return;
 
 constreq=newFSReqCallback(options.bigint);
 req.oncomplete=callback;

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

@@ -0,0 +1,34 @@
+'use strict';
+
+require('../common');
+consttest=require('node:test');
+constassert=require('node:assert');
+constfs=require('node:fs');
+consttmpdir=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();
+
+constfilePath=tmpdir.resolve('temp.txt');
+fs.writeFileSync(filePath,'Test');
+
+// Create an already aborted AbortSignal.
+constsignal=AbortSignal.abort();
+
+const{ promise, resolve, reject }=Promise.withResolvers();
+fs.stat(filePath,{ signal },(err,stats)=>{
+if(err){
+returnreject(err);
+}
+resolve(stats);
+});
+
+// Assert that the promise is rejected with an AbortError.
+awaitassert.rejects(promise,{name: 'AbortError'});
+
+fs.unlinkSync(filePath);
+tmpdir.refresh();
+});