From a7c9daa4972b31b2af777b49d9e0c0b8fda69d62 Mon Sep 17 00:00:00 2001
From: Colin Ihrig <cjihrig@gmail.com>
Date: Sun, 29 Jan 2023 12:43:20 -0500
Subject: [PATCH] fs: add statfs() functions

This commit adds statfs() and statfsSync() to the fs module, and
statfs() to the fsPromises module.

Co-authored-by: cjihrig <cjihrig@gmail.com>
Fixes: /~https://github.com/nodejs/node/issues/10745
Refs: /~https://github.com/nodejs/node/pull/31351
PR-URL: /~https://github.com/nodejs/node/pull/46358
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api/fs.md                     | 159 ++++++++++++++++++++++++++++++
 lib/fs.js                         |  30 ++++++
 lib/internal/fs/promises.js       |   9 ++
 lib/internal/fs/utils.js          |  19 ++++
 src/node_file-inl.h               |  61 +++++++++---
 src/node_file.cc                  |  76 +++++++++++++-
 src/node_file.h                   |  29 ++++++
 test/parallel/test-fs-promises.js |  26 +++++
 test/parallel/test-fs-statfs.js   |  59 +++++++++++
 tools/doc/type-parser.mjs         |   1 +
 10 files changed, 457 insertions(+), 12 deletions(-)
 create mode 100644 test/parallel/test-fs-statfs.js

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 6c7099b265f454..ee67a125b43b66 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -1531,6 +1531,19 @@ changes:
 * Returns: {Promise}  Fulfills with the {fs.Stats} object for the
   given `path`.
 
+### `fsPromises.statfs(path[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string|Buffer|URL}
+* `options` {Object}
+  * `bigint` {boolean} Whether the numeric values in the returned
+    {fs.StatFs} object should be `bigint`. **Default:** `false`.
+* Returns: {Promise} Fulfills with the {fs.StatFs} object for the
+  given `path`.
+
 ### `fsPromises.symlink(target, path[, type])`
 
 <!-- YAML
@@ -4101,6 +4114,26 @@ Stats {
 }
 ```
 
+### `fs.statfs(path[, options], callback)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string|Buffer|URL}
+* `options` {Object}
+  * `bigint` {boolean} Whether the numeric values in the returned
+    {fs.StatFs} object should be `bigint`. **Default:** `false`.
+* `callback` {Function}
+  * `err` {Error}
+  * `stats` {fs.StatFs}
+
+Asynchronous statfs(2). Returns information about the mounted file system which
+contains `path`. The callback gets two arguments `(err, stats)` where `stats`
+is an {fs.StatFs} object.
+
+In case of an error, the `err.code` will be one of [Common System Errors][].
+
 ### `fs.symlink(target, path[, type], callback)`
 
 <!-- YAML
@@ -5852,6 +5885,23 @@ changes:
 
 Retrieves the {fs.Stats} for the path.
 
+### `fs.statfsSync(path[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `path` {string|Buffer|URL}
+* `options` {Object}
+  * `bigint` {boolean} Whether the numeric values in the returned
+    {fs.StatFs} object should be `bigint`. **Default:** `false`.
+* Returns: {fs.StatFs}
+
+Synchronous statfs(2). Returns information about the mounted file system which
+contains `path`.
+
+In case of an error, the `err.code` will be one of [Common System Errors][].
+
 ### `fs.symlinkSync(target, path[, type])`
 
 <!-- YAML
@@ -6944,6 +6994,114 @@ The times in the stat object have the following semantics:
 Prior to Node.js 0.12, the `ctime` held the `birthtime` on Windows systems. As
 of 0.12, `ctime` is not "creation time", and on Unix systems, it never was.
 
