fs: drop duplicate API in promises mode

[ChALkeR]

This drops exporting duplicate methods that accept FileHandle as the first argument (to mirror callback-based methods accepting 'fd').

Those methods were not adding actual value to the API because all of those are already present as FileHandle methods, and they would probably be confusing to the new users and making docs harder to read.

Also, the API was a bit inconsistent and lacked .close(handle).

Removed documentation is completely duplicated under the FileHandle methods doc.

Fixes: #20548

On the downside, this will make porting existing promisified and callback-based fs usage to promises API harder, but I estimate that as being less important than not confusing new users (exponential growth 😉) and not having to support 3 variants of the same API for a long time. Also, there are more differences in the API — not only the fd → filehandle change, but also the return values are already different there.

Checklist

• make -j4 test passes
  I tested only lint, parallel/test-fs-promises* and benchmark/fs/bench-stat-promise, but other files do not import fs/promises.
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

/cc @jasnell @Trott @BridgeAR @nodejs/tsc

[ChALkeR]

@jasnell Am I understanding it correct that the current state of things was mostly historical and was caused by a chain of changes, one of which initially exposed those methods only on the fsPromises object and intentionally omitted .close (because it was already present on the FileHandle) and the other one added all the other ones to FileHandle without removing them from fsPromises object?

[mcollina]

LGTM

[Trott]

@nodejs/fs

[Trott]

Seems good to me but I'll defer to others who have thought much more about this than I have.

[benjamingr]

Blocking since I definitely want to take a look at this PR although I also noticed this and generally agree with the sentiment of not having this additional API.

[benjamingr]

Actual changes LGTM and thinking about this a little more - I really think this should be discussed at a TSC meeting since it's a huge API surface.

...

[ChALkeR]

Note: after landing this, the code could be refactored a bit, e.g. by removing validateFileHandle checks.

I decided to leave that out of this PR for now, though — code refactoring could be done separately and actual changes (that need more eyes) are now isolated in this PR, making it easier to review.

[ChALkeR]

CI: https://ci.nodejs.org/job/node-test-pull-request/14737/