@photostructure/fs-metadata 1.4.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photostructure/fs-metadata",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "description": "Cross-platform native filesystem metadata retrieval for Node.js",
   "homepage": "https://photostructure.github.io/fs-metadata/",
   "types": "./dist/index.d.ts",
@@ -13,7 +13,7 @@
         "default": "./dist/index.cjs"
       },
       "import": {
-        "types": "./dist/index.d.ts",
+        "types": "./dist/index.d.mts",
         "default": "./dist/index.mjs"
       }
     },
@@ -46,6 +46,8 @@
     "lint:native": "tsx scripts/clang-tidy.ts",
     "lint:tsc": "tsc --noEmit",
     "lint:eslint": "eslint",
+    "// check:exports": "verify package.json exports + type declarations resolve correctly (arethetypeswrong). Requires `npm run build:dist` first.",
+    "check:exports": "attw --pack .",
     "fmt": "run-p fmt:*",
     "// fmt:cpp": "on ubuntu: `sudo apt install clang-format`. Note that windows emits `invalid format` with this || true approach, but it works and is better than introducing Yet Another Script Script (like scripts/clang-format.mjs).",
     "fmt:cpp": "clang-format --style=LLVM -i src/*.cpp src/*/*.cpp src/*/*.h || echo \"problem with clang-format\"",
