doc: add example for file existence with fs.stat

[connium]

Checklist

• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

Add an example on how to test if a file exists with fs.stat. Also add
a link to the Common System Errors.

Fixed with help of @dschnei @narf101010

Fixes: #6752

[imyller]

If there is need to document an example of fs.stat usage for checking file existince, I have few reservations about this implementation:

• Checking for ENOENT alone might not be enough to indicate file (non)existence (which is more complex issue than one might initially think). Considering all the imaginable filesystem, file consistency and platform variants.
• fs.Stats.isFile() and fs.Stats.isDirectory() methods could be more reliable cross-platform ways to determine file or directory existence than Common System Error code.

More collaborator feedback needed here.

[bnoordhuis]

If you just want to check that a file exists, fs.access() is a better, more efficient solution.

If you want to manipulate the file, stat-then-open (or stat-then-move, etc.) is subject to TOCTOU race conditions. The right way is to simply open the file and handle the error if it doesn't exist or isn't accessible.

[imyller]

Your effort is much appreciated @connium, but I'm -1 on landing this.

What I'd like to see added is the part where err.code is referenced to Common System Errors. That alone would be good improvement to the documentation.

[jasnell]

@connium .. the clarification on the error code is definite +1.

@imyller @bnoordhuis ... I think I'd be fine with adding this example so long as there's also a note added saying exactly what @bnoordhuis is describing in his comment... that while this example works, there are better and more reliable ways of accomplishing it. I would definitely sign off on it with that added.

[imyller]

I agree with @jasnell and I won't object to this PR being landed, if doc is amended with valid points @bnoordhuis made in his comment.

[connium]

@imyller @bnoordhuis @jasnell thanks for your feedback!

I wasn't aware of the complexity of doing file existence checks the right way 😃
I just extended the documentation and removed the example as it looks like there is no silver bullet and I don't want to introduce "bad behavior" 😉

[imyller]

I think that the doc is much better now.

This adds important err.code reference to Common System Errors and also properly instructs user in implementing file existence checking.

[imyller]

LGTM

[jasnell]

nit: long line here

[connium]

Sorry, I missed that. It is fixed now.

[jasnell]

LGTM with a nit.

[jasnell]

Landed in 23b9625. Thank you!