From a7415198487484d49cbba728cc41d038870c5d94 Mon Sep 17 00:00:00 2001
From: zhanglinqian <zhanglinqian@github.com>
Date: Thu, 12 Feb 2026 11:25:29 +0800
Subject: [PATCH] docs: add missing documentation for fs.StatFs class

- Clarify that bsize is in bytes
- Add examples for calculating available space using bsize and bavail
- Add examples for calculating free space using bsize and bfree
- Add examples for calculating total space using bsize and blocks
- Add examples for calculating used file node percentage using files and ffree
- Document statfs.type with explanation of magic numbers

Fixes #50749
---
 doc/api/fs.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 66 insertions(+), 6 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 66d29bc80fbf18..0408808830eac7 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7656,7 +7656,21 @@ added:
 
 * Type: {number|bigint}
 
-Free blocks available to unprivileged users.
+Free blocks available to unprivileged users. For example, to calculate the available space:
+
+```mjs
+import { statfs } from 'node:fs/promises';
+const stats = await statfs('/tmp');
+const availableBytes = stats.bsize * stats.bavail;
+```
+
+```cjs
+const { statfs } = require('node:fs/promises');
+(async () => {
+  const stats = await statfs('/tmp');
+  const availableBytes = stats.bsize * stats.bavail;
+})();
+```
 
 #### `statfs.bfree`
 
@@ -7668,7 +7682,21 @@ added:
 
 * Type: {number|bigint}
 
-Free blocks in file system.
+Free blocks in file system. For example, to calculate the free space:
+
+```mjs
+import { statfs } from 'node:fs/promises';
+const stats = await statfs('/tmp');
+const freeBytes = stats.bsize * stats.bfree;
+```
+
+```cjs
+const { statfs } = require('node:fs/promises');
+(async () => {
+  const stats = await statfs('/tmp');
+  const freeBytes = stats.bsize * stats.bfree;
+})();
+```
 
 #### `statfs.blocks`
 
@@ -7680,7 +7708,21 @@ added:
 
 * Type: {number|bigint}
 
-Total data blocks in file system.
+Total data blocks in file system. For example, to calculate the total space:
+
+```mjs
+import { statfs } from 'node:fs/promises';
+const stats = await statfs('/tmp');
+const totalBytes = stats.bsize * stats.blocks;
+```
+
+```cjs
+const { statfs } = require('node:fs/promises');
+(async () => {
+  const stats = await statfs('/tmp');
+  const totalBytes = stats.bsize * stats.blocks;
+})();
+```
 
 #### `statfs.bsize`
 
@@ -7692,7 +7734,7 @@ added:
 
 * Type: {number|bigint}
 
-Optimal transfer block size.
+Optimal transfer block size, in bytes.
 
 #### `statfs.ffree`
 
@@ -7716,7 +7758,23 @@ added:
 
 * Type: {number|bigint}
 
-Total file nodes in file system.
+Total file nodes in file system. For example, to get the percentage of used file nodes:
+
+```mjs
+import { statfs } from 'node:fs/promises';
+const stats = await statfs('/tmp');
+const usedFileNodes = stats.files - stats.ffree;
+const usedPercentage = (usedFileNodes / stats.files) * 100;
+```
+
+```cjs
+const { statfs } = require('node:fs/promises');
+(async () => {
+  const stats = await statfs('/tmp');
+  const usedFileNodes = stats.files - stats.ffree;
+  const usedPercentage = (usedFileNodes / stats.files) * 100;
+})();
+```
 
 #### `statfs.type`
 
@@ -7728,7 +7786,9 @@ added:
 
 * Type: {number|bigint}
 
-Type of file system.
+Type of file system. This is a magic number that identifies the file system type.
+Common values include `0xEF53` (ext4), `0x58465342` (xfs), `0x01021994` (tmpfs), etc.
+The exact values depend on the operating system and file system implementation.
 
 ### Class: `fs.Utf8Stream`