+### Class: `fs.StatFs`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Provides information about a mounted file system.
+
+Objects returned from [`fs.statfs()`][] and its synchronous counterpart are of
+this type. If `bigint` in the `options` passed to those methods is `true`, the
+numeric values will be `bigint` instead of `number`.
+
+```console
+StatFs {
+  type: 1397114950,
+  bsize: 4096,
+  blocks: 121938943,
+  bfree: 61058895,
+  bavail: 61058895,
+  files: 999,
+  ffree: 1000000
+}
+```
+
+`bigint` version:
+
+```console
+StatFs {
+  type: 1397114950n,
+  bsize: 4096n,
+  blocks: 121938943n,
+  bfree: 61058895n,
+  bavail: 61058895n,
+  files: 999n,
+  ffree: 1000000n
+}
+```
+
+#### `statfs.bavail`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {number|bigint}
+
+Free blocks available to unprivileged users.
+
+#### `statfs.bfree`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {number|bigint}
+
+Free blocks in file system.
+
+#### `statfs.blocks`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {number|bigint}
+
+Total data blocks in file system.
+
+#### `statfs.bsize`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {number|bigint}
+
+Optimal transfer block size.
+
+#### `statfs.ffree`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {number|bigint}
+
+Free file nodes in file system.
+
+#### `statfs.files`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {number|bigint}
+
+Total file nodes in file system.
+
+#### `statfs.type`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {number|bigint}
+
+Type of file system.
+
 ### Class: `fs.WriteStream`
 
 <!-- YAML
@@ -7787,6 +7945,7 @@ the file contents.
 [`fs.rmSync()`]: #fsrmsyncpath-options
 [`fs.rmdir()`]: #fsrmdirpath-options-callback
 [`fs.stat()`]: #fsstatpath-options-callback
+[`fs.statfs()`]: #fsstatfspath-options-callback
 [`fs.symlink()`]: #fssymlinktarget-path-type-callback
 [`fs.utimes()`]: #fsutimespath-atime-mtime-callback
 [`fs.watch()`]: #fswatchfilename-options-listener
