Skip to content

Commit db2ad9a

Browse files
ehmickyehmicky
authored
Improve main method documentation (#545)
1 parent 72443f3 commit db2ad9a

File tree

2 files changed

+77
-57
lines changed

2 files changed

+77
-57
lines changed

‎index.d.ts

+23-15
Original file line numberDiff line numberDiff line change
@@ -504,9 +504,11 @@ ExecaChildPromise<StdoutStderrType> &
504504
Promise<ExecaReturnValue<StdoutStderrType>>;
505505

506506
/**
507-
Execute a file.
507+
Executes a command using `file ...arguments`. `arguments` are specified as an array of strings. Returns a `childProcess`.
508508
509-
Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
509+
Arguments are automatically escaped. They can contain any character, including spaces.
510+
511+
This is the preferred method when executing single commands.
510512
511513
@param file - The program/script to execute.
512514
@param arguments - Arguments to pass to `file` on execution.
@@ -700,11 +702,11 @@ export function execaSync(
700702
): ExecaSyncReturnValue<Buffer>;
701703

702704
/**
703-
Same as `execa()` (including its return value) except both file and arguments are specified in a single `command` string. For example, `execa('echo', ['unicorns'])` is the same as `execaCommand('echo unicorns')`.
705+
Executes a command. The `command` string includes both the `file` and its `arguments`. Returns a `childProcess`.
704706
705-
If the file or an argument contains spaces, they must be escaped with backslashes. This matters especially if `command` is not a constant but a variable, for example with `__dirname` or `process.cwd()`. Except for spaces, no escaping/quoting is needed.
707+
Arguments are automatically escaped. They can contain any character, but spaces must be escaped with a backslash like `execaCommand('echo has\\ space')`.
706708
707-
The `shell` option must be used if the `command` uses shell-specific features (for example, `&&` or `||`), as opposed to being a simple `file` followed by its `arguments`.
709+
This is the preferred method when executing a user-supplied `command` string, such as in a REPL.
708710
709711
@param command - The program/script to execute and its arguments.
710712
@returns An `ExecaChildProcess` that is both:
@@ -752,9 +754,11 @@ type TemplateExpression =
752754

753755
type Execa$<StdoutStderrType extends StdoutStderrAll = string> = {
754756
/**
755-
Binds options to the `$` 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` `` and synchronous `` $.sync`command` `` APIs.
757+
Returns a new instance of `$` but with different default `options`. Consecutive calls are merged to previous ones.
756758
757-
> **Note:** Consecutive calls to this API will shallow merge the options.
759+
This can be used to either:
760+
- Set options for a specific command: `` $(options)`command` ``
761+
- Share options for multiple commands: `` const $$ = $(options); $$`command`; $$`otherCommand` ``
758762
759763
@param options - Options to set
760764
@returns A new instance of `$` with those `options` set
@@ -832,13 +836,13 @@ type Execa$<StdoutStderrType extends StdoutStderrAll = string> = {
832836
};
833837

834838
/**
835-
Same as `execa()` except both file and arguments are specified in a single tagged template string. For example, `` $`echo unicorns` `` is the same as `execa('echo', ['unicorns'])`.
839+
Executes a command. The `command` string includes both the `file` and its `arguments`. Returns a `childProcess`.
836840
837-
It's important to note that quotes, backslashes, and spaces are automatically escaped and have no special meaning unless the `shell` option is used. This escaping behavior also applies to interpolated expressions such as strings (`` $`echo ${'string'}` ``), arrays of strings (`` $`echo ${['array', 'of strings']}` ``), and so on.
841+
Arguments are automatically escaped. They can contain any character, but spaces must use `${}` like `` $`echo ${'has space'}` ``.
838842
839-
The `shell` option must be used if the `command` uses shell-specific features (for example, `&&` or `||`), as opposed to being a simple `file` followed by its `arguments`.
843+
This is the preferred method when executing multiple commands in a script file.
840844
841-
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.
845+
The `command` string can inject any `${value}` with the following types: string, number, `childProcess` or an array of those types. For example: `` $`echo one ${'two'} ${3} ${['four', 'five']}` ``. For `${childProcess}`, the process's `stdout` is used.
842846
843847
@returns An `ExecaChildProcess` that is both:
844848
- a `Promise` resolving or rejecting with a `childProcessResult`.
@@ -889,10 +893,14 @@ export const $: Execa$;
889893
/**
890894
Execute a Node.js script as a child process.
891895
892-
Same as `execa('node', [scriptPath, ...arguments], options)` except (like [`child_process#fork()`](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options)):
893-
- the current Node version and options are used. This can be overridden using the `nodePath` and `nodeArguments` options.
894-
- the `shell` option cannot be used
895-
- an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio)
896+
Arguments are automatically escaped. They can contain any character, including spaces.
897+
898+
This is the preferred method when executing Node.js files.
899+
900+
Like [`child_process#fork()`](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options):
901+
- the current Node version and options are used. This can be overridden using the `nodePath` and `nodeOptions` options.
902+
- the `shell` option cannot be used
903+
- an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to `stdio`
896904
897905
@param scriptPath - Node.js script to execute.
898906
@param arguments - Arguments to pass to `scriptPath` on execution.

‎readme.md

+54-42
Original file line numberDiff line numberDiff line change
@@ -204,52 +204,82 @@ setTimeout(() => {
204204

205205
## API
206206

207-
### execa(file, arguments, options?)
207+
### Methods
208208

209-
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). This returns a [`childProcess`](#childprocess).
209+
#### execa(file, arguments?, options?)
210210

211-
No escaping/quoting is needed.
211+
Executes a command using `file ...arguments`. `arguments` are specified as an array of strings. Returns a [`childProcess`](#childprocess).
212212

213-
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.
213+
Arguments are [automatically escaped](#shell-syntax). They can contain any character, including spaces.
214214

215-
### $\`command\`
215+
This is the preferred method when executing single commands.
216216

217-
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'])`.
217+
#### execaNode(scriptPath, arguments?, options?)
218218

219-
It's important to note that quotes, backslashes, and spaces are automatically escaped and have no special meaning unless the [`shell` option](#shell) is used. This escaping behavior also applies to interpolated expressions such as strings (`` $`echo ${'string'}` ``), arrays of strings (`` $`echo ${['array', 'of strings']}` ``), and so on.
219+
Executes a Node.js file using `node scriptPath ...arguments`. `arguments` are specified as an array of strings. Returns a [`childProcess`](#childprocess).
220220

221-
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`.
221+
Arguments are [automatically escaped](#shell-syntax). They can contain any character, including spaces.
222222

223-
As a convenience, the result from previous [`` $`command` ``](#command) or [`` $.sync`command` ``](#synccommand) calls can be used as template expressions in subsequent commands and `$`/`$.sync` will use the `stdout` value. See the example above [with results from `$` or `$.sync`](#with-results-from--or-sync) for more details.
223+
This is the preferred method when executing Node.js files.
224224

225-
For more information, please see [this page](docs/scripts.md).
225+
Like [`child_process#fork()`](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options):
226+
- the current Node version and options are used. This can be overridden using the [`nodePath`](#nodepath-for-node-only) and [`nodeOptions`](#nodeoptions-for-node-only) options.
227+
- the [`shell`](#shell) option cannot be used
228+
- an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio)
226229

227-
### $(options)
230+
#### $\`command\`
228231

229-
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.
232+
Executes a command. The `command` string includes both the `file` and its `arguments`. Returns a [`childProcess`](#childprocess).
230233

231-
> **Note:** Consecutive calls to this API will shallow merge the options.
234+
Arguments are [automatically escaped](#shell-syntax). They can contain any character, but spaces must use `${}` like `` $`echo ${'has space'}` ``.
232235

233-
### execaCommand(command, options?)
236+
This is the preferred method when executing multiple commands in a script file.
234237

235-
Same as [`execa()`](#execafile-arguments-options) (including its [return value](#childprocess)) except both file and arguments are specified in a single `command` string. For example, `execa('echo', ['unicorns'])` is the same as `execaCommand('echo unicorns')`.
238+
The `command` string can inject any `${value}` with the following types: string, number, [`childProcess`](#childprocess) or an array of those types. For example: `` $`echo one ${'two'} ${3} ${['four', 'five']}` ``. For `${childProcess}`, the process's `stdout` is used.
236239

237-
If the file or an argument contains spaces, they must be escaped with backslashes. This matters especially if `command` is not a constant but a variable, for example with `__dirname` or `process.cwd()`. Except for spaces, no escaping/quoting is needed.
240+
For more information, please see [this section](#scripts-interface) and [this page](docs/scripts.md).
238241

239-
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`.
242+
#### $(options)
240243

241-
### execaNode(scriptPath, arguments?, options?)
244+
Returns a new instance of [`$`](#command) but with different default `options`. Consecutive calls are merged to previous ones.
242245

243-
Execute a Node.js script as a child process.
246+
This can be used to either:
247+
- Set options for a specific command: `` $(options)`command` ``
248+
- Share options for multiple commands: `` const $$ = $(options); $$`command`; $$`otherCommand`; ``
244249

245-
Same as `execa('node', [scriptPath, ...arguments], options)` except (like [`child_process#fork()`](https://nodejs.org/api/child_process.html#child_process_child_process_fork_modulepath_args_options)):
246-
- the current Node version and options are used. This can be overridden using the [`nodePath`](#nodepath-for-node-only) and [`nodeOptions`](#nodeoptions-for-node-only) options.
247-
- the [`shell`](#shell) option cannot be used
248-
- an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio)
250+
#### execaCommand(command, options?)
251+
252+
Executes a command. The `command` string includes both the `file` and its `arguments`. Returns a [`childProcess`](#childprocess).
253+
254+
Arguments are [automatically escaped](#shell-syntax). They can contain any character, but spaces must be escaped with a backslash like `execaCommand('echo has\\ space')`.
255+
256+
This is the preferred method when executing a user-supplied `command` string, such as in a REPL.
257+
258+
### execaSync(file, arguments?, options?)
259+
260+
Same as [`execa()`](#execacommandcommand-options) but synchronous.
261+
262+
Returns or throws a [`childProcessResult`](#childProcessResult).
263+
264+
### $.sync\`command\`
265+
266+
Same as [$\`command\`](#command) but synchronous.
267+
268+
Returns or throws a [`childProcessResult`](#childProcessResult).
269+
270+
### execaCommandSync(command, options?)
271+
272+
Same as [`execaCommand()`](#execacommand-command-options) but synchronous.
273+
274+
Returns or throws a [`childProcessResult`](#childProcessResult).
275+
276+
### Shell syntax
277+
278+
For all the [methods above](#methods), no shell interpreter (Bash, cmd.exe, etc.) is used unless the [`shell` option](#shell) is set. This means shell-specific characters and expressions (`$variable`, `&&`, `||`, `;`, `|`, etc.) have no special meaning and do not need to be escaped.
249279

250280
### childProcess
251281

252-
This is both:
282+
The return value of all [asynchronous methods](#methods) is both:
253283
- a `Promise` resolving or rejecting with a [`childProcessResult`](#childProcessResult).
254284
- a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess) with the following additional methods and properties.
255285

@@ -299,24 +329,6 @@ Combines both [`pipeStdout()`](#pipestdouttarget) and [`pipeStderr()`](#pipestde
299329

300330
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`.
301331

302-
### execaSync(file, arguments?, options?)
303-
304-
Same as [`execa()`](#execacommandcommand-options) but synchronous.
305-
306-
Returns or throws a [`childProcessResult`](#childProcessResult).
307-
308-
### $.sync\`command\`
309-
310-
Same as [$\`command\`](#command) but synchronous.
311-
312-
Returns or throws a [`childProcessResult`](#childProcessResult).
313-
314-
### execaCommandSync(command, options?)
315-
316-
Same as [`execaCommand()`](#execacommand-command-options) but synchronous.
317-
318-
Returns or throws a [`childProcessResult`](#childProcessResult).
319-
320332
### childProcessResult
321333

322334
Type: `object`

0 commit comments

Comments
 (0)