From 0d39fdffeb053215a56a631db8d2cf32ea119a95 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Mon, 13 May 2019 08:49:25 -0700 Subject: [PATCH] Improve the API section of the readme (#239) --- index.d.ts | 6 ++-- readme.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 84 insertions(+), 16 deletions(-) diff --git a/index.d.ts b/index.d.ts index 1b50206216..a6a1976cbd 100644 --- a/index.d.ts +++ b/index.d.ts @@ -294,9 +294,7 @@ declare namespace execa { ): Promise | ResultType>; /** - Cancel the subprocess. - - Causes the promise to reject an error with a `.isCanceled = true` property, provided the process gets canceled. The process will not be canceled if it has already exited. + Similar to [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal). This is preferred when cancelling the child process execution as the error is more descriptive and [`childProcessResult.isCanceled`](#iscanceled) is set to `true`. */ cancel(): void; } @@ -362,7 +360,7 @@ declare const execa: { @param file - The program/script to execute. @param arguments - Arguments to pass to `file` on execution. - @returns The same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options). + @returns A result `Object` with `stdout` and `stderr` properties. */ sync( file: string, diff --git a/readme.md b/readme.md index 30c84fe51e..f7be045378 100644 --- a/readme.md +++ b/readme.md @@ -15,7 +15,7 @@ - Higher max buffer. 10 MB instead of 200 KB. - [Executes locally installed binaries by name.](#preferlocal) - [Cleans up spawned processes when the parent process dies.](#cleanup) -- [Get interleaved output](#execafile-arguments-options) from `stdout` and `stderr` similar to what is printed on the terminal. [*(Async only)*](#execasyncfile-arguments-options) +- [Get interleaved output](#all) from `stdout` and `stderr` similar to what is printed on the terminal. [*(Async only)*](#execasyncfile-arguments-options) - [Can specify command and arguments as a single string without a shell](#execafile-arguments-options) - More descriptive errors. @@ -112,36 +112,106 @@ try { ### execa(file, [arguments], [options]) ### execa(command, [options]) -Execute a file. +Execute a file. Think of this as a mix of [`child_process.execFile()`](https://nodejs.org/api/child_process.html#child_process_child_process_execfile_file_args_options_callback) and [`child_process.spawn()`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options). Arguments can be specified in either: - `arguments`: `execa('echo', ['unicorns'])`. - `command`: `execa('echo unicorns')`. -Arguments should not be escaped nor quoted. Exception: inside `command`, spaces can be escaped with a backslash. - -Think of this as a mix of `child_process.execFile` and `child_process.spawn`. +Arguments should not be escaped nor quoted, except inside `command` where spaces can be escaped with a backslash. Unless the [`shell`](#shell) option is used, no shell interpreter (Bash, `cmd.exe`, etc.) is used, so shell features such as variables substitution (`echo $PATH`) are not allowed. -Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) which is enhanced to be a `Promise`. +Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) which: + - is also a `Promise` resolving or rejecting with a [`childProcessResult`](#childProcessResult). + - exposes the following additional methods and properties. + +#### cancel() -It exposes an additional `.all` stream, with `stdout` and `stderr` interleaved. +Similar to [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal). This is preferred when cancelling the child process execution as the error is more descriptive and [`childProcessResult.isCanceled`](#iscanceled) is set to `true`. -The spawned process can be canceled with the `.cancel()` method on the promise, which causes the promise to reject an error with a `.isCanceled = true` property, provided the process gets canceled. The process will not be canceled if it has already exited. +#### all -The promise result is an `Object` with `stdout`, `stderr` and `all` properties. +Stream combining/interleaving [`stdout`](https://nodejs.org/api/child_process.html#child_process_subprocess_stdout) and [`stderr`](https://nodejs.org/api/child_process.html#child_process_subprocess_stderr). ### execa.sync(file, [arguments], [options]) ### execa.sync(command, [options]) Execute a file synchronously. -Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options). +Returns or throws a [`childProcessResult`](#childProcessResult). + +### childProcessResult + +Type: `object` + +Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance. + +#### exitCode + +Type: `number` + +The numeric exit code of the process that was run. + +#### exitCodeName + +Type: `string` + +The textual exit code of the process that was run. + +#### stdout + +Type: `string | Buffer` + +The output of the process on stdout. + +#### stderr + +Type: `string | Buffer` + +The output of the process on stderr. + +#### all + +Type: `string | Buffer` + +The output of the process on both stdout and stderr. `undefined` if `execa.sync()` was used. + +#### command + +Type: `string` + +The command that was run. + +#### failed + +Type: `boolean` + +Whether the process failed to run. + +#### timedOut + +Type: `boolean` + +Whether the process timed out. + +#### killed + +Type: `boolean` + +Whether the process was killed. + +#### isCanceled + +Type: `boolean` + +Whether the process was canceled. + +#### signal -It does not have the `.all` property that `execa()` has because the [underlying synchronous implementation](https://nodejs.org/api/child_process.html#child_process_child_process_execfilesync_file_args_options) only returns `stdout` and `stderr` at the end of the execution, so they cannot be interleaved. +Type: `string | undefined` -This method throws an `Error` if the command fails. +The signal that was used to terminate the process. ### options