fs: undeprecate existsSync

[dfabulich]

Checklist

• make -j4 test (UNIX), or vcbuild test nosign (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

fs

Description of change

Undeprecate fs.existsSync, apropos @Fishrock123's comment on PR #7455

[dfabulich]

For those not following along with the multiple giant threads around this, I think my summary comment tells the clearest story:

1. There's an enormous gripe thread about the deprecation of existsSync in issue gripe: deprecating fs.exists/existsSync #1592, which is summarized pretty well in PR fs: add accessibleSync() which returns a boolean #4217.

2. accessSync throws an exception if the file isn't accessible — you're asserting that the file exists and is accessible. But most developers don't want/need the actual exception object, so they just discard it. (Look at the existing implementation of existsSync.)

Generating an exception just so you can ignore it hurts performance. In PR #4217 we're considering adding a new method accessibleSync that would return a boolean (fast!) instead, but that would add unnecessary methods to Node's core, when we could just undeprecate existsSync.

Furthermore, accessSync is just plain annoying to use for ordinary use cases.

if(fs.existsSync(".git/rebase-apply/rebasing")){console.error("You are in the middle of a rebase!");}

To write that with accessSync you have to use a catch block.

try{fs.accessSync(".git/rebase-apply/rebasing");}catch(ignored){console.error("You are in the middle of a rebase!");}

Perhaps if annoyance were the only problem, we could all just use a one-liner npm module for existsSync, but there's also performance to consider. You just can't make accessSync fast without making it return a boolean, like existsSync does.

Today, exists uses stat under the hood, returning false if stat returns an error. It would be faster to make exists use access under the hood, which is PR #7455, but this may be risky; it's rumored that access may be able to succeed where stat fails, particularly on Windows where it might be possible to configure permissions in such a way that access succeeds but stat fails.

Hence this PR, to simply undeprecate existsSync.

[Fishrock123]

@nodejs/ctc I find the arguments here compelling and would like to follow through.

[yosuke-furukawa]

IMHO, our fs is a wrapper of posix standard API.

exists is easy API, that is really helpful for development. But POSIX API does not have exists.

And, we would be better to keep core simple. we should not re-support those easy API like exists.

[dfabulich]

It may surprise you that I mostly agree with this. In PR #4217, I think we reached some consensus that it would have been better if accessibleSync had been part of the API all along.

But the problem now is that node is doing too much on top of the POSIX API. access wraps access(2) in an asynchronous API; accessSync calls access(2) but then throws an exception on failure; access(2) doesn't do that because C doesn't even have exceptions.

What we need is an API that calls access(2) and then returns a value, like POSIX does.

That either means adding a new accessibleSync function to core, or undeprecating existsSync.

Undeprecating existsSync is the least bad thing we can do; it's even better than nothing.

[jasnell]

LGTM

[thefourtheye]

Deprecating only the async version would be confusing to the new users I believe. The doc just points to the exists documentation, which is actually deprecated.

[Fishrock123]

We can add the relevant documentation to this method... (We're not gona undeprecate fs.exists()...)

[dfabulich]

Added relevant documentation to fs.exists() and fs.existsSync(), clarifying that the callback of fs.exists() is non-standard, but fs.existsSync() does not use a callback.

[thefourtheye]

Node.js

[dfabulich]

Thanks, fixed.

[jasnell]

Another one ;-) s/Node/Node.js/g

[Trott]

Are doc-only deprecations semver-major? If so, then should undoing a doc-only deprecation like this also be semver-major? I don't have an opinion either way; just seeking clarity.

[ChALkeR]

If so, then should undoing a doc-only deprecation like this also be semver-major?

No, undoing a semver-major generally should be either semver-minor (in most cases) or semver-patch (in case if the breakage that is being reverted was unintended). Likewise, undoing a semver-minor is generally a semver-major.

Undoing a semver-major is a semver-major only in cases of an API behaviour change which is not an addition, deprecation or removal of something — and something like that should generally be avoided, if possible.

But in this specific situation (where the deprecation was docs-only) we could just land that to all branches starting from 4.x in a patch release, IMO.

[dfabulich]

Fixed the last outstanding s/Node/Node.js/

[dfabulich]

ping?

[Trott]

Are any @nodejs/collaborators strongly in favor of undeprecating fs.existsSync() as proposed here? There are differences of opinion among collaborators on this. Without a collaborator champion to help work things through the process, this is unlikely to land.

I see @jasnell gave this a LGTM but I'm not sure that he's willing to champion this. (Hey, @jasnell, are you?)

Anyone else?

[dfabulich]

I thought (hoped?) @Fishrock123 was the relevant champion here.

[Trott]

I thought (hoped?) @Fishrock123 was the relevant champion here.

Good point. @Fishrock123 assigned the issue to themselves as well, which seems like a pretty good indication.

It wouldn't hurt to have more champions, I suppose. :-D

[jasnell]

I believe this should be done. If that's the same as championing, then ok 😃

On Monday, September 19, 2016, Rich Trott notifications@github.com wrote:

I thought (hoped?) @Fishrock123https://github.com/Fishrock123 was the
relevant champion here.

Good point. @Fishrock123https://github.com/Fishrock123 assigned the
issue to themselves as well, which seems like a pretty good indication.

It wouldn't hurt to have more champions, I suppose. :-D

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#8364 (comment), or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAa2eUp_SYyeDwmCbhY0FH-kNTiZC89Eks5qrixRgaJpZM4JyKL5
.

[imyller]

I'm quite new-in-town, but I'm also in favor of undeprecating fs.existsSync.

LGTM

[mcollina]

LGTM

[Trott]

OK, that's three LGTMs and some additional supportive comments from others.

Do any Collaborators object? That is, are any Collaborators opposed to it to the point that they would veto it? Something stronger than just "I don't like it but I'm not going to stop it if others want it".

/cc @seishun@yosuke-furukawa@thefourtheye

[dfabulich]

doc/api/fs.md: no issues found

[Fishrock123]

@ChALkeR can you approve so I can merge? Thanks :)

[ChALkeR]

@Fishrock123, @dfabulich, @Trott, sorry for the delay. LGTM now.

The PR with the doclint tooling is in #8551, if you will want that again until it's merged =).
Removing the trailing / for manual checking is fine, it's needed for the tooling to function correctly (#8666 explains why).

[Fishrock123]

Landed in 7b5ffa4. Hopefully this will put it to rest (for the most part).

(I wrote an extensive summary into the commit description.)

Thanks so much @dfabulich for helping push this forward. :)