FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: document BigInt support in fs.Stats · nodejs/node@fe5d351 · GitHub

/ node Public

Commit fe5d351

Browse files
joyeecheung
authored and
targos
committed
doc: document BigInt support in fs.Stats
PR-URL: #20220 Fixes: #12115 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
1 parent 04e8f07 commit fe5d351

2 files changed

Lines changed: 121 additions & 26 deletions

File tree

‎doc/api/fs.md‎

Lines changed: 119 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -415,6 +415,8 @@ A `fs.Stats` object provides information about a file.
415415

416416
Objects returned from [`fs.stat()`][], [`fs.lstat()`][] and [`fs.fstat()`][] and
417417
their synchronous counterparts are of this type.
418+
If `bigint` in the `options` passed to those methods is true, the numeric values
419+
will be `bigint` instead of `number`.
418420

419421
```console
420422
Stats {
@@ -438,6 +440,30 @@ Stats {
438440
birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
439441
```
440442

443+
`bigint` version:
444+
445+
```console
446+
Stats {
447+
dev: 2114n,
448+
ino: 48064969n,
449+
mode: 33188n,
450+
nlink: 1n,
451+
uid: 85n,
452+
gid: 100n,
453+
rdev: 0n,
454+
size: 527n,
455+
blksize: 4096n,
456+
blocks: 8n,
457+
atimeMs: 1318289051000n,
458+
mtimeMs: 1318289051000n,
459+
ctimeMs: 1318289051000n,
460+
birthtimeMs: 1318289051000n,
461+
atime: Mon, 10 Oct 2011 23:24:11 GMT,
462+
mtime: Mon, 10 Oct 2011 23:24:11 GMT,
463+
ctime: Mon, 10 Oct 2011 23:24:11 GMT,
464+
birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
465+
```
466+
441467
### stats.isBlockDevice()
442468
<!-- YAML
443469
added: v0.1.10
@@ -506,61 +532,61 @@ This method is only valid when using [`fs.lstat()`][].
506532

507533
### stats.dev
508534

509-
* {number}
535+
* {number|bigint}
510536

511537
The numeric identifier of the device containing the file.
512538

513539
### stats.ino
514540

515-
* {number}
541+
* {number|bigint}
516542

517543
The file system specific "Inode" number for the file.
518544

519545
### stats.mode
520546

521-
* {number}
547+
* {number|bigint}
522548

523549
A bit-field describing the file type and mode.
524550

525551
### stats.nlink
526552

527-
* {number}
553+
* {number|bigint}
528554

529555
The number of hard-links that exist for the file.
530556

531557
### stats.uid
532558

533-
* {number}
559+
* {number|bigint}
534560

535561
The numeric user identifier of the user that owns the file (POSIX).
536562

537563
### stats.gid
538564

539-
* {number}
565+
* {number|bigint}
540566

541567
The numeric group identifier of the group that owns the file (POSIX).
542568

543569
### stats.rdev
544570

545-
* {number}
571+
* {number|bigint}
546572

547573
A numeric device identifier if the file is considered "special".
548574

549575
### stats.size
550576

551-
* {number}
577+
* {number|bigint}
552578

553579
The size of the file in bytes.
554580

555581
### stats.blksize
556582

557-
* {number}
583+
* {number|bigint}
558584

559585
The file system block size for i/o operations.
560586

561587
### stats.blocks
562588

563-
* {number}
589+
* {number|bigint}
564590

565591
The number of blocks allocated for this file.
566592

@@ -569,7 +595,7 @@ The number of blocks allocated for this file.
569595
added: v8.1.0
570596
-->
571597

572-
* {number}
598+
* {number|bigint}
573599

574600
The timestamp indicating the last time this file was accessed expressed in
575601
milliseconds since the POSIX Epoch.
@@ -579,7 +605,7 @@ milliseconds since the POSIX Epoch.
579605
added: v8.1.0
580606
-->
581607

582-
* {number}
608+
* {number|bigint}
583609

