From 64ff02e3dbcb785b32ab7b66d81c93d78e9ed763 Mon Sep 17 00:00:00 2001
From: Bryan English <bryan@bryanenglish.com>
Date: Mon, 6 Jan 2020 21:39:10 -0500
Subject: [PATCH 1/2] fs: use async writeFile in FileHandle#appendFile

When operating on a FileHandle, the file has already been opened with
the flag given as an option to fs.promises.open(). This means defaulting
to 'a' has no effect here, and FileHandle#appendFile turns out to
exactly be an alias of writeFile. This is now explicit, saving a stack
frame, object copy and assignment.
---
 lib/internal/fs/promises.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index 785d0b082cc1a2..65e4fdb63c7ecb 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -70,7 +70,7 @@ class FileHandle {
   }
 
   appendFile(data, options) {
-    return appendFile(this, data, options);
+    return writeFile(this, data, options);
   }
 
   chmod(mode) {

From ecc2d7865263c6dd69c87def3c91a1757f1ba12a Mon Sep 17 00:00:00 2001
From: Bryan English <bryan@bryanenglish.com>
Date: Mon, 6 Jan 2020 22:21:54 -0500
Subject: [PATCH 2/2] doc: correcting filehandle.[read|write|append]File

* Remove `mode` and `flag` options for all three functions, since they
all ignore those options.
* Remove mention of `path` argument for `readFile`, since it isn't
actually an option to this method.
* Clarify that for file handles, `appendFile` and `writeFile` are
equivalent.
---
 doc/api/fs.md | 22 ++++++----------------
 1 file changed, 6 insertions(+), 16 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 82bb47a2116b4c..7f782b1d1ecf8b 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -4253,17 +4253,13 @@ added: v10.0.0
 * `data` {string|Buffer}
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
-  * `mode` {integer} **Default:** `0o666`
-  * `flag` {string} See [support of file system `flags`][]. **Default:** `'a'`.
 * Returns: {Promise}
 
-Asynchronously append data to this file, creating the file if it does not yet
-exist. `data` can be a string or a [`Buffer`][]. The `Promise` will be
-resolved with no arguments upon success.
+Alias of [`filehandle.writeFile()`][].
 
-If `options` is a string, then it specifies the encoding.
-
-The `FileHandle` must have been opened for appending.
+When operating on file handles, the mode cannot be changed from what it was set
+to with [`fsPromises.open()`][]. Therefore, this is equivalent to
+[`filehandle.writeFile()`][].
 
 #### `filehandle.chmod(mode)`
 <!-- YAML
@@ -4364,7 +4360,6 @@ added: v10.0.0
 
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `null`
-  * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`.
 * Returns: {Promise}
 
 Asynchronously reads the entire contents of a file.
@@ -4375,11 +4370,6 @@ object. Otherwise, the data will be a string.
 
 If `options` is a string, then it specifies the encoding.
 
-When the `path` is a directory, the behavior of `fsPromises.readFile()` is
-platform-specific. On macOS, Linux, and Windows, the promise will be rejected
-with an error. On FreeBSD, a representation of the directory's contents will be
-returned.
-
 The `FileHandle` has to support reading.
 
 If one or more `filehandle.read()` calls are made on a file handle and then a
@@ -4569,8 +4559,6 @@ added: v10.0.0
 * `data` {string|Buffer|Uint8Array}
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
-  * `mode` {integer} **Default:** `0o666`
-  * `flag` {string} See [support of file system `flags`][]. **Default:** `'w'`.
 * Returns: {Promise}
 
 Asynchronously writes data to a file, replacing the file if it already exists.
@@ -5545,6 +5533,7 @@ the file contents.
 [`UV_THREADPOOL_SIZE`]: cli.html#cli_uv_threadpool_size_size
 [`WriteStream`]: #fs_class_fs_writestream
 [`event ports`]: https://illumos.org/man/port_create
+[`filehandle.writeFile()`]: #fs_filehandle_writefile_data_options
 [`fs.Dir`]: #fs_class_fs_dir
 [`fs.Dirent`]: #fs_class_fs_dirent
 [`fs.FSWatcher`]: #fs_class_fs_fswatcher
@@ -5579,6 +5568,7 @@ the file contents.
 [`fs.write(fd, string...)`]: #fs_fs_write_fd_string_position_encoding_callback
 [`fs.writeFile()`]: #fs_fs_writefile_file_data_options_callback
 [`fs.writev()`]: #fs_fs_writev_fd_buffers_position_callback
+[`fsPromises.open()`]: #fs_fspromises_open_path_flags_mode
 [`fsPromises.opendir()`]: #fs_fspromises_opendir_path_options
 [`inotify(7)`]: http://man7.org/linux/man-pages/man7/inotify.7.html
 [`kqueue(2)`]: https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2