fs: add signal option to fs.stat() · nodejs/node@9705f62

<!-- 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()`

/**

* 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

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);

if (checkAborted(options.signal, callback)) return;

const req = new FSReqCallback(options.bigint);

req.oncomplete = callback;

'use strict';

require('../common');

const test = require('node:test');

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();

const filePath = tmpdir.resolve('temp.txt');

fs.writeFileSync(filePath, 'Test');

// Create an already aborted AbortSignal.

const signal = AbortSignal.abort();

const { promise, resolve, reject } = Promise.withResolvers();

fs.stat(filePath, { signal }, (err, stats) => {

if (err) {

return reject(err);

}

resolve(stats);

});

// Assert that the promise is rejected with an AbortError.

await assert.rejects(promise, { name: 'AbortError' });

fs.unlinkSync(filePath);

tmpdir.refresh();

});