autoinstallers/install/secu/make/node_modules/cmd-promise/README.md

165 lines
4.8 KiB
Markdown
Raw Normal View History

2022-05-31 19:28:17 -04:00
# CMD Promise
Node command line interface with a simple Promise based API.
[![JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)
[![Version](https://img.shields.io/npm/v/cmd-promise.svg)](https://www.npmjs.com/package/cmd-promise)
[![Downloads](https://img.shields.io/npm/dt/cmd-promise.svg)](https://www.npmjs.com/package/cmd-promise)
Inspired by [node-cmd](https://github.com/RIAEvangelist/node-cmd).
## Features
- Simple Promise based API.
- Single or multiple commands in one call.
- Passes the [`exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback) node options through.
- Returns an `object` containing both `stdout` and `stderr`.
- Optionally return the [child process](https://nodejs.org/api/child_process.html#child_process_class_childprocess) instead of the output.
- Zero dependencies.
## Requirments
Uses native node promises (including `Promise.all` with generic iterables) so requires at least node version 4.0.0. See [http://node.green/](http://node.green/#ES2015-built-ins-Promise).
## Install
`npm install cmd-promise`
## Examples
### Single command
```js
const cmd = require('cmd-promise')
cmd(`node -v`).then(out => {
console.log('out =', out)
}).catch(err => {
console.log('err =', err)
})
// out = { stdout: 'v4.2.2\r\n', stderr: '' }
```
### Multiple commands
```js
const cmd = require('cmd-promise')
const commands = `
node -v
npm -v
`
cmd(commands).then(out => {
console.log('out =', out)
}).catch(err => {
console.log('err =', err)
})
// out = [ { stdout: 'v4.2.2\r\n', stderr: '' }, { stdout: '4.4.1\n', stderr: '' } ]
// out[0].stdout = v4.2.2
```
### More involved example
```js
const semver = require('semver') // https://github.com/npm/node-semver
const cmd = require('cmd-promise')
const commands = `
npm view npm version
npm -v
`
cmd(commands).then(out => {
return {
npm: out[0].stdout.replace(/\n/g, ''),
me: out[1].stdout.replace(/\n/g, '')
}
}).then(versions => {
if (semver.lt(versions.me, versions.npm)) {
console.log(`My npm version is out of date (npm install npm@latest -g).`)
} else {
console.log(`My npm version is up to date! :-)`)
}
}).catch(err => {
console.log('err =', err)
})
```
### Return the child process instead
```js
const cmd = require('../cmd-promise')
const options = { returnProcess: true }
cmd(`node -v`, options).then(childProcess => {
console.log('pid =', childProcess.pid)
childProcess.stdout.on('data', stdout => {
console.log('stdout =', stdout)
})
childProcess.stderr.on('data', stderr => {
console.log('stderr =', stderr)
})
}).catch(err => {
console.log('err =', err)
})
```
### Pass exec() options
Pass [`child_process.exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback) options as defined in the node docs.
```js
const cmd = require('../cmd-promise')
const execOptions = { timeout: 1000 }
cmd(`node -v`, {}, execOptions).then(out => {
console.log('out =', out)
}).catch(err => {
console.log('err =', err)
})
```
## API
`cmd(commands [,options] [,execOptions]) -> Promise`
- **commands** (string) Single or multiple line string of commands to execute.
- **options** (object)
- `returnProcess` (boolean) Return the child process instead of waiting on and returning the outcome. Default is `false`.
- **execOptions** (object) Options as passed to the [`exec()`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback) method of the [child_process](https://nodejs.org/api/child_process.html) node module.
Returns a Promise.
For **single** commands the promises return value is an `object` containing `stdout` and `stderr` properties. If `options.returnProcess` is set to `true` the return value is the [child process](https://nodejs.org/api/child_process.html#child_process_class_childprocess) instead.
```js
const cmd = require('cmd-promise')
cmd(`node -v`).then(out => {
console.log('out.stdout =', out.stdout) // v4.2.2
console.log('out.stderr =', out.stderr)
})
```
For **multiple line** command calls the promises return value is an array of `object`'s containing `stdout` and `stderr` properties. If `options.returnProcess` is set to `true` the return value is an array of [child processes](https://nodejs.org/api/child_process.html#child_process_class_childprocess) instead.
```js
const cmd = require('cmd-promise')
const commands = `
node -v
npm -v
`
cmd(commands).then(out => {
console.log('out[0] =', out[0]) // result from 'node -v'
console.log('out[1] =', out[1]) // result from 'npm -v'
})
```