lib: add throws option to fs.f/l/statSync

benchmark/fs/bench-statSync-failure.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common');
+const fs = require('fs');
+const path = require('path');
+
+const bench = common.createBenchmark(main, {
+  n: [1e6],
+  statSyncType: ['throw', 'noThrow']
+});
+
+
+function main({ n, statSyncType }) {
+  const arg = path.join(__dirname, 'non.existent');
+
+  bench.start();
+  for (let i = 0; i < n; i++) {
+    if (statSyncType === 'noThrow') {
+      fs.statSync(arg, { throwIfNoEntry: false });
+    } else {
+      try {
+        fs.statSync(arg);
+      } catch {
+      }
+    }
+  }
+  bench.end(n);
+}

doc/api/fs.md

@@ -2568,6 +2568,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: {fs.Stats}
 
 Synchronous lstat(2).
@@ -3810,6 +3813,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: {fs.Stats}
 
 Synchronous stat(2).

lib/fs.js

@@ -72,6 +72,7 @@ const {
     ERR_FEATURE_UNAVAILABLE_ON_PLATFORM
   },
   hideStackFrames,
+  uvErrmapGet,
   uvException
 } = require('internal/errors');
 
@@ -1076,28 +1077,47 @@ function stat(path, options = { bigint: false }, callback) {
   binding.stat(pathModule.toNamespacedPath(path), options.bigint, req);
 }
 
-function fstatSync(fd, options = { bigint: false }) {
+function hasNoEntryError(ctx) {
+  if (ctx.errno) {
+    const uvErr = uvErrmapGet(ctx.errno);
+    return uvErr && uvErr[0] === 'ENOENT';
+  }
+
+  if (ctx.error) {
+    return ctx.error.code === 'ENOENT';
+  }
+
+  return false;
+}
+
+function fstatSync(fd, options = { bigint: false, throwIfNoEntry: true }) {
   validateInt32(fd, 'fd', 0);
   const ctx = { fd };
   const stats = binding.fstat(fd, options.bigint, undefined, ctx);
   handleErrorFromBinding(ctx);
   return getStatsFromBinding(stats);
 }
 
-function lstatSync(path, options = { bigint: false }) {
+function lstatSync(path, options = { bigint: false, throwIfNoEntry: true }) {
   path = getValidatedPath(path);
   const ctx = { path };
   const stats = binding.lstat(pathModule.toNamespacedPath(path),
                               options.bigint, undefined, ctx);
+  if (options.throwIfNoEntry === false && hasNoEntryError(ctx)) {
+    return undefined;
+  }
   handleErrorFromBinding(ctx);
   return getStatsFromBinding(stats);
 }
 
-function statSync(path, options = { bigint: false }) {
+function statSync(path, options = { bigint: false, throwIfNoEntry: true }) {
   path = getValidatedPath(path);
   const ctx = { path };
   const stats = binding.stat(pathModule.toNamespacedPath(path),
                              options.bigint, undefined, ctx);
+  if (options.throwIfNoEntry === false && hasNoEntryError(ctx)) {
+    return undefined;
+  }
   handleErrorFromBinding(ctx);
   return getStatsFromBinding(stats);
 }

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

@@ -122,6 +122,33 @@ if (!common.isWindows) {
   fs.closeSync(fd);
 }
 
+{
+  assert.throws(
+    () => fs.statSync('does_not_exist'),
+    { code: 'ENOENT' });
+  assert.strictEqual(
+    fs.statSync('does_not_exist', { throwIfNoEntry: false }),
+    undefined);
+}
+
+{
+  assert.throws(
+    () => fs.lstatSync('does_not_exist'),
+    { code: 'ENOENT' });
+  assert.strictEqual(
+    fs.lstatSync('does_not_exist', { throwIfNoEntry: false }),
+    undefined);
+}
+
+{
+  assert.throws(
+    () => fs.fstatSync(9999),
+    { code: 'EBADF' });
+  assert.throws(
+    () => fs.fstatSync(9999, { throwIfNoEntry: false }),
+    { code: 'EBADF' });
+}
+
 const runCallbackTest = (func, arg, done) => {
   const startTime = process.hrtime.bigint();
   func(arg, { bigint: true }, common.mustCall((err, bigintStats) => {