util: add util.promisify()

doc/api/child_process.md

@@ -214,6 +214,23 @@ child runs longer than `timeout` milliseconds.
 *Note: Unlike the exec(3) POSIX system call, `child_process.exec()` does not
 replace the existing process and uses a shell to execute the command.*
 
+If this method is invoked as its [`util.promisify()`][]ed version, it returns
+a Promise for an object with `stdout` and `stderr` properties.
+
+For example:
+
+```js
+const util = require('util');
+const exec = util.promisify(require('child_process').exec);
+
+async function lsExample() {
+  const {stdout, stderr} = await exec('ls');
+  console.log('stdout:', stdout);
+  console.log('stderr:', stderr);
+}
+lsExample();
+```
+
 ### child_process.execFile(file[, args][, options][, callback])
 <!-- YAML
 added: v0.1.91
@@ -263,6 +280,19 @@ can be used to specify the character encoding used to decode the stdout and
 stderr output. If `encoding` is `'buffer'`, or an unrecognized character
 encoding, `Buffer` objects will be passed to the callback instead.
 
+If this method is invoked as its [`util.promisify()`][]ed version, it returns
+a Promise for an object with `stdout` and `stderr` properties.
+
+```js
+const util = require('util');
+const execFile = util.promisify(require('child_process').execFile);
+async function getVersion() {
+  const {stdout} = await execFile('node', ['--version']);
+  console.log(stdout);
+}
+getVersion();
+```
+
 ### child_process.fork(modulePath[, args][, options])
 <!-- YAML
 added: v0.5.0
@@ -1269,4 +1299,5 @@ to `stdout` although there are only 4 characters.
 [`process.on('message')`]: process.html#process_event_message
 [`process.send()`]: process.html#process_process_send_message_sendhandle_options_callback
 [`stdio`]: #child_process_options_stdio
+[`util.promisify()`]: util.html#util_util_promisify_original
 [synchronous counterparts]: #child_process_synchronous_process_creation

doc/api/dns.md

