commander 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -7,11 +7,32 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 <!-- markdownlint-disable MD024 -->
 
+## [4.1.0] (2020-01-06)
+
+### Added
+
+- two routines to change how option values are handled, and eliminate name clashes with command properties ([#933] [#1102])
+  - see storeOptionsAsProperties and passCommandToAction in README
+- `.parseAsync` to use instead of `.parse` if supply async action handlers ([#806] [#1118])
+
+### Fixed
+
+- Remove trailing blanks from wrapped help text ([#1096])
+
+### Changed
+
+- update dependencies
+- extend security coverage for Commander 2.x to 2020-02-03
+- improvements to README
+- improvements to TypeScript definition documentation
+- move old versions out of main CHANGELOG
+- removed explicit use of `ts-node` in tests
+
 ## [4.0.1] (2019-11-12)
 
 ### Fixed
 
-* display help when requested, even if there are missing required options [(#1091)]
+* display help when requested, even if there are missing required options ([#1091])
 
 ## [4.0.0] (2019-11-02)
 
@@ -355,152 +376,16 @@ program
 
 * remove input methods (.prompt, .confirm, etc)
 
-## 1.3.2 / 2013-07-18
-
-* add support for sub-commands to co-exist with the original command
-
-## 1.3.1 / 2013-07-18
-
-* add quick .runningCommand hack so you can opt-out of other logic when running a sub command
-
-## 1.3.0 / 2013-07-09
-
-* add EACCES error handling
-* fix sub-command --help
-
-## 1.2.0 / 2013-06-13
-
-* allow "-" hyphen as an option argument
-* support for RegExp coercion
-
-## 1.1.1 / 2012-11-20
-
-* add more sub-command padding
-* fix .usage() when args are present. Closes #106
-
-## 1.1.0 / 2012-11-16
-
-* add git-style executable subcommand support. Closes #94
-
-## 1.0.5 / 2012-10-09
-
-* fix `--name` clobbering. Closes #92
-* fix examples/help. Closes #89
-
-## 1.0.4 / 2012-09-03
-
-* add `outputHelp()` method.
-
-## 1.0.3 / 2012-08-30
-
-* remove invalid .version() defaulting
-
-## 1.0.2 / 2012-08-24
-
-* add `--foo=bar` support [arv]
-* fix password on node 0.8.8. Make backward compatible with 0.6 [focusaurus]
-
-## 1.0.1 / 2012-08-03
-
-* fix issue #56
-* fix tty.setRawMode(mode) was moved to tty.ReadStream#setRawMode() (i.e. process.stdin.setRawMode())
-
-## 1.0.0 / 2012-07-05
-
-* add support for optional option descriptions
-* add defaulting of `.version()` to package.json's version
-
-## 0.6.1 / 2012-06-01
-
-* Added: append (yes or no) on confirmation
-* Added: allow node.js v0.7.x
-
-## 0.6.0 / 2012-04-10
-
-* Added `.prompt(obj, callback)` support. Closes #49
-* Added default support to .choose(). Closes #41
-* Fixed the choice example
-
-## 0.5.1 / 2011-12-20
-
-* Fixed `password()` for recent nodes. Closes #36
-
-## 0.5.0 / 2011-12-04
-
-* Added sub-command option support [itay]
-
-## 0.4.3 / 2011-12-04
-
-* Fixed custom help ordering. Closes #32
-
-## 0.4.2 / 2011-11-24
-
-* Added travis support
-* Fixed: line-buffered input automatically trimmed. Closes #31
-
-## 0.4.1 / 2011-11-18
-
-* Removed listening for "close" on --help
-
-## 0.4.0 / 2011-11-15
-
-* Added support for `--`. Closes #24
-
-## 0.3.3 / 2011-11-14
-
-* Fixed: wait for close event when writing help info [Jerry Hamlet]
-
-## 0.3.2 / 2011-11-01
-
-* Fixed long flag definitions with values [felixge]
-
-## 0.3.1 / 2011-10-31
-
-* Changed `--version` short flag to `-V` from `-v`
-* Changed `.version()` so it's configurable [felixge]
-
-## 0.3.0 / 2011-10-31
-
-* Added support for long flags only. Closes #18
-
-## 0.2.1 / 2011-10-24
-
-* "node": ">= 0.4.x < 0.7.0". Closes #20
-
-## 0.2.0 / 2011-09-26
-
-* Allow for defaults that are not just boolean. Default peassignment only occurs for --no-*, optional, and required arguments. [Jim Isaacs]
-
-## 0.1.0 / 2011-08-24
-
-* Added support for custom `--help` output
-
-## 0.0.5 / 2011-08-18
-
-* Changed: when the user enters nothing prompt for password again
-* Fixed issue with passwords beginning with numbers [NuckChorris]
-
-## 0.0.4 / 2011-08-15
-
-* Fixed `Commander#args`
-
-## 0.0.3 / 2011-08-15
-
-* Added default option value support
-
-## 0.0.2 / 2011-08-15
-
-* Added mask support to `Command#password(str[, mask], fn)`
-* Added `Command#password(str, fn)`
-
-## 0.0.1 / 2010-01-03
+## Older versions
 
-* Initial release
+* [1.x](./changelogs/CHANGELOG-1.md)
+* [0.x](./changelogs/CHANGELOG-0.md)
 
 [#599]: https://github.com/tj/commander.js/issues/599
 [#611]: https://github.com/tj/commander.js/issues/611
 [#697]: https://github.com/tj/commander.js/issues/697
 [#795]: https://github.com/tj/commander.js/issues/795
+[#806]: https://github.com/tj/commander.js/issues/806
 [#915]: https://github.com/tj/commander.js/issues/915
 [#938]: https://github.com/tj/commander.js/issues/938
 [#963]: https://github.com/tj/commander.js/issues/963
@@ -509,6 +394,7 @@ program
 [#987]: https://github.com/tj/commander.js/issues/987
 [#990]: https://github.com/tj/commander.js/issues/990
 [#991]: https://github.com/tj/commander.js/issues/991
+[#993]: https://github.com/tj/commander.js/issues/993
 [#999]: https://github.com/tj/commander.js/issues/999
 [#1010]: https://github.com/tj/commander.js/pull/1010
 [#1018]: https://github.com/tj/commander.js/pull/1018
@@ -526,6 +412,9 @@ program
 [#1071]: https://github.com/tj/commander.js/pull/1071
 [#1081]: https://github.com/tj/commander.js/pull/1081
 [#1091]: https://github.com/tj/commander.js/pull/1091
+[#1096]: https://github.com/tj/commander.js/pull/1096
+[#1102]: https://github.com/tj/commander.js/pull/1102
+[#1118]: https://github.com/tj/commander.js/pull/1118
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
 [4.0.1]: https://github.com/tj/commander.js/compare/v4.0.0..v4.0.1

package/Readme.md

@@ -11,7 +11,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
 
 - [Commander.js](#commanderjs)
   - [Installation](#installation)
-  - [Declaring _program_ variable](#declaring-program-variable)
+  - [Declaring program variable](#declaring-program-variable)
   - [Options](#options)
     - [Common option types, boolean and value](#common-option-types-boolean-and-value)
     - [Default option value](#default-option-value)
@@ -31,8 +31,9 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [.help(cb)](#helpcb)
   - [Custom event listeners](#custom-event-listeners)
   - [Bits and pieces](#bits-and-pieces)
+    - [Avoiding option name clashes](#avoiding-option-name-clashes)
     - [TypeScript](#typescript)
-    - [Node options such as `--harmony`](#node-options-such-as---harmony)
+    - [Node options such as --harmony](#node-options-such-as---harmony)
     - [Node debugging](#node-debugging)
     - [Override exit handling](#override-exit-handling)
   - [Examples](#examples)
@@ -70,6 +71,8 @@ Options are defined with the `.option()` method, also serving as documentation f
 
 The options can be accessed as properties on the Command object. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc. Multiple short flags may be combined as a single arg, for example `-abc` is equivalent to `-a -b -c`.
 
+See also optional new behaviour to [avoid name clashes](#avoiding-option-name-clashes).
+
 ### Common option types, boolean and value
 
 The two most used option types are a boolean flag, and an option which takes a value (declared using angle brackets). Both are `undefined` unless specified on command line.
@@ -374,6 +377,19 @@ program
 program.parse(process.argv)
 ```
 
+You may supply an `async` action handler, in which case you call `.parseAsync` rather than `.parse`.
+
+```js
+async function run() { /* code goes here */ }
+
+async function main() {
+  program
+    .command('run')
+    .action(run);
+  await program.parseAsync(process.argv);
+}
+```
+
 A command's options on the command line are validated when the command is used. Any unknown options will be reported as an error. However, if an action-based command does not define an action, then the options are not validated.
 
 Configuration options can be passed with the call to `.command()`. Specifying `true` for `opts.noHelp` will remove the command from the generated help output.
@@ -550,6 +566,43 @@ program.on('command:*', function () {
 
 ## Bits and pieces
 
+### Avoiding option name clashes
+
+The original and default behaviour is that the option values are stored
+as properties on the program, and the action handler is passed a
+command object with the options values stored as properties.
+This is very convenient to code, but the downside is possible clashes with
+existing properties of Command.
+
+There are two new routines to change the behaviour, and the default behaviour may change in the future:
+
+- `storeOptionsAsProperties`: whether to store option values as properties on command object, or store separately (specify false) and access using `.opts()`
+- `passCommandToAction`: whether to pass command to action handler,
+or just the options (specify false)
+
+```js
+// file: ./examples/storeOptionsAsProperties.action.js
+program
+  .storeOptionsAsProperties(false)
+  .passCommandToAction(false);
+
+program
+  .name('my-program-name')
+  .option('-n,--name <name>');
+
+program
+  .command('show')
+  .option('-a,--action <action>')
+  .action((options) => {
+    console.log(options.action);
+  });
+
+program.parse(process.argv);
+
+const programOptions = program.opts();
+console.log(programOptions.name);
+```
+
 ### TypeScript
 
 The Commander package includes its TypeScript Definition file, but also requires the node types which you need to install yourself. e.g.
@@ -648,7 +701,8 @@ More Demos can be found in the [examples](https://github.com/tj/commander.js/tre
 
 ## Support
 
-Commander is supported on Node 8 and above. (Commander is likely to still work on older versions of Node, but is not tested below Node 8.)
+Commander 4.x is supported on Node 8 and above, and is likely to work with Node 6 but not tested.
+(For versions of Node below Node 6, use Commander 3.x or 2.x.)
 
 The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.
 

package/index.js

@@ -115,7 +115,7 @@ exports.CommanderError = CommanderError;
 /**
  * Initialize a new `Command`.
  *
- * @param {String} name
+ * @param {String} [name]
  * @api public
  */
 
@@ -126,6 +126,10 @@ function Command(name) {
   this._allowUnknownOption = false;
   this._args = [];
   this._name = name || '';
+  this._optionValues = {};
+  this._storeOptionsAsProperties = true; // backwards compatible by default
+  this._passCommandToAction = true; // backwards compatible by default
+  this._actionResults = [];
 
   this._helpFlags = '-h, --help';
   this._helpDescription = 'output usage information';
@@ -151,7 +155,7 @@ function Command(name) {
  *      // Command implemented using separate executable file (description is second parameter to `.command`)
  *      program
  *        .command('start <service>', 'start named service')
- *        .command('stop [service]', 'stop named serice, or all if no name supplied');
+ *        .command('stop [service]', 'stop named service, or all if no name supplied');
  *
  * @param {string} nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
  * @param {Object|string} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable)
@@ -183,6 +187,8 @@ Command.prototype.command = function(nameAndArgs, actionOptsOrExecDesc, execOpts
   cmd._helpShortFlag = this._helpShortFlag;
   cmd._helpLongFlag = this._helpLongFlag;
   cmd._exitCallback = this._exitCallback;
+  cmd._storeOptionsAsProperties = this._storeOptionsAsProperties;
+  cmd._passCommandToAction = this._passCommandToAction;
 
   cmd._executableFile = opts.executableFile; // Custom name for executable file
   this.commands.push(cmd);
@@ -323,7 +329,7 @@ Command.prototype.action = function(fn) {
     var parsed = self.parseOptions(unknown);
 
     // Output help if necessary
-    outputHelpIfNecessary(self, parsed.unknown);
+    outputHelpIfRequested(self, parsed.unknown);
     self._checkForMissingMandatoryOptions();
 
     // If there are still any unknown options, then we simply
@@ -351,13 +357,23 @@ Command.prototype.action = function(fn) {
     // The .action callback takes an extra parameter which is the command itself.
     var expectedArgsCount = self._args.length;
     var actionArgs = args.slice(0, expectedArgsCount);
-    actionArgs[expectedArgsCount] = self;
+    if (self._passCommandToAction) {
+      actionArgs[expectedArgsCount] = self;
+    } else {
+      actionArgs[expectedArgsCount] = self.opts();
+    }
     // Add the extra arguments so available too.
     if (args.length > expectedArgsCount) {
       actionArgs.push(args.slice(expectedArgsCount));
     }
 
-    fn.apply(self, actionArgs);
+    const actionResult = fn.apply(self, actionArgs);
+    // Remember result in case it is async. Assume parseAsync getting called on root.
+    let rootCommand = self;
+    while (rootCommand.parent) {
+      rootCommand = rootCommand.parent;
+    }
+    rootCommand._actionResults.push(actionResult);
   };
   var parent = this.parent || this;
   var name = parent === this ? '*' : this._name;
@@ -405,12 +421,12 @@ Command.prototype._optionEx = function(config, flags, description, fn, defaultVa
   if (option.negate || option.optional || option.required || typeof defaultValue === 'boolean') {
     // when --no-foo we make sure default is true, unless a --foo option is already defined
     if (option.negate) {
-      var opts = self.opts();
-      defaultValue = Object.prototype.hasOwnProperty.call(opts, name) ? opts[name] : true;
+      const positiveLongFlag = option.long.replace(/^--no-/, '--');
+      defaultValue = self.optionFor(positiveLongFlag) ? self._getOptionValue(name) : true;
     }
     // preassign only if we have a default
     if (defaultValue !== undefined) {
-      self[name] = defaultValue;
+      self._setOptionValue(name, defaultValue);
       option.defaultValue = defaultValue;
     }
   }
@@ -423,22 +439,22 @@ Command.prototype._optionEx = function(config, flags, description, fn, defaultVa
   this.on('option:' + oname, function(val) {
     // coercion
     if (val !== null && fn) {
-      val = fn(val, self[name] === undefined ? defaultValue : self[name]);
+      val = fn(val, self._getOptionValue(name) === undefined ? defaultValue : self._getOptionValue(name));
     }
 
     // unassigned or boolean value
-    if (typeof self[name] === 'boolean' || typeof self[name] === 'undefined') {
+    if (typeof self._getOptionValue(name) === 'boolean' || typeof self._getOptionValue(name) === 'undefined') {
       // if no value, negate false, and we have a default, then use it!
       if (val == null) {
-        self[name] = option.negate
+        self._setOptionValue(name, option.negate
           ? false
-          : defaultValue || true;
+          : defaultValue || true);
       } else {
-        self[name] = val;
+        self._setOptionValue(name, val);
       }
     } else if (val !== null) {
       // reassign
-      self[name] = option.negate ? false : val;
+      self._setOptionValue(name, option.negate ? false : val);
     }
   });
 
@@ -532,7 +548,70 @@ Command.prototype.allowUnknownOption = function(arg) {
 };
 
 /**
- * Parse `argv`, settings options and invoking commands when defined.
+  * Whether to store option values as properties on command object,
+  * or store separately (specify false). In both cases the option values can be accessed using .opts().
+  *
+  * @param {boolean} value
+  * @return {Command} Command for chaining
+  * @api public
+  */
+
+Command.prototype.storeOptionsAsProperties = function(value) {
+  this._storeOptionsAsProperties = (value === undefined) || value;
+  if (this.options.length) {
+    // This is for programmer, not end user.
+    console.error('Commander usage error: call storeOptionsAsProperties before adding options');
+  }
+  return this;
+};
+
+/**
+  * Whether to pass command to action handler,
+  * or just the options (specify false).
+  *
+  * @param {boolean} value
+  * @return {Command} Command for chaining
+  * @api public
+  */
+
+Command.prototype.passCommandToAction = function(value) {
+  this._passCommandToAction = (value === undefined) || value;
+  return this;
+};
+
+/**
+ * Store option value
+ *
+ * @param {String} key
+ * @param {Object} value
+ * @api private
+ */
+
+Command.prototype._setOptionValue = function(key, value) {
+  if (this._storeOptionsAsProperties) {
+    this[key] = value;
+  } else {
+    this._optionValues[key] = value;
+  }
+};
+
+/**
+ * Retrieve option value
+ *
+ * @param {String} key
+ * @return {Object} value
+ * @api private
+ */
+
+Command.prototype._getOptionValue = function(key) {
+  if (this._storeOptionsAsProperties) {
+    return this[key];
+  }
+  return this._optionValues[key];
+};
+
+/**
+ * Parse `argv`, setting options and invoking commands when defined.
  *
  * @param {Array} argv
  * @return {Command} for chaining
@@ -616,13 +695,27 @@ Command.prototype.parse = function(argv) {
   return result;
 };
 
+/**
+ * Parse `argv`, setting options and invoking commands when defined.
+ *
+ * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise.
+ *
+ * @param {Array} argv
+ * @return {Promise}
+ * @api public
+ */
+Command.prototype.parseAsync = function(argv) {
+  this.parse(argv);
+  return Promise.all(this._actionResults);
+};
+
 /**
  * Execute a sub-command executable.
  *
  * @param {Array} argv
  * @param {Array} args
  * @param {Array} unknown
- * @param {String} specifySubcommand
+ * @param {String} executableFile
  * @api private
  */
 
@@ -801,7 +894,7 @@ Command.prototype.parseArgs = function(args, unknown) {
       this.emit('command:*', args, unknown);
     }
   } else {
-    outputHelpIfNecessary(this, unknown);
+    outputHelpIfRequested(this, unknown);
 
     // If there were no args and we have unknown options,
     // then they are extraneous and we need to error.
@@ -843,7 +936,7 @@ Command.prototype._checkForMissingMandatoryOptions = function() {
   // Walk up hierarchy so can call from action handler after checking for displaying help.
   for (var cmd = this; cmd; cmd = cmd.parent) {
     cmd.options.forEach((anOption) => {
-      if (anOption.mandatory && (cmd[anOption.attributeName()] === undefined)) {
+      if (anOption.mandatory && (cmd._getOptionValue(anOption.attributeName()) === undefined)) {
         cmd.missingMandatoryOptionValue(anOption);
       }
     });
@@ -855,7 +948,7 @@ Command.prototype._checkForMissingMandatoryOptions = function() {
  * void of these options.
  *
  * @param {Array} argv
- * @return {Array}
+ * @return {{args: Array, unknown: Array}}
  * @api public
  */
 
@@ -936,14 +1029,19 @@ Command.prototype.parseOptions = function(argv) {
  * @api public
  */
 Command.prototype.opts = function() {
-  var result = {},
-    len = this.options.length;
-
-  for (var i = 0; i < len; i++) {
-    var key = this.options[i].attributeName();
-    result[key] = key === this._versionOptionName ? this._version : this[key];
+  if (this._storeOptionsAsProperties) {
+    // Preserve original behaviour so backwards compatible when still using properties
+    var result = {},
+      len = this.options.length;
+
+    for (var i = 0; i < len; i++) {
+      var key = this.options[i].attributeName();
+      result[key] = key === this._versionOptionName ? this._version : this[key];
+    }
+    return result;
   }
-  return result;
+
+  return this._optionValues;
 };
 
 /**
@@ -962,8 +1060,8 @@ Command.prototype.missingArgument = function(name) {
 /**
  * `Option` is missing an argument, but received `flag` or nothing.
  *
- * @param {String} option
- * @param {String} flag
+ * @param {Option} option
+ * @param {String} [flag]
  * @api private
  */
 
@@ -981,7 +1079,7 @@ Command.prototype.optionMissingArgument = function(option, flag) {
 /**
  * `Option` does not have a value, and is a mandatory option.
  *
- * @param {String} option
+ * @param {Option} option
  * @api private
  */
 
@@ -1041,9 +1139,10 @@ Command.prototype.version = function(str, flags, description) {
   var versionOption = new Option(flags, description);
   this._versionOptionName = versionOption.long.substr(2) || 'version';
   this.options.push(versionOption);
+  var self = this;
   this.on('option:' + this._versionOptionName, function() {
     process.stdout.write(str + '\n');
-    this._exit(0, 'commander.version', str);
+    self._exit(0, 'commander.version', str);
   });
   return this;
 };
@@ -1052,7 +1151,7 @@ Command.prototype.version = function(str, flags, description) {
  * Set the description to `str`.
  *
  * @param {String} str
- * @param {Object} argsDescription
+ * @param {Object} [argsDescription]
  * @return {String|Command}
  * @api public
  */
@@ -1089,7 +1188,7 @@ Command.prototype.alias = function(alias) {
 /**
  * Set / get the command usage `str`.
  *
- * @param {String} str
+ * @param {String} [str]
  * @return {String|Command}
  * @api public
  */
@@ -1112,7 +1211,7 @@ Command.prototype.usage = function(str) {
 /**
  * Get or set the name of the command
  *
- * @param {String} str
+ * @param {String} [str]
  * @return {String|Command}
  * @api public
  */
@@ -1429,7 +1528,7 @@ function wrap(str, width, indent) {
     if (line.slice(-1) === '\n') {
       line = line.slice(0, line.length - 1);
     }
-    return ((i > 0 && indent) ? Array(indent + 1).join(' ') : '') + line;
+    return ((i > 0 && indent) ? Array(indent + 1).join(' ') : '') + line.trimRight();
   }).join('\n');
 }
 
@@ -1456,14 +1555,14 @@ function optionalWrap(str, width, indent) {
 }
 
 /**
- * Output help information if necessary
+ * Output help information if help flags specified
  *
- * @param {Command} command to output help for
- * @param {Array} array of options to search for -h or --help
+ * @param {Command} cmd - command to output help for
+ * @param {Array} options - array of options to search for -h or --help
  * @api private
  */
 
-function outputHelpIfNecessary(cmd, options) {
+function outputHelpIfRequested(cmd, options) {
   options = options || [];
 
   for (var i = 0; i < options.length; i++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -26,14 +26,13 @@
   ],
   "dependencies": {},
   "devDependencies": {
-    "@types/jest": "^24.0.18",
-    "@types/node": "^12.7.5",
-    "eslint": "^6.4.0",
-    "eslint-plugin-jest": "^22.17.0",
+    "@types/jest": "^24.0.23",
+    "@types/node": "^12.12.11",
+    "eslint": "^6.7.0",
+    "eslint-plugin-jest": "^22.21.0",
     "jest": "^24.8.0",
     "standard": "^14.3.1",
-    "ts-node": "^8.4.1",
-    "typescript": "^3.6.3"
+    "typescript": "^3.7.2"
   },
   "typings": "typings/index.d.ts",
   "engines": {

package/typings/index.d.ts

@@ -1,7 +1,5 @@
-// Type definitions for commander 2.11
-// Project: https://github.com/visionmedia/commander.js
-// Definitions by: Alan Agius <https://github.com/alan-agius4>, Marcelo Dezem <https://github.com/mdezem>, vvakame <https://github.com/vvakame>, Jules Randolph <https://github.com/sveinburne>
-// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+// Type definitions for commander
+// Original definitions by: Alan Agius <https://github.com/alan-agius4>, Marcelo Dezem <https://github.com/mdezem>, vvakame <https://github.com/vvakame>, Jules Randolph <https://github.com/sveinburne>
 
 ///<reference types="node" />
 
@@ -39,7 +37,6 @@ declare namespace commander {
      * which will print the version number when passed.
      * 
      * You can optionally supply the  flags and description to override the defaults.
-     *
      */
     version(str: string, flags?: string, description?: string): Command;
 
@@ -87,8 +84,7 @@ declare namespace commander {
     /**
      * Define argument syntax for the top-level command.
      *
-     * @param {string} desc
-     * @returns {Command} for chaining
+     * @returns Command for chaining
      */
     arguments(desc: string): Command;
 
@@ -97,8 +93,7 @@ declare namespace commander {
      *
      * For example `["[type]"]` becomes `[{ required: false, name: 'type' }]`.
      *
-     * @param {string[]} args
-     * @returns {Command} for chaining
+     * @returns Command for chaining
      */
      parseExpectedArgs(args: string[]): Command;
 
@@ -118,8 +113,7 @@ declare namespace commander {
      *           // output help here
      *        });
      *
-     * @param {(...args: any[]) => void} fn
-     * @returns {Command} for chaining
+     * @returns Command for chaining
      */
     action(fn: (...args: any[]) => void): Command;
 
@@ -163,11 +157,7 @@ declare namespace commander {
      *     // optional argument
      *     program.option('-c, --cheese [type]', 'add cheese [marble]');
      *
-     * @param {string} flags
-     * @param {string} [description]
-     * @param {((arg1: any, arg2: any) => void) | RegExp} [fn] function or default
-     * @param {*} [defaultValue]
-     * @returns {Command} for chaining
+     * @returns Command for chaining
      */
     option(flags: string, description?: string, fn?: ((arg1: any, arg2: any) => void) | RegExp, defaultValue?: any): Command;
     option(flags: string, description?: string, defaultValue?: any): Command;
@@ -181,77 +171,98 @@ declare namespace commander {
     requiredOption(flags: string, description?: string, fn?: ((arg1: any, arg2: any) => void) | RegExp, defaultValue?: any): Command;
     requiredOption(flags: string, description?: string, defaultValue?: any): Command;
 
+
+    /**
+     * Whether to store option values as properties on command object,
+     * or store separately (specify false). In both cases the option values can be accessed using .opts().
+     *
+     * @return Command for chaining
+     */
+    storeOptionsAsProperties(value?: boolean): Command;
+
+    /**
+     * Whether to pass command to action handler,
+     * or just the options (specify false).
+     * 
+     * @return Command for chaining
+     */
+    passCommandToAction(value?: boolean): Command;
+
     /**
      * Allow unknown options on the command line.
      *
-     * @param {boolean} [arg] if `true` or omitted, no error will be thrown for unknown options.
-     * @returns {Command} for chaining
+     * @param [arg] if `true` or omitted, no error will be thrown for unknown options.
+     * @returns Command for chaining
      */
     allowUnknownOption(arg?: boolean): Command;
 
     /**
-     * Parse `argv`, settings options and invoking commands when defined.
+     * Parse `argv`, setting options and invoking commands when defined.
      *
-     * @param {string[]} argv
-     * @returns {Command} for chaining
+     * @returns Command for chaining
      */
     parse(argv: string[]): Command;
 
     /**
-     * Parse options from `argv` returning `argv` void of these options.
+     * Parse `argv`, setting options and invoking commands when defined.
+     * 
+     * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise.
      *
-     * @param {string[]} argv
-     * @returns {ParseOptionsResult}
+     * @returns Promise
+     */
+    parseAsync(argv: string[]): Promise<any>;
+
+    /**
+     * Parse options from `argv` returning `argv` void of these options.
      */
     parseOptions(argv: string[]): commander.ParseOptionsResult;
 
     /**
      * Return an object containing options as key-value pairs
-     *
-     * @returns {{[key: string]: any}}
      */
     opts(): { [key: string]: any };
 
     /**
-     * Set the description to `str`.
-     *
-     * @param {string} str
-     * @param {{[argName: string]: string}} argsDescription
-     * @return {(Command | string)}
+     * Set the description.
+     * 
+     * @returns Command for chaining
      */
     description(str: string, argsDescription?: {[argName: string]: string}): Command;
+    /**
+     * Get the description.
+     */
     description(): string;
 
     /**
      * Set an alias for the command.
-     *
-     * @param {string} alias
-     * @return {(Command | string)}
+     * 
+     * @returns Command for chaining
      */
     alias(alias: string): Command;
+    /**
+     * Get alias for the command.
+     */
     alias(): string;
 
     /**
-     * Set or get the command usage.
-     *
-     * @param {string} str
-     * @return {(Command | string)}
+     * Set the command usage.
+     * 
+     * @returns Command for chaining
      */
     usage(str: string): Command;
+    /**
+     * Get the command usage.
+     */
     usage(): string;
 
     /**
      * Set the name of the command.
-     *
-     * @param {string} str
-     * @return {Command}
+     * 
+     * @returns Command for chaining
      */
     name(str: string): Command;
-
     /**
      * Get the name of the command.
-     *
-     * @return {string}
      */
     name(): string;
 
@@ -260,8 +271,6 @@ declare namespace commander {
      *
      * When listener(s) are available for the helpLongFlag
      * those callbacks are invoked.
-     * 
-     * @param {(str: string) => string} [cb]
      */
     outputHelp(cb?: (str: string) => string): void;