fs: support util.promisify for fs.read/fs.write

PR-URL: #12442
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: William Kapke <william.kapke@gmail.com>
Reviewed-By: Timothy Gu <timothygu99@gmail.com>
Reviewed-By: Teddy Katz <teddy.katz@gmail.com>

doc/api/fs.md

@@ -1612,6 +1612,9 @@ If `position` is `null`, data will be read from the current file position.
 
 The callback is given the three arguments, `(err, bytesRead, buffer)`.
 
+If this method is invoked as its [`util.promisify()`][]ed version, it returns
+a Promise for an object with `bytesRead` and `buffer` properties.
+
 ## fs.readdir(path[, options], callback)
 <!-- YAML
 added: v0.1.8
@@ -2393,8 +2396,11 @@ an integer specifying the number of bytes to write.
 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, written, buffer)` where
-`written` specifies how many _bytes_ were written from `buffer`.
+The callback will be given three arguments `(err, bytesWritten, buffer)` where
+`bytesWritten` specifies how many _bytes_ were written from `buffer`.
+
+If this method is invoked as its [`util.promisify()`][]ed version, it returns
+a Promise for an object with `bytesWritten` and `buffer` properties.
 
 Note that it is unsafe to use `fs.write` multiple times on the same file
 without waiting for the callback. For this scenario,
@@ -2810,6 +2816,7 @@ The following constants are meant for use with the [`fs.Stats`][] object's
 [`net.Socket`]: net.html#net_class_net_socket
 [`stat()`]: fs.html#fs_fs_stat_path_callback
 [`util.inspect(stats)`]: util.html#util_util_inspect_object_options
+[`util.promisify()`]: util.html#util_util_promisify_original
 [Caveats]: #fs_caveats
 [Common System Errors]: errors.html#errors_common_system_errors
 [FS Constants]: #fs_fs_constants_1

lib/fs.js

@@ -656,6 +656,9 @@ fs.read = function(fd, buffer, offset, length, position, callback) {
   binding.read(fd, buffer, offset, length, position, req);
 };
 
+Object.defineProperty(fs.read, internalUtil.customPromisifyArgs,
+                      { value: ['bytesRead', 'buffer'], enumerable: false });
+
 fs.readSync = function(fd, buffer, offset, length, position) {
   if (length === 0) {
     return 0;
@@ -706,6 +709,9 @@ fs.write = function(fd, buffer, offset, length, position, callback) {
   return binding.writeString(fd, buffer, offset, length, req);
 };
 
+Object.defineProperty(fs.write, internalUtil.customPromisifyArgs,
+                      { value: ['bytesWritten', 'buffer'], enumerable: false });
+
 // usage:
 //  fs.writeSync(fd, buffer[, offset[, length[, position]]]);
 // OR

test/parallel/test-fs-promisified.js

@@ -0,0 +1,31 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const { promisify } = require('util');
+
+common.crashOnUnhandledRejection();
+
+const read = promisify(fs.read);
+const write = promisify(fs.write);
+
+{
+  const fd = fs.openSync(__filename, 'r');
+  read(fd, Buffer.alloc(1024), 0, 1024, null).then(common.mustCall((obj) => {
+    assert.strictEqual(typeof obj.bytesRead, 'number');
+    assert(obj.buffer instanceof Buffer);
+    fs.closeSync(fd);
+  }));
+}
+
+common.refreshTmpDir();
+{
+  const filename = path.join(common.tmpDir, 'write-promise.txt');
+  const fd = fs.openSync(filename, 'w');
+  write(fd, Buffer.from('foobar')).then(common.mustCall((obj) => {
+    assert.strictEqual(typeof obj.bytesWritten, 'number');
+    assert.strictEqual(obj.buffer.toString(), 'foobar');
+    fs.closeSync(fd);
+  }));
+}