80 lines
3 KiB
Markdown
80 lines
3 KiB
Markdown
|
# @npmcli/promise-spawn
|
||
|
|
|
||
|
|
Spawn processes the way the npm cli likes to do. Give it some options,
|
||
|
|
it'll give you a Promise that resolves or rejects based on the results of
|
||
|
|
the execution.
|
||
|
|
|
||
|
|
## USAGE
|
||
|
|
|
||
|
|
```js
|
||
|
|
const promiseSpawn = require('@npmcli/promise-spawn')
|
||
|
|
|
||
|
|
promiseSpawn('ls', [ '-laF', 'some/dir/*.js' ], {
|
||
|
|
cwd: '/tmp/some/path', // defaults to process.cwd()
|
||
|
|
stdioString: true, // stdout/stderr as strings rather than buffers
|
||
|
|
stdio: 'pipe', // any node spawn stdio arg is valid here
|
||
|
|
// any other arguments to node child_process.spawn can go here as well,
|
||
|
|
}, {
|
||
|
|
extra: 'things',
|
||
|
|
to: 'decorate',
|
||
|
|
the: 'result',
|
||
|
|
}).then(result => {
|
||
|
|
// {code === 0, signal === null, stdout, stderr, and all the extras}
|
||
|
|
console.log('ok!', result)
|
||
|
|
}).catch(er => {
|
||
|
|
// er has all the same properties as the result, set appropriately
|
||
|
|
console.error('failed!', er)
|
||
|
|
})
|
||
|
|
```
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
### `promiseSpawn(cmd, args, opts, extra)` -> `Promise`
|
||
|
|
|
||
|
|
Run the command, return a Promise that resolves/rejects based on the
|
||
|
|
process result.
|
||
|
|
|
||
|
|
Result or error will be decorated with the properties in the `extra`
|
||
|
|
object. You can use this to attach some helpful info about _why_ the
|
||
|
|
command is being run, if it makes sense for your use case.
|
||
|
|
|
||
|
|
If `stdio` is set to anything other than `'inherit'`, then the result/error
|
||
|
|
will be decorated with `stdout` and `stderr` values. If `stdioString` is
|
||
|
|
set to `true`, these will be strings. Otherwise they will be Buffer
|
||
|
|
objects.
|
||
|
|
|
||
|
|
Returned promise is decorated with the `stdin` stream if the process is set
|
||
|
|
to pipe from `stdin`. Writing to this stream writes to the `stdin` of the
|
||
|
|
spawned process.
|
||
|
|
|
||
|
|
#### Options
|
||
|
|
|
||
|
|
- `stdioString` Boolean, default `true`. Return stdout/stderr output as
|
||
|
|
strings rather than buffers.
|
||
|
|
- `cwd` String, default `process.cwd()`. Current working directory for
|
||
|
|
running the script. Also the argument to `infer-owner` to determine
|
||
|
|
effective uid/gid when run as root on Unix systems.
|
||
|
|
- `shell` Boolean or String. If false, no shell is used during spawn. If true,
|
||
|
|
the system default shell is used. If a String, that specific shell is used.
|
||
|
|
When a shell is used, the given command runs from within that shell by
|
||
|
|
concatenating the command and its escaped arguments and running the result.
|
||
|
|
This option is _not_ passed through to `child_process.spawn`.
|
||
|
|
- Any other options for `child_process.spawn` can be passed as well.
|
||
|
|
|
||
|
|
### `promiseSpawn.open(arg, opts, extra)` -> `Promise`
|
||
|
|
|
||
|
|
Use the operating system to open `arg` with a default program. This is useful
|
||
|
|
for things like opening the user's default browser to a specific URL.
|
||
|
|
|
||
|
|
Depending on the platform in use this will use `start` (win32), `open` (darwin)
|
||
|
|
or `xdg-open` (everything else). In the case of Windows Subsystem for Linux we
|
||
|
|
use the default win32 behavior as it is much more predictable to open the arg
|
||
|
|
using the host operating system.
|
||
|
|
|
||
|
|
#### Options
|
||
|
|
|
||
|
|
Options are identical to `promiseSpawn` except for the following:
|
||
|
|
|
||
|
|
- `command` String, the command to use to open the file in question. Default is
|
||
|
|
one of `start`, `open` or `xdg-open` depending on platform in use.
|