child_process: support promisified exec(File)

Author: Benjamin Gruenbaum <[email protected]> Author: Anna Henningsen <[email protected]> PR-URL: #12442 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Myles Borins <[email protected]> Reviewed-By: Evan Lucas <[email protected]> Reviewed-By: William Kapke <[email protected]> Reviewed-By: Timothy Gu <[email protected]> Reviewed-By: Teddy Katz <[email protected]>

Author: addaleax

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
+constutil=require('util');
+constexec=util.promisify(require('child_process').exec);
+
+asyncfunctionlsExample(){
+const{stdout, stderr} =awaitexec('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
+constutil=require('util');
+constexecFile=util.promisify(require('child_process').execFile);
+asyncfunctiongetVersion(){
+const{stdout} =awaitexecFile('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

lib/child_process.js

@@ -22,7 +22,9 @@
 'use strict';
 
 constutil=require('util');
-const{ deprecate, convertToValidSignal }=require('internal/util');
+const{
+ deprecate, convertToValidSignal, customPromisifyArgs
+}=require('internal/util');
 constdebug=util.debuglog('child_process');
 
 constuv=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*/){
 varargs=[];
@@ -333,6 +338,9 @@ exports.execFile = function(file /*, args, options, callback*/){
 returnchild;
 };
 
+Object.defineProperty(exports.execFile,customPromisifyArgs,
+{value: ['stdout','stderr'],enumerable: false});
+
 const_deprecatedCustomFds=deprecate(
 functiondeprecateCustomFds(options){
 options.stdio=options.customFds.map(functionmapCustomFds(fd){

test/parallel/test-child-process-promisified.js

@@ -0,0 +1,34 @@
+'use strict';
+constcommon=require('../common');
+constassert=require('assert');
+constchild_process=require('child_process');
+const{ promisify }=require('util');
+
+common.crashOnUnhandledRejection();
+
+constexec=promisify(child_process.exec);
+constexecFile=promisify(child_process.execFile);
+
+{
+exec(`${process.execPath} -p 42`).then(common.mustCall((obj)=>{
+assert.deepStrictEqual(obj,{stdout: '42\n',stderr: ''});
+}));
+}
+
+{
+execFile(process.execPath,['-p','42']).then(common.mustCall((obj)=>{
+assert.deepStrictEqual(obj,{stdout: '42\n',stderr: ''});
+}));
+}
+
+{
+exec('doesntexist').catch(common.mustCall((err)=>{
+assert(err.message.includes('doesntexist'));
+}));
+}
+
+{
+execFile('doesntexist',['-p','42']).catch(common.mustCall((err)=>{
+assert(err.message.includes('doesntexist'));
+}));
+}