@@ -68,7 +70,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22"
   },
   "os": [
     "darwin",
@@ -90,32 +92,33 @@
     "cross-platform"
   ],
   "dependencies": {
-    "node-addon-api": "^8.7.0",
+    "node-addon-api": "^8.8.0",
     "node-gyp-build": "^4.8.4"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.9.1",
     "@types/semver": "^7.7.1",
     "cross-env": "^10.1.0",
     "del-cli": "^7.0.0",
     "eslint": "9.39.1",
     "eslint-plugin-regexp": "^3.1.0",
     "eslint-plugin-security": "^4.0.0",
-    "globals": "^17.5.0",
-    "jest": "^30.3.0",
-    "jest-environment-node": "^30.3.0",
+    "globals": "^17.6.0",
+    "jest": "^30.4.2",
+    "jest-environment-node": "^30.4.1",
     "jest-extended": "^7.0.0",
-    "node-gyp": "^12.2.0",
-    "npm-check-updates": "^21.0.2",
-    "npm-run-all2": "8.0.4",
+    "node-gyp": "^12.3.0",
+    "npm-check-updates": "^22.2.2",
+    "npm-run-all2": "9.0.1",
     "prebuildify": "^6.0.1",
     "prettier": "^3.8.3",
     "prettier-plugin-organize-imports": "4.3.0",
-    "terser": "^5.46.1",
-    "ts-jest": "^29.4.9",
+    "terser": "^5.48.0",
+    "ts-jest": "^29.4.11",
     "tsup": "^8.5.1",
-    "tsx": "^4.21.0",
+    "tsx": "^4.22.4",
     "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.2"

package/scripts/post-build.mjs

@@ -7,15 +7,24 @@ import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const distDir = join(__dirname, "..", "dist");
 
-// Copy .d.ts to .d.cts for CommonJS type safety
-async function createCjsTypes() {
+// Copy .d.ts to .d.cts and .d.mts so each exports condition resolves to a
+// declaration file whose module format matches its JavaScript counterpart.
+//
+// Without a .d.mts file, the `import` condition's types (`index.d.ts`) are
+// interpreted as CommonJS (the package has no `"type": "module"`), while the
+// resolved JavaScript (`index.mjs`) is ESM. That mismatch is the "Masquerading
+// as CJS" / FalseCJS problem reported by arethetypeswrong. A .d.cts pairs with
+// the CJS `.cjs` output; a .d.mts pairs with the ESM `.mjs` output.
+async function createDualTypes() {
   try {
     await copyFile(join(distDir, "index.d.ts"), join(distDir, "index.d.cts"));
     console.log("Created index.d.cts for CommonJS type safety");
+    await copyFile(join(distDir, "index.d.ts"), join(distDir, "index.d.mts"));
+    console.log("Created index.d.mts for ESM type safety");
   } catch (error) {
-    console.error("Error creating .d.cts file:", error);
+    console.error("Error creating dual declaration files:", error);
     process.exit(1);
   }
 }
 
-createCjsTypes();
+createDualTypes();

package/scripts/prebuildify-wrapper.ts

@@ -21,6 +21,11 @@ console.log(`Building for platform: ${currentPlatform}, arch: ${currentArch}`);
 // Set up environment variables to help node-gyp
 const env = { ...process.env };
 
+// Architecture-specific compiler defines for Windows. Tracked in a local so we
+// can log the value we set without reading it back out of the environment
+// (which CodeQL flags as clear-text logging of process environment data).
+let clDefines: string | undefined;
+
 // Set architecture-specific defines for Windows
 if (currentPlatform === "win32") {
   // Try various environment variables that might work
@@ -30,9 +35,13 @@ if (currentPlatform === "win32") {
 
   // Try setting compiler flags directly
   if (currentArch === "x64") {
-    env.CL = "/D_M_X64 /D_WIN64 /D_AMD64_";
+    clDefines = "/D_M_X64 /D_WIN64 /D_AMD64_";
   } else if (currentArch === "arm64") {
-    env.CL = "/D_M_ARM64 /D_WIN64";
+    clDefines = "/D_M_ARM64 /D_WIN64";
+  }
+
+  if (clDefines) {
+    env.CL = clDefines;
   }
 }
 
@@ -53,8 +62,8 @@ if (process.argv.length > 2) {
 }
 
 console.log(`Running: prebuildify ${args.join(" ")}`);
-if (currentPlatform === "win32" && env.CL) {
-  console.log(`CL environment variable: ${env.CL}`);
+if (currentPlatform === "win32" && clDefines) {
+  console.log(`CL environment variable: ${clDefines}`);
 }
 
 // Spawn prebuildify with the arguments

package/scripts/precommit.ts

@@ -36,6 +36,10 @@ run({ cmd: "npm run fmt", desc: "Formatting code" });
 run({ cmd: "npm run lint", desc: "Running linting checks" });
 run({ cmd: "npm run docs", desc: "TypeDoc generation" });
 run({ cmd: "npm run build:dist", desc: "Building distribution files" });
+run({
+  cmd: "npm run check:exports",
+  desc: "Verifying package exports & type declarations (arethetypeswrong)",
+});
 
 // Detect if we're using glibc (vs musl)
 // Check process.report for musl loader - if not found, assume glibc

package/src/binding.cpp

@@ -3,6 +3,7 @@
 #include <string>
 
 #include "common/debug_log.h"
+#include "common/shutdown.h"
 #if defined(_WIN32)
 #include "windows/fs_meta.h"
 #include "windows/hidden.h"
@@ -67,6 +68,10 @@ Napi::Value SetHiddenAttribute(const Napi::CallbackInfo &info) {
 #endif
 
 Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  // Register a cleanup hook so in-flight native workers can short-circuit
+  // during env teardown instead of racing FreeEnvironment.
+  FSMeta::EnsureShutdownHook(env);
+
   exports.Set("setDebugLogging", Napi::Function::New(env, SetDebugLogging));
   exports.Set("setDebugPrefix", Napi::Function::New(env, SetDebugPrefix));
 

package/src/common/metadata_worker.h

@@ -1,11 +1,12 @@
 // src/common/metadata_worker.h
 #pragma once
+#include "./shutdown.h"
 #include "./volume_metadata.h"
 #include <napi.h>
 
 namespace FSMeta {
 
-class MetadataWorkerBase : public Napi::AsyncWorker {
+class MetadataWorkerBase : public SafeAsyncWorker {
 protected:
   std::string mountPoint;
   VolumeMetadata metadata;
@@ -13,17 +14,18 @@ protected:
 
   MetadataWorkerBase(const std::string &path,
                      const Napi::Promise::Deferred &deferred)
-      : Napi::AsyncWorker(deferred.Env()), mountPoint(path),
-        deferred_(deferred) {}
+      : SafeAsyncWorker(deferred.Env()), mountPoint(path), deferred_(deferred) {
+  }
 
   void OnError(const Napi::Error &error) override {
-    deferred_.Reject(error.Value());
+    Napi::HandleScope scope(Env());
+    SafeReject(deferred_, error.Value());
   }
 
   void OnOK() override {
     Napi::HandleScope scope(Env());
-    deferred_.Resolve(metadata.ToObject(Env()));
+    SafeResolve(deferred_, metadata.ToObject(Env()));
   }
 }; // class MetadataWorkerBase
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/common/shutdown.h

@@ -0,0 +1,160 @@
+// src/common/shutdown.h
+// Shutdown-safety helpers: a per-env flag set during Node env teardown,
+// plus deferred Resolve/Reject wrappers that swallow C++ Napi errors so they
+// can never escape AsyncWorker callbacks.
+//
+// Why this exists: AsyncWorker::OnWorkComplete can run during
+// node::FreeEnvironment cleanup. If napi_resolve_deferred /
+// napi_reject_deferred fail at that point (env tearing down), node-addon-api
+// throws a C++ Napi::Error. With NAPI_CPP_EXCEPTIONS the rethrow path inside
+// WrapVoidCallback then calls ThrowAsJavaScriptException, which can also fail,
+// letting the C++ exception escape into a libuv cleanup hook frame that has
+// no catch - terminate() / SIGABRT.
+//
+// The flag is stored as napi instance data so worker threads (each their own
+// env) don't poison the main env's flag when they tear down.
+//
+
+#pragma once
+
+#include <atomic>
+#include <memory>
+#include <napi.h>
+#include <string>
+
+namespace FSMeta {
+
+struct ShutdownState {
+  std::atomic<bool> shuttingDown{false};
+};
+
+struct ModuleInstanceData {
+  std::shared_ptr<ShutdownState> shutdownState =
+      std::make_shared<ShutdownState>();
+};
+
+inline ModuleInstanceData *GetInstanceData(napi_env env) {
+  void *raw = nullptr;
+  if (napi_get_instance_data(env, &raw) != napi_ok) {
+    return nullptr;
+  }
+  return static_cast<ModuleInstanceData *>(raw);
+}
+
+inline bool IsShuttingDown(napi_env env) {
+  if (auto *d = GetInstanceData(env)) {
+    return d->shutdownState->shuttingDown.load(std::memory_order_acquire);
+  }
+  // No instance data registered (test harness, etc.) - fail safe: not shutting.
+  return false;
+}
+
+inline std::shared_ptr<ShutdownState> GetShutdownState(napi_env env) {
+  if (auto *d = GetInstanceData(env)) {
+    return d->shutdownState;
+  }
+  return nullptr;
+}
+
+inline bool IsShuttingDown(const std::shared_ptr<ShutdownState> &state) {
+  return state != nullptr &&
+         state->shuttingDown.load(std::memory_order_acquire);
+}
+
+// Registers per-env shutdown state and a cleanup hook that flips the flag.
+// Idempotent per env: binding.cpp Init runs once per env load.
+inline void EnsureShutdownHook(napi_env env) {
+  if (GetInstanceData(env) != nullptr) {
+    return;
+  }
+  auto *data = new ModuleInstanceData();
+  auto *cleanupState = new std::shared_ptr<ShutdownState>(data->shutdownState);
+  napi_status status = napi_set_instance_data(
+      env, data,
+      [](napi_env /*env*/, void *raw, void * /*hint*/) {
+        delete static_cast<ModuleInstanceData *>(raw);
+      },
+      nullptr);
+  if (status != napi_ok) {
+    delete cleanupState;
+    delete data;
+    return;
+  }
+  status = napi_add_env_cleanup_hook(
+      env,
+      [](void *arg) {
+        auto *state = static_cast<std::shared_ptr<ShutdownState> *>(arg);
+        (*state)->shuttingDown.store(true, std::memory_order_release);
+        delete state;
+      },
+      cleanupState);
+  if (status != napi_ok) {
+    delete cleanupState;
+  }
+}
+
+// Wrap deferred.Resolve so a teardown-time napi failure cannot escape the
+// AsyncWorker callback as an uncaught C++ exception.
+inline void SafeResolve(const Napi::Promise::Deferred &deferred,
+                        napi_value value) {
+  try {
+    deferred.Resolve(value);
+  } catch (...) {
+    // Env is tearing down; the JS-side promise is unobservable anyway.
+  }
+}
+
+inline void SafeReject(const Napi::Promise::Deferred &deferred,
+                       napi_value value) {
+  try {
+    deferred.Reject(value);
+  } catch (...) {
+    // Env is tearing down; the JS-side promise is unobservable anyway.
+  }
+}
+
+class SafeAsyncWorker : public Napi::AsyncWorker {
+public:
+  void OnExecute(Napi::Env /*env*/) override {
+    try {
+      Execute();
+    } catch (const std::exception &e) {
+      SetError(e.what());
+    } catch (...) {
+      SetError("Unknown native error");
+    }
+  }
+
+  void OnWorkComplete(Napi::Env env, napi_status status) override {
+    if (status != napi_cancelled && !IsShuttingDown()) {
+      try {
+        Napi::HandleScope scope(env);
+        if (status != napi_ok) {
+          OnError(Napi::Error::New(env));
+        } else if (error_.empty()) {
+          OnOK();
+        } else {
+          OnError(Napi::Error::New(env, error_));
+        }
+      } catch (...) {
+        // Env teardown can make value construction, handle scopes, or deferred
+        // resolution fail. The JS promise is no longer observable then.
+      }
+    }
+    Destroy();
+  }
+
+protected:
+  explicit SafeAsyncWorker(Napi::Env env)
+      : Napi::AsyncWorker(env), shutdownState_(GetShutdownState(env)) {}
+
+  void SetError(const std::string &error) { error_ = error; }
+
+  bool IsShuttingDown() const { return FSMeta::IsShuttingDown(shutdownState_); }
+
+private:
+  std::shared_ptr<ShutdownState> shutdownState_;
+  std::string error_;
+};
+
+} // namespace FSMeta

package/src/darwin/get_mount_point.cpp

@@ -7,6 +7,7 @@
 #include "../common/error_utils.h"
 #include "../common/fd_guard.h"
 #include "../common/path_security.h"
+#include "../common/shutdown.h"
 
 #include <fcntl.h>
 #include <string>
@@ -16,11 +17,11 @@
 
 namespace FSMeta {
 
-class GetMountPointWorker : public Napi::AsyncWorker {
+class GetMountPointWorker : public SafeAsyncWorker {
 public:
   GetMountPointWorker(const std::string &path,
                       const Napi::Promise::Deferred &deferred)
-      : Napi::AsyncWorker(deferred.Env()), path_(path), deferred_(deferred) {}
+      : SafeAsyncWorker(deferred.Env()), path_(path), deferred_(deferred) {}
 
   void Execute() override {
     DEBUG_LOG("[GetMountPointWorker] Executing for path: %s", path_.c_str());
@@ -65,11 +66,12 @@ public:
 
   void OnOK() override {
     Napi::HandleScope scope(Env());
-    deferred_.Resolve(Napi::String::New(Env(), result_));
+    SafeResolve(deferred_, Napi::String::New(Env(), result_));
   }
 
   void OnError(const Napi::Error &error) override {
-    deferred_.Reject(error.Value());
+    Napi::HandleScope scope(Env());
+    SafeReject(deferred_, error.Value());
   }
 
 private:

package/src/darwin/hidden.cpp

@@ -4,6 +4,7 @@
 #include "../common/error_utils.h"
 #include "../common/fd_guard.h"
 #include "../common/path_security.h"
+#include "../common/shutdown.h"
 #include <fcntl.h>  // for open(), O_RDONLY, O_CLOEXEC
 #include <string.h> // for strcmp
 #include <sys/mount.h>
@@ -14,7 +15,7 @@ namespace FSMeta {
 
 GetHiddenWorker::GetHiddenWorker(std::string path,
                                  Napi::Promise::Deferred deferred)
-    : Napi::AsyncWorker(deferred.Env()), path_(std::move(path)),
+    : SafeAsyncWorker(deferred.Env()), path_(std::move(path)),
       deferred_(deferred), is_hidden_(false) {
   DEBUG_LOG("[GetHiddenWorker] created for path: %s", path_.c_str());
 }
@@ -81,12 +82,12 @@ void GetHiddenWorker::Execute() {
 void GetHiddenWorker::OnOK() {
   Napi::HandleScope scope(Env());
   auto env = Env();
-  deferred_.Resolve(Napi::Boolean::New(env, is_hidden_));
+  SafeResolve(deferred_, Napi::Boolean::New(env, is_hidden_));
 }
 
 void GetHiddenWorker::OnError(const Napi::Error &error) {
   Napi::HandleScope scope(Env());
-  deferred_.Reject(error.Value());
+  SafeReject(deferred_, error.Value());
 }
 
 Napi::Promise GetHiddenAttribute(const Napi::CallbackInfo &info) {
@@ -111,8 +112,8 @@ Napi::Promise GetHiddenAttribute(const Napi::CallbackInfo &info) {
 
 SetHiddenWorker::SetHiddenWorker(std::string path, bool hidden,
                                  Napi::Promise::Deferred deferred)
-    : Napi::AsyncWorker(deferred.Env()), path_(std::move(path)),
-      hidden_(hidden), deferred_(deferred) {
+    : SafeAsyncWorker(deferred.Env()), path_(std::move(path)), hidden_(hidden),
+      deferred_(deferred) {
   DEBUG_LOG("[SetHiddenWorker] created for path: %s, hidden: %d", path_.c_str(),
             hidden_);
 }
@@ -206,12 +207,12 @@ void SetHiddenWorker::Execute() {
 void SetHiddenWorker::OnOK() {
   Napi::HandleScope scope(Env());
   auto env = Env();
-  deferred_.Resolve(env.Undefined());
+  SafeResolve(deferred_, env.Undefined());
 }
 
 void SetHiddenWorker::OnError(const Napi::Error &error) {
   Napi::HandleScope scope(Env());
-  deferred_.Reject(error.Value());
+  SafeReject(deferred_, error.Value());
 }
 
 Napi::Promise SetHiddenAttribute(const Napi::CallbackInfo &info) {
@@ -238,4 +239,4 @@ Napi::Promise SetHiddenAttribute(const Napi::CallbackInfo &info) {
   return deferred.Promise();
 }
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/darwin/hidden.h

@@ -1,11 +1,12 @@
 // src/darwin/hidden.h
 #pragma once
 #include "../common/hidden.h"
+#include "../common/shutdown.h"
 #include <napi.h>
 
 namespace FSMeta {
 
-class GetHiddenWorker : public Napi::AsyncWorker {
+class GetHiddenWorker : public SafeAsyncWorker {
 public:
   GetHiddenWorker(std::string path, Napi::Promise::Deferred deferred);
   void Execute() override;
@@ -18,7 +19,7 @@ private:
   bool is_hidden_;
 };
 
-class SetHiddenWorker : public Napi::AsyncWorker {
+class SetHiddenWorker : public SafeAsyncWorker {
 public:
   SetHiddenWorker(std::string path, bool hidden,
                   Napi::Promise::Deferred deferred);
@@ -32,4 +33,4 @@ private:
   Napi::Promise::Deferred deferred_;
 };
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/darwin/volume_metadata.cpp

@@ -4,6 +4,7 @@
 #include "../common/debug_log.h"
 #include "../common/fd_guard.h"
 #include "../common/path_security.h"
+#include "../common/shutdown.h"
 #include "../common/volume_utils.h"
 #include "./da_mutex.h"
 #include "./fs_meta.h"
@@ -76,6 +77,11 @@ public:
   void Execute() override {
     DEBUG_LOG("[GetVolumeMetadataWorker] Executing for mount point: %s",
               mountPoint.c_str());
+    if (IsShuttingDown()) {
+      // Avoid kicking off blocking IOKit/DA calls during env teardown.
+      SetError("fs-metadata: shutdown in progress");
+      return;
+    }
     try {
       // Validate and canonicalize mount point using realpath()
       // This follows Apple's Secure Coding Guide recommendations
@@ -207,6 +213,14 @@ private:
     DEBUG_LOG("[GetVolumeMetadataWorker] Getting Disk Arbitration info for: %s",
               mountPoint.c_str());
 
+    if (IsShuttingDown()) {
+      // IOServiceGetMatchingService is uncancellable; if we're already in
+      // teardown, surface a partial result rather than block FreeEnvironment.
+      metadata.status = "partial";
+      metadata.error = "shutdown in progress";
+      return;
+    }
+
     // Check if this is a network filesystem
     if (metadata.fstype == "smbfs" || metadata.fstype == "nfs" ||
         metadata.fstype == "afpfs" || metadata.fstype == "webdav") {
@@ -370,4 +384,4 @@ Napi::Value GetVolumeMetadata(const Napi::CallbackInfo &info) {
   return deferred.Promise();
 }
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/darwin/volume_mount_points.cpp

@@ -2,6 +2,7 @@
 #include "../common/volume_mount_points.h"
 #include "../common/debug_log.h"
 #include "../common/error_utils.h"
+#include "../common/shutdown.h"
 #include "./da_mutex.h"
 #include "./fs_meta.h"
 #include "./raii_utils.h"
@@ -13,7 +14,7 @@
 
 namespace FSMeta {
 
-class GetVolumeMountPointsWorker : public Napi::AsyncWorker {
+class GetVolumeMountPointsWorker : public SafeAsyncWorker {
 private:
   Napi::Promise::Deferred deferred_;
   std::vector<MountPoint> mountPoints_;
@@ -22,11 +23,15 @@ private:
 public:
   GetVolumeMountPointsWorker(const Napi::Promise::Deferred &deferred,
                              uint32_t timeoutMs = 5000)
-      : Napi::AsyncWorker(deferred.Env()), deferred_(deferred),
+      : SafeAsyncWorker(deferred.Env()), deferred_(deferred),
         timeoutMs_(timeoutMs) {}
 
   void Execute() override {
     DEBUG_LOG("[GetVolumeMountPointsWorker] Executing");
+    if (IsShuttingDown()) {
+      SetError("fs-metadata: shutdown in progress");
+      return;
+    }
     try {
       MountBufferRAII mntbuf;
       // Use MNT_NOWAIT for better performance - we'll verify accessibility
@@ -57,6 +62,10 @@ public:
       {
         std::lock_guard<std::mutex> lock(g_diskArbitrationMutex);
 
+        if (IsShuttingDown()) {
+          return;
+        }
+
         DASessionRAII session(DASessionCreate(kCFAllocatorDefault));
         if (session.isValid()) {
           static dispatch_queue_t da_queue = dispatch_queue_create(
@@ -66,6 +75,10 @@ public:
         }
 
         for (int j = 0; j < count; j++) {
+          if (IsShuttingDown()) {
+            return;
+          }
+
           MountPoint mp;
           mp.mountPoint = mntbuf.get()[j].f_mntonname;
           mp.fstype = mntbuf.get()[j].f_fstypename;
@@ -88,6 +101,10 @@ public:
       const size_t maxConcurrentChecks = 4; // Limit concurrent access checks
 
       for (size_t i = 0; i < allMountPoints.size(); i += maxConcurrentChecks) {
+        if (IsShuttingDown()) {
+          return;
+        }
+
         std::vector<std::future<std::pair<std::string, bool>>> futures;
         std::vector<MountPoint *> batchPtrs;
 
@@ -182,7 +199,12 @@ public:
       result[i] = mountPoints_[i].ToObject(env);
     }
 
-    deferred_.Resolve(result);
+    SafeResolve(deferred_, result);
+  }
+
+  void OnError(const Napi::Error &error) override {
+    Napi::HandleScope scope(Env());
+    SafeReject(deferred_, error.Value());
   }
 };
 
@@ -202,4 +224,4 @@ Napi::Promise GetVolumeMountPoints(const Napi::CallbackInfo &info) {
   return deferred.Promise();
 }
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/fs.ts

@@ -10,7 +10,10 @@ import { withTimeout } from "./async";
  */
 export async function statAsync(
   path: PathLike,
-  options?: StatOptions & { bigint?: false },
+  // `throwIfNoEntry?: true` selects the overload that resolves to
+  // Promise<Stats> rather than Promise<Stats | undefined>; this wrapper always
+  // throws (rather than returning undefined) when the path doesn't exist.
+  options?: StatOptions & { bigint?: false; throwIfNoEntry?: true },
 ): Promise<Stats> {
   return stat(path, options);
 }