584610
The timestamp indicating the last time this file was modified expressed in
585611
milliseconds since the POSIX Epoch.
@@ -589,7 +615,7 @@ milliseconds since the POSIX Epoch.
589615
added: v8.1.0
590616
-->
591617

592-
* {number}
618+
* {number|bigint}
593619

594620
The timestamp indicating the last time the file status was changed expressed
595621
in milliseconds since the POSIX Epoch.
@@ -599,7 +625,7 @@ in milliseconds since the POSIX Epoch.
599625
added: v8.1.0
600626
-->
601627

602-
* {number}
628+
* {number|bigint}
603629

604630
The timestamp indicating the creation time of this file expressed in
605631
milliseconds since the POSIX Epoch.
@@ -1643,7 +1669,7 @@ added: v0.1.96
16431669

16441670
Synchronous fdatasync(2). Returns `undefined`.
16451671

1646-
## fs.fstat(fd, callback)
1672+
## fs.fstat(fd[, options], callback)
16471673
<!-- YAML
16481674
added: v0.1.95
16491675
changes:
@@ -1655,9 +1681,16 @@ changes:
16551681
pr-url: https://github.com/nodejs/node/pull/7897
16561682
description: The `callback` parameter is no longer optional. Not passing
16571683
it will emit a deprecation warning with id DEP0013.
1684+
- version: REPLACEME
1685+
pr-url: REPLACEME
1686+
description: Accepts an additional `options` object to specify whether
1687+
the numeric values returned should be bigint.
16581688
-->
16591689

16601690
* `fd` {integer}
1691+
* `options` {Object}
1692+
* `bigint` {boolean} Whether the numeric values in the returned
1693+
[`fs.Stats`][] object should be `bigint`. **Default:** `false`.
16611694
* `callback` {Function}
16621695
* `err` {Error}
16631696
* `stats` {fs.Stats}
@@ -1666,12 +1699,20 @@ Asynchronous fstat(2). The callback gets two arguments `(err, stats)` where
16661699
`stats` is an [`fs.Stats`][] object. `fstat()` is identical to [`stat()`][],
16671700
except that the file to be stat-ed is specified by the file descriptor `fd`.
16681701

1669-
## fs.fstatSync(fd)
1702+
## fs.fstatSync(fd[, options])
16701703
<!-- YAML
16711704
added: v0.1.95
1705+
changes:
1706+
- version: REPLACEME
1707+
pr-url: REPLACEME
1708+
description: Accepts an additional `options` object to specify whether
1709+
the numeric values returned should be bigint.
16721710
-->
16731711

16741712
* `fd` {integer}
1713+
* `options` {Object}
1714+
* `bigint` {boolean} Whether the numeric values in the returned
1715+
[`fs.Stats`][] object should be `bigint`. **Default:** `false`.
16751716
* Returns: {fs.Stats}
16761717

16771718
Synchronous fstat(2).
@@ -1937,7 +1978,7 @@ changes:
19371978

19381979
Synchronous link(2). Returns `undefined`.
19391980

1940-
## fs.lstat(path, callback)
1981+
## fs.lstat(path[, options], callback)
19411982
<!-- YAML
19421983
added: v0.1.30
19431984
changes:
@@ -1953,9 +1994,16 @@ changes:
19531994
pr-url: https://github.com/nodejs/node/pull/7897
19541995
description: The `callback` parameter is no longer optional. Not passing
19551996
it will emit a deprecation warning with id DEP0013.
1997+
- version: REPLACEME
1998+
pr-url: REPLACEME
1999+
description: Accepts an additional `options` object to specify whether
2000+
the numeric values returned should be bigint.
19562001
-->
19572002

19582003
* `path` {string|Buffer|URL}
2004+
* `options` {Object}
2005+
* `bigint` {boolean} Whether the numeric values in the returned
2006+
[`fs.Stats`][] object should be `bigint`. **Default:** `false`.
19592007
* `callback` {Function}
19602008
* `err` {Error}
19612009
* `stats` {fs.Stats}
@@ -1965,17 +2013,24 @@ Asynchronous lstat(2). The callback gets two arguments `(err, stats)` where
19652013
except that if `path` is a symbolic link, then the link itself is stat-ed,
19662014
not the file that it refers to.
19672015

