From 0c539c29eb185936ada7d841894a5cb644e742b2 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 16:39:03 +0200 Subject: [PATCH 01/12] Add links --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 30c84fe51e..b82efc783f 100644 --- a/readme.md +++ b/readme.md @@ -120,7 +120,7 @@ Arguments can be specified in either: 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`. +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). 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. From 13a4c27c0edfecfb4713b8c6a9ea30db9e064568 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 17:44:46 +0200 Subject: [PATCH 02/12] Improve README `API` section --- readme.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 89 insertions(+), 11 deletions(-) diff --git a/readme.md b/readme.md index b82efc783f..acc6f60c2a 100644 --- a/readme.md +++ b/readme.md @@ -112,36 +112,114 @@ 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()`](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 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 [`childProcess`](#childProcess). + +### childProcess + +[`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess). + +That instance is also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult). + +The following methods and properties are also available. + +#### childProcess.cancel() -It exposes an additional `.all` stream, with `stdout` and `stderr` interleaved. +Same as `childProcess.kill()` but with a different error message and with `childProcessResult.isCanceled` 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. +#### childProcess.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|Error` + +Result of a child process execution. + +On failure this is also an `Error` instance. + +#### childProcessResult.exitCode + +Type: `number` + +The numeric exit code of the process that was run. + +#### childProcessResult.exitCodeName + +Type: `string` + +The textual exit code of the process that was run. + +#### childProcessResult.stdout + +Type: `string|Buffer` + +The output of the process on stdout. + +#### childProcessResult.stderr + +Type: `string|Buffer` + +The output of the process on stderr. + +#### childProcessResult.all + +Type: `string|Buffer` + +The output of the process on both stdout and stderr. `undefined` if `execa.sync()` was used. + +#### childProcessResult.command + +Type: `string` + +The command that was run. + +#### childProcessResult.failed + +Type: `boolean` + +Whether the process failed to run. + +#### childProcessResult.timedOut + +Type: `boolean` + +Whether the process timed out. + +#### childProcessResult.killed + +Type: `boolean` + +Whether the process was killed. + +#### childProcessResult.isCanceled + +Type: `boolean` + +Whether the process was canceled. + +#### childProcessResult.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 From 3334b8cd1ebaf59502bc0bb67494e594524743c4 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 17:53:27 +0200 Subject: [PATCH 03/12] Improve style --- readme.md | 42 +++++++++++++++++------------------------- 1 file changed, 17 insertions(+), 25 deletions(-) diff --git a/readme.md b/readme.md index acc6f60c2a..ad16497db9 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. @@ -122,21 +122,15 @@ Arguments should not be escaped nor quoted, except inside `command` where spaces 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 [`childProcess`](#childProcess). - -### childProcess - -[`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess). - -That instance is also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult). +Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess). That instance is also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult). The following methods and properties are also available. -#### childProcess.cancel() +#### cancel() -Same as `childProcess.kill()` but with a different error message and with `childProcessResult.isCanceled` set to `true`. +Same as [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal) but with a different error message and with [`childProcessResult.isCanceled`](#iscanceled) set to `true`. -#### childProcess.all +#### all 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). @@ -151,71 +145,69 @@ Returns or throws a [`childProcessResult`](#childProcessResult). Type: `object|Error` -Result of a child process execution. +Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance. -On failure this is also an `Error` instance. - -#### childProcessResult.exitCode +#### exitCode Type: `number` The numeric exit code of the process that was run. -#### childProcessResult.exitCodeName +#### exitCodeName Type: `string` The textual exit code of the process that was run. -#### childProcessResult.stdout +#### stdout Type: `string|Buffer` The output of the process on stdout. -#### childProcessResult.stderr +#### stderr Type: `string|Buffer` The output of the process on stderr. -#### childProcessResult.all +#### all Type: `string|Buffer` The output of the process on both stdout and stderr. `undefined` if `execa.sync()` was used. -#### childProcessResult.command +#### command Type: `string` The command that was run. -#### childProcessResult.failed +#### failed Type: `boolean` Whether the process failed to run. -#### childProcessResult.timedOut +#### timedOut Type: `boolean` Whether the process timed out. -#### childProcessResult.killed +#### killed Type: `boolean` Whether the process was killed. -#### childProcessResult.isCanceled +#### isCanceled Type: `boolean` Whether the process was canceled. -#### childProcessResult.signal +#### signal Type: `string|undefined` From 1520c6e47336f79fc773c6894bf30216af715959 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 17:54:46 +0200 Subject: [PATCH 04/12] Improve style --- readme.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/readme.md b/readme.md index ad16497db9..f8c6cfb5a4 100644 --- a/readme.md +++ b/readme.md @@ -122,9 +122,9 @@ Arguments should not be escaped nor quoted, except inside `command` where spaces 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). That instance is also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult). - -The following methods and properties are also available. +Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess). That instance: + - is also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult) + - expose the following additional methods and properties #### cancel() From 02d4ba5fce374cdfcbe7ef8e62a599984eba5c2c Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 17:55:17 +0200 Subject: [PATCH 05/12] Fix indentation --- readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index f8c6cfb5a4..9c7cee02e8 100644 --- a/readme.md +++ b/readme.md @@ -123,8 +123,8 @@ Arguments should not be escaped nor quoted, except inside `command` where spaces 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). That instance: - - is also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult) - - expose the following additional methods and properties + - is also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult). + - expose the following additional methods and properties. #### cancel() From 67af0a7ffbaa965132914d365f1dbb9e2c355b30 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 17:55:47 +0200 Subject: [PATCH 06/12] Fix indentation --- readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index 9c7cee02e8..b782dc5973 100644 --- a/readme.md +++ b/readme.md @@ -123,8 +123,8 @@ Arguments should not be escaped nor quoted, except inside `command` where spaces 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). That instance: - - is also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult). - - expose the following additional methods and properties. + - is also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult). + - expose the following additional methods and properties. #### cancel() From a7ea71cccc14aba22bc1a359024613ae2c654033 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 17:56:27 +0200 Subject: [PATCH 07/12] Improve style --- readme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index b782dc5973..9787e02f2b 100644 --- a/readme.md +++ b/readme.md @@ -122,9 +122,9 @@ Arguments should not be escaped nor quoted, except inside `command` where spaces 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). That instance: +Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) which: - is also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult). - - expose the following additional methods and properties. + - exposes the following additional methods and properties. #### cancel() From 0d5a4a555675476138fb97d43e577335a1c8b565 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 17:57:24 +0200 Subject: [PATCH 08/12] Improve style --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index 9787e02f2b..e662cfcdd7 100644 --- a/readme.md +++ b/readme.md @@ -123,7 +123,7 @@ Arguments should not be escaped nor quoted, except inside `command` where spaces 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 also a `Promise` which resolves or rejects with a [`childProcessResult`](#childProcessResult). + - is also a `Promise` resolving or rejecting with a [`childProcessResult`](#childProcessResult). - exposes the following additional methods and properties. #### cancel() From 00e3b1da5e028abbd61d40ade8eaf10d592c3cf8 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 21:40:41 +0200 Subject: [PATCH 09/12] Add whitespaces --- readme.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/readme.md b/readme.md index e662cfcdd7..e2101a6cd9 100644 --- a/readme.md +++ b/readme.md @@ -143,7 +143,7 @@ Returns or throws a [`childProcessResult`](#childProcessResult). ### childProcessResult -Type: `object|Error` +Type: `object | Error` Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance. @@ -161,19 +161,19 @@ The textual exit code of the process that was run. #### stdout -Type: `string|Buffer` +Type: `string | Buffer` The output of the process on stdout. #### stderr -Type: `string|Buffer` +Type: `string | Buffer` The output of the process on stderr. #### all -Type: `string|Buffer` +Type: `string | Buffer` The output of the process on both stdout and stderr. `undefined` if `execa.sync()` was used. @@ -209,7 +209,7 @@ Whether the process was canceled. #### signal -Type: `string|undefined` +Type: `string | undefined` The signal that was used to terminate the process. From db091f9f8d7489c3dc75ce0cd63a237000ed5da6 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 21:40:50 +0200 Subject: [PATCH 10/12] Fix main return type --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index e2101a6cd9..fe6f40f980 100644 --- a/readme.md +++ b/readme.md @@ -143,7 +143,7 @@ Returns or throws a [`childProcessResult`](#childProcessResult). ### childProcessResult -Type: `object | Error` +Type: `object` Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance. From d7de492ae3bf0c802bcb90af33be0b47dd985934 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 21:43:58 +0200 Subject: [PATCH 11/12] Improve cancel() description --- readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.md b/readme.md index fe6f40f980..f7be045378 100644 --- a/readme.md +++ b/readme.md @@ -128,7 +128,7 @@ Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#c #### cancel() -Same as [`childProcess.kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal) but with a different error message and with [`childProcessResult.isCanceled`](#iscanceled) set to `true`. +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`. #### all From 5faa51bc807c761ebc9a4eb896a4705ffad0036e Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 12 May 2019 21:54:32 +0200 Subject: [PATCH 12/12] Fix index.d.ts --- index.d.ts | 6 ++---- 1 file changed, 2 insertions(+), 4 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,