diff --git a/lib/fs.js b/lib/fs.js
index b727d1747c6c06..1e40720512b1bf 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -102,6 +102,7 @@ const {
   nullCheck,
   preprocessSymlinkDestination,
   Stats,
+  getStatFsFromBinding,
   getStatsFromBinding,
   realpathCacheKey,
   stringToFlags,
@@ -1509,6 +1510,24 @@ function stat(path, options = { bigint: false }, callback) {
   binding.stat(pathModule.toNamespacedPath(path), options.bigint, req);
 }
 
+function statfs(path, options = { bigint: false }, callback) {
+  if (typeof options === 'function') {
+    callback = options;
+    options = kEmptyObject;
+  }
+  callback = maybeCallback(callback);
+  path = getValidatedPath(path);
+  const req = new FSReqCallback(options.bigint);
+  req.oncomplete = (err, stats) => {
+    if (err) {
+      return callback(err);
+    }
+
+    callback(err, getStatFsFromBinding(stats));
+  };
+  binding.statfs(pathModule.toNamespacedPath(path), options.bigint, req);
+}
+
 function hasNoEntryError(ctx) {
   if (ctx.errno) {
     const uvErr = uvErrmapGet(ctx.errno);
@@ -1583,6 +1602,15 @@ function statSync(path, options = { bigint: false, throwIfNoEntry: true }) {
   return getStatsFromBinding(stats);
 }
 
+function statfsSync(path, options = { bigint: false }) {
+  path = getValidatedPath(path);
+  const ctx = { path };
+  const stats = binding.statfs(pathModule.toNamespacedPath(path),
+                               options.bigint, undefined, ctx);
+  handleErrorFromBinding(ctx);
+  return getStatFsFromBinding(stats);
+}
+
 /**
  * Reads the contents of a symbolic link
  * referred to by `path`.
@@ -3013,7 +3041,9 @@ module.exports = fs = {
   rmdir,
   rmdirSync,
   stat,
+  statfs,
   statSync,
+  statfsSync,
   symlink,
   symlinkSync,
   truncate,
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 91f90e8b11fe53..6ba58f89527976 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -52,6 +52,7 @@ const {
   emitRecursiveRmdirWarning,
   getDirents,
   getOptions,
+  getStatFsFromBinding,
   getStatsFromBinding,
   getValidatedPath,
   getValidMode,
@@ -781,6 +782,13 @@ async function stat(path, options = { bigint: false }) {
   return getStatsFromBinding(result);
 }
 
+async function statfs(path, options = { bigint: false }) {
+  path = getValidatedPath(path);
+  const result = await binding.statfs(pathModule.toNamespacedPath(path),
+                                      options.bigint, kUsePromises);
+  return getStatFsFromBinding(result);
+}
+
 async function link(existingPath, newPath) {
   existingPath = getValidatedPath(existingPath, 'existingPath');
   newPath = getValidatedPath(newPath, 'newPath');
@@ -953,6 +961,7 @@ module.exports = {
     symlink,
     lstat,
     stat,
+    statfs,
     link,
     unlink,
     chmod,
diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js
index 5b57de3f7dda03..f2b0cb6b94bb1b 100644
--- a/lib/internal/fs/utils.js
+++ b/lib/internal/fs/utils.js
@@ -556,6 +556,24 @@ function getStatsFromBinding(stats, offset = 0) {
   );
 }
 
+class StatFs {
+  constructor(type, bsize, blocks, bfree, bavail, files, ffree) {
+    this.type = type;
+    this.bsize = bsize;
+    this.blocks = blocks;
+    this.bfree = bfree;
+    this.bavail = bavail;
+    this.files = files;
+    this.ffree = ffree;
+  }
+}
+
+function getStatFsFromBinding(stats) {
+  return new StatFs(
+    stats[0], stats[1], stats[2], stats[3], stats[4], stats[5], stats[6]
+  );
+}
+
 function stringToFlags(flags, name = 'flags') {
   if (typeof flags === 'number') {
     validateInt32(flags, name);
@@ -912,6 +930,7 @@ module.exports = {
   nullCheck,
   preprocessSymlinkDestination,
   realpathCacheKey: Symbol('realpathCacheKey'),
+  getStatFsFromBinding,
   getStatsFromBinding,
   stringToFlags,
   stringToSymlinkType,
diff --git a/src/node_file-inl.h b/src/node_file-inl.h
index 1170d57754ffad..adce4cab53eba6 100644
--- a/src/node_file-inl.h
+++ b/src/node_file-inl.h
@@ -144,6 +144,38 @@ v8::Local<v8::Value> FillGlobalStatsArray(BindingData* binding_data,
   }
 }
 
+template <typename NativeT, typename V8T>
+void FillStatFsArray(AliasedBufferBase<NativeT, V8T>* fields,
+                     const uv_statfs_t* s) {
+#define SET_FIELD(field, stat)                                                 \
+  fields->SetValue(static_cast<size_t>(FsStatFsOffset::field),                 \
+                   static_cast<NativeT>(stat))
+
+  SET_FIELD(kType, s->f_type);
+  SET_FIELD(kBSize, s->f_bsize);
+  SET_FIELD(kBlocks, s->f_blocks);
+  SET_FIELD(kBFree, s->f_bfree);
+  SET_FIELD(kBAvail, s->f_bavail);
+  SET_FIELD(kFiles, s->f_files);
+  SET_FIELD(kFFree, s->f_ffree);
+
+#undef SET_FIELD
+}
+
+v8::Local<v8::Value> FillGlobalStatFsArray(BindingData* binding_data,
+                                           const bool use_bigint,
+                                           const uv_statfs_t* s) {
+  if (use_bigint) {
+    auto* const arr = &binding_data->statfs_field_bigint_array;
+    FillStatFsArray(arr, s);
+    return arr->GetJSArray();
+  } else {
+    auto* const arr = &binding_data->statfs_field_array;
+    FillStatFsArray(arr, s);
+    return arr->GetJSArray();
+  }
+}
+
 template <typename AliasedBufferT>
 FSReqPromise<AliasedBufferT>*
 FSReqPromise<AliasedBufferT>::New(BindingData* binding_data,
@@ -172,17 +204,17 @@ FSReqPromise<AliasedBufferT>::~FSReqPromise() {
 }
 
 template <typename AliasedBufferT>
-FSReqPromise<AliasedBufferT>::FSReqPromise(
-    BindingData* binding_data,
-    v8::Local<v8::Object> obj,
-    bool use_bigint)
-  : FSReqBase(binding_data,
-              obj,
-              AsyncWrap::PROVIDER_FSREQPROMISE,
-              use_bigint),
-    stats_field_array_(
-        env()->isolate(),
-        static_cast<size_t>(FsStatsOffset::kFsStatsFieldsNumber)) {}
+FSReqPromise<AliasedBufferT>::FSReqPromise(BindingData* binding_data,
+                                           v8::Local<v8::Object> obj,
+                                           bool use_bigint)
+    : FSReqBase(
+          binding_data, obj, AsyncWrap::PROVIDER_FSREQPROMISE, use_bigint),
+      stats_field_array_(
+          env()->isolate(),
+          static_cast<size_t>(FsStatsOffset::kFsStatsFieldsNumber)),
+      statfs_field_array_(
+          env()->isolate(),
+          static_cast<size_t>(FsStatFsOffset::kFsStatFsFieldsNumber)) {}
 
 template <typename AliasedBufferT>
 void FSReqPromise<AliasedBufferT>::Reject(v8::Local<v8::Value> reject) {
@@ -214,6 +246,12 @@ void FSReqPromise<AliasedBufferT>::ResolveStat(const uv_stat_t* stat) {
   Resolve(stats_field_array_.GetJSArray());
 }
 
+template <typename AliasedBufferT>
+void FSReqPromise<AliasedBufferT>::ResolveStatFs(const uv_statfs_t* stat) {
+  FillStatFsArray(&statfs_field_array_, stat);
+  Resolve(statfs_field_array_.GetJSArray());
+}
+
 template <typename AliasedBufferT>
 void FSReqPromise<AliasedBufferT>::SetReturnValue(
     const v8::FunctionCallbackInfo<v8::Value>& args) {
@@ -228,6 +266,7 @@ template <typename AliasedBufferT>
 void FSReqPromise<AliasedBufferT>::MemoryInfo(MemoryTracker* tracker) const {
   FSReqBase::MemoryInfo(tracker);
   tracker->TrackField("stats_field_array", stats_field_array_);
+  tracker->TrackField("statfs_field_array", statfs_field_array_);
 }
 
 FSReqBase* GetReqWrap(const v8::FunctionCallbackInfo<v8::Value>& args,
diff --git a/src/node_file.cc b/src/node_file.cc
index 1a99057bb6e95f..49ed96eca05416 100644
--- a/src/node_file.cc
+++ b/src/node_file.cc
@@ -688,6 +688,10 @@ void FSReqCallback::ResolveStat(const uv_stat_t* stat) {
   Resolve(FillGlobalStatsArray(binding_data(), use_bigint(), stat));
 }
 
+void FSReqCallback::ResolveStatFs(const uv_statfs_t* stat) {
+  Resolve(FillGlobalStatFsArray(binding_data(), use_bigint(), stat));
+}
+
 void FSReqCallback::Resolve(Local<Value> value) {
   Local<Value> argv[2] {
     Null(env()->isolate()),
@@ -780,6 +784,16 @@ void AfterStat(uv_fs_t* req) {
   }
 }
 
+void AfterStatFs(uv_fs_t* req) {
+  FSReqBase* req_wrap = FSReqBase::from_req(req);
+  FSReqAfterScope after(req_wrap, req);
+  FS_ASYNC_TRACE_END1(
+      req->fs_type, req_wrap, "result", static_cast<int>(req->result))
+  if (after.Proceed()) {
+    req_wrap->ResolveStatFs(static_cast<uv_statfs_t*>(req->ptr));
+  }
+}
+
 void AfterInteger(uv_fs_t* req) {
   FSReqBase* req_wrap = FSReqBase::from_req(req);
   FSReqAfterScope after(req_wrap, req);
@@ -1199,6 +1213,48 @@ static void FStat(const FunctionCallbackInfo<Value>& args) {
   }
 }
 
+static void StatFs(const FunctionCallbackInfo<Value>& args) {
+  BindingData* binding_data = Environment::GetBindingData<BindingData>(args);
+  Environment* env = binding_data->env();
+
+  const int argc = args.Length();
+  CHECK_GE(argc, 2);
+
+  BufferValue path(env->isolate(), args[0]);
+  CHECK_NOT_NULL(*path);
+
+  bool use_bigint = args[1]->IsTrue();
+  FSReqBase* req_wrap_async = GetReqWrap(args, 2, use_bigint);
+  if (req_wrap_async != nullptr) {  // statfs(path, use_bigint, req)
+    FS_ASYNC_TRACE_BEGIN1(
+        UV_FS_STATFS, req_wrap_async, "path", TRACE_STR_COPY(*path))
+    AsyncCall(env,
+              req_wrap_async,
+              args,
+              "statfs",
+              UTF8,
+              AfterStatFs,
+              uv_fs_statfs,
+              *path);
+  } else {  // statfs(path, use_bigint, undefined, ctx)
+    CHECK_EQ(argc, 4);
+    FSReqWrapSync req_wrap_sync;
+    FS_SYNC_TRACE_BEGIN(statfs);
+    int err =
+        SyncCall(env, args[3], &req_wrap_sync, "statfs", uv_fs_statfs, *path);
+    FS_SYNC_TRACE_END(statfs);
+    if (err != 0) {
+      return;  // error info is in ctx
+    }
+
+    Local<Value> arr = FillGlobalStatFsArray(
+        binding_data,
+        use_bigint,
+        static_cast<const uv_statfs_t*>(req_wrap_sync.req.ptr));
+    args.GetReturnValue().Set(arr);
+  }
+}
+
 static void Symlink(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   Isolate* isolate = env->isolate();
@@ -2557,6 +2613,8 @@ static void Mkdtemp(const FunctionCallbackInfo<Value>& args) {
 void BindingData::MemoryInfo(MemoryTracker* tracker) const {
   tracker->TrackField("stats_field_array", stats_field_array);
   tracker->TrackField("stats_field_bigint_array", stats_field_bigint_array);
+  tracker->TrackField("statfs_field_array", statfs_field_array);
+  tracker->TrackField("statfs_field_bigint_array", statfs_field_bigint_array);
   tracker->TrackField("file_handle_read_wrap_freelist",
                       file_handle_read_wrap_freelist);
 }
@@ -2564,7 +2622,9 @@ void BindingData::MemoryInfo(MemoryTracker* tracker) const {
 BindingData::BindingData(Environment* env, v8::Local<v8::Object> wrap)
     : SnapshotableObject(env, wrap, type_int),
       stats_field_array(env->isolate(), kFsStatsBufferLength),
-      stats_field_bigint_array(env->isolate(), kFsStatsBufferLength) {
+      stats_field_bigint_array(env->isolate(), kFsStatsBufferLength),
+      statfs_field_array(env->isolate(), kFsStatFsBufferLength),
+      statfs_field_bigint_array(env->isolate(), kFsStatFsBufferLength) {
   wrap->Set(env->context(),
             FIXED_ONE_BYTE_STRING(env->isolate(), "statValues"),
             stats_field_array.GetJSArray())
@@ -2574,6 +2634,16 @@ BindingData::BindingData(Environment* env, v8::Local<v8::Object> wrap)
             FIXED_ONE_BYTE_STRING(env->isolate(), "bigintStatValues"),
             stats_field_bigint_array.GetJSArray())
       .Check();
+
+  wrap->Set(env->context(),
+            FIXED_ONE_BYTE_STRING(env->isolate(), "statFsValues"),
+            statfs_field_array.GetJSArray())
+      .Check();
+
+  wrap->Set(env->context(),
+            FIXED_ONE_BYTE_STRING(env->isolate(), "bigintStatFsValues"),
+            statfs_field_bigint_array.GetJSArray())
+      .Check();
 }
 
 void BindingData::Deserialize(Local<Context> context,
@@ -2594,6 +2664,8 @@ bool BindingData::PrepareForSerialization(Local<Context> context,
   // contents can be thrown away once consumed in the previous call.
   stats_field_array.Release();
   stats_field_bigint_array.Release();
+  statfs_field_array.Release();
+  statfs_field_bigint_array.Release();
   // Return true because we need to maintain the reference to the binding from
   // JS land.
   return true;
@@ -2634,6 +2706,7 @@ void Initialize(Local<Object> target,
   SetMethod(context, target, "stat", Stat);
   SetMethod(context, target, "lstat", LStat);
   SetMethod(context, target, "fstat", FStat);
+  SetMethod(context, target, "statfs", StatFs);
   SetMethod(context, target, "link", Link);
   SetMethod(context, target, "symlink", Symlink);
   SetMethod(context, target, "readlink", ReadLink);
@@ -2750,6 +2823,7 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(Stat);
   registry->Register(LStat);
   registry->Register(FStat);
+  registry->Register(StatFs);
   registry->Register(Link);
   registry->Register(Symlink);
   registry->Register(ReadLink);
diff --git a/src/node_file.h b/src/node_file.h
index a043f8a0eaea55..5554ba7de51a2a 100644
--- a/src/node_file.h
+++ b/src/node_file.h
@@ -40,6 +40,20 @@ enum class FsStatsOffset {
 constexpr size_t kFsStatsBufferLength =
     static_cast<size_t>(FsStatsOffset::kFsStatsFieldsNumber) * 2;
 
+enum class FsStatFsOffset {
+  kType = 0,
+  kBSize,
+  kBlocks,
+  kBFree,
+  kBAvail,
+  kFiles,
+  kFFree,
+  kFsStatFsFieldsNumber
+};
+
+constexpr size_t kFsStatFsBufferLength =
+    static_cast<size_t>(FsStatFsOffset::kFsStatFsFieldsNumber);
+
 class BindingData : public SnapshotableObject {
  public:
   explicit BindingData(Environment* env, v8::Local<v8::Object> wrap);
@@ -47,6 +61,9 @@ class BindingData : public SnapshotableObject {
   AliasedFloat64Array stats_field_array;
   AliasedBigInt64Array stats_field_bigint_array;
 
+  AliasedFloat64Array statfs_field_array;
+  AliasedBigInt64Array statfs_field_bigint_array;
+
   std::vector<BaseObjectPtr<FileHandleReadWrap>>
       file_handle_read_wrap_freelist;
 
@@ -109,6 +126,7 @@ class FSReqBase : public ReqWrap<uv_fs_t> {
   virtual void Reject(v8::Local<v8::Value> reject) = 0;
   virtual void Resolve(v8::Local<v8::Value> value) = 0;
   virtual void ResolveStat(const uv_stat_t* stat) = 0;
+  virtual void ResolveStatFs(const uv_statfs_t* stat) = 0;
   virtual void SetReturnValue(
       const v8::FunctionCallbackInfo<v8::Value>& args) = 0;
 
@@ -165,6 +183,7 @@ class FSReqCallback final : public FSReqBase {
   void Reject(v8::Local<v8::Value> reject) override;
   void Resolve(v8::Local<v8::Value> value) override;
   void ResolveStat(const uv_stat_t* stat) override;
+  void ResolveStatFs(const uv_statfs_t* stat) override;
   void SetReturnValue(const v8::FunctionCallbackInfo<v8::Value>& args) override;
 
   SET_MEMORY_INFO_NAME(FSReqCallback)
@@ -184,6 +203,14 @@ inline v8::Local<v8::Value> FillGlobalStatsArray(BindingData* binding_data,
                                                  const uv_stat_t* s,
                                                  const bool second = false);
 
+template <typename NativeT, typename V8T>
+void FillStatFsArray(AliasedBufferBase<NativeT, V8T>* fields,
+                     const uv_statfs_t* s);
+
+inline v8::Local<v8::Value> FillGlobalStatFsArray(BindingData* binding_data,
+                                                  const bool use_bigint,
+                                                  const uv_statfs_t* s);
+
 template <typename AliasedBufferT>
 class FSReqPromise final : public FSReqBase {
  public:
@@ -194,6 +221,7 @@ class FSReqPromise final : public FSReqBase {
   inline void Reject(v8::Local<v8::Value> reject) override;
   inline void Resolve(v8::Local<v8::Value> value) override;
   inline void ResolveStat(const uv_stat_t* stat) override;
+  inline void ResolveStatFs(const uv_statfs_t* stat) override;
   inline void SetReturnValue(
       const v8::FunctionCallbackInfo<v8::Value>& args) override;
   inline void MemoryInfo(MemoryTracker* tracker) const override;
@@ -213,6 +241,7 @@ class FSReqPromise final : public FSReqBase {
 
   bool finished_ = false;
   AliasedBufferT stats_field_array_;
+  AliasedBufferT statfs_field_array_;
 };
 
 class FSReqAfterScope final {
diff --git a/test/parallel/test-fs-promises.js b/test/parallel/test-fs-promises.js
index 98f333421911e5..c1e61040a98e3f 100644
--- a/test/parallel/test-fs-promises.js
+++ b/test/parallel/test-fs-promises.js
@@ -27,6 +27,7 @@ const {
   rename,
   rmdir,
   stat,
+  statfs,
   symlink,
   truncate,
   unlink,
@@ -81,6 +82,19 @@ function verifyStatObject(stat) {
   assert.strictEqual(typeof stat.mode, 'number');
 }
 
+function verifyStatFsObject(stat, isBigint = false) {
+  const valueType = isBigint ? 'bigint' : 'number';
+
+  assert.strictEqual(typeof stat, 'object');
+  assert.strictEqual(typeof stat.type, valueType);
+  assert.strictEqual(typeof stat.bsize, valueType);
+  assert.strictEqual(typeof stat.blocks, valueType);
+  assert.strictEqual(typeof stat.bfree, valueType);
+  assert.strictEqual(typeof stat.bavail, valueType);
+  assert.strictEqual(typeof stat.files, valueType);
+  assert.strictEqual(typeof stat.ffree, valueType);
+}
+
 async function getHandle(dest) {
   await copyFile(fixtures.path('baz.js'), dest);
   await access(dest);
@@ -137,6 +151,18 @@ async function executeOnHandle(dest, func) {
       });
     }
 
+    // File system stats
+    {
+      const statFs = await statfs(dest);
+      verifyStatFsObject(statFs);
+    }
+
+    // File system stats bigint
+    {
+      const statFs = await statfs(dest, { bigint: true });
+      verifyStatFsObject(statFs, true);
+    }
+
     // Test fs.read promises when length to read is zero bytes
     {
       const dest = path.resolve(tmpDir, 'test1.js');
diff --git a/test/parallel/test-fs-statfs.js b/test/parallel/test-fs-statfs.js
new file mode 100644
index 00000000000000..5fd34f215bc34a
--- /dev/null
+++ b/test/parallel/test-fs-statfs.js
@@ -0,0 +1,59 @@
+'use strict';
+const common = require('../common');
+const assert = require('node:assert');
+const fs = require('node:fs');
+
+function verifyStatFsObject(statfs, isBigint = false) {
+  const valueType = isBigint ? 'bigint' : 'number';
+
+  [
+    'type', 'bsize', 'blocks', 'bfree', 'bavail', 'files', 'ffree',
+  ].forEach((k) => {
+    assert.ok(Object.hasOwn(statfs, k));
+    assert.strictEqual(typeof statfs[k], valueType,
+                       `${k} should be a ${valueType}`);
+  });
+}
+
+fs.statfs(__filename, common.mustSucceed(function(stats) {
+  verifyStatFsObject(stats);
+  assert.strictEqual(this, undefined);
+}));
+
+fs.statfs(__filename, { bigint: true }, function(err, stats) {
+  assert.ifError(err);
+  verifyStatFsObject(stats, true);
+  assert.strictEqual(this, undefined);
+});
+
+// Synchronous
+{
+  const statFsObj = fs.statfsSync(__filename);
+  verifyStatFsObject(statFsObj);
+}
+
+// Synchronous Bigint
+{
+  const statFsBigIntObj = fs.statfsSync(__filename, { bigint: true });
+  verifyStatFsObject(statFsBigIntObj, true);
+}
+
+[false, 1, {}, [], null, undefined].forEach((input) => {
+  assert.throws(
+    () => fs.statfs(input, common.mustNotCall()),
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      name: 'TypeError'
+    }
+  );
+  assert.throws(
+    () => fs.statfsSync(input),
+    {
+      code: 'ERR_INVALID_ARG_TYPE',
+      name: 'TypeError'
+    }
+  );
+});
+
+// Should not throw an error
+fs.statfs(__filename, undefined, common.mustCall());
diff --git a/tools/doc/type-parser.mjs b/tools/doc/type-parser.mjs
index 93e098bfd99639..afca9383fc0b04 100644
--- a/tools/doc/type-parser.mjs
+++ b/tools/doc/type-parser.mjs
@@ -127,6 +127,7 @@ const customTypesMap = {
   'fs.FSWatcher': 'fs.html#class-fsfswatcher',
   'fs.ReadStream': 'fs.html#class-fsreadstream',
   'fs.Stats': 'fs.html#class-fsstats',
+  'fs.StatFs': 'fs.html#class-fsstatfs',
   'fs.StatWatcher': 'fs.html#class-fsstatwatcher',
   'fs.WriteStream': 'fs.html#class-fswritestream',