doc: distinguish between fs.Stats and fs.BigIntStats

Author: LiviaMedeiros

doc/api/fs.md

@@ -637,9 +637,9 @@ changes:
 -->
 
 * `options` {Object}
-  * `bigint` {boolean} Whether the numeric values in the returned
-    {fs.Stats} object should be `bigint`. **Default:** `false`.
-* Returns: {Promise} Fulfills with an {fs.Stats} for the file.
+  * `bigint` {boolean} Whether the returned object should be
+    a {fs.BigIntStats} instance. **Default:** `false`.
+* Returns: {Promise} Fulfills with an {fs.Stats} or {fs.BigIntStats} for the file.
 
 #### `filehandle.sync()`
 
@@ -1213,9 +1213,9 @@ changes:
 
 * `path` {string|Buffer|URL}
 * `options` {Object}
-  * `bigint` {boolean} Whether the numeric values in the returned
-    {fs.Stats} object should be `bigint`. **Default:** `false`.
-* Returns: {Promise}  Fulfills with the {fs.Stats} object for the given
+  * `bigint` {boolean} Whether the returned object should be
+    a {fs.BigIntStats} instance. **Default:** `false`.
+* Returns: {Promise} Fulfills with the {fs.Stats} or {fs.BigIntStats} object for the given
   symbolic link `path`.
 
 Equivalent to [`fsPromises.stat()`][] unless `path` refers to a symbolic link,
@@ -1291,7 +1291,7 @@ changes:
 * `prefix` {string|Buffer|URL}
 * `options` {string|Object}
   * `encoding` {string} **Default:** `'utf8'`
-* Returns: {Promise}  Fulfills with a string containing the file system path
+* Returns: {Promise} Fulfills with a string containing the file system path
   of the newly created temporary directory.
 
 Creates a unique temporary directory. A unique directory name is generated by
@@ -1715,9 +1715,9 @@ changes:
 
 * `path` {string|Buffer|URL}
 * `options` {Object}
-  * `bigint` {boolean} Whether the numeric values in the returned
-    {fs.Stats} object should be `bigint`. **Default:** `false`.
-* Returns: {Promise}  Fulfills with the {fs.Stats} object for the
+  * `bigint` {boolean} Whether the returned object should be
+    a {fs.BigIntStats} instance. **Default:** `false`.
+* Returns: {Promise} Fulfills with the {fs.Stats} or {fs.BigIntStats} object for the
   given `path`.
 
 ### `fsPromises.statfs(path[, options])`
@@ -3044,13 +3044,13 @@ changes:
 
 * `fd` {integer}
 * `options` {Object}
