commander 8.2.0 → 8.3.0

package/Readme.md

@@ -98,7 +98,8 @@ const program = new Command();
 Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|').
 
 The parsed options can be accessed by calling `.opts()` on a `Command` object, and are passed to the action handler.
-You can also use `.getOptionValue()` and `.setOptionValue()` to work with a single option value.
+(You can also use `.getOptionValue()` and `.setOptionValue()` to work with a single option value,
+and `.getOptionValueSource()` and `.setOptionValueWithSource()` when it matters where the option value came from.)
 
 Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.
 
@@ -778,13 +779,6 @@ You can execute custom actions by listening to command and option events.
 program.on('option:verbose', function () {
   process.env.VERBOSE = this.opts().verbose;
 });
-
-program.on('command:*', function (operands) {
-  console.error(`error: unknown command '${operands[0]}'`);
-  const availableCommands = program.commands.map(cmd => cmd.name());
-  mySuggestBestMatch(operands[0], availableCommands);
-  process.exitCode = 1;
-});
 ```
 
 ## Bits and pieces

package/lib/command.js

@@ -36,7 +36,7 @@ class Command extends EventEmitter {
     this._scriptPath = null;
     this._name = name || '';
     this._optionValues = {};
-    this._optionValueSources = {}; // default < env < cli
+    this._optionValueSources = {}; // default < config < env < cli
     this._storeOptionsAsProperties = false;
     this._actionHandler = null;
     this._executableHandler = false;
@@ -463,10 +463,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *
    * @example
    * program
-   *   .command('help')
-   *   .description('display verbose help')
+   *   .command('serve')
+   *   .description('start service')
    *   .action(function() {
-   *      // output help here
+   *      // do work here
    *   });
    *
    * @param {Function} fn
@@ -527,7 +527,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       }
       // preassign only if we have a default
       if (defaultValue !== undefined) {
-        this._setOptionValueWithSource(name, defaultValue, 'default');
+        this.setOptionValueWithSource(name, defaultValue, 'default');
       }
     }
 
@@ -558,13 +558,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
       if (typeof oldValue === 'boolean' || typeof oldValue === 'undefined') {
         // if no value, negate false, and we have a default, then use it!
         if (val == null) {
-          this._setOptionValueWithSource(name, option.negate ? false : defaultValue || true, valueSource);
+          this.setOptionValueWithSource(name, option.negate ? false : defaultValue || true, valueSource);
         } else {
-          this._setOptionValueWithSource(name, val, valueSource);
+          this.setOptionValueWithSource(name, val, valueSource);
         }
       } else if (val !== null) {
         // reassign
-        this._setOptionValueWithSource(name, option.negate ? false : val, valueSource);
+        this.setOptionValueWithSource(name, option.negate ? false : val, valueSource);
       }
     };
 
@@ -793,13 +793,32 @@ Expecting one of '${allowedValues.join("', '")}'`);
   };
 
   /**
-   * @api private
-   */
-  _setOptionValueWithSource(key, value, source) {
+   * Store option value and where the value came from.
+    *
+    * @param {string} key
+    * @param {Object} value
+    * @param {string} source - expected values are default/config/env/cli
+    * @return {Command} `this` command for chaining
+    */
+
+  setOptionValueWithSource(key, value, source) {
     this.setOptionValue(key, value);
     this._optionValueSources[key] = source;
+    return this;
   }
 
+  /**
+    * Get source of option value.
+    * Expected values are default | config | env | cli
+    *
+    * @param {string} key
+    * @return {string}
+    */
+
+  getOptionValueSource(key) {
+    return this._optionValueSources[key];
+  };
+
   /**
    * Get user arguments implied or explicit arguments.
    * Side-effects: set _scriptPath if args included application, and use that to set implicit command name.
@@ -1112,6 +1131,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {Promise|undefined} promise
    * @param {Function} fn
    * @return {Promise|undefined}
+   * @api private
    */
 
   _chainOrCall(promise, fn) {
@@ -1456,8 +1476,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
     this.options.forEach((option) => {
       if (option.envVar && option.envVar in process.env) {
         const optionKey = option.attributeName();
-        // env is second lowest priority source, above default
-        if (this.getOptionValue(optionKey) === undefined || this._optionValueSources[optionKey] === 'default') {
+        // Priority check. Do not overwrite cli or options from unknown source (client-code).
+        if (this.getOptionValue(optionKey) === undefined || ['default', 'config', 'env'].includes(this.getOptionValueSource(optionKey))) {
           if (option.required || option.optional) { // option can take a value
             // keep very simple, optional always takes value
             this.emit(`optionEnv:${option.name()}`, process.env[option.envVar]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "8.2.0",
+  "version": "8.3.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",

package/typings/index.d.ts

@@ -214,8 +214,9 @@ export interface OutputConfiguration {
 
 }
 
-type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
-type HookEvent = 'preAction' | 'postAction';
+export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
+export type HookEvent = 'preAction' | 'postAction';
+export type OptionValueSource = 'default' | 'env' | 'config' | 'cli';
 
 export interface OptionValues {
   [key: string]: any;
@@ -424,10 +425,10 @@ export class Command {
    * @example
    * ```
    * program
-   *   .command('help')
-   *   .description('display verbose help')
+   *   .command('serve')
+   *   .description('start service')
    *   .action(function() {
-   *     // output help here
+   *     // do work here
    *   });
    * ```
    *
@@ -526,12 +527,22 @@ export class Command {
    */
   getOptionValue(key: string): any;
 
-   /**
+  /**
    * Store option value.
    */
   setOptionValue(key: string, value: unknown): this;
 
   /**
+   * Store option value and where the value came from.
+   */
+  setOptionValueWithSource(key: string, value: unknown, source: OptionValueSource): this;
+
+  /**
+   * Retrieve option value source.
+   */
+  getOptionValueSource(key: string): OptionValueSource;
+
+   /**
    * Alter parsing of short flags with optional values.
    *
    * @example