Add implied to option value sources (#1794)

* TypeScript: add implied to OptionValueSource

* Add implied to JSDoc and TSDoc. Mention config in env priority.

* TypeScript: add undefined to return type of getOptionValueSource

* Reword env description so not  priority ordering as such. More accurately describe behaviour.

lib/command.js

@@ -37,7 +37,7 @@ class Command extends EventEmitter {
     this._scriptPath = null;
     this._name = name || '';
     this._optionValues = {};
-    this._optionValueSources = {}; // default < config < env < cli
+    this._optionValueSources = {}; // default, env, cli etc
     this._storeOptionsAsProperties = false;
     this._actionHandler = null;
     this._executableHandler = false;
@@ -784,11 +784,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
   }
 
   /**
-   * Store option value and where the value came from.
+    * 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
+    * @param {string} source - expected values are default/config/env/cli/implied
     * @return {Command} `this` command for chaining
     */
 
@@ -804,7 +804,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   /**
     * Get source of option value.
-    * Expected values are default | config | env | cli
+    * Expected values are default | config | env | cli | implied
     *
     * @param {string} key
     * @return {string}

lib/option.js

@@ -105,7 +105,9 @@ class Option {
 
   /**
    * Set environment variable to check for option value.
-   * Priority order of option values is default < env < cli
+   *
+   * An environment variable is only used if when processed the current option value is
+   * undefined, or the source of the current value is 'default' or 'config' or 'env'.
    *
    * @param {string} name
    * @return {Option}

typings/index.d.ts

@@ -144,7 +144,9 @@ export class Option {
 
   /**
    * Set environment variable to check for option value.
-   * Priority order of option values is default < env < cli
+   *
+   * An environment variables is only used if when processed the current option value is
+   * undefined, or the source of the current value is 'default' or 'config' or 'env'.
    */
   env(name: string): this;
 
@@ -266,7 +268,7 @@ export interface OutputConfiguration {
 
 export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
 export type HookEvent = 'preSubcommand' | 'preAction' | 'postAction';
-export type OptionValueSource = 'default' | 'env' | 'config' | 'cli';
+export type OptionValueSource = 'default' | 'config' | 'env' | 'cli' | 'implied';
 
 export interface OptionValues {
   [key: string]: any;
@@ -595,7 +597,7 @@ export class Command {
   /**
    * Retrieve option value source.
    */
-  getOptionValueSource(key: string): OptionValueSource;
+  getOptionValueSource(key: string): OptionValueSource | undefined;
 
   /**
    * Alter parsing of short flags with optional values.

typings/index.test-d.ts

@@ -172,7 +172,7 @@ expectType<commander.Command>(program.setOptionValue('example', true));
 expectType<commander.Command>(program.setOptionValueWithSource('example', [], 'cli'));
 
 // getOptionValueSource
-expectType<commander.OptionValueSource>(program.getOptionValueSource('example'));
+expectType<commander.OptionValueSource | undefined>(program.getOptionValueSource('example'));
 
 // combineFlagAndOptionalValue
 expectType<commander.Command>(program.combineFlagAndOptionalValue());