No Description

index.d.ts 17KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549
  1. /// <reference types="node"/>
  2. import {ChildProcess} from 'child_process';
  3. import {Stream, Readable as ReadableStream} from 'stream';
  4. declare namespace execa {
  5. type StdioOption =
  6. | 'pipe'
  7. | 'ipc'
  8. | 'ignore'
  9. | 'inherit'
  10. | Stream
  11. | number
  12. | undefined;
  13. interface CommonOptions<EncodingType> {
  14. /**
  15. Kill the spawned process when the parent process exits unless either:
  16. - the spawned process is [`detached`](https://nodejs.org/api/child_process.html#child_process_options_detached)
  17. - the parent process is terminated abruptly, for example, with `SIGKILL` as opposed to `SIGTERM` or a normal exit
  18. @default true
  19. */
  20. readonly cleanup?: boolean;
  21. /**
  22. Prefer locally installed binaries when looking for a binary to execute.
  23. If you `$ npm install foo`, you can then `execa('foo')`.
  24. @default false
  25. */
  26. readonly preferLocal?: boolean;
  27. /**
  28. Preferred path to find locally installed binaries in (use with `preferLocal`).
  29. @default process.cwd()
  30. */
  31. readonly localDir?: string;
  32. /**
  33. Path to the Node.js executable to use in child processes.
  34. This can be either an absolute path or a path relative to the `cwd` option.
  35. Requires `preferLocal` to be `true`.
  36. For example, this can be used together with [`get-node`](https://github.com/ehmicky/get-node) to run a specific Node.js version in a child process.
  37. @default process.execPath
  38. */
  39. readonly execPath?: string;
  40. /**
  41. Buffer the output from the spawned process. When set to `false`, you must read the output of `stdout` and `stderr` (or `all` if the `all` option is `true`). Otherwise the returned promise will not be resolved/rejected.
  42. If the spawned process fails, `error.stdout`, `error.stderr`, and `error.all` will contain the buffered data.
  43. @default true
  44. */
  45. readonly buffer?: boolean;
  46. /**
  47. Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
  48. @default 'pipe'
  49. */
  50. readonly stdin?: StdioOption;
  51. /**
  52. Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
  53. @default 'pipe'
  54. */
  55. readonly stdout?: StdioOption;
  56. /**
  57. Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
  58. @default 'pipe'
  59. */
  60. readonly stderr?: StdioOption;
  61. /**
  62. Setting this to `false` resolves the promise with the error instead of rejecting it.
  63. @default true
  64. */
  65. readonly reject?: boolean;
  66. /**
  67. Add an `.all` property on the promise and the resolved value. The property contains the output of the process with `stdout` and `stderr` interleaved.
  68. @default false
  69. */
  70. readonly all?: boolean;
  71. /**
  72. Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output.
  73. @default true
  74. */
  75. readonly stripFinalNewline?: boolean;
  76. /**
  77. Set to `false` if you don't want to extend the environment variables when providing the `env` property.
  78. @default true
  79. */
  80. readonly extendEnv?: boolean;
  81. /**
  82. Current working directory of the child process.
  83. @default process.cwd()
  84. */
  85. readonly cwd?: string;
  86. /**
  87. Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this.
  88. @default process.env
  89. */
  90. readonly env?: NodeJS.ProcessEnv;
  91. /**
  92. Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified.
  93. */
  94. readonly argv0?: string;
  95. /**
  96. Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.
  97. @default 'pipe'
  98. */
  99. readonly stdio?: 'pipe' | 'ignore' | 'inherit' | readonly StdioOption[];
  100. /**
  101. Specify the kind of serialization used for sending messages between processes when using the `stdio: 'ipc'` option or `execa.node()`:
  102. - `json`: Uses `JSON.stringify()` and `JSON.parse()`.
  103. - `advanced`: Uses [`v8.serialize()`](https://nodejs.org/api/v8.html#v8_v8_serialize_value)
  104. Requires Node.js `13.2.0` or later.
  105. [More info.](https://nodejs.org/api/child_process.html#child_process_advanced_serialization)
  106. @default 'json'
  107. */
  108. readonly serialization?: 'json' | 'advanced';
  109. /**
  110. 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).
  111. @default false
  112. */
  113. readonly detached?: boolean;
  114. /**
  115. Sets the user identity of the process.
  116. */
  117. readonly uid?: number;
  118. /**
  119. Sets the group identity of the process.
  120. */
  121. readonly gid?: number;
  122. /**
  123. 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.
  124. We recommend against using this option since it is:
  125. - not cross-platform, encouraging shell-specific syntax.
  126. - slower, because of the additional shell interpretation.
  127. - unsafe, potentially allowing command injection.
  128. @default false
  129. */
  130. readonly shell?: boolean | string;
  131. /**
  132. 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.
  133. @default 'utf8'
  134. */
  135. readonly encoding?: EncodingType;
  136. /**
  137. 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.
  138. @default 0
  139. */
  140. readonly timeout?: number;
  141. /**
  142. Largest amount of data in bytes allowed on `stdout` or `stderr`. Default: 100 MB.
  143. @default 100_000_000
  144. */
  145. readonly maxBuffer?: number;
  146. /**
  147. Signal value to be used when the spawned process will be killed.
  148. @default 'SIGTERM'
  149. */
  150. readonly killSignal?: string | number;
  151. /**
  152. 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`.
  153. @default false
  154. */
  155. readonly windowsVerbatimArguments?: boolean;
  156. /**
  157. On Windows, do not create a new console window. Please note this also prevents `CTRL-C` [from working](https://github.com/nodejs/node/issues/29837) on Windows.
  158. @default true
  159. */
  160. readonly windowsHide?: boolean;
  161. }
  162. interface Options<EncodingType = string> extends CommonOptions<EncodingType> {
  163. /**
  164. Write some input to the `stdin` of your binary.
  165. */
  166. readonly input?: string | Buffer | ReadableStream;
  167. }
  168. interface SyncOptions<EncodingType = string> extends CommonOptions<EncodingType> {
  169. /**
  170. Write some input to the `stdin` of your binary.
  171. */
  172. readonly input?: string | Buffer;
  173. }
  174. interface NodeOptions<EncodingType = string> extends Options<EncodingType> {
  175. /**
  176. The Node.js executable to use.
  177. @default process.execPath
  178. */
  179. readonly nodePath?: string;
  180. /**
  181. List of [CLI options](https://nodejs.org/api/cli.html#cli_options) passed to the Node.js executable.
  182. @default process.execArgv
  183. */
  184. readonly nodeOptions?: string[];
  185. }
  186. interface ExecaReturnBase<StdoutStderrType> {
  187. /**
  188. The file and arguments that were run.
  189. */
  190. command: string;
  191. /**
  192. The numeric exit code of the process that was run.
  193. */
  194. exitCode: number;
  195. /**
  196. The output of the process on stdout.
  197. */
  198. stdout: StdoutStderrType;
  199. /**
  200. The output of the process on stderr.
  201. */
  202. stderr: StdoutStderrType;
  203. /**
  204. Whether the process failed to run.
  205. */
  206. failed: boolean;
  207. /**
  208. Whether the process timed out.
  209. */
  210. timedOut: boolean;
  211. /**
  212. Whether the process was killed.
  213. */
  214. killed: boolean;
  215. /**
  216. The name of the signal that was used to terminate the process. For example, `SIGFPE`.
  217. If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`.
  218. */
  219. signal?: string;
  220. /**
  221. A human-friendly description of the signal that was used to terminate the process. For example, `Floating point arithmetic error`.
  222. If a signal terminated the process, this property is defined and included in the error message. Otherwise it is `undefined`. It is also `undefined` when the signal is very uncommon which should seldomly happen.
  223. */
  224. signalDescription?: string;
  225. }
  226. interface ExecaSyncReturnValue<StdoutErrorType = string>
  227. extends ExecaReturnBase<StdoutErrorType> {
  228. }
  229. /**
  230. Result of a child process execution. On success this is a plain object. On failure this is also an `Error` instance.
  231. The child process fails when:
  232. - its exit code is not `0`
  233. - it was killed with a signal
  234. - timing out
  235. - being canceled
  236. - there's not enough memory or there are already too many child processes
  237. */
  238. interface ExecaReturnValue<StdoutErrorType = string>
  239. extends ExecaSyncReturnValue<StdoutErrorType> {
  240. /**
  241. The output of the process with `stdout` and `stderr` interleaved.
  242. This is `undefined` if either:
  243. - the `all` option is `false` (default value)
  244. - `execa.sync()` was used
  245. */
  246. all?: StdoutErrorType;
  247. /**
  248. Whether the process was canceled.
  249. */
  250. isCanceled: boolean;
  251. }
  252. interface ExecaSyncError<StdoutErrorType = string>
  253. extends Error,
  254. ExecaReturnBase<StdoutErrorType> {
  255. /**
  256. Error message when the child process failed to run. In addition to the underlying error message, it also contains some information related to why the child process errored.
  257. The child process stderr then stdout are appended to the end, separated with newlines and not interleaved.
  258. */
  259. message: string;
  260. /**
  261. This is the same as the `message` property except it does not include the child process stdout/stderr.
  262. */
  263. shortMessage: string;
  264. /**
  265. Original error message. This is the same as the `message` property except it includes neither the child process stdout/stderr nor some additional information added by Execa.
  266. This is `undefined` unless the child process exited due to an `error` event or a timeout.
  267. */
  268. originalMessage?: string;
  269. }
  270. interface ExecaError<StdoutErrorType = string>
  271. extends ExecaSyncError<StdoutErrorType> {
  272. /**
  273. The output of the process with `stdout` and `stderr` interleaved.
  274. This is `undefined` if either:
  275. - the `all` option is `false` (default value)
  276. - `execa.sync()` was used
  277. */
  278. all?: StdoutErrorType;
  279. /**
  280. Whether the process was canceled.
  281. */
  282. isCanceled: boolean;
  283. }
  284. interface KillOptions {
  285. /**
  286. Milliseconds to wait for the child process to terminate before sending `SIGKILL`.
  287. Can be disabled with `false`.
  288. @default 5000
  289. */
  290. forceKillAfterTimeout?: number | false;
  291. }
  292. interface ExecaChildPromise<StdoutErrorType> {
  293. catch<ResultType = never>(
  294. onRejected?: (reason: ExecaError<StdoutErrorType>) => ResultType | PromiseLike<ResultType>
  295. ): Promise<ExecaReturnValue<StdoutErrorType> | ResultType>;
  296. /**
  297. Same as the original [`child_process#kill()`](https://nodejs.org/api/child_process.html#child_process_subprocess_kill_signal), except if `signal` is `SIGTERM` (the default value) and the child process is not terminated after 5 seconds, force it by sending `SIGKILL`.
  298. */
  299. kill(signal?: string, options?: execa.KillOptions): void;
  300. /**
  301. 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`.
  302. */
  303. cancel(): void;
  304. /**
  305. 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).
  306. This is `undefined` if either:
  307. - the `all` option is `false` (the default value)
  308. - both `stdout` and `stderr` options are set to [`'inherit'`, `'ipc'`, `Stream` or `integer`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio)
  309. */
  310. all?: ReadableStream;
  311. }
  312. type ExecaChildProcess<StdoutErrorType = string> = ChildProcess &
  313. ExecaChildPromise<StdoutErrorType> &
  314. Promise<ExecaReturnValue<StdoutErrorType>>;
  315. }
  316. declare const execa: {
  317. /**
  318. Execute a file.
  319. Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
  320. @param file - The program/script to execute.
  321. @param arguments - Arguments to pass to `file` on execution.
  322. @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.
  323. @example
  324. ```
  325. import execa = require('execa');
  326. (async () => {
  327. const {stdout} = await execa('echo', ['unicorns']);
  328. console.log(stdout);
  329. //=> 'unicorns'
  330. // Cancelling a spawned process
  331. const subprocess = execa('node');
  332. setTimeout(() => { spawned.cancel() }, 1000);
  333. try {
  334. await subprocess;
  335. } catch (error) {
  336. console.log(subprocess.killed); // true
  337. console.log(error.isCanceled); // true
  338. }
  339. })();
  340. // Pipe the child process stdout to the current stdout
  341. execa('echo', ['unicorns']).stdout.pipe(process.stdout);
  342. ```
  343. */
  344. (
  345. file: string,
  346. arguments?: readonly string[],
  347. options?: execa.Options
  348. ): execa.ExecaChildProcess;
  349. (
  350. file: string,
  351. arguments?: readonly string[],
  352. options?: execa.Options<null>
  353. ): execa.ExecaChildProcess<Buffer>;
  354. (file: string, options?: execa.Options): execa.ExecaChildProcess;
  355. (file: string, options?: execa.Options<null>): execa.ExecaChildProcess<
  356. Buffer
  357. >;
  358. /**
  359. Execute a file synchronously.
  360. This method throws an `Error` if the command fails.
  361. @param file - The program/script to execute.
  362. @param arguments - Arguments to pass to `file` on execution.
  363. @returns A result `Object` with `stdout` and `stderr` properties.
  364. */
  365. sync(
  366. file: string,
  367. arguments?: readonly string[],
  368. options?: execa.SyncOptions
  369. ): execa.ExecaSyncReturnValue;
  370. sync(
  371. file: string,
  372. arguments?: readonly string[],
  373. options?: execa.SyncOptions<null>
  374. ): execa.ExecaSyncReturnValue<Buffer>;
  375. sync(file: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue;
  376. sync(
  377. file: string,
  378. options?: execa.SyncOptions<null>
  379. ): execa.ExecaSyncReturnValue<Buffer>;
  380. /**
  381. Same as `execa()` except both file and arguments are specified in a single `command` string. For example, `execa('echo', ['unicorns'])` is the same as `execa.command('echo unicorns')`.
  382. 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.
  383. The `shell` option must be used if the `command` uses shell-specific features, as opposed to being a simple `file` followed by its `arguments`.
  384. @param command - The program/script to execute and its arguments.
  385. @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.
  386. @example
  387. ```
  388. import execa = require('execa');
  389. (async () => {
  390. const {stdout} = await execa.command('echo unicorns');
  391. console.log(stdout);
  392. //=> 'unicorns'
  393. })();
  394. ```
  395. */
  396. command(command: string, options?: execa.Options): execa.ExecaChildProcess;
  397. command(command: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>;
  398. /**
  399. Same as `execa.command()` but synchronous.
  400. @param command - The program/script to execute and its arguments.
  401. @returns A result `Object` with `stdout` and `stderr` properties.
  402. */
  403. commandSync(command: string, options?: execa.SyncOptions): execa.ExecaSyncReturnValue;
  404. commandSync(command: string, options?: execa.SyncOptions<null>): execa.ExecaSyncReturnValue<Buffer>;
  405. /**
  406. Execute a Node.js script as a child process.
  407. 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)):
  408. - the current Node version and options are used. This can be overridden using the `nodePath` and `nodeArguments` options.
  409. - the `shell` option cannot be used
  410. - an extra channel [`ipc`](https://nodejs.org/api/child_process.html#child_process_options_stdio) is passed to [`stdio`](#stdio)
  411. @param scriptPath - Node.js script to execute.
  412. @param arguments - Arguments to pass to `scriptPath` on execution.
  413. @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.
  414. */
  415. node(
  416. scriptPath: string,
  417. arguments?: readonly string[],
  418. options?: execa.NodeOptions
  419. ): execa.ExecaChildProcess;
  420. node(
  421. scriptPath: string,
  422. arguments?: readonly string[],
  423. options?: execa.Options<null>
  424. ): execa.ExecaChildProcess<Buffer>;
  425. node(scriptPath: string, options?: execa.Options): execa.ExecaChildProcess;
  426. node(scriptPath: string, options?: execa.Options<null>): execa.ExecaChildProcess<Buffer>;
  427. };
  428. export = execa;