diff --git a/index.d.ts b/index.d.ts index cc60e9d77c..cb68179ffd 100644 --- a/index.d.ts +++ b/index.d.ts @@ -495,6 +495,7 @@ Think of this as a mix of `child_process.execFile` and `child_process.spawn`. @returns An `ExecaChildProcess` that is both: - a `Promise` resolving or rejecting with a `childProcessResult`. - a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) with some additional methods and properties. +@throws A `childProcessResult` error @example ``` @@ -537,13 +538,12 @@ export function execa(file: string, options?: Options): ExecaChildProcess; export function execa(file: string, options?: Options): ExecaChildProcess; /** -Execute a file synchronously. - -This method throws an `Error` if the command fails. +Same as `execa()` but synchronous. @param file - The program/script to execute. @param arguments - Arguments to pass to `file` on execution. -@returns A result `Object` with `stdout` and `stderr` properties. +@returns A `childProcessResult` object +@throws A `childProcessResult` error */ export function execaSync( file: string, @@ -572,6 +572,7 @@ The `shell` option must be used if the `command` uses shell-specific features (f @returns An `ExecaChildProcess` that is both: - a `Promise` resolving or rejecting with a `childProcessResult`. - a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) with some additional methods and properties. +@throws A `childProcessResult` error @example ``` @@ -605,6 +606,7 @@ type Execa$ = { @returns An `ExecaChildProcess` that is both: - a `Promise` resolving or rejecting with a `childProcessResult`. - a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) with some additional methods and properties. + @throws A `childProcessResult` error @example Basic ``` @@ -669,9 +671,10 @@ type Execa$ = { ): ExecaChildProcess; /** - Same as `$` but synchronous like `execaSync()`. + Same as $\`command\` but synchronous. - @returns The stdout and stderr output. + @returns A `childProcessResult` object + @throws A `childProcessResult` error @example ``` @@ -700,7 +703,10 @@ The `shell` option must be used if the `command` uses shell-specific features (f As a convenience, the result from previous `` $`command` `` or `` $.sync`command` `` calls can be used as template expressions in subsequent commands and `$`/`$.sync` will use the `stdout` value. See the example below `` with results from `$` or `$.sync` `` for more details. -@returns A [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties. +@returns An `ExecaChildProcess` that is both: + - a `Promise` resolving or rejecting with a `childProcessResult`. + - a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) with some additional methods and properties. +@throws A `childProcessResult` error @example Basic ``` @@ -762,7 +768,8 @@ export const $: Execa$; Same as `execaCommand()` but synchronous. @param command - The program/script to execute and its arguments. -@returns A result `Object` with `stdout` and `stderr` properties. +@returns A `childProcessResult` object +@throws A `childProcessResult` error */ export function execaCommandSync(command: string, options?: SyncOptions): ExecaSyncReturnValue; export function execaCommandSync(command: string, options?: SyncOptions): ExecaSyncReturnValue; @@ -777,7 +784,10 @@ Same as `execa('node', [scriptPath, ...arguments], options)` except (like [`chil @param scriptPath - Node.js script to execute. @param arguments - Arguments to pass to `scriptPath` on execution. -@returns A [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties. +@returns An `ExecaChildProcess` that is both: + - a `Promise` resolving or rejecting with a `childProcessResult`. + - a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) with some additional methods and properties. +@throws A `childProcessResult` error */ export function execaNode( scriptPath: string, diff --git a/readme.md b/readme.md index ba6fc0b157..8d07d31cd4 100644 --- a/readme.md +++ b/readme.md @@ -279,12 +279,6 @@ No escaping/quoting is needed. 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. -### execaSync(file, arguments?, options?) - -Execute a file synchronously. - -Returns or throws a [`childProcessResult`](#childProcessResult). - ### $\`command\` Same as [`execa()`](#execafile-arguments-options) (including its [return value](#childprocess)) except both file and arguments are specified in a single tagged template string. For example, `` $`echo unicorns` `` is the same as `execa('echo', ['unicorns'])`. @@ -297,12 +291,6 @@ As a convenience, the result from previous [`` $`command` ``](#command) or [`` $ For more information, please see [this page](docs/scripts.md). -### $.sync\`command\` - -Same as [$\`command\`](#command) but synchronous like [`execaSync()`](#execasyncfile-arguments-options). - -Returns or throws a [`childProcessResult`](#childProcessResult). - ### $(options) Binds options to the [`$`](#command) API. For example, you can use `$(options)` to create a new `$` instance with specific default options, which are then bound to both the asynchronous [`` $`command` ``](#command) and synchronous [`` $.sync`command` ``](#synccommand) APIs. @@ -317,12 +305,6 @@ If the file or an argument contains spaces, they must be escaped with backslashe The [`shell` option](#shell) must be used if the `command` uses shell-specific features (for example, `&&` or `||`), as opposed to being a simple `file` followed by its `arguments`. -### execaCommandSync(command, options?) - -Same as [`execaCommand()`](#execacommand-command-options) but synchronous. - -Returns or throws a [`childProcessResult`](#childProcessResult). - ### execaNode(scriptPath, arguments?, options?) Execute a Node.js script as a child process. @@ -384,6 +366,24 @@ Combines both [`pipeStdout()`](#pipestdouttarget) and [`pipeStderr()`](#pipestde Either the [`stdout` option](#stdout-1) or the [`stderr` option](#stderr-1) must be kept as `pipe`, their default value. Also, the [`all` option](#all-2) must be set to `true`. +### execaSync(file, arguments?, options?) + +Same as [`execa()`](#execacommandcommand-options) but synchronous. + +Returns or throws a [`childProcessResult`](#childProcessResult). + +### $.sync\`command\` + +Same as [$\`command\`](#command) but synchronous. + +Returns or throws a [`childProcessResult`](#childProcessResult). + +### execaCommandSync(command, options?) + +Same as [`execaCommand()`](#execacommand-command-options) but synchronous. + +Returns or throws a [`childProcessResult`](#childProcessResult). + ### childProcessResult Type: `object`