@@ -55,6 +55,10 @@ Project is [semantically](https://semver.org) versioned & automatically released
5555## Table of Contents
5656
5757- [ Install] ( #install )
58+ - [ API] ( #api )
59+ - [ .exec] ( #exec )
60+ - [ .shell] ( #shell )
61+ - [ execa] ( #execa )
5862- [ Contributing] ( #contributing )
5963 - [ Guides and Community] ( #guides-and-community )
6064 - [ Support the project] ( #support-the-project )
@@ -74,7 +78,142 @@ _We highly recommend to use Yarn when you think to contribute to this project._
7478$ yarn add @tunnckocore/execa
7579```
7680
77- () => include(process.cwd() + '/.verb.md')
81+ <!-- docks-start -->
82+
83+ ## API
84+
85+ _ Generated using [ jest-runner-docs] ( https://npmjs.com/package/jest-runner-docs ) ._
86+
87+ ### [ .exec] ( ./src/index.js#L39 )
88+
89+ Uses [ execa] [ ] v2, ` execa.command() ` method.
90+ As stated there, think of it as mix of ` child_process ` 's ` .execFile ` and ` .spawn ` .
91+ It is pretty similar to the ` .shell ` method too, but only visually because
92+ it does not uses the system's shell, meaning it does not have access to
93+ the system's environment variables. You also can control concurrency by
94+ passing ` options.concurrency ` option. For example, pass ` concurrency: 1 ` to run in series
95+ instead of in parallel which is the default behavior.
96+
97+ ** Signature**
98+
99+ ``` ts
100+ function (cmds , options )
101+ ```
102+
103+ ** Params **
104+
105+ - ` cmds ` - a commands to execute in parallel or series
106+ - ` options ` - directly passed to [execa ][] and so to ` child_process `
107+ - ` returns ` - resolved or rejected promises
108+
109+ > It also can accept array of multiple strings of commands that will be
110+ > executed in series or in parallel (default ).
111+
112+ ** Example **
113+
114+ ` ` ` js
115+ import { exec } from '@tunnckocore/execa';
116+ // or
117+ // const { exec } = require('@tunnckocore/execa');
118+
119+ async function main() {
120+ await exec('echo "hello world"', { stdio: 'inherit' });
121+
122+ // executes in series (because ` concurrency ` option is set to ` 1 ` )
123+ await exec(
124+ [
125+ 'prettier-eslint --write foobar.js',
126+ 'eslint --format codeframe foobar.js --fix',
127+ ],
128+ { stdio: 'inherit', preferLocal: true, concurrency: 1 },
129+ );
130+ }
131+
132+ main();
133+ ` ` `
134+
135+ ### [.shell ](./ src / index .js #L94 )
136+
137+ Similar to ` exec ` , but also ** can ** access the system ' s environment variables from the command.
138+
139+ ** Signature **
140+
141+ ` ` ` ts
142+ function(cmds, options)
143+ ` ` `
144+
145+ ** Params **
146+
147+ - ` cmds ` - a commands to execute in parallel or series
148+ - ` options ` - directly passed to ` execa `
149+ - ` returns ` - resolved or rejected promises
150+
151+ ** Example **
152+
153+ ` ` ` js
154+ import { shell } from '@tunnckocore/execa';
155+ // or
156+ // const { shell } = require('@tunnckocore/execa');
157+
158+ async function main() {
159+ // executes in series
160+ await shell(['echo unicorns', 'echo "foo-$HOME-bar"', 'echo dragons'], {
161+ stdio: 'inherit',
162+ });
163+
164+ // exits with code 3
165+ try {
166+ await shell(['exit 3', 'echo nah']);
167+ } catch (er) {
168+ console.error(er);
169+ // => {
170+ // message: 'Command failed: /bin/sh -c exit 3'
171+ // killed: false,
172+ // code: 3,
173+ // signal: null,
174+ // cmd: '/bin/sh -c exit 3',
175+ // stdout: '',
176+ // stderr: '',
177+ // timedOut: false
178+ // }
179+ }
180+ }
181+
182+ main();
183+ ` ` `
184+
185+ ### [execa ](./ src / index .js #L120 )
186+
187+ Same as [execa ][]' s default export, see its documentation.
188+ Think of this as a mix of ` child_process.execFile() ` and ` child_process.spawn() ` .
189+
190+ ** Signature **
191+
192+ ` ` ` ts
193+ function(file, args, options)
194+ ` ` `
195+
196+ ** Params **
197+
198+ - ` file ` - executable to run
199+ - ` args ` - arguments / flags to be passed to ` file `
200+ - ` options ` - optional options , passed to ` child_process ` ' s methods
201+
202+ ** Example **
203+
204+ ` ` ` js
205+ import execa from '@tunnckocore/execa';
206+ // or
207+ // const execa = require('@tunnckocore/execa');
208+
209+ async function main() {
210+ await execa('npm', ['install', '--save-dev', 'react'], { stdio: 'inherit' });
211+ }
212+
213+ main();
214+ ` ` `
215+
216+ < ! -- docks - end -- >
78217
79218** [back to top ](#readme )**
80219
@@ -207,3 +346,4 @@ Released under the [MPL-2.0 License][license-url].
207346[tunnckocore_security ]: https :// badgen.net/https/liam-badge-daknys6gadky.runkit.sh/com/security/tunnckocore?label&color=ed1848&icon=https://svgshare.com/i/Dt6.svg
208347[tunnckocore_opensource ]: https :// badgen.net/https/liam-badge-daknys6gadky.runkit.sh/com/opensource/tunnckocore?label&color=ff7a2f&icon=https://svgshare.com/i/Dt6.svg
209348[tunnckocore_newsletter ]: https :// badgen.net/https/liam-badge-daknys6gadky.runkit.sh/com/newsletter/tunnckocore?label&color=5199FF&icon=https://svgshare.com/i/Dt6.svg
349+ [execa ]: https :// github.com/sindresorhus/execa
0 commit comments