fs: drop duplicate API in promises mode

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).

Fixes: https://github.com/nodejs/node/issues/20548
PR-URL: https://github.com/nodejs/node/pull/20559
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

4 files changed, 8 insertions, 214 deletions

diff --git a/benchmark/fs/bench-stat-promise.js b/benchmark/fs/bench-stat-promise.js
index 96c7058fa6..99a5da5799 100644
--- a/benchmark/fs/bench-stat-promise.js
+++ b/benchmark/fs/bench-stat-promise.js
@@ -9,12 +9,12 @@ const bench = common.createBenchmark(main, {
 });
 
 async function run(n, statType) {
-  const arg = statType === 'fstat' ?
-    await fsPromises.open(__filename, 'r') : __filename;
+  const handleMode = statType === 'fstat';
+  const arg = handleMode ? await fsPromises.open(__filename, 'r') : __filename;
   let remaining = n;
   bench.start();
   while (remaining-- > 0)
-    await fsPromises[statType](arg);
+    await (handleMode ? arg.stat() : fsPromises[statType](arg));
   bench.end(n);
 
   if (typeof arg.close === 'function')
diff --git a/doc/api/fs.md b/doc/api/fs.md
index 470601f0b7..55691dedac 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -3797,128 +3797,6 @@ fsPromises.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL)
   .catch(() => console.log('The file could not be copied'));
 ```
 
-### fsPromises.fchmod(filehandle, mode)
-<!-- YAML
-added: v10.0.0
--->
-
-* `filehandle` {FileHandle}
-* `mode` {integer}
-* Returns: {Promise}
-
-Asynchronous fchmod(2). The `Promise` is resolved with no arguments upon
-success.
-
-### fsPromises.fchown(filehandle, uid, gid)
-<!-- YAML
-added: v10.0.0
--->
-
-* `filehandle` {FileHandle}
-* `uid` {integer}
-* `gid` {integer}
-* Returns: {Promise}
-
-Changes the ownership of the file represented by `filehandle` then resolves
-the `Promise` with no arguments upon success.
-
-### fsPromises.fdatasync(filehandle)
-<!-- YAML
-added: v10.0.0
--->
-
-* `filehandle` {FileHandle}
-* Returns: {Promise}
-
-Asynchronous fdatasync(2). The `Promise` is resolved with no arguments upon
-success.
-
-### fsPromises.fstat(filehandle)
-<!-- YAML
-added: v10.0.0
--->
-
-* `filehandle` {FileHandle}
-* Returns: {Promise}
-
-Retrieves the [`fs.Stats`][] for the given `filehandle`.
-
-### fsPromises.fsync(filehandle)
-<!-- YAML
-added: v10.0.0
--->
-
-* `filehandle` {FileHandle}
-* Returns: {Promise}
-
-Asynchronous fsync(2). The `Promise` is resolved with no arguments upon
-success.
-
-### fsPromises.ftruncate(filehandle[, len])
-<!-- YAML
-added: v10.0.0
--->
-
-* `filehandle` {FileHandle}
-* `len` {integer} **Default:** `0`
-* Returns: {Promise}
-
-Truncates the file represented by `filehandle` then resolves the `Promise`
-with no arguments upon success.
-
-If the file referred to by the `FileHandle` was larger than `len` bytes, only
-the first `len` bytes will be retained in the file.
-
-For example, the following program retains only the first four bytes of the
-file:
-
-```js
-console.log(fs.readFileSync('temp.txt', 'utf8'));
-// Prints: Node.js
-
-async function doTruncate() {
-  const fd = await fsPromises.open('temp.txt', 'r+');
-  await fsPromises.ftruncate(fd, 4);
-  console.log(fs.readFileSync('temp.txt', 'utf8'));  // Prints: Node
-}
-
-doTruncate().catch(console.error);
-```
-
-If the file previously was shorter than `len` bytes, it is extended, and the
-extended part is filled with null bytes (`'\0'`). For example,
-
-```js
-console.log(fs.readFileSync('temp.txt', 'utf8'));
-// Prints: Node.js
-
-async function doTruncate() {
-  const fd = await fsPromises.open('temp.txt', 'r+');
-  await fsPromises.ftruncate(fd, 10);
-  console.log(fs.readFileSync('temp.txt', 'utf8'));  // Prints Node.js\0\0\0
-}
-
-doTruncate().catch(console.error);
-```
-
-The last three bytes are null bytes (`'\0'`), to compensate the over-truncation.
-
-### fsPromises.futimes(filehandle, atime, mtime)
-<!-- YAML
-added: v10.0.0
--->
-
-* `filehandle` {FileHandle}
-* `atime` {number|string|Date}
-* `mtime` {number|string|Date}
-* Returns: {Promise}
-
-Change the file system timestamps of the object referenced by the supplied
-`FileHandle` then resolves the `Promise` with no arguments upon success.
-
-This function does not work on AIX versions before 7.1, it will resolve the
-`Promise` with an error using code `UV_ENOSYS`.
-
 ### fsPromises.lchmod(path, mode)
 <!-- YAML
 deprecated: v10.0.0
@@ -4027,35 +3905,6 @@ by [Naming Files, Paths, and Namespaces][]. Under NTFS, if the filename contains
 a colon, Node.js will open a file system stream, as described by
 [this MSDN page][MSDN-Using-Streams].
 
-### fsPromises.read(filehandle, buffer, offset, length, position)
-<!-- YAML
-added: v10.0.0
--->
-
-* `filehandle` {FileHandle}
-* `buffer` {Buffer|Uint8Array}
-* `offset` {integer}
-* `length` {integer}
-* `position` {integer}
-* Returns: {Promise}
-
-Read data from the file specified by `filehandle`.
-
-`buffer` is the buffer that the data will be written to.
-
-`offset` is the offset in the buffer to start writing at.
-
-`length` is an integer specifying the number of bytes to read.
-
-`position` is an argument specifying where to begin reading from in the file.
-If `position` is `null`, data will be read from the current file position,
-and the file position will be updated.
-If `position` is an integer, the file position will remain unchanged.
-
-Following successful read, the `Promise` is resolved with an object with a
-`bytesRead` property specifying the number of bytes read, and a `buffer`
-property that is a reference to the passed in `buffer` argument.
-
 ### fsPromises.readdir(path[, options])
 <!-- YAML
 added: v10.0.0
@@ -4240,39 +4089,6 @@ The `atime` and `mtime` arguments follow these rules:
 - If the value can not be converted to a number, or is `NaN`, `Infinity` or
   `-Infinity`, an `Error` will be thrown.
 
-### fsPromises.write(filehandle, buffer[, offset[, length[, position]]])
-<!-- YAML
-added: v10.0.0
--->
-
-* `filehandle` {FileHandle}
-* `buffer` {Buffer|Uint8Array}
-* `offset` {integer}
-* `length` {integer}
-* `position` {integer}
-* Returns: {Promise}
-
-Write `buffer` to the file specified by `filehandle`.
-
-The `Promise` is resolved with an object containing a `bytesWritten` property
-identifying the number of bytes written, and a `buffer` property containing
-a reference to the `buffer` written.
-
-`offset` determines the part of the buffer to be written, and `length` is
-an integer specifying the number of bytes to write.
-
-`position` refers to the offset from the beginning of the file where this data
-should be written. If `typeof position !== 'number'`, the data will be written
-at the current position. See pwrite(2).
-
-It is unsafe to use `fsPromises.write()` multiple times on the same file
-without waiting for the `Promise` to be resolved (or rejected). For this
-scenario, `fs.createWriteStream` is strongly recommended.
-
-On Linux, positional writes do not work when the file is opened in append mode.
-The kernel ignores the position argument and always appends the data to
-the end of the file.
-
 ### fsPromises.writeFile(file, data[, options])
 <!-- YAML
 added: v10.0.0
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index ee985761ac..9700765f08 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -466,31 +466,22 @@ module.exports = {
   access,
   copyFile,
   open,
-  read,
-  write,
   rename,
   truncate,
-  ftruncate,
   rmdir,
-  fdatasync,
-  fsync,
   mkdir,
   readdir,
   readlink,
   symlink,
-  fstat,
   lstat,
   stat,
   link,
   unlink,
-  fchmod,
   chmod,
   lchmod,
   lchown,
-  fchown,
   chown,
   utimes,
-  futimes,
   realpath,
   mkdtemp,
   writeFile,
diff --git a/test/parallel/test-fs-promises.js b/test/parallel/test-fs-promises.js
index ea779e499e..7dccdea9bc 100644
--- a/test/parallel/test-fs-promises.js
+++ b/test/parallel/test-fs-promises.js
@@ -11,18 +11,11 @@ const {
   access,
   chmod,
   copyFile,
-  fchmod,
-  fdatasync,
-  fstat,
-  fsync,
-  ftruncate,
-  futimes,
   link,
   lstat,
   mkdir,
   mkdtemp,
   open,
-  read,
   readdir,
   readlink,
   realpath,
@@ -30,7 +23,6 @@ const {
   rmdir,
   stat,
   symlink,
-  write,
   unlink,
   utimes
 } = fsPromises;
@@ -74,13 +66,13 @@ function verifyStatObject(stat) {
     const handle = await open(dest, 'r+');
     assert.strictEqual(typeof handle, 'object');
 
-    let stats = await fstat(handle);
+    let stats = await handle.stat();
     verifyStatObject(stats);
     assert.strictEqual(stats.size, 35);
 
-    await ftruncate(handle, 1);
+    await handle.truncate(1);
 
-    stats = await fstat(handle);
+    stats = await handle.stat();
     verifyStatObject(stats);
     assert.strictEqual(stats.size, 1);
 
@@ -90,15 +82,13 @@ function verifyStatObject(stat) {
     stats = await handle.stat();
     verifyStatObject(stats);
 
-    await fdatasync(handle);
     await handle.datasync();
-    await fsync(handle);
     await handle.sync();
 
     const buf = Buffer.from('hello fsPromises');
     const bufLen = buf.length;
-    await write(handle, buf);
-    const ret = await read(handle, Buffer.alloc(bufLen), 0, bufLen, 0);
+    await handle.write(buf);
+    const ret = await handle.read(Buffer.alloc(bufLen), 0, bufLen, 0);
     assert.strictEqual(ret.bytesRead, bufLen);
     assert.deepStrictEqual(ret.buffer, buf);
 
@@ -110,18 +100,15 @@ function verifyStatObject(stat) {
     assert.deepStrictEqual(ret2.buffer, buf2);
 
     await chmod(dest, 0o666);
-    await fchmod(handle, 0o666);
     await handle.chmod(0o666);
 
     // Mode larger than 0o777 should be masked off.
     await chmod(dest, (0o777 + 1));
-    await fchmod(handle, 0o777 + 1);
     await handle.chmod(0o777 + 1);
 
     await utimes(dest, new Date(), new Date());
 
     try {
-      await futimes(handle, new Date(), new Date());
       await handle.utimes(new Date(), new Date());
     } catch (err) {
       // Some systems do not have futimes. If there is an error,