| 1 | # @npmcli/promise-spawn
|
|---|
| 2 |
|
|---|
| 3 | Spawn processes the way the npm cli likes to do. Give it some options,
|
|---|
| 4 | it'll give you a Promise that resolves or rejects based on the results of
|
|---|
| 5 | the execution.
|
|---|
| 6 |
|
|---|
| 7 | Note: When the current user is root, this will use
|
|---|
| 8 | [`infer-owner`](http://npm.im/infer-owner) to find the owner of the current
|
|---|
| 9 | working directory, and run with that effective uid/gid. Otherwise, it runs
|
|---|
| 10 | as the current user always. (This helps prevent doing git checkouts and
|
|---|
| 11 | such, and leaving root-owned files lying around in user-owned locations.)
|
|---|
| 12 |
|
|---|
| 13 | ## USAGE
|
|---|
| 14 |
|
|---|
| 15 | ```js
|
|---|
| 16 | const promiseSpawn = require('@npmcli/promise-spawn')
|
|---|
| 17 |
|
|---|
| 18 | promiseSpawn('ls', [ '-laF', 'some/dir/*.js' ], {
|
|---|
| 19 | cwd: '/tmp/some/path', // defaults to process.cwd()
|
|---|
| 20 | stdioString: false, // stdout/stderr as strings rather than buffers
|
|---|
| 21 | stdio: 'pipe', // any node spawn stdio arg is valid here
|
|---|
| 22 | // any other arguments to node child_process.spawn can go here as well,
|
|---|
| 23 | // but uid/gid will be ignored and set by infer-owner if relevant.
|
|---|
| 24 | }, {
|
|---|
| 25 | extra: 'things',
|
|---|
| 26 | to: 'decorate',
|
|---|
| 27 | the: 'result',
|
|---|
| 28 | }).then(result => {
|
|---|
| 29 | // {code === 0, signal === null, stdout, stderr, and all the extras}
|
|---|
| 30 | console.log('ok!', result)
|
|---|
| 31 | }).catch(er => {
|
|---|
| 32 | // er has all the same properties as the result, set appropriately
|
|---|
| 33 | console.error('failed!', er)
|
|---|
| 34 | })
|
|---|
| 35 | ```
|
|---|
| 36 |
|
|---|
| 37 | ## API
|
|---|
| 38 |
|
|---|
| 39 | ### `promiseSpawn(cmd, args, opts, extra)` -> `Promise`
|
|---|
| 40 |
|
|---|
| 41 | Run the command, return a Promise that resolves/rejects based on the
|
|---|
| 42 | process result.
|
|---|
| 43 |
|
|---|
| 44 | Result or error will be decorated with the properties in the `extra`
|
|---|
| 45 | object. You can use this to attach some helpful info about _why_ the
|
|---|
| 46 | command is being run, if it makes sense for your use case.
|
|---|
| 47 |
|
|---|
| 48 | If `stdio` is set to anything other than `'inherit'`, then the result/error
|
|---|
| 49 | will be decorated with `stdout` and `stderr` values. If `stdioString` is
|
|---|
| 50 | set to `true`, these will be strings. Otherwise they will be Buffer
|
|---|
| 51 | objects.
|
|---|
| 52 |
|
|---|
| 53 | Returned promise is decorated with the `stdin` stream if the process is set
|
|---|
| 54 | to pipe from `stdin`. Writing to this stream writes to the `stdin` of the
|
|---|
| 55 | spawned process.
|
|---|
| 56 |
|
|---|
| 57 | #### Options
|
|---|
| 58 |
|
|---|
| 59 | - `stdioString` Boolean, default `false`. Return stdout/stderr output as
|
|---|
| 60 | strings rather than buffers.
|
|---|
| 61 | - `cwd` String, default `process.cwd()`. Current working directory for
|
|---|
| 62 | running the script. Also the argument to `infer-owner` to determine
|
|---|
| 63 | effective uid/gid when run as root on Unix systems.
|
|---|
| 64 | - Any other options for `child_process.spawn` can be passed as well, but
|
|---|
| 65 | note that `uid` and `gid` will be overridden by the owner of the cwd when
|
|---|
| 66 | run as root on Unix systems, or `null` otherwise.
|
|---|