@@ -123,6 +123,10 @@ dns.lookup('example.com', options, (err, addresses) =>
 // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
 ```
 
+If this method is invoked as its [`util.promisify()`][]ed version, and `all`
+is not set to `true`, it returns a Promise for an object with `address` and
+`family` properties.
+
 ### Supported getaddrinfo flags
 
 The following flags can be passed as hints to [`dns.lookup()`][].
@@ -163,6 +167,9 @@ dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
 });
 ```
 
+If this method is invoked as its [`util.promisify()`][]ed version, it returns a
+Promise for an object with `hostname` and `service` properties.
+
 ## dns.resolve(hostname[, rrtype], callback)
 <!-- YAML
 added: v0.1.27
@@ -528,3 +535,4 @@ uses. For instance, _they do not use the configuration from `/etc/hosts`_.
 [Implementation considerations section]: #dns_implementation_considerations
 [supported `getaddrinfo` flags]: #dns_supported_getaddrinfo_flags
 [the official libuv documentation]: http://docs.libuv.org/en/latest/threadpool.html
+[`util.promisify()`]: util.html#util_util_promisify_original

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

doc/api/timers.md

@@ -85,6 +85,27 @@ next event loop iteration.
 
 If `callback` is not a function, a [`TypeError`][] will be thrown.
 
+*Note*: This method has a custom variant for promises that is available using
+[`util.promisify()`][]:
+
+```js
+const util = require('util');
+const setImmediatePromise = util.promisify(setImmediate);
+
+setImmediatePromise('foobar').then((value) => {
+  // value === 'foobar' (passing values is optional)
+  // This is executed after all I/O callbacks.
+});
+
+// or with async function
+async function timerExample() {
+  console.log('Before I/O callbacks');
+  await setImmediatePromise();
+  console.log('After I/O callbacks');
+}
+timerExample();
+```
+
 ### setInterval(callback, delay[, ...args])
 <!-- YAML
 added: v0.0.1
@@ -126,12 +147,28 @@ will be set to `1`.
 
 If `callback` is not a function, a [`TypeError`][] will be thrown.
 
+*Note*: This method has a custom variant for promises that is available using
+[`util.promisify()`][]:
+
+```js
+const util = require('util');
+const setTimeoutPromise = util.promisify(setTimeout);
+
+setTimeoutPromise(40, 'foobar').then((value) => {
+  // value === 'foobar' (passing values is optional)
+  // This is executed after about 40 milliseconds.
+});
+```
+
 ## Cancelling Timers
 
 The [`setImmediate()`][], [`setInterval()`][], and [`setTimeout()`][] methods
 each return objects that represent the scheduled timers. These can be used to
 cancel the timer and prevent it from triggering.
 
+It is not possible to cancel timers that were created using the promisified
+variants of [`setImmediate()`][], [`setTimeout()`][].
+
 ### clearImmediate(immediate)
 <!-- YAML
 added: v0.9.1
@@ -168,4 +205,5 @@ Cancels a `Timeout` object created by [`setTimeout()`][].
 [`setImmediate()`]: timers.html#timers_setimmediate_callback_args
 [`setInterval()`]: timers.html#timers_setinterval_callback_delay_args
 [`setTimeout()`]: timers.html#timers_settimeout_callback_delay_args
+[`util.promisify()`]: util.html#util_util_promisify_original
 [the Node.js Event Loop]: https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick

doc/api/util.md

@@ -399,6 +399,86 @@ util.inspect.defaultOptions.maxArrayLength = null;
 console.log(arr); // logs the full array
 ```
 
+## util.promisify(original)
+<!-- YAML
+added: REPLACEME
+-->
+
+* `original` {Function}
+
+Takes a function following the common Node.js callback style, i.e. taking a
+`(err, value) => ...` callback as the last argument, and returns a version
+that returns promises.
+
+For example:
+
+```js
+const util = require('util');
+const fs = require('fs');
+
+const stat = util.promisify(fs.stat);
+stat('.').then((stats) => {
+  // Do something with `stats`
+}).catch((error) => {
+  // Handle the error.
+});
+```
+
+Or, equivalently using `async function`s:
+
+```js
+const util = require('util');
+const fs = require('fs');
+
+const stat = util.promisify(fs.stat);
+
+async function callStat() {
+  const stats = await stat('.');
+  console.log(`This directory is owned by ${stats.uid}`);
+}
+```
+
+If there is an `original[util.promisify.custom]` property present, `promisify`
+will return its value, see [Custom promisified functions][].
+
+`promisify()` assumes that `original` is a function taking a callback as its
+final argument in all cases, and the returned function will result in undefined
+behaviour if it does not.
+
+### Custom promisified functions
+
+Using the `util.promisify.custom` symbol one can override the return value of
+[`util.promisify()`][]:
+
+```js
+const util = require('util');
+
+function doSomething(foo, callback) {
+  // ...
+}
+
+doSomething[util.promisify.custom] = function(foo) {
+  return getPromiseSomehow();
+};
+
+const promisified = util.promisify(doSomething);
+console.log(promisified === doSomething[util.promisify.custom]);
+  // prints 'true'
+```
+
+This can be useful for cases where the original function does not follow the
+standard format of taking an error-first callback as the last argument.
+
+### util.promisify.custom
+<!-- YAML
+added: REPLACEME
+-->
+
+* {symbol}
+
+A Symbol that can be used to declare custom promisified variants of functions,
+see [Custom promisified functions][].
+
 ## Deprecated APIs
 
 The following APIs have been deprecated and should no longer be used. Existing
@@ -878,7 +958,9 @@ Deprecated predecessor of `console.log`.
 [`console.error()`]: console.html#console_console_error_data_args
 [`console.log()`]: console.html#console_console_log_data_args
 [`util.inspect()`]: #util_util_inspect_object_options
+[`util.promisify()`]: #util_util_promisify_original
 [Custom inspection functions on Objects]: #util_custom_inspection_functions_on_objects
 [Customizing `util.inspect` colors]: #util_customizing_util_inspect_colors
+[Custom promisified functions]: #util_custom_promisified_functions
 [constructor]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor
 [semantically incompatible]: https://github.com/nodejs/node/issues/4179

lib/child_process.js

@@ -22,7 +22,9 @@
 'use strict';
 
 const util = require('util');
-const { deprecate, convertToValidSignal } = require('internal/util');
+const {
+  deprecate, convertToValidSignal, customPromisifyArgs
+} = require('internal/util');
 const debug = util.debuglog('child_process');
 
 const uv = process.binding('uv');
@@ -138,6 +140,9 @@ exports.exec = function(command /*, options, callback*/) {
                           opts.callback);
 };
 
+Object.defineProperty(exports.exec, customPromisifyArgs,
+                      { value: ['stdout', 'stderr'], enumerable: false });
+
 
 exports.execFile = function(file /*, args, options, callback*/) {
   var args = [];
@@ -333,6 +338,9 @@ exports.execFile = function(file /*, args, options, callback*/) {
   return child;
 };
 
+Object.defineProperty(exports.execFile, customPromisifyArgs,
+                      { value: ['stdout', 'stderr'], enumerable: false });
+
 const _deprecatedCustomFds = deprecate(
   function deprecateCustomFds(options) {
     options.stdio = options.customFds.map(function mapCustomFds(fd) {

lib/dns.js

@@ -26,6 +26,7 @@ const util = require('util');
 const cares = process.binding('cares_wrap');
 const uv = process.binding('uv');
 const internalNet = require('internal/net');
+const { customPromisifyArgs } = require('internal/util');
 
 const GetAddrInfoReqWrap = cares.GetAddrInfoReqWrap;
 const GetNameInfoReqWrap = cares.GetNameInfoReqWrap;
@@ -189,6 +190,9 @@ function lookup(hostname, options, callback) {
   return req;
 }
 
+Object.defineProperty(lookup, customPromisifyArgs,
+                      { value: ['address', 'family'], enumerable: false });
+
 
 function onlookupservice(err, host, service) {
   if (err)
@@ -228,6 +232,9 @@ function lookupService(host, port, callback) {
   return req;
 }
 
+Object.defineProperty(lookupService, customPromisifyArgs,
+                      { value: ['hostname', 'service'], enumerable: false });
+
 
 function onresolve(err, result, ttls) {
   if (ttls && this.ttl)

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