mirror of
https://github.com/nodejs/node.git
synced 2025-05-16 07:33:15 +00:00
dc05c70c8f
PR-URL: https://github.com/nodejs/node/pull/35908 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Ruy Adorno <ruyadorno@github.com> Reviewed-By: Guy Bedford <guybedford@gmail.com>
67 lines
2.5 KiB
Markdown
67 lines
2.5 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.
|
|
|
|
Note: When the current user is root, this will use
|
|
[`infer-owner`](http://npm.im/infer-owner) to find the owner of the current
|
|
working directory, and run with that effective uid/gid. Otherwise, it runs
|
|
as the current user always. (This helps prevent doing git checkouts and
|
|
such, and leaving root-owned files lying around in user-owned locations.)
|
|
|
|
## USAGE
|
|
|
|
```js
|
|
const promiseSpawn = require('@npmcli/promise-spawn')
|
|
|
|
promiseSpawn('ls', [ '-laF', 'some/dir/*.js' ], {
|
|
cwd: '/tmp/some/path', // defaults to process.cwd()
|
|
stdioString: false, // 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,
|
|
// but uid/gid will be ignored and set by infer-owner if relevant.
|
|
}, {
|
|
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 `false`. 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.
|
|
- Any other options for `child_process.spawn` can be passed as well, but
|
|
note that `uid` and `gid` will be overridden by the owner of the cwd when
|
|
run as root on Unix systems, or `null` otherwise.
|