fs: add FSReqPromise

fs: add FileHandle object fd wrapper
The `node::fs::FileHandle` object wraps a file descriptor and will close it on garbage collection along with a process warning. The intent is to prevent (as much as possible) file descriptors from being leaked if the user does not close them explicitly.
The `node::fs::FileHandle` object wraps a file descriptor and will close it on garbage collection along with a process warning. The intent is to prevent (as much as possible) file descriptors from being leaked if the user does not close them explicitly.
nodejs · jasnell · jasnell · Jan 22, 2018 · nodejs-github-bot · Jan 22, 2018
diff --git a/doc/api/fs.md b/doc/api/fs.md
+`fs.promises.open()` method.
+
+Unlike the callback-based `fs.fstat()`, `fs.fchown()`, `fs.fchmod()`,
+`fs.ftruncate()`, `fs.read()`, and `fs.write()`, operations -- all of which
diff --git a/doc/api/fs.md b/doc/api/fs.md
+-->
+
+* Returns: {Promise} A `Promise` that will be resolved once the underlying
+  file descriptor is closed, or will reject if an error occurs while closing.
diff --git a/doc/api/fs.md b/doc/api/fs.md
+* `fs.constants.X_OK` - `path` can be executed by the calling process. This has
+no effect on Windows (will behave like `fs.constants.F_OK`).
+
+If the accessible check is successful, the `Promise` is resolved with no
diff --git a/doc/api/fs.md b/doc/api/fs.md
+  * `encoding` {string|null} **Default:** `'utf8'`
+  * `mode` {integer} **Default:** `0o666`
+  * `flag` {string} **Default:** `'a'`
+
diff --git a/doc/api/fs.md b/doc/api/fs.md
+
+The `file` may be specified as a `FileHandle` that has been opened
+for appending (using `fs.promises.open()`). The `FileHandle` will
+not be closed automatically.
diff --git a/doc/api/fs.md b/doc/api/fs.md
+* Returns: {Promise}
+
+Changes the ownership of a file then resolves the `Promise` with no arguments
+upon success
diff --git a/doc/api/fs.md b/doc/api/fs.md
+
+Asynchronously copies `src` to `dest`. By default, `dest` is overwritten if it
+already exists. No arguments other than a possible exception are given to the
+callback function. Node.js makes no guarantees about the atomicity of the copy
diff --git a/doc/api/fs.md b/doc/api/fs.md
+Truncates the file represented by `filehandle` then resolves the `Promise`
+with no arguments upon success.
+
+If the file referred to by the file descriptor was larger than `len` bytes, only
diff --git a/doc/api/fs.md b/doc/api/fs.md
+If the file referred to by the file descriptor 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
diff --git a/doc/api/fs.md b/doc/api/fs.md
+* `mtime` {number|string|Date}
+* Returns: {Promise}
+
+Change the file system timestamps of the object referenced by the supplied file
diff --git a/doc/api/fs.md b/doc/api/fs.md
+* `path` {string|Buffer|URL}
+* Returns: {Promise}
+
+Asynchronous lstat(2). The `Promise` is resolved with the [`fs.Stats'][] object
diff --git a/doc/api/fs.md b/doc/api/fs.md
+
+*Note*: The behavior of `fs.promises.open()` is platform-specific for some
+flags. As such, opening a directory on macOS and Linux with the `'a+'` flag -
+see example below - will return an error. In contrast, on Windows and FreeBSD,
diff --git a/doc/api/fs.md b/doc/api/fs.md
+
+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 referece to the passed in `buffer` argument.
diff --git a/doc/api/fs.md b/doc/api/fs.md
+  * `encoding` {string} **Default:** `'utf8'`
+* Returns: {Promise}
+
+Reads the contents of a directory then resolves with `Promise` with an array
diff --git a/doc/api/fs.md b/doc/api/fs.md
+
+The optional `options` argument can be a string specifying an encoding, or an
+object with an `encoding` property specifying the character encoding to use for
+the filenames passed to the callback. If the `encoding` is set to `'buffer'`,
diff --git a/doc/api/fs.md b/doc/api/fs.md
+* `options` {Object|string}
+  * `encoding` {string|null} **Default:** `null`
+  * `flag` {string} **Default:** `'r'`
+
diff --git a/doc/api/fs.md b/doc/api/fs.md
+returned.
+
+Any specified `FileHandle` has to support reading. If a `FileHandle` is
+specified as the `path`, it will not be closed automatically.
diff --git a/doc/api/fs.md b/doc/api/fs.md
+
+The optional `options` argument can be a string specifying an encoding, or an
+object with an `encoding` property specifying the character encoding to use for
+the link path passed to the callback. If the `encoding` is set to `'buffer'`,
diff --git a/doc/api/fs.md b/doc/api/fs.md
+* Returns: {Promise}
+
+Determines the actual location of `path` using the same semantics as the
+`fs.realpath.native()` function then resolves the `Promise` with the resolved
diff --git a/doc/api/fs.md b/doc/api/fs.md
+
+The optional `options` argument can be a string specifying an encoding, or an
+object with an `encoding` property specifying the character encoding to use for
+the path passed to the callback. If the `encoding` is set to `'buffer'`,
diff --git a/doc/api/fs.md b/doc/api/fs.md
+no arguments upon success.
+
+Using `fs.promises.rmdir()` on a file (not a directory) results in the
+`Promise` being reject with an `ENOENT` error on Windows and an `ENOTDIR` error
diff --git a/doc/api/fs.md b/doc/api/fs.md
+- Values can be either numbers representing Unix epoch time, `Date`s, or a
+  numeric string like `'123456789.0'`.
+- If the value can not be converted to a number, or is `NaN`, `Infinity` or
+  `-Infinity`, a `Error` will be thrown.
diff --git a/doc/api/fs.md b/doc/api/fs.md
+
+The `Promise` is resolved with an object containing a `bytesWritten` property
+identifying the number of bytes written, and a `buffer` property containing
+the a reference to the `buffer` written.
diff --git a/doc/api/fs.md b/doc/api/fs.md
+should be written. If `typeof position !== 'number'`, the data will be written
+at the current position. See pwrite(2).
+
+The callback will be given three arguments `(err, bytesWritten, buffer)` where
diff --git a/doc/api/fs.md b/doc/api/fs.md
+The callback will be given three arguments `(err, bytesWritten, buffer)` where
+`bytesWritten` specifies how many _bytes_ were written from `buffer`.
+
+Note that it is unsafe to use `fs.write` multiple times on the same file
diff --git a/doc/api/fs.md b/doc/api/fs.md
+`bytesWritten` specifies how many _bytes_ were written from `buffer`.
+
+Note that it is unsafe to use `fs.write` multiple times on the same file
+without waiting for the `Promise` to resolve. For this scenario,
diff --git a/doc/api/fs.md b/doc/api/fs.md
+  * `encoding` {string|null} **Default:** `'utf8'`
+  * `mode` {integer} **Default:** `0o666`
+  * `flag` {string} **Default:** `'w'`
+
diff --git a/doc/api/fs.md b/doc/api/fs.md
+The `encoding` option is ignored if `data` is a buffer. It defaults
+to `'utf8'`.
+
+If `options` is a string, then it specifies the encoding. Example:
diff --git a/doc/api/fs.md b/doc/api/fs.md
+
+Any specified `FileHandle` has to support writing.
+
+It is unsafe to use `fs.writeFile` multiple times on the same file without
diff --git a/doc/api/fs.md b/doc/api/fs.md
+waiting for the `Promise` to be resolved (or rejected).
+
+If a `FileHandle` is specified as the `file`, it will not be closed
+automatically.
diff --git a/doc/api/fs.md b/doc/api/fs.md
@@ -3446,6 +4203,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's
 [`AHAFS`]: https://www.ibm.com/developerworks/aix/library/au-aix_event_infrastructure/
 [`Buffer.byteLength`]: buffer.html#buffer_class_method_buffer_bytelength_string_encoding
 [`Buffer`]: buffer.html#buffer_buffer
+[`FileHandle`]: #fs_class_filehandle
diff --git a/lib/fs.js b/lib/fs.js
+}
+
+fs.promises = {
+  async access(path, mode = fs.F_OK) {
diff --git a/src/env.cc b/src/env.cc
       cb.cb_(this, cb.data_);
+      if (try_catch.HasCaught()) {
diff --git a/src/node_file.cc b/src/node_file.cc
+  int ret = uv_fs_close(env()->event_loop(), &req, fd_, nullptr);
+  uv_fs_req_cleanup(&req);
+
+  struct err_detail { int ret; int fd; };
diff --git a/src/node_file.cc b/src/node_file.cc
+    AsyncCall(env, args, "open", UTF8, AfterOpenFileHandle,
+              uv_fs_open, *path, flags, mode);
+  } else {
+    SYNC_CALL(open, *path, *path, flags, mode)
diff --git a/src/node_file.h b/src/node_file.h
+
+ private:
+  bool finished_ = false;
+  double statFields_[14] {};
diff --git a/test/parallel/test-fs-promises.js b/test/parallel/test-fs-promises.js
+    }
+
+    const base = path.resolve(common.tmpDir, 'FOO');
+    assert(
diff --git a/src/env.cc b/src/env.cc
       cb.cb_(this, cb.data_);
+      if (try_catch.HasCaught()) {
+        FatalException(isolate(), try_catch);
+      }
diff --git a/src/node_file.cc b/src/node_file.cc
+
+  // If the close was successful, we still want to emit a process warning
+  // to notify that the file descriptor was gc'd. We want to be noisy about
+  // this because not explicitly closing the garbage collector is a bug.
diff --git a/src/node_file.cc b/src/node_file.cc
+  resolver->Reject(env()->context(), reason);
+}
+
+FileHandle* FileHandle::CloseReq::fd() {
diff --git a/src/node_file.cc b/src/node_file.cc
-FSReqAfterScope::FSReqAfterScope(FSReqWrap* wrap, uv_fs_t* req)
+void FSReqPromise::Resolve(Local<Value> value) {
+  finished_ = true;
+  InternalCallbackScope callback_scope(this);
diff --git a/src/node_file.cc b/src/node_file.cc
+                    env()->promise_string()).ToLocalChecked();
+  CHECK(val->IsPromise());
+  Local<Promise> promise = val.As<Promise>();
+  Local<Promise::Resolver> resolver = promise.As<Promise::Resolver>();
diff --git a/src/node_file.cc b/src/node_file.cc
@@ -190,15 +380,15 @@ bool FSReqAfterScope::Proceed() {
 }
 
 void AfterNoArgs(uv_fs_t* req) {
-  FSReqWrap* req_wrap = static_cast<FSReqWrap*>(req->data);
+  FSReqBase* req_wrap = static_cast<FSReqBase*>(req->data);
diff --git a/src/node_file.cc b/src/node_file.cc
 
 #define SYNC_RESULT err
 
+inline FSReqBase* GetReqWrap(Environment* env, const Local<Value>& value) {
diff --git a/src/node_file.h b/src/node_file.h
+
+ private:
+  bool finished_ = false;
+  AliasedBuffer<double, v8::Float64Array> stats_field_array_;
diff --git a/doc/api/fs.md b/doc/api/fs.md
+added: REPLACEME
+-->
+
+* `file` {string|Buffer|[FileHandle][]} filename or `FileHandle`
diff --git a/doc/api/fs.md b/doc/api/fs.md
+deprecated: REPLACEME
+-->
+
+* `path` {string|Buffer}
diff --git a/doc/api/fs.md b/doc/api/fs.md
+deprecated: REPLACEME
+-->
+
+* `path` {string|Buffer}
diff --git a/doc/api/fs.md b/doc/api/fs.md
+added: REPLACEME
+-->
+
+* `path` {string|Buffer}
diff --git a/doc/api/fs.md b/doc/api/fs.md
+added: REPLACEME
+-->
+
+* `file` {string|Buffer|[FileHandle][]} filename or `FileHandle`
diff --git a/doc/api/fs.md b/doc/api/fs.md
+The `fs.promises` API provides an alternative set of asynchronous file system
+methods that return `Promise` objects rather than using callbacks. The
+API is accessible via `fs.promises()` (for example:
+`const fsp = require('fs').promises()`).
diff --git a/doc/api/fs.md b/doc/api/fs.md
+  .catch(() => console.log('The file could not be copied'));
+```
+
+### fs.promises().fchmod(filehandle, mode)
diff --git a/src/node_file.cc b/src/node_file.cc
+      stats_field_array_(env->isolate(), 14) {
+  auto resolver = Promise::Resolver::New(env->context()).ToLocalChecked();
+  object()->Set(env->context(), env->promise_string(),
+                resolver.As<Promise>()).FromJust();
diff --git a/benchmark/fs/bench-stat-promise.js b/benchmark/fs/bench-stat-promise.js
+const fs = require('fs');
+
+const bench = common.createBenchmark(main, {
+  n: [20e4],