-  * `bigint` {boolean} Whether the numeric values in the returned
-    {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `bigint` {boolean} Whether the returned object should be
+    a {fs.BigIntStats} instance. **Default:** `false`.
 * `callback` {Function}
   * `err` {Error}
-  * `stats` {fs.Stats}
+  * `stats` {fs.Stats|fs.BigIntStats}
 
-Invokes the callback with the {fs.Stats} for the file descriptor.
+Invokes the callback with the {fs.Stats} or {fs.BigIntStats} for the file descriptor.
 
 See the POSIX fstat(2) documentation for more detail.
 
@@ -3404,13 +3404,13 @@ changes:
 
 * `path` {string|Buffer|URL}
 * `options` {Object}
-  * `bigint` {boolean} Whether the numeric values in the returned
-    {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `bigint` {boolean} Whether the returned object should be
+    a {fs.BigIntStats} instance. **Default:** `false`.
 * `callback` {Function}
   * `err` {Error}
-  * `stats` {fs.Stats}
+  * `stats` {fs.Stats|fs.BigIntStats}
 
-Retrieves the {fs.Stats} for the symbolic link referred to by the path.
+Retrieves the {fs.Stats} or {fs.BigIntStats} for the symbolic link referred to by the path.
 The callback gets two arguments `(err, stats)` where `stats` is a {fs.Stats}
 object. `lstat()` is identical to `stat()`, except that if `path` is a symbolic
 link, then the link itself is stat-ed, not the file that it refers to.
@@ -4427,14 +4427,14 @@ changes:
 
 * `path` {string|Buffer|URL}
 * `options` {Object}
-  * `bigint` {boolean} Whether the numeric values in the returned
-    {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `bigint` {boolean} Whether the returned object should be
+    a {fs.BigIntStats} instance. **Default:** `false`.
 * `callback` {Function}
   * `err` {Error}
-  * `stats` {fs.Stats}
+  * `stats` {fs.Stats|fs.BigIntStats}
 
 Asynchronous stat(2). The callback gets two arguments `(err, stats)` where
-`stats` is an {fs.Stats} object.
+`stats` is an {fs.Stats} or {fs.BigIntStats} object.
 
 In case of an error, the `err.code` will be one of [Common System Errors][].
 
@@ -4922,8 +4922,8 @@ changes:
   * `persistent` {boolean} **Default:** `true`
   * `interval` {integer} **Default:** `5007`
 * `listener` {Function}
-  * `current` {fs.Stats}
-  * `previous` {fs.Stats}
+  * `current` {fs.Stats|fs.BigIntStats}
+  * `previous` {fs.Stats|fs.BigIntStats}
 * Returns: {fs.StatWatcher}
 
 Watch for changes on `filename`. The callback `listener` will be called each
@@ -4947,8 +4947,8 @@ watchFile('message.text', (curr, prev) => {
 });
 ```
 
-These stat objects are instances of `fs.Stat`. If the `bigint` option is `true`,
-the numeric values in these objects are specified as `BigInt`s.
+These stat objects are instances of `fs.Stats` if `bigint` option is `false`,
+or instances of `fs.BigIntStats` if it's `true`.
 
 To be notified when the file was modified, not just accessed, it is necessary
 to compare `curr.mtimeMs` and `prev.mtimeMs`.
@@ -5687,11 +5687,11 @@ changes:
 
 * `fd` {integer}
 * `options` {Object}
-  * `bigint` {boolean} Whether the numeric values in the returned
-    {fs.Stats} object should be `bigint`. **Default:** `false`.
-* Returns: {fs.Stats}
+  * `bigint` {boolean} Whether the returned object should be
+    a {fs.BigIntStats} instance. **Default:** `false`.
+* Returns: {fs.Stats|fs.BigIntStats}
 
-Retrieves the {fs.Stats} for the file descriptor.
+Retrieves the {fs.Stats} or {fs.BigIntStats} for the file descriptor.
 
 See the POSIX fstat(2) documentation for more detail.
 
@@ -5878,14 +5878,14 @@ changes:
 
 * `path` {string|Buffer|URL}
 * `options` {Object}
-  * `bigint` {boolean} Whether the numeric values in the returned
-    {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `bigint` {boolean} Whether the returned object should be
+    a {fs.BigIntStats} instance. **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}
+* Returns: {fs.Stats|fs.BigIntStats}
 
-Retrieves the {fs.Stats} for the symbolic link referred to by `path`.
+Retrieves the {fs.Stats} or {fs.BigIntStats} for the symbolic link referred to by `path`.
 
 See the POSIX lstat(2) documentation for more details.
 
@@ -6409,14 +6409,14 @@ changes:
 
 * `path` {string|Buffer|URL}
 * `options` {Object}
-  * `bigint` {boolean} Whether the numeric values in the returned
-    {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `bigint` {boolean} Whether the returned object should be
+    a {fs.BigIntStats} instance. **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}
+* Returns: {fs.Stats|fs.BigIntStats}
 
-Retrieves the {fs.Stats} for the path.
+Retrieves the {fs.Stats} or {fs.BigIntStats} for the path.
 
 ### `fs.statfsSync(path[, options])`
 
@@ -7217,10 +7217,11 @@ A {fs.Stats} object provides information about a file.
 
 Objects returned from [`fs.stat()`][], [`fs.lstat()`][], [`fs.fstat()`][], and
 their synchronous counterparts are of this type.
-If `bigint` in the `options` passed to those methods is true, the numeric values
-will be `bigint` instead of `number`, and the object will contain additional
-nanosecond-precision properties suffixed with `Ns`.
-`Stat` objects are not to be created directly using the `new` keyword.
+If `bigint` in the `options` passed to those methods is true, the returned objects
+will be instances of {fs.BigIntStats} which numeric values will be `bigint` instead
+of `number`, and the object will contain additional nanosecond-precision properties
+suffixed with `Ns`.
+`Stats` objects are not to be created directly using the `new` keyword.
 
 ```console
 Stats {
@@ -7244,7 +7245,17 @@ Stats {
   birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
 ```
 
-`bigint` version:
+### Class: `fs.BigIntStats`
+
+<!-- YAML
+added: v12.10.0
+-->
+
+{fs.BigIntStats} objects are returned instead of {fs.Stats} when the `bigint` option
+passed to the corresponding function is true.
+Their numeric values are `bigint` instead of `number`, and they contain additional
+nanosecond-precision properties suffixed with `Ns`.
+`BigIntStats` objects are not to be created directly using the `new` keyword.
 
 ```console
 BigIntStats {
@@ -7280,7 +7291,7 @@ added: v0.1.10
 
 * Returns: {boolean}
 
-Returns `true` if the {fs.Stats} object describes a block device.
+Returns `true` if the stats object describes a block device.
 
 #### `stats.isCharacterDevice()`
 
@@ -7290,7 +7301,7 @@ added: v0.1.10
 
 * Returns: {boolean}
 
-Returns `true` if the {fs.Stats} object describes a character device.
+Returns `true` if the stats object describes a character device.
 
 #### `stats.isDirectory()`
 
@@ -7300,7 +7311,7 @@ added: v0.1.10
 
 * Returns: {boolean}
 
-Returns `true` if the {fs.Stats} object describes a file system directory.
+Returns `true` if the stats object describes a file system directory.
 
 If the {fs.Stats} object was obtained from calling [`fs.lstat()`][] on a
 symbolic link which resolves to a directory, this method will return `false`.
@@ -7315,7 +7326,7 @@ added: v0.1.10
 
 * Returns: {boolean}
 
-Returns `true` if the {fs.Stats} object describes a first-in-first-out (FIFO)
+Returns `true` if the stats object describes a first-in-first-out (FIFO)
 pipe.
 
 #### `stats.isFile()`
@@ -7326,7 +7337,7 @@ added: v0.1.10
 
 * Returns: {boolean}
 
-Returns `true` if the {fs.Stats} object describes a regular file.
+Returns `true` if the stats object describes a regular file.
 
 #### `stats.isSocket()`
 
@@ -7336,7 +7347,7 @@ added: v0.1.10
 
 * Returns: {boolean}
 
-Returns `true` if the {fs.Stats} object describes a socket.
+Returns `true` if the stats object describes a socket.
 
 #### `stats.isSymbolicLink()`
 
@@ -7346,7 +7357,7 @@ added: v0.1.10
 
 * Returns: {boolean}
 
-Returns `true` if the {fs.Stats} object describes a symbolic link.
+Returns `true` if the stats object describes a symbolic link.
 
 This method is only valid when using [`fs.lstat()`][].
 
@@ -7465,8 +7476,7 @@ added: v12.10.0
 
 * Type: {bigint}
 
-Only present when `bigint: true` is passed into the method that generates
-the object.
+Only present when on `BigIntStats` objects.
 The timestamp indicating the last time this file was accessed expressed in
 nanoseconds since the POSIX Epoch.
 
@@ -7478,8 +7488,7 @@ added: v12.10.0
 
 * Type: {bigint}
 
-Only present when `bigint: true` is passed into the method that generates
-the object.
+Only present on `BigIntStats` objects.
 The timestamp indicating the last time this file was modified expressed in
 nanoseconds since the POSIX Epoch.
 
@@ -7491,8 +7500,7 @@ added: v12.10.0
 
 * Type: {bigint}
 
-Only present when `bigint: true` is passed into the method that generates
-the object.
+Only present on `BigIntStats` objects.
 The timestamp indicating the last time the file status was changed expressed
 in nanoseconds since the POSIX Epoch.
 
@@ -7504,8 +7512,7 @@ added: v12.10.0
 
 * Type: {bigint}
 
-Only present when `bigint: true` is passed into the method that generates
-the object.
+Only present on `BigIntStats` objects.
 The timestamp indicating the creation time of this file expressed in
 nanoseconds since the POSIX Epoch.
 
@@ -7559,8 +7566,7 @@ otherwise they will be [numbers][MDN-Number].
 
 The `atimeNs`, `mtimeNs`, `ctimeNs`, `birthtimeNs` properties are
 [bigints][] that hold the corresponding times in nanoseconds. They are
-only present when `bigint: true` is passed into the method that generates
-the object. Their precision is platform specific.
+only present on `BigIntStats` objects. Their precision is platform specific.
 
 `atime`, `mtime`, `ctime`, and `birthtime` are
 [`Date`][MDN-Date] object alternate representations of the various times. The