commander 4.0.0-1 → 4.1.1

package/CHANGELOG.md

@@ -7,25 +7,54 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 <!-- markdownlint-disable MD024 -->
 
-## [4.0.0-1] Prerelease (2019-10-08)
+## [4.1.1] (2020-02-02)
+
+### Fixed
+
+* TypeScript definition for `.action()` should include Promise for async ([#1157])
+
+## [4.1.0] (2020-01-06)
 
 ### Added
 
-* support for declaring required options with `.requiredOptions()` ([#1071])
+* 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])
 
-## [4.0.0-0] Prerelease (2019-10-01)
+### 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])
+
+## [4.0.0] (2019-11-02)
 
 ### Added
 
 * automatically wrap and indent help descriptions for options and commands ([#1051])
 * `.exitOverride()` allows override of calls to `process.exit` for additional error handling and to keep program running ([#1040])
-* dev: work in progress GitHub Actions support ([#1027])
+* support for declaring required options with `.requiredOptions()` ([#1071])
+* GitHub Actions support ([#1027])
+* translation links in README
 
 ### Changed
 
 * dev: switch tests from Sinon+Should to Jest with major rewrite of tests ([#1035])
 * call default subcommand even when there are unknown options ([#1047])
-* *Breaking* Commander is only officially supported on Node 8 and above ([#1053])
+* *Breaking* Commander is only officially supported on Node 8 and above, and requires Node 6 ([#1053])
 
 ### Fixed
 
@@ -34,6 +63,31 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 * complain about unknown options when program argument supplied and action handler ([#1049])
   * this changes parameters to `command:*` event to include unknown arguments
 * removed deprecated `customFds` option from call to `child_process.spawn` ([#1052])
+* rework TypeScript declarations to bring all types into imported namespace ([#1081])
+
+### Migration Tips
+
+#### Testing for no arguments
+
+If you were previously using code like:
+
+```js
+if (!program.args.length) ...
+```
+
+a partial replacement is:
+
+```js
+if (program.rawArgs.length < 3) ...
+```
+
+## [4.0.0-1] Prerelease (2019-10-08)
+
+(Released in 4.0.0)
+
+## [4.0.0-0] Prerelease (2019-10-01)
+
+(Released in 4.0.0)
 
 ## [2.20.1] (2019-09-29)
 
@@ -71,7 +125,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 * help for sub commands with custom executableFile ([#1018])
 
-## 3.0.0 / 2019-08-08
+## [3.0.0] / 2019-08-08
 
 * Add option to specify executable file name ([#999])
   * e.g. `.command('clone', 'clone description', { executableFile: 'myClone' })`
@@ -328,152 +382,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
@@ -482,6 +400,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
@@ -497,10 +416,21 @@ program
 [#1052]: https://github.com/tj/commander.js/pull/1052
 [#1053]: https://github.com/tj/commander.js/pull/1053
 [#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
+[#1157]: https://github.com/tj/commander.js/pull/1157
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[4.1.1]: https://github.com/tj/commander.js/compare/v4.0.0..v4.1.1
+[4.1.0]: https://github.com/tj/commander.js/compare/v4.0.1..v4.1.0
+[4.0.1]: https://github.com/tj/commander.js/compare/v4.0.0..v4.0.1
+[4.0.0]: https://github.com/tj/commander.js/compare/v3.0.2..v4.0.0
 [4.0.0-1]: https://github.com/tj/commander.js/compare/v4.0.0-0..v4.0.0-1
 [4.0.0-0]: https://github.com/tj/commander.js/compare/v3.0.2...v4.0.0-0
 [3.0.2]: https://github.com/tj/commander.js/compare/v3.0.1...v3.0.2
 [3.0.1]: https://github.com/tj/commander.js/compare/v3.0.0...v3.0.1
+[3.0.0]: https://github.com/tj/commander.js/compare/v2.20.1...v3.0.0
 [2.20.1]: https://github.com/tj/commander.js/compare/v2.20.0...v2.20.1

package/Readme.md

@@ -7,9 +7,11 @@
 
 The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/commander-rb/commander).
 
+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)
@@ -29,13 +31,15 @@ The complete solution for [node.js](http://nodejs.org) command-line interfaces,
     - [.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)
   - [License](#license)
   - [Support](#support)
+    - [Commander for enterprise](#commander-for-enterprise)
 
 ## Installation
 
@@ -67,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.
@@ -371,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.
@@ -547,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.
@@ -645,10 +701,13 @@ 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.
 
-[Professionally supported commander is now available](https://tidelift.com/subscription/pkg/npm-commander?utm_source=npm-commander&utm_medium=referral&utm_campaign=readme)
+### Commander for enterprise
+
+Available as part of the Tidelift Subscription
 
-Tidelift gives software development teams a single source for purchasing and maintaining their software, with professional grade assurances from the experts who know it best, while seamlessly integrating with existing tools.
+The maintainers of Commander and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-commander?utm_source=npm-commander&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)

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,8 @@ 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
     // die, unless someone asked for help, in which case we give it
@@ -350,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;
@@ -404,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;
     }
   }
@@ -422,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);
     }
   });
 
@@ -531,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
@@ -563,10 +643,17 @@ Command.prototype.parse = function(argv) {
 
   if (args[0] === 'help' && args.length === 1) this.help();
 
+  // Note for future: we could return early if we found an action handler in parseArgs, as none of following code needed?
+
   // <cmd> --help
   if (args[0] === 'help') {
     args[0] = args[1];
     args[1] = this._helpLongFlag;
+  } else {
+    // If calling through to executable subcommand we could check for help flags before failing,
+    // but a somewhat unlikely case since program options not passed to executable subcommands.
+    // Wait for reports to see if check needed and what usage pattern is.
+    this._checkForMissingMandatoryOptions();
   }
 
   // executable sub-commands
@@ -608,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
  */
 
@@ -793,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.
@@ -832,12 +933,14 @@ Command.prototype.optionFor = function(arg) {
  */
 
 Command.prototype._checkForMissingMandatoryOptions = function() {
-  const self = this;
-  this.options.forEach((anOption) => {
-    if (anOption.mandatory && (self[anOption.attributeName()] === undefined)) {
-      self.missingMandatoryOptionValue(anOption);
-    }
-  });
+  // 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._getOptionValue(anOption.attributeName()) === undefined)) {
+        cmd.missingMandatoryOptionValue(anOption);
+      }
+    });
+  }
 };
 
 /**
@@ -845,7 +948,7 @@ Command.prototype._checkForMissingMandatoryOptions = function() {
  * void of these options.
  *
  * @param {Array} argv
- * @return {Array}
+ * @return {{args: Array, unknown: Array}}
  * @api public
  */
 
@@ -916,8 +1019,6 @@ Command.prototype.parseOptions = function(argv) {
     args.push(arg);
   }
 
-  this._checkForMissingMandatoryOptions();
-
   return { args: args, unknown: unknownOptions };
 };
 
@@ -928,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;
 };
 
 /**
@@ -954,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
  */
 
@@ -973,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
  */
 
@@ -1033,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;
 };
@@ -1044,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
  */
@@ -1081,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
  */
@@ -1104,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
  */
@@ -1421,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');
 }
 
@@ -1448,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.0-1",
+  "version": "4.1.1",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -26,14 +26,16 @@
   ],
   "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"
+  "typings": "typings/index.d.ts",
+  "engines": {
+    "node": ">= 6"
+  }
 }

package/typings/index.d.ts

@@ -1,22 +1,19 @@
-// 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" />
 
-declare namespace local {
+declare namespace commander {
 
-  class CommanderError extends Error {
+  interface CommanderError extends Error {
     code: string;
     exitCode: number;
     message: string;
     nestedError?: string;
-
-    constructor(exitCode: number, code: string, message: string);
   }
+  type CommanderErrorConstructor = { new (exitCode: number, code: string, message: string): CommanderError };
 
-  class Option {
+  interface Option {
     flags: string;
     required: boolean; // A value must be supplied when the option is specified.
     optional: boolean; // A value is optional when the option is specified.
@@ -25,28 +22,14 @@ declare namespace local {
     short?: string;
     long: string;
     description: string;
-
-    /**
-     * Initialize a new `Option` with the given `flags` and `description`.
-     *
-     * @param {string} flags
-     * @param {string} [description]
-     */
-    constructor(flags: string, description?: string);
   }
+  type OptionConstructor = { new (flags: string, description?: string): Option };
 
-  class Command extends NodeJS.EventEmitter {
+  interface Command extends NodeJS.EventEmitter {
     [key: string]: any; // options as properties
 
     args: string[];
 
-    /**
-     * Initialize a new `Command`.
-     *
-     * @param {string} [name]
-     */
-    constructor(name?: string);
-
     /**
      * Set the program version to `str`. 
      *
@@ -54,7 +37,6 @@ declare namespace local {
      * 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;
 
@@ -78,7 +60,7 @@ declare namespace local {
      * @param opts - configuration options
      * @returns new command
      */
-    command(nameAndArgs: string, opts?: commander.CommandOptions): Command;
+    command(nameAndArgs: string, opts?: CommandOptions): Command;
     /**
      * Define a command, implemented in a separate executable file.
      * 
@@ -102,8 +84,7 @@ declare namespace local {
     /**
      * Define argument syntax for the top-level command.
      *
-     * @param {string} desc
-     * @returns {Command} for chaining
+     * @returns Command for chaining
      */
     arguments(desc: string): Command;
 
@@ -112,8 +93,7 @@ declare namespace local {
      *
      * For example `["[type]"]` becomes `[{ required: false, name: 'type' }]`.
      *
-     * @param {string[]} args
-     * @returns {Command} for chaining
+     * @returns Command for chaining
      */
      parseExpectedArgs(args: string[]): Command;
 
@@ -133,10 +113,9 @@ declare namespace local {
      *           // output help here
      *        });
      *
-     * @param {(...args: any[]) => void} fn
-     * @returns {Command} for chaining
+     * @returns Command for chaining
      */
-    action(fn: (...args: any[]) => void): Command;
+    action(fn: (...args: any[]) => void | Promise<void>): Command;
 
     /**
      * Define option with `flags`, `description` and optional
@@ -178,11 +157,7 @@ declare namespace local {
      *     // 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;
@@ -196,77 +171,98 @@ declare namespace local {
     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;
 
@@ -275,8 +271,6 @@ declare namespace local {
      *
      * When listener(s) are available for the helpLongFlag
      * those callbacks are invoked.
-     * 
-     * @param {(str: string) => string} [cb]
      */
     outputHelp(cb?: (str: string) => string): void;
 
@@ -291,14 +285,8 @@ declare namespace local {
      */
     help(cb?: (str: string) => string): never;
   }
+  type CommandConstructor = { new (name?: string): Command };
 
-}
-
-declare namespace commander {
-
-    type Command = local.Command
-
-    type Option = local.Option
 
     interface CommandOptions {
         noHelp?: boolean;
@@ -312,11 +300,9 @@ declare namespace commander {
     }
 
     interface CommanderStatic extends Command {
-        Command: typeof local.Command;
-        Option: typeof local.Option;
-        CommandOptions: CommandOptions;
-        ParseOptionsResult: ParseOptionsResult;
-        CommanderError : typeof local.CommanderError;
+        Command: CommandConstructor;
+        Option: OptionConstructor;
+        CommanderError:CommanderErrorConstructor;
       }
 
 }