1968-
## fs.lstatSync(path)
2016+
## fs.lstatSync(path[, options])
19692017
<!-- YAML
19702018
added: v0.1.30
19712019
changes:
19722020
- version: v7.6.0
19732021
pr-url: https://github.com/nodejs/node/pull/10739
19742022
description: The `path` parameter can be a WHATWG `URL` object using `file:`
19752023
protocol. Support is currently still *experimental*.
2024+
- version: REPLACEME
2025+
pr-url: REPLACEME
2026+
description: Accepts an additional `options` object to specify whether
2027+
the numeric values returned should be bigint.
19762028
-->
19772029

19782030
* `path` {string|Buffer|URL}
2031+
* `options` {Object}
2032+
* `bigint` {boolean} Whether the numeric values in the returned
2033+
[`fs.Stats`][] object should be `bigint`. **Default:** `false`.
19792034
* Returns: {fs.Stats}
19802035

19812036
Synchronous lstat(2).
@@ -2693,7 +2748,7 @@ Synchronous rmdir(2). Returns `undefined`.
26932748
Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT` error
26942749
on Windows and an `ENOTDIR` error on POSIX.
26952750

2696-
## fs.stat(path, callback)
2751+
## fs.stat(path[, options], callback)
26972752
<!-- YAML
26982753
added: v0.0.2
26992754
changes:
@@ -2709,9 +2764,16 @@ changes:
27092764
pr-url: https://github.com/nodejs/node/pull/7897
27102765
description: The `callback` parameter is no longer optional. Not passing
27112766
it will emit a deprecation warning with id DEP0013.
2767+
- version: REPLACEME
2768+
pr-url: REPLACEME
2769+
description: Accepts an additional `options` object to specify whether
2770+
the numeric values returned should be bigint.
27122771
-->
27132772

27142773
* `path` {string|Buffer|URL}
2774+
* `options` {Object}
2775+
* `bigint` {boolean} Whether the numeric values in the returned
2776+
[`fs.Stats`][] object should be `bigint`. **Default:** `false`.
27152777
* `callback` {Function}
27162778
* `err` {Error}
27172779
* `stats` {fs.Stats}
@@ -2729,17 +2791,24 @@ error raised if the file is not available.
27292791
To check if a file exists without manipulating it afterwards, [`fs.access()`]
27302792
is recommended.
27312793

2732-
## fs.statSync(path)
2794+
## fs.statSync(path[, options])
27332795
<!-- YAML
27342796
added: v0.1.21
27352797
changes:
27362798
- version: v7.6.0
27372799
pr-url: https://github.com/nodejs/node/pull/10739
27382800
description: The `path` parameter can be a WHATWG `URL` object using `file:`
27392801
protocol. Support is currently still *experimental*.
2802+
- version: REPLACEME
2803+
pr-url: REPLACEME
2804+
description: Accepts an additional `options` object to specify whether
2805+
the numeric values returned should be bigint.
27402806
-->
27412807

27422808
* `path` {string|Buffer|URL}
2809+
* `options` {Object}
2810+
* `bigint` {boolean} Whether the numeric values in the returned
2811+
[`fs.Stats`][] object should be `bigint`. **Default:** `false`.
27432812
* Returns: {fs.Stats}
27442813

27452814
Synchronous stat(2).
@@ -3516,10 +3585,18 @@ returned.
35163585

35173586
The `FileHandle` has to support reading.
35183587

3519-
#### filehandle.stat()
3588+
#### filehandle.stat([options])
35203589
<!-- YAML
35213590
added: v10.0.0
3591+
changes:
3592+
- version: REPLACEME
3593+
pr-url: REPLACEME
3594+
description: Accepts an additional `options` object to specify whether
3595+
the numeric values returned should be bigint.
35223596
-->
3597+
* `options` {Object}
3598+
* `bigint` {boolean} Whether the numeric values in the returned
3599+
[`fs.Stats`][] object should be `bigint`. **Default:** `false`.
35233600
* Returns: {Promise}
35243601

35253602
Retrieves the [`fs.Stats`][] for the file.
@@ -3844,12 +3921,20 @@ added: v10.0.0
38443921

38453922
Asynchronous link(2). The `Promise` is resolved with no arguments upon success.
38463923

3847-
### fsPromises.lstat(path)
3924+
### fsPromises.lstat(path[, options])
38483925
<!-- YAML
38493926
added: v10.0.0
3927+
changes:
3928+
- version: REPLACEME
3929+
pr-url: REPLACEME
3930+
description: Accepts an additional `options` object to specify whether
3931+
the numeric values returned should be bigint.
38503932
-->
38513933

38523934
* `path` {string|Buffer|URL}
3935+
* `options` {Object}
3936+
* `bigint` {boolean} Whether the numeric values in the returned
3937+
[`fs.Stats`][] object should be `bigint`. **Default:** `false`.
38533938
* Returns: {Promise}
38543939

38553940
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
40304115
`Promise` being rejected with an `ENOENT` error on Windows and an `ENOTDIR`
40314116
error on POSIX.
40324117

4033-
### fsPromises.stat(path)
4118+
### fsPromises.stat(path[, options])
40344119
<!-- YAML
40354120
added: v10.0.0
4121+
changes:
4122+
- version: REPLACEME
4123+
pr-url: REPLACEME
4124+
description: Accepts an additional `options` object to specify whether
4125+
the numeric values returned should be bigint.
40364126
-->
40374127

40384128
* `path` {string|Buffer|URL}
4129+
* `options` {Object}
4130+
* `bigint` {boolean} Whether the numeric values in the returned
4131+
[`fs.Stats`][] object should be `bigint`. **Default:** `false`.
40394132
* Returns: {Promise}
40404133

40414134
The `Promise` is resolved with the [`fs.Stats`][] object for the given `path`.
@@ -4491,9 +4584,9 @@ the file contents.
44914584
[`fs.chown()`]: #fs_fs_chown_path_uid_gid_callback
44924585
[`fs.copyFile()`]: #fs_fs_copyfile_src_dest_flags_callback
44934586
[`fs.exists()`]: fs.html#fs_fs_exists_path_callback
4494-
[`fs.fstat()`]: #fs_fs_fstat_fd_callback
4587+
[`fs.fstat()`]: #fs_fs_fstat_fd_options_callback
44954588
[`fs.futimes()`]: #fs_fs_futimes_fd_atime_mtime_callback
4496-
[`fs.lstat()`]: #fs_fs_lstat_path_callback
4589+
[`fs.lstat()`]: #fs_fs_lstat_path_options_callback
44974590
[`fs.mkdir()`]: #fs_fs_mkdir_path_mode_callback
44984591
[`fs.mkdtemp()`]: #fs_fs_mkdtemp_prefix_options_callback
44994592
[`fs.open()`]: #fs_fs_open_path_flags_mode_callback
@@ -4502,7 +4595,7 @@ the file contents.
45024595
[`fs.readFileSync()`]: #fs_fs_readfilesync_path_options
45034596
[`fs.realpath()`]: #fs_fs_realpath_path_options_callback
45044597
[`fs.rmdir()`]: #fs_fs_rmdir_path_callback
4505-
[`fs.stat()`]: #fs_fs_stat_path_callback
4598+
[`fs.stat()`]: #fs_fs_stat_path_options_callback
45064599
[`fs.utimes()`]: #fs_fs_utimes_path_atime_mtime_callback
45074600
[`fs.watch()`]: #fs_fs_watch_filename_options_listener
45084601
[`fs.write()`]: #fs_fs_write_fd_buffer_offset_length_position_callback

‎tools/doc/type-parser.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ const customTypesMap = {
3131

3232
'AsyncIterator': 'https://github.com/tc39/proposal-async-iteration',
3333

34+
'bigint': 'https://github.com/tc39/proposal-bigint',
35+
3436
'Iterable':
3537
`${jsDocPrefix}Reference/Iteration_protocols#The_iterable_protocol`,
3638
'Iterator':

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL