1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
|
# @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.
|
