diff --git a/index.d.ts b/index.d.ts index f432e2e23e..746056e504 100644 --- a/index.d.ts +++ b/index.d.ts @@ -14,66 +14,64 @@ declare namespace execa { interface CommonOptions { /** - Current working directory of the child process. + Kill the spawned process when the parent process exits unless either: + - the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached) + - the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit - @default process.cwd() + @default true */ - readonly cwd?: string; + readonly cleanup?: boolean; /** - Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this. + Prefer locally installed binaries when looking for a binary to execute. - @default process.env + If you `$ npm install foo`, you can then `execa('foo')`. + + @default true */ - readonly env?: NodeJS.ProcessEnv; + readonly preferLocal?: boolean; /** - Set to `false` if you don't want to extend the environment variables when providing the `env` property. + Preferred path to find locally installed binaries in (use with `preferLocal`). - @default true + @default process.cwd() */ - readonly extendEnv?: boolean; + readonly localDir?: string; /** - Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified. + Buffer the output from the spawned process. When buffering is disabled you must consume the output of the `stdout` and `stderr` streams because the promise will not be resolved/rejected until they have completed. + + @default true */ - readonly argv0?: string; + readonly buffer?: boolean; /** - Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration. + Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). @default 'pipe' */ - readonly stdio?: 'pipe' | 'ignore' | 'inherit' | readonly StdioOption[]; + readonly stdin?: StdioOption; /** - Prepare child to run independently of its parent process. Specific behavior [depends on the platform](https://nodejs.org/api/child_process.html#child_process_options_detached). + Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - @default false + @default 'pipe' */ - readonly detached?: boolean; + readonly stdout?: StdioOption; /** - Sets the user identity of the process. - */ - readonly uid?: number; + Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - /** - Sets the group identity of the process. + @default 'pipe' */ - readonly gid?: number; + readonly stderr?: StdioOption; /** - If `true`, runs `command` inside of a shell. Uses `/bin/sh` on UNIX and `cmd.exe` on Windows. A different shell can be specified as a string. The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows. - - We recommend against using this option since it is: - - not cross-platform, encouraging shell-specific syntax. - - slower, because of the additional shell interpretation. - - unsafe, potentially allowing command injection. + Setting this to `false` resolves the promise with the error instead of rejecting it. - @default false + @default true */ - readonly shell?: boolean | string; + readonly reject?: boolean; /** Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output. @@ -83,92 +81,94 @@ declare namespace execa { readonly stripFinalNewline?: boolean; /** - Prefer locally installed binaries when looking for a binary to execute. - - If you `$ npm install foo`, you can then `execa('foo')`. + Set to `false` if you don't want to extend the environment variables when providing the `env` property. @default true */ - readonly preferLocal?: boolean; + readonly extendEnv?: boolean; /** - Preferred path to find locally installed binaries in (use with `preferLocal`). + Current working directory of the child process. @default process.cwd() */ - readonly localDir?: string; + readonly cwd?: string; /** - Setting this to `false` resolves the promise with the error instead of rejecting it. + Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this. - @default true + @default process.env */ - readonly reject?: boolean; + readonly env?: NodeJS.ProcessEnv; /** - Kill the spawned process when the parent process exits unless either: - - the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached) - - the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit - - @default true + Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified. */ - readonly cleanup?: boolean; + readonly argv0?: string; /** - Specify the character encoding used to decode the `stdout` and `stderr` output. If set to `null`, then `stdout` and `stderr` will be a `Buffer` instead of a string. + Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration. - @default 'utf8' + @default 'pipe' */ - readonly encoding?: EncodingType; + readonly stdio?: 'pipe' | 'ignore' | 'inherit' | readonly StdioOption[]; /** - If `timeout` is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `SIGTERM`) if the child runs longer than `timeout` milliseconds. + Prepare child to run independently of its parent process. Specific behavior [depends on the platform](https://nodejs.org/api/child_process.html#child_process_options_detached). - @default 0 + @default false */ - readonly timeout?: number; + readonly detached?: boolean; /** - Buffer the output from the spawned process. When buffering is disabled you must consume the output of the `stdout` and `stderr` streams because the promise will not be resolved/rejected until they have completed. + Sets the user identity of the process. + */ + readonly uid?: number; - @default true + /** + Sets the group identity of the process. */ - readonly buffer?: boolean; + readonly gid?: number; /** - Largest amount of data in bytes allowed on `stdout` or `stderr`. Default: 10MB. + If `true`, runs `command` inside of a shell. Uses `/bin/sh` on UNIX and `cmd.exe` on Windows. A different shell can be specified as a string. The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows. - @default 10000000 + We recommend against using this option since it is: + - not cross-platform, encouraging shell-specific syntax. + - slower, because of the additional shell interpretation. + - unsafe, potentially allowing command injection. + + @default false */ - readonly maxBuffer?: number; + readonly shell?: boolean | string; /** - Signal value to be used when the spawned process will be killed. + Specify the character encoding used to decode the `stdout` and `stderr` output. If set to `null`, then `stdout` and `stderr` will be a `Buffer` instead of a string. - @default 'SIGTERM' + @default 'utf8' */ - readonly killSignal?: string | number; + readonly encoding?: EncodingType; /** - Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). + If `timeout` is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `SIGTERM`) if the child runs longer than `timeout` milliseconds. - @default 'pipe' + @default 0 */ - readonly stdin?: StdioOption; + readonly timeout?: number; /** - Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). + Largest amount of data in bytes allowed on `stdout` or `stderr`. Default: 10MB. - @default 'pipe' + @default 10000000 */ - readonly stdout?: StdioOption; + readonly maxBuffer?: number; /** - Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). + Signal value to be used when the spawned process will be killed. - @default 'pipe' + @default 'SIGTERM' */ - readonly stderr?: StdioOption; + readonly killSignal?: string | number; /** If `true`, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to `true` automatically when the `shell` option is `true`. diff --git a/index.test-d.ts b/index.test-d.ts index 98bda0759c..048f46a0b5 100644 --- a/index.test-d.ts +++ b/index.test-d.ts @@ -69,31 +69,13 @@ try { expectType(execaError.signal); } -execa('unicorns', {cwd: '.'}); -execa('unicorns', {env: {PATH: ''}}); -execa('unicorns', {extendEnv: false}); -execa('unicorns', {argv0: ''}); -execa('unicorns', {stdio: 'pipe'}); -execa('unicorns', {stdio: 'ignore'}); -execa('unicorns', {stdio: 'inherit'}); -execa('unicorns', { - stdio: ['pipe', 'ipc', 'ignore', 'inherit', process.stdin, 1, undefined] -}); -execa('unicorns', {detached: true}); -execa('unicorns', {uid: 0}); -execa('unicorns', {gid: 0}); -execa('unicorns', {shell: true}); -execa('unicorns', {shell: '/bin/sh'}); -execa('unicorns', {stripFinalNewline: false}); +execa('unicorns', {cleanup: false}); execa('unicorns', {preferLocal: false}); execa('unicorns', {localDir: '.'}); -execa('unicorns', {reject: false}); -execa('unicorns', {cleanup: false}); -execa('unicorns', {timeout: 1000}); execa('unicorns', {buffer: false}); -execa('unicorns', {maxBuffer: 1000}); -execa('unicorns', {killSignal: 'SIGTERM'}); -execa('unicorns', {killSignal: 9}); +execa('unicorns', {input: ''}); +execa('unicorns', {input: Buffer.from('')}); +execa('unicorns', {input: process.stdin}); execa('unicorns', {stdin: 'pipe'}); execa('unicorns', {stdin: 'ipc'}); execa('unicorns', {stdin: 'ignore'}); @@ -115,10 +97,28 @@ execa('unicorns', {stderr: 'inherit'}); execa('unicorns', {stderr: process.stderr}); execa('unicorns', {stderr: 1}); execa('unicorns', {stderr: undefined}); +execa('unicorns', {reject: false}); +execa('unicorns', {stripFinalNewline: false}); +execa('unicorns', {extendEnv: false}); +execa('unicorns', {cwd: '.'}); +execa('unicorns', {env: {PATH: ''}}); +execa('unicorns', {argv0: ''}); +execa('unicorns', {stdio: 'pipe'}); +execa('unicorns', {stdio: 'ignore'}); +execa('unicorns', {stdio: 'inherit'}); +execa('unicorns', { + stdio: ['pipe', 'ipc', 'ignore', 'inherit', process.stdin, 1, undefined] +}); +execa('unicorns', {detached: true}); +execa('unicorns', {uid: 0}); +execa('unicorns', {gid: 0}); +execa('unicorns', {shell: true}); +execa('unicorns', {shell: '/bin/sh'}); +execa('unicorns', {timeout: 1000}); +execa('unicorns', {maxBuffer: 1000}); +execa('unicorns', {killSignal: 'SIGTERM'}); +execa('unicorns', {killSignal: 9}); execa('unicorns', {windowsVerbatimArguments: true}); -execa('unicorns', {input: ''}); -execa('unicorns', {input: Buffer.from('')}); -execa('unicorns', {input: process.stdin}); expectType>(execa('unicorns')); expectType>(await execa('unicorns')); diff --git a/readme.md b/readme.md index ac1d5eb9a8..a1d36c9a17 100644 --- a/readme.md +++ b/readme.md @@ -229,19 +229,78 @@ The signal that was used to terminate the process. Type: `object` -#### cwd +#### cleanup + +Type: `boolean`
+Default: `true` + +Kill the spawned process when the parent process exits unless either: + - the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached) + - the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit + +#### preferLocal + +Type: `boolean`
+Default: `true` + +Prefer locally installed binaries when looking for a binary to execute.
+If you `$ npm install foo`, you can then `execa('foo')`. + +#### localDir Type: `string`
Default: `process.cwd()` -Current working directory of the child process. +Preferred path to find locally installed binaries in (use with `preferLocal`). -#### env +#### buffer -Type: `object`
-Default: `process.env` +Type: `boolean`
+Default: `true` + +Buffer the output from the spawned process. When buffering is disabled you must consume the output of the `stdout` and `stderr` streams because the promise will not be resolved/rejected until they have completed. + +#### input + +Type: `string | Buffer | stream.Readable` + +Write some input to the `stdin` of your binary.
+Streams are not allowed when using the synchronous methods. + +#### stdin -Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this. +Type: `string | number | Stream | undefined`
+Default: `pipe` + +Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). + +#### stdout + +Type: `string | number | Stream | undefined`
+Default: `pipe` + +Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). + +#### stderr + +Type: `string | number | Stream | undefined`
+Default: `pipe` + +Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). + +#### reject + +Type: `boolean`
+Default: `true` + +Setting this to `false` resolves the promise with the error instead of rejecting it. + +#### stripFinalNewline + +Type: `boolean`
+Default: `true` + +Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output. #### extendEnv @@ -250,6 +309,24 @@ Default: `true` Set to `false` if you don't want to extend the environment variables when providing the `env` property. +--- + +Execa also accepts the below options which are the same as the options for [`child_process#spawn()`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options)/[`child_process#exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback) + +#### cwd + +Type: `string`
+Default: `process.cwd()` + +Current working directory of the child process. + +#### env + +Type: `object`
+Default: `process.env` + +Environment key-value pairs. Extends automatically from `process.env`. Set [`extendEnv`](#extendenv) to `false` if you don't want this. + #### argv0 Type: `string` @@ -293,51 +370,6 @@ We recommend against using this option since it is: - slower, because of the additional shell interpretation. - unsafe, potentially allowing command injection. -#### stripFinalNewline - -Type: `boolean`
-Default: `true` - -Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output. - -#### preferLocal - -Type: `boolean`
-Default: `true` - -Prefer locally installed binaries when looking for a binary to execute.
-If you `$ npm install foo`, you can then `execa('foo')`. - -#### localDir - -Type: `string`
-Default: `process.cwd()` - -Preferred path to find locally installed binaries in (use with `preferLocal`). - -#### input - -Type: `string | Buffer | stream.Readable` - -Write some input to the `stdin` of your binary.
-Streams are not allowed when using the synchronous methods. - -#### reject - -Type: `boolean`
-Default: `true` - -Setting this to `false` resolves the promise with the error instead of rejecting it. - -#### cleanup - -Type: `boolean`
-Default: `true` - -Kill the spawned process when the parent process exits unless either: - - the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached) - - the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit - #### encoding Type: `string | null`
@@ -352,13 +384,6 @@ Default: `0` If timeout is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `SIGTERM`) if the child runs longer than timeout milliseconds. -#### buffer - -Type: `boolean`
-Default: `true` - -Buffer the output from the spawned process. When buffering is disabled you must consume the output of the `stdout` and `stderr` streams because the promise will not be resolved/rejected until they have completed. - #### maxBuffer Type: `number`
@@ -373,27 +398,6 @@ Default: `SIGTERM` Signal value to be used when the spawned process will be killed. -#### stdin - -Type: `string | number | Stream | undefined`
-Default: `pipe` - -Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - -#### stdout - -Type: `string | number | Stream | undefined`
-Default: `pipe` - -Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - -#### stderr - -Type: `string | number | Stream | undefined`
-Default: `pipe` - -Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). - #### windowsVerbatimArguments Type: `boolean`