From d024c39e6326789dc62e55e12db0f9f23c2752fe Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 5 Mar 2023 11:55:12 +0000 Subject: [PATCH 1/3] Improve Documentation of the Usage section --- readme.md | 139 ++++++++++++++++-------------------------------------- 1 file changed, 40 insertions(+), 99 deletions(-) diff --git a/readme.md b/readme.md index e582236d0b..76016469c9 100644 --- a/readme.md +++ b/readme.md @@ -34,6 +34,8 @@ npm install execa ## Usage +### Promise interface + ```js import {execa} from 'execa'; @@ -44,19 +46,21 @@ console.log(stdout); ### Scripts interface -For more information, please see [this page](docs/scripts.md). +For more information about Execa scripts, please see [this page](docs/scripts.md). #### Basic ```js import {$} from 'execa'; -const {stdout} = await $`echo unicorns`; -// const {stdout} = await $`echo ${'unicorns'}`; -// const {stdout} = await $`echo ${['unicorns', 'rainbows']}`; +const unicorns = await $`echo unicorns`; +const {stdout} = await $`echo ${unicorns}${'!'}}`; +console.log(stdout); +//=> 'unicorns!' +const {stdout} = await $`echo ${['unicorns', 'rainbows']}`; console.log(stdout); -//=> 'unicorns' +//=> 'unicorns rainbows' ``` #### With options @@ -64,48 +68,16 @@ console.log(stdout); ```js import {$} from 'execa'; -await $({stdio: 'inherit'})`echo unicorns`; -//=> 'unicorns' -``` - -#### With pre-defined options - -```js -import {$} from 'execa'; - const $$ = $({stdio: 'inherit'}); await $$`echo unicorns`; //=> 'unicorns' -await $$({shell: true})`echo unicorns && echo rainbows`; -//=> 'unicorns' -//=> 'rainbows' -``` - -#### Synchronous - -```js -import {$} from 'execa'; -const {stdout} = $.sync`echo unicorns`; -console.log(stdout); +await $$({shell: true})`echo unicorns && echo rainbows`; //=> 'unicorns' - -$({stdio: 'inherit'}).sync`echo rainbows`; //=> 'rainbows' ``` -#### With results from `$` or `$.sync` - -```js -import {$} from 'execa'; - -const unicorns = await $`echo unicorns`; - -$({stdio: 'inherit'}).sync`echo ${unicorns} rainbows`; -//=> 'unicorns rainbows' -``` - #### Verbose mode ```sh @@ -120,7 +92,9 @@ unicorns rainbows ``` -### Redirect output to a file +### Input/output + +#### Redirect output to a file ```js import {execa} from 'execa'; @@ -135,7 +109,7 @@ await execa('echo', ['unicorns']).pipeStderr('stderr.txt'); await execa('echo', ['unicorns'], {all:true}).pipeAll('all.txt'); ``` -### Redirect input from a file +#### Redirect input from a file ```js import {execa} from 'execa'; @@ -146,7 +120,7 @@ console.log(stdout); //=> 'unicorns' ``` -### Save and pipe output from a child process +#### Save and pipe output from a child process ```js import {execa} from 'execa'; @@ -157,7 +131,7 @@ console.log(stdout); // Also returns 'unicorns' ``` -### Pipe multiple processes +#### Pipe multiple processes ```js import {execa} from 'execa'; @@ -202,60 +176,7 @@ try { } ``` -### Cancelling a spawned process - -```js -import {execa} from 'execa'; - -const abortController = new AbortController(); -const subprocess = execa('node', [], {signal: abortController.signal}); - -setTimeout(() => { - abortController.abort(); -}, 1000); - -try { - await subprocess; -} catch (error) { - console.log(subprocess.killed); // true - console.log(error.isCanceled); // true -} -``` - -### Catching an error with the sync method - -```js -import {execaSync} from 'execa'; - -try { - execaSync('unknown', ['command']); -} catch (error) { - console.log(error); - /* - { - message: 'Command failed with ENOENT: unknown command spawnSync unknown ENOENT', - errno: -2, - code: 'ENOENT', - syscall: 'spawnSync unknown', - path: 'unknown', - spawnargs: ['command'], - originalMessage: 'spawnSync unknown ENOENT', - shortMessage: 'Command failed with ENOENT: unknown command spawnSync unknown ENOENT', - command: 'unknown command', - escapedCommand: 'unknown command', - stdout: '', - stderr: '', - all: '', - failed: true, - timedOut: false, - isCanceled: false, - killed: false - } - */ -} -``` - -### Kill a process +### Graceful termination Using SIGTERM, and after 2 seconds, kill it with SIGKILL. @@ -776,13 +697,33 @@ const run = async () => { console.log(await pRetry(run, {retries: 5})); ``` +### Cancelling a spawned process + +```js +import {execa} from 'execa'; + +const abortController = new AbortController(); +const subprocess = execa('node', [], {signal: abortController.signal}); + +setTimeout(() => { + abortController.abort(); +}, 1000); + +try { + await subprocess; +} catch (error) { + console.log(subprocess.killed); // true + console.log(error.isCanceled); // true +} +``` + ### Execute the current package's binary ```js -import {getBinPathSync} from 'get-bin-path'; +import {getBinPath} from 'get-bin-path'; -const binPath = getBinPathSync(); -const subprocess = execa(binPath); +const binPath = await getBinPath(); +await execa(binPath); ``` `execa` can be combined with [`get-bin-path`](https://github.com/ehmicky/get-bin-path) to test the current package's binary. As opposed to hard-coding the path to the binary, this validates that the `package.json` `bin` field is correctly set up. From 4343175a68e366b42643f875fe4bc37ebea17736 Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 5 Mar 2023 14:09:52 +0000 Subject: [PATCH 2/3] Fix documentation of Options --- readme.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index 76016469c9..e2a66e9a27 100644 --- a/readme.md +++ b/readme.md @@ -68,13 +68,21 @@ console.log(stdout); ```js import {$} from 'execa'; +await $({stdio: 'inherit'})`echo unicorns`; +//=> 'unicorns' +``` + +#### Shared options + +```js +import {$} from 'execa'; + const $$ = $({stdio: 'inherit'}); await $$`echo unicorns`; //=> 'unicorns' -await $$({shell: true})`echo unicorns && echo rainbows`; -//=> 'unicorns' +await $$`echo rainbows`; //=> 'rainbows' ``` From ee1c12552c47ad69226a1fed81267724f7fed47b Mon Sep 17 00:00:00 2001 From: ehmicky Date: Sun, 5 Mar 2023 14:10:44 +0000 Subject: [PATCH 3/3] Fix readme --- readme.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/readme.md b/readme.md index e2a66e9a27..60bd92ca52 100644 --- a/readme.md +++ b/readme.md @@ -53,14 +53,19 @@ For more information about Execa scripts, please see [this page](docs/scripts.md ```js import {$} from 'execa'; -const unicorns = await $`echo unicorns`; -const {stdout} = await $`echo ${unicorns}${'!'}}`; -console.log(stdout); -//=> 'unicorns!' +const branch = await $`git branch --show-current` +await $`dep deploy --branch=${branch}` +``` + +#### Multiple arguments + +```js +import {$} from 'execa'; -const {stdout} = await $`echo ${['unicorns', 'rainbows']}`; +const args = ['unicorns', '&', 'rainbows!'] +const {stdout} = await $`echo ${args}`; console.log(stdout); -//=> 'unicorns rainbows' +//=> 'unicorns & rainbows!' ``` #### With options