child_process: add promises API by Felipeness · Pull Request #62337 · nodejs/node · GitHub

Summary

Add node:child_process/promises module providing promise-based exec() and execFile() functions.

Delegates to the existing customPromiseExecFunction in child_process.js via promisify(), following the same pattern as fs/promises, dns/promises, and stream/promises.

Fixes: #49904

Suggested change

      
            function execFile(file, args, options) {
          
            async function execFile(file, args, options) {

Hey @aduh95, these suggestions were on the previous version — I've since rewritten the implementation to delegate to the existing \ via \ / , so the module is now just 9 lines. The force-push landed after your review, sorry for the confusion!

Suggested change

      
            function exec(command, options) {
          
            async function exec(command, options) {

Same as above — this was on the old version. The current implementation delegates via promisify(exec) so this function no longer exists. Sorry for the confusing force-push timing!

Suggested change

      
              exec(...common.escapePOSIXShell`"${process.execPath}" -e "${failingCodeWithStdoutErr}"`)
          
                .catch(common.mustCall((err) => {
          
                  assert.strictEqual(err.code, 1);
          
                  assert.strictEqual(err.stdout, '42\n');
          
                  assert.strictEqual(err.stderr, '43\n');
          
                }));
          
              assert.rejects(exec(...common.escapePOSIXShell`"${process.execPath}" -e "${failingCodeWithStdoutErr}"`),
          
                {
          
                  code: 1,
          
                  stdout: '42\n',
          
                  stderr: '43\n',
          
                }).then(common.mustCall());

Applied, much cleaner — thanks!

Suggested change

      
              execFile(process.execPath, { timeout: 5000 })
          
                .catch(common.mustCall(() => {
          
                  // Expected to fail (no script), but should not throw synchronously.
          
                }));
          
              assert.rejects(execFile(process.execPath, { timeout: 5 }), {
          
                code: 'TODO',
          
              });

Applied! Used assert.rejects with { killed: true } — the timeout path kills the child with SIGTERM and sets killed: true on the error, so that seemed like the right property to assert on.

Suggested change

      
                  assert.strictEqual(typeof result.stdout, 'string');
          
                  assert.strictEqual(typeof result.stderr, 'string');
          
                  assert.strictEqual(result.stdout, 'hello\n');
          
                  assert.strictDeepEqual(result, {
          
                    stdout: 'hello\n',
          
                    stderr: '',
          
                  });

Applied, makes the assertions much tighter.

Suggested change

      
                  assert(Buffer.isBuffer(result.stdout));
          
                  assert(Buffer.isBuffer(result.stderr));
          
                  assert.strictEqual(result.stdout.toString(), 'hello\n');
          
                  assert.strictDeepEqual(result, {
          
                    stderr: Buffer.from(),
          
                    stdout: Buffer.from('hello\n'),
          
                  });

Applied!

Suggested change

      
              execFile(
          
                process.execPath,
          
                ['-e', "console.log('a'.repeat(100))"],
          
                { maxBuffer: 10 },
          
              ).catch(common.mustCall((err) => {
          
                assert(err instanceof RangeError);
          
                assert.strictEqual(err.code, 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER');
          
              }));
          
              assert.rejects(execFile(
          
                process.execPath,
          
                ['-e', "console.log('a'.repeat(100))"],
          
                { maxBuffer: 10 },
          
              ), {
          
                name: 'RangeError',
          
                code: 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
          
              }).then(common.mustCall());

Applied, cleaner structure.

I don't think this is needed

Suggested change

      
            // Test: module can be loaded with node: scheme.
          
            {
          
              const promises = require('node:child_process/promises');
          
              assert.strictEqual(typeof promises.exec, 'function');
          
              assert.strictEqual(typeof promises.execFile, 'function');
          
            }

If we really want it, we should be checking for strict equality.

Suggested change

      
            // Test: module can be loaded with node: scheme.
          
            {
          
              const promises = require('node:child_process/promises');
          
              assert.strictEqual(typeof promises.exec, 'function');
          
              assert.strictEqual(typeof promises.execFile, 'function');
          
            }
          
            assert.strictEqual(require('node:child_process/promises'), require('child_process/promises'));

Good call — replaced it with the strict equality check between node: and non-prefixed require, which is more useful.

I'm not sure we should expose that, I wonder if folks who want access to ChildProcess would not already be using spawn

That's a fair point. The .child property is inherited from util.promisify(exec) — it's already part of the existing customPromiseExecFunction in child_process.js, so it's not something we explicitly add. Since it's already there and documented, I kept the test, but I removed the .child assertions from this file for now. Happy to add them back or remove the property from the docs entirely if you think it shouldn't be surfaced in the promises API. What do you think?

What's up with your last commit?

Hey @aduh95, sorry about that! I realized the original implementation was a 415-line reimplementation of logic that already exists in child_process.js (customPromiseExecFunction). I rewrote it to delegate via promisify(exec) / promisify(execFile), which brings the module down to 9 lines and inherits all the existing error handling, AbortSignal support, and .child property for free. The force-push landed right as you were reviewing — bad timing, sorry!

Did you rewrite it or are you using an agent to do it for you?

I wrote the core implementation and did the analysis myself — the rewrite from reimplementation to delegation was my call after reviewing how fs/promises and dns/promises work internally. I do use Claude Code as a coding assistant, mainly because English isn't my native language (I'm Brazilian) and it helps me write clearer commit messages, PR descriptions, and adapt to the project's code style. The actual design decisions and code review are mine — I wouldn't submit something I don't understand.

I mean you did submit a PR saying in bold "Not a thin util.promisify() wrapper" to override the entire implementation with a thin util.promisify() wrapper in the next commit, which is not a good look

Yes, fair enough, it's entirely my fault. The description was written for the original 415-line version, and I simply forgot to update it after switching to the delegation approach. It definitely doesn't look good when the bold text says the opposite of what the code does. Thanks for pointing it out.

The description being outdated is one thing, but usually when folks have identified a key point (e.g. the implementation should not be a thin promisify layer), they usually stay consistent with that. Usually humans do not end up re-implementing 415 lines of code by accident, and if they realize that the existing util.promisify does the job, they won't bother open a PR, because what's the point? Wasting everyone's time? If you look like a bot, you risk being treated as such, see nodejs/admin@8b746bc

nodejs-github-bot added child_process Issues and PRs related to the child_process subsystem. needs-ci PRs that need a full CI run. labels Mar 19, 2026

aduh95 reviewed Mar 19, 2026

View reviewed changes

feat(child_process): add promises API via delegation

94ab73c

Felipeness force-pushed the fix/child-process-promises branch from f583b4b to 94ab73c Compare March 19, 2026 15:36

fix(child_process): apply review feedback from aduh95

6a758b9

aduh95 closed this Mar 20, 2026

cjihrig mentioned this pull request Mar 22, 2026

test_runner: add statement coverage support #62340

Closed

6 tasks

+               * }} [options]
+               * @returns {Promise<{ stdout: string | Buffer, stderr: string | Buffer }>}
+               */
+              function execFile(file, args, options) {

+               * }} [options]
+               * @returns {Promise<{ stdout: string | Buffer, stderr: string | Buffer }>}
+               */
+              function exec(command, options) {

	function execFile(file, args, options) {
	async function execFile(file, args, options) {

	function exec(command, options) {
	async function exec(command, options) {

+              {
+                const promise = exec(...common.escapePOSIXShell`"${process.execPath}" -p 42`);
+                assert(promise.child instanceof child_process.ChildProcess);

child_process: add promises API by Felipeness · Pull Request #62337 · nodejs/node · GitHub

Uh oh!

Uh oh!

child_process: add promises API - #62337

child_process: add promises API#62337Felipeness wants to merge 2 commits intonodejs:mainnodejs/node:mainfrom Felipeness:fix/child-process-promisesFelipeness/node:fix/child-process-promisesCopy head branch name to clipboard

Conversation

Felipeness commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aduh95 commented Mar 19, 2026

Uh oh!

Felipeness commented Mar 19, 2026

Uh oh!

aduh95 commented Mar 19, 2026

Uh oh!

Felipeness commented Mar 19, 2026

Uh oh!

aduh95 commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Felipeness commented Mar 19, 2026

Uh oh!

aduh95 commented Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

child_process: add promises API#62337
Felipeness wants to merge 2 commits into
nodejs:mainfrom
Felipeness:fix/child-process-promises

Felipeness commented Mar 19, 2026 •
edited
Loading

aduh95 commented Mar 19, 2026 •
edited
Loading