From d7f48262c6c7f3bfe9f306c4a72a04466e31304b Mon Sep 17 00:00:00 2001
From: Chiang Fong Lee <myself@cflee.net>
Date: Thu, 5 Jun 2025 00:41:25 +0800
Subject: [PATCH] doc: fix return types for sync methods

For the sync methods spawnSync(), execSync() and execFileSync(), when
the stdio option is set to anything other than 'pipe', the stdout and
stderr returned from the C++ code will be null, and not a string or
Buffer as currently documented.
---
 doc/api/child_process.md | 12 ++++++++----
 lib/child_process.js     |  8 ++++----
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/doc/api/child_process.md b/doc/api/child_process.md
index ba7cc2af6bfb14..ff2d6bbdf3ccc1 100644
--- a/doc/api/child_process.md
+++ b/doc/api/child_process.md
@@ -1196,7 +1196,8 @@ changes:
     `'/bin/sh'` on Unix, and `process.env.ComSpec` on Windows. A different
     shell can be specified as a string. See [Shell requirements][] and
     [Default Windows shell][]. **Default:** `false` (no shell).
-* Returns: {Buffer|string} The stdout from the command.
+* Returns: {Buffer|string|null} If `stdio` is `'pipe'`, the stdout from the
+  command, otherwise null.
 
 The `child_process.execFileSync()` method is generally identical to
 [`child_process.execFile()`][] with the exception that the method will not
@@ -1323,7 +1324,8 @@ changes:
     **Default:** `'buffer'`.
   * `windowsHide` {boolean} Hide the subprocess console window that would
     normally be created on Windows systems. **Default:** `false`.
-* Returns: {Buffer|string} The stdout from the command.
+* Returns: {Buffer|string|null} If `stdio` is `'pipe'`, the stdout from the
+  command, otherwise null.
 
 The `child_process.execSync()` method is generally identical to
 [`child_process.exec()`][] with the exception that the method will not return
@@ -1407,8 +1409,10 @@ changes:
 * Returns: {Object}
   * `pid` {number} Pid of the child process.
   * `output` {Array} Array of results from stdio output.
-  * `stdout` {Buffer|string} The contents of `output[1]`.
-  * `stderr` {Buffer|string} The contents of `output[2]`.
+  * `stdout` {Buffer|string|null} If `stdio` is `'pipe'`, the contents of
+    `output[1]`, otherwise null.
+  * `stderr` {Buffer|string|null} If `stdio` is `'pipe'`, the contents of
+    `output[2]`, otherwise null.
   * `status` {number|null} The exit code of the subprocess, or `null` if the
     subprocess terminated due to a signal.
   * `signal` {string|null} The signal used to kill the subprocess, or `null` if
diff --git a/lib/child_process.js b/lib/child_process.js
index bba860a78fe20e..b8a576ff47b091 100644
--- a/lib/child_process.js
+++ b/lib/child_process.js
@@ -856,8 +856,8 @@ function spawn(file, args, options) {
  * @returns {{
  *   pid: number;
  *   output: Array;
- *   stdout: Buffer | string;
- *   stderr: Buffer | string;
+ *   stdout: Buffer | string | null;
+ *   stderr: Buffer | string | null;
  *   status: number | null;
  *   signal: string | null;
  *   error: Error;
@@ -945,7 +945,7 @@ function checkExecSyncError(ret, args, cmd) {
  *   windowsHide?: boolean;
  *   shell?: boolean | string;
  *   }} [options]
- * @returns {Buffer | string}
+ * @returns {Buffer | string | null}
  */
 function execFileSync(file, args, options) {
   ({ file, args, options } = normalizeExecFileArgs(file, args, options));
@@ -983,7 +983,7 @@ function execFileSync(file, args, options) {
  *   encoding?: string;
  *   windowsHide?: boolean;
  *   }} [options]
- * @returns {Buffer | string}
+ * @returns {Buffer | string | null}
  */
 function execSync(command, options) {
   const opts = normalizeExecArgs(command, options, null);