diff --git a/doc/api/fs.md b/doc/api/fs.md index f09395cb123150..a22f48185ff0a7 100644 --- a/doc/api/fs.md +++ b/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` + + + +{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 diff --git a/tools/doc/type-parser.mjs b/tools/doc/type-parser.mjs index 5af6e86651af28..fbf9aba2847977 100644 --- a/tools/doc/type-parser.mjs +++ b/tools/doc/type-parser.mjs @@ -157,6 +157,7 @@ const customTypesMap = { 'WebSocket': `${mdnPrefix}/API/WebSocket`, 'FileHandle': 'fs.html#class-filehandle', + 'fs.BigIntStats': 'fs.html#class-fsbigintstats', 'fs.Dir': 'fs.html#class-fsdir', 'fs.Dirent': 'fs.html#class-fsdirent', 'fs.FSWatcher': 'fs.html#class-fsfswatcher',