feat(unstable): rework Deno.Command (#16812)

Refactors the `Deno.Command` class to not handle any state, but only being an intermediary to calling its methods, and as such any methods and properties besides `output`, `outputSync` & `spawn` have been removed. Interracting with a `spawn`ed subprocess now works by using the methods and properties on the returned class of the `spawn` method.

1 files changed, 24 insertions, 12 deletions

diff --git a/cli/tsc/dts/lib.deno.unstable.d.ts b/cli/tsc/dts/lib.deno.unstable.d.ts
index eaa40abc5..ce609736b 100644
--- a/cli/tsc/dts/lib.deno.unstable.d.ts
+++ b/cli/tsc/dts/lib.deno.unstable.d.ts
@@ -1639,14 +1639,14 @@ declare namespace Deno {
    *   ],
    *   stdin: "piped",
    * });
-   * command.spawn();
+   * const child = command.spawn();
    *
    * // open a file and pipe the subprocess output to it.
-   * command.stdout.pipeTo(Deno.openSync("output").writable);
+   * child.stdout.pipeTo(Deno.openSync("output").writable);
    *
    * // manually close stdin
-   * command.stdin.close();
-   * const status = await command.status;
+   * child.stdin.close();
+   * const status = await child.status;
    * ```
    *
    * ```ts
@@ -1678,13 +1678,6 @@ declare namespace Deno {
    * @category Sub Process
    */
   export class Command {
-    get stdin(): WritableStream<Uint8Array>;
-    get stdout(): ReadableStream<Uint8Array>;
-    get stderr(): ReadableStream<Uint8Array>;
-    readonly pid: number;
-    /** Get the status of the child process. */
-    readonly status: Promise<CommandStatus>;
-
     constructor(command: string | URL, options?: CommandOptions);
     /**
      * Executes the {@linkcode Deno.Command}, waiting for it to finish and
@@ -1711,8 +1704,27 @@ declare namespace Deno {
     /**
      * Spawns a streamable subprocess, allowing to use the other methods.
      */
-    spawn(): void;
+    spawn(): ChildProcess;
+  }
+
+  /** **UNSTABLE**: New API, yet to be vetted.
+   *
+   * The interface for handling a child process returned from
+   * {@linkcode Deno.Command.spawn}.
+   *
+   * @category Sub Process
+   */
+  export class ChildProcess {
+    get stdin(): WritableStream<Uint8Array>;
+    get stdout(): ReadableStream<Uint8Array>;
+    get stderr(): ReadableStream<Uint8Array>;
+    readonly pid: number;
+    /** Get the status of the child. */
+    readonly status: Promise<CommandStatus>;
 
+    /** Waits for the child to exit completely, returning all its output and
+     * status. */
+    output(): Promise<CommandOutput>;
     /** Kills the process with given {@linkcode Deno.Signal}. Defaults to
      * `"SIGTERM"`. */
     kill(signo?: Signal): void;