Skip to content

Commit

Permalink
Separate core options from execa-specific options (#256)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ehmicky @sindresorhus
ehmicky authored and sindresorhus committed May 20, 2019
1 parent 50e3ef4 commit 76191ae
Show file tree
Hide file tree
Showing 3 changed files with 177 additions and 173 deletions.
138 changes: 69 additions & 69 deletions index.d.ts
View file
Expand Up @@ -14,66 +14,64 @@ declare namespace execa {

interface CommonOptions<EncodingType> {
/**
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.
Expand All @@ -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`.
Expand Down
50 changes: 25 additions & 25 deletions index.test-d.ts
View file
Expand Up @@ -69,31 +69,13 @@ try {
expectType<string | undefined>(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'});
Expand All @@ -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<ExecaChildProcess<string>>(execa('unicorns'));
expectType<ExecaReturnValue<string>>(await execa('unicorns'));
Expand Down

0 comments on commit 76191ae

Please sign in to comment.