Major discrepancy in FS constants between the docs and distribution

[dead-claudia]

Version

v16.13.2

Platform

Microsoft Windows NT 10.0.19043.0 x64

Subsystem

fs

Ref: https://nodejs.org/docs/latest-v16.x/api/fs.html#file-access-constants

What steps will reproduce the bug?

Run the following script:

const {constants} = require("fs")

for (const k of Object.keys(constants).sort()) {
    const v = constants[k]
    if (v != null && typeof v !== "function" && typeof v !== "object") {
        console.log(k)
    }
}

How often does it reproduce? Is there a required condition?

100% of the time

What is the expected behavior?

The following modulo whatever legacy constants there are.

COPYFILE_EXCL
COPYFILE_FICLONE_FORCE
COPYFILE_FICLONE
F_OK
O_APPEND
O_CREAT
O_DIRECT
O_DIRECTORY
O_DSYNC
O_EXCL
O_NOATIME
O_NOCTTY
O_NOFOLLOW
O_NONBLOCK
O_RDONLY
O_RDWR
O_SYMLINK
O_SYNC
O_TRUNC
O_WRONLY
R_OK
S_IFBLK
S_IFCHR
S_IFDIR
S_IFIFO
S_IFLNK
S_IFMT
S_IFREG
S_IFSOCK
S_IRGRP
S_IROTH
S_IRUSR
S_IRWXG
S_IRWXO
S_IRWXU
S_IWGRP
S_IWOTH
S_IWUSR
S_IXGRP
S_IXOTH
S_IXUSR
UV_FS_O_FILEMAP
W_OK
X_OK

What do you see instead?

COPYFILE_EXCL
COPYFILE_FICLONE
COPYFILE_FICLONE_FORCE
F_OK
O_APPEND
O_CREAT
O_EXCL
O_RDONLY
O_RDWR
O_TRUNC
O_WRONLY
R_OK
S_IFCHR
S_IFDIR
S_IFLNK
S_IFMT
S_IFREG
UV_DIRENT_BLOCK
UV_DIRENT_CHAR
UV_DIRENT_DIR
UV_DIRENT_FIFO
UV_DIRENT_FILE
UV_DIRENT_LINK
UV_DIRENT_SOCKET
UV_DIRENT_UNKNOWN
UV_FS_COPYFILE_EXCL
UV_FS_COPYFILE_FICLONE
UV_FS_COPYFILE_FICLONE_FORCE
UV_FS_O_FILEMAP
UV_FS_SYMLINK_DIR
UV_FS_SYMLINK_JUNCTION
W_OK
X_OK

Additional information

This represents the following diff (hand-written):

---distribution
+++docs
 COPYFILE_EXCL
 COPYFILE_FICLONE
 COPYFILE_FICLONE_FORCE
 F_OK
 O_APPEND
 O_CREAT
+O_DIRECT
+O_DIRECTORY
+O_DSYNC
 O_EXCL
+O_NOATIME
+O_NOCTTY
+O_NOFOLLOW
+O_NONBLOCK
 O_RDONLY
 O_RDWR
+O_SYMLINK
+O_SYNC
 O_TRUNC
 O_WRONLY
 R_OK
+S_IFBLK
 S_IFCHR
 S_IFDIR
+S_IFIFO
 S_IFLNK
 S_IFMT
 S_IFREG
+S_IFSOCK
+S_IRGRP
+S_IROTH
+S_IRUSR
+S_IRWXG
+S_IRWXO
+S_IRWXU
+S_IWGRP
+S_IWOTH
+S_IWUSR
+S_IXGRP
+S_IXOTH
+S_IXUSR
-UV_DIRENT_BLOCK
-UV_DIRENT_CHAR
-UV_DIRENT_DIR
-UV_DIRENT_FIFO
-UV_DIRENT_FILE
-UV_DIRENT_LINK
-UV_DIRENT_SOCKET
-UV_DIRENT_UNKNOWN
-UV_FS_COPYFILE_EXCL
-UV_FS_COPYFILE_FICLONE
-UV_FS_COPYFILE_FICLONE_FORCE
+UV_FS_O_FILEMAP
-UV_FS_SYMLINK_DIR
-UV_FS_SYMLINK_JUNCTION
 W_OK
 X_OK

[targos]

The documentation says:

Not every constant will be available on every operating system.

This explains why some constants are in the documentation but not available on Windows.

The red lines in your diff are probably additions that we forgot to document.

[dead-claudia]

Not every constant will be available on every operating system.

Okay, I missed that bit. I'll log a separate feature request for that so the docs are easier to follow in that area.