From fe5d35123bdd1f8a2c5cc8ab636491012b9584fe Mon Sep 17 00:00:00 2001 From: Joyee Cheung Date: Mon, 23 Apr 2018 17:14:56 +0800 Subject: [PATCH] doc: document BigInt support in fs.Stats PR-URL: https://github.com/nodejs/node/pull/20220 Fixes: https://github.com/nodejs/node/issues/12115 Reviewed-By: Ben Noordhuis --- doc/api/fs.md | 145 ++++++++++++++++++++++++++++++++------- tools/doc/type-parser.js | 2 + 2 files changed, 121 insertions(+), 26 deletions(-) diff --git a/doc/api/fs.md b/doc/api/fs.md index 02bf4abdf8b13b..55ba07a002965a 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -415,6 +415,8 @@ A `fs.Stats` object provides information about a file. Objects returned from [`fs.stat()`][], [`fs.lstat()`][] and [`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`. ```console Stats { @@ -438,6 +440,30 @@ Stats { birthtime: Mon, 10 Oct 2011 23:24:11 GMT } ``` +`bigint` version: + +```console +Stats { + dev: 2114n, + ino: 48064969n, + mode: 33188n, + nlink: 1n, + uid: 85n, + gid: 100n, + rdev: 0n, + size: 527n, + blksize: 4096n, + blocks: 8n, + atimeMs: 1318289051000n, + mtimeMs: 1318289051000n, + ctimeMs: 1318289051000n, + birthtimeMs: 1318289051000n, + atime: Mon, 10 Oct 2011 23:24:11 GMT, + mtime: Mon, 10 Oct 2011 23:24:11 GMT, + ctime: Mon, 10 Oct 2011 23:24:11 GMT, + birthtime: Mon, 10 Oct 2011 23:24:11 GMT } +``` + ### stats.isBlockDevice() -* {number} +* {number|bigint} The timestamp indicating the last time this file was accessed expressed in milliseconds since the POSIX Epoch. @@ -579,7 +605,7 @@ milliseconds since the POSIX Epoch. added: v8.1.0 --> -* {number} +* {number|bigint} The timestamp indicating the last time this file was modified expressed in milliseconds since the POSIX Epoch. @@ -589,7 +615,7 @@ milliseconds since the POSIX Epoch. added: v8.1.0 --> -* {number} +* {number|bigint} The timestamp indicating the last time the file status was changed expressed in milliseconds since the POSIX Epoch. @@ -599,7 +625,7 @@ in milliseconds since the POSIX Epoch. added: v8.1.0 --> -* {number} +* {number|bigint} The timestamp indicating the creation time of this file expressed in milliseconds since the POSIX Epoch. @@ -1643,7 +1669,7 @@ added: v0.1.96 Synchronous fdatasync(2). Returns `undefined`. -## fs.fstat(fd, callback) +## fs.fstat(fd[, options], callback) * `fd` {integer} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + [`fs.Stats`][] object should be `bigint`. **Default:** `false`. * `callback` {Function} * `err` {Error} * `stats` {fs.Stats} @@ -1666,12 +1699,20 @@ Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where `stats` is an [`fs.Stats`][] object. `fstat()` is identical to [`stat()`][], except that the file to be stat-ed is specified by the file descriptor `fd`. -## fs.fstatSync(fd) +## fs.fstatSync(fd[, options]) * `fd` {integer} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + [`fs.Stats`][] object should be `bigint`. **Default:** `false`. * Returns: {fs.Stats} Synchronous fstat(2). @@ -1937,7 +1978,7 @@ changes: Synchronous link(2). Returns `undefined`. -## fs.lstat(path, callback) +## fs.lstat(path[, options], callback) * `path` {string|Buffer|URL} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + [`fs.Stats`][] object should be `bigint`. **Default:** `false`. * `callback` {Function} * `err` {Error} * `stats` {fs.Stats} @@ -1965,7 +2013,7 @@ Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where except that if `path` is a symbolic link, then the link itself is stat-ed, not the file that it refers to. -## fs.lstatSync(path) +## fs.lstatSync(path[, options]) * `path` {string|Buffer|URL} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + [`fs.Stats`][] object should be `bigint`. **Default:** `false`. * Returns: {fs.Stats} Synchronous lstat(2). @@ -2693,7 +2748,7 @@ Synchronous rmdir(2). Returns `undefined`. Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT` error on Windows and an `ENOTDIR` error on POSIX. -## fs.stat(path, callback) +## fs.stat(path[, options], callback) * `path` {string|Buffer|URL} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + [`fs.Stats`][] object should be `bigint`. **Default:** `false`. * `callback` {Function} * `err` {Error} * `stats` {fs.Stats} @@ -2729,7 +2791,7 @@ error raised if the file is not available. To check if a file exists without manipulating it afterwards, [`fs.access()`] is recommended. -## fs.statSync(path) +## fs.statSync(path[, options]) * `path` {string|Buffer|URL} +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + [`fs.Stats`][] object should be `bigint`. **Default:** `false`. * Returns: {fs.Stats} Synchronous stat(2). @@ -3516,10 +3585,18 @@ returned. The `FileHandle` has to support reading. -#### filehandle.stat() +#### filehandle.stat([options]) +* `options` {Object} + * `bigint` {boolean} Whether the numeric values in the returned + [`fs.Stats`][] object should be `bigint`. **Default:** `false`. * Returns: {Promise} Retrieves the [`fs.Stats`][] for the file. @@ -3844,12 +3921,20 @@ added: v10.0.0 Asynchronous link(2). The `Promise` is resolved with no arguments upon success. -### fsPromises.lstat(path) +### fsPromises.lstat(path[, options]) * `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} Asynchronous lstat(2). The `Promise` is resolved with the [`fs.Stats`][] object @@ -4030,12 +4115,20 @@ Using `fsPromises.rmdir()` on a file (not a directory) results in the `Promise` being rejected with an `ENOENT` error on Windows and an `ENOTDIR` error on POSIX. -### fsPromises.stat(path) +### fsPromises.stat(path[, options]) * `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} The `Promise` is resolved with the [`fs.Stats`][] object for the given `path`. @@ -4491,9 +4584,9 @@ the file contents. [`fs.chown()`]: #fs_fs_chown_path_uid_gid_callback [`fs.copyFile()`]: #fs_fs_copyfile_src_dest_flags_callback [`fs.exists()`]: fs.html#fs_fs_exists_path_callback -[`fs.fstat()`]: #fs_fs_fstat_fd_callback +[`fs.fstat()`]: #fs_fs_fstat_fd_options_callback [`fs.futimes()`]: #fs_fs_futimes_fd_atime_mtime_callback -[`fs.lstat()`]: #fs_fs_lstat_path_callback +[`fs.lstat()`]: #fs_fs_lstat_path_options_callback [`fs.mkdir()`]: #fs_fs_mkdir_path_mode_callback [`fs.mkdtemp()`]: #fs_fs_mkdtemp_prefix_options_callback [`fs.open()`]: #fs_fs_open_path_flags_mode_callback @@ -4502,7 +4595,7 @@ the file contents. [`fs.readFileSync()`]: #fs_fs_readfilesync_path_options [`fs.realpath()`]: #fs_fs_realpath_path_options_callback [`fs.rmdir()`]: #fs_fs_rmdir_path_callback -[`fs.stat()`]: #fs_fs_stat_path_callback +[`fs.stat()`]: #fs_fs_stat_path_options_callback [`fs.utimes()`]: #fs_fs_utimes_path_atime_mtime_callback [`fs.watch()`]: #fs_fs_watch_filename_options_listener [`fs.write()`]: #fs_fs_write_fd_buffer_offset_length_position_callback diff --git a/tools/doc/type-parser.js b/tools/doc/type-parser.js index be72893832373a..87138668c07426 100644 --- a/tools/doc/type-parser.js +++ b/tools/doc/type-parser.js @@ -31,6 +31,8 @@ const customTypesMap = { 'AsyncIterator': 'https://github.com/tc39/proposal-async-iteration', + 'bigint': 'https://github.com/tc39/proposal-bigint', + 'Iterable': `${jsDocPrefix}Reference/Iteration_protocols#The_iterable_protocol`, 'Iterator':