commander 9.0.0-0 → 9.0.0-1

package/Readme.md

@@ -11,6 +11,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
 
 - [Commander.js](#commanderjs)
   - [Installation](#installation)
+  - [Quick Start](#quick-start)
   - [Declaring _program_ variable](#declaring-program-variable)
   - [Options](#options)
     - [Common option types, boolean and value](#common-option-types-boolean-and-value)
@@ -46,9 +47,9 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [createCommand()](#createcommand)
     - [Node options such as `--harmony`](#node-options-such-as---harmony)
     - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
+    - [Display error](#display-error)
     - [Override exit and output handling](#override-exit-and-output-handling)
     - [Additional documentation](#additional-documentation)
-  - [Examples](#examples)
   - [Support](#support)
     - [Commander for enterprise](#commander-for-enterprise)
 
@@ -60,6 +61,85 @@ For information about terms used in this document see: [terminology](./docs/term
 npm install commander
 ```
 
+## Quick Start
+
+You write code to describe your command line interface.
+Commander looks after parsing the arguments into options and command-arguments,
+displays usage errors for problems, and implements a help system.
+
+Commander is strict and displays an error for unrecognised options.
+The two most used option types are a boolean option, and an option which takes its value from the following argument.
+
+Example file: [split.js](./examples/split.js)
+
+```js
+const { program } = require('commander');
+
+program
+  .option('--first')
+  .option('-s, --separator <char>');
+
+program.parse();
+
+const options = program.opts();
+const limit = options.first ? 1 : undefined;
+console.log(program.args[0].split(options.separator, limit));
+```
+
+```sh
+$ node split.js -s / --fits a/b/c
+error: unknown option '--fits'
+(Did you mean --first?)
+$ node split.js -s / --first a/b/c
+[ 'a' ]
+```
+
+Here is a more complete program using a subcommand and with descriptions for the help. In a multi-command program, you have an action handler for each command (or stand-alone executables for the commands).
+
+Example file: [string-util.js](./examples/string-util.js)
+
+```js
+const { Command } = require('commander');
+const program = new Command();
+
+program
+  .name('string-util')
+  .description('CLI to some JavaScript string utilities')
+  .version('0.8.0');
+
+program.command('split')
+  .description('Split a string into substrings and display as an array')
+  .argument('<string>', 'string to split')
+  .option('--first', 'display just the first substring')
+  .option('-s, --separator <char>', 'separator character', ',')
+  .action((str, options) => {
+    const limit = options.first ? 1 : undefined;
+    console.log(str.split(options.separator, limit));
+  });
+
+program.parse();
+```
+
+```sh
+$ node string-util.js help split
+Usage: string-util split [options] <string>
+
+Split a string into substrings and display as an array.
+
+Arguments:
+  string                  string to split
+
+Options:
+  --first                 display just the first substring
+  -s, --separator <char>  separator character (default: ",")
+  -h, --help              display help for command
+
+$ node string-util.js split --separator=/ a/b/c
+[ 'a', 'b', 'c' ]
+```
+
+More samples can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.
+
 ## Declaring _program_ variable
 
 Commander exports a global object which is convenient for quick programs.
@@ -95,8 +175,6 @@ 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,
-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.
 
@@ -107,6 +185,12 @@ You can use `--` to indicate the end of the options, and any remaining arguments
 
 By default options on the command line are not positional, and can be specified before or after other arguments.
 
+There are additional related routines for when `.opts()` is not enough:
+
+- `.optsWithGlobals()` returns merged local and global option values
+- `.getOptionValue()` and `.setOptionValue()` work with a single option value
+- `.getOptionValueSource()` and `.setOptionValueWithSource()` include where the option value came from
+
 ### Common option types, boolean and value
 
 The two most used option types are a boolean option, and an option which takes its value
@@ -535,6 +619,20 @@ program
   });
 ```
 
+If you prefer, you can work with the command directly and skip declaring the parameters for the action handler. The `this` keyword is set to the running command and can be used from a function expression (but not from an arrow function).
+
+Example file: [action-this.js](./examples/action-this.js)
+
+```js
+program
+  .command('serve')
+  .argument('<script>')
+  .option('-p, --port <number>', 'port number', 80)
+  .action(function() {
+    console.error('Run script %s on port %s', this.args[0], this.opts().port);
+  });
+```
+
 You may supply an `async` action handler, in which case you call `.parseAsync` rather than `.parse`.
 
 ```js
@@ -906,6 +1004,18 @@ the inspector port is incremented by 1 for the spawned subcommand.
 
 If you are using VSCode to debug executable subcommands you need to set the `"autoAttachChildProcesses": true` flag in your launch.json configuration.
 
+### Display error
+
+This routine is available to invoke the Commander error handling for your own error conditions. (See also the next section about exit handling.)
+
+As well as the error message, you can optionally specify the `exitCode` (used with `process.exit`)
+and `code` (used with `CommanderError`).
+
+```js
+program.exit('Password must be longer than four characters');
+program.exit('Custom processing has failed', { exitCode: 2, code: 'my.custom.error' });
+```
+
 ### Override exit and output handling
 
 By default Commander calls `process.exit` when it detects errors, or after displaying the help or version. You can override
@@ -952,72 +1062,6 @@ There is more information available about:
 - [deprecated](./docs/deprecated.md) features still supported for backwards compatibility
 - [options taking varying arguments](./docs/options-taking-varying-arguments.md)
 
-## Examples
-
-In a single command program, you might not need an action handler.
-
-Example file: [pizza](./examples/pizza)
-
-```js
-const { program } = require('commander');
-
-program
-  .description('An application for pizza ordering')
-  .option('-p, --peppers', 'Add peppers')
-  .option('-c, --cheese <type>', 'Add the specified type of cheese', 'marble')
-  .option('-C, --no-cheese', 'You do not want any cheese');
-
-program.parse();
-
-const options = program.opts();
-console.log('you ordered a pizza with:');
-if (options.peppers) console.log('  - peppers');
-const cheese = !options.cheese ? 'no' : options.cheese;
-console.log('  - %s cheese', cheese);
-```
-
-In a multi-command program, you will have action handlers for each command (or stand-alone executables for the commands).
-
-Example file: [deploy](./examples/deploy)
-
-```js
-const { Command } = require('commander');
-const program = new Command();
-
-program
-  .name('deploy')
-  .version('0.0.1')
-  .option('-c, --config <path>', 'set config path', './deploy.conf');
-
-program
-  .command('setup [env]')
-  .description('run setup commands for all envs')
-  .option('-s, --setup_mode <mode>', 'Which setup mode to use', 'normal')
-  .action((env, options) => {
-    env = env || 'all';
-    console.log('read config from %s', program.opts().config);
-    console.log('setup for %s env(s) with %s mode', env, options.setup_mode);
-  });
-
-program
-  .command('exec <script>')
-  .alias('ex')
-  .description('execute the given remote cmd')
-  .option('-e, --exec_mode <mode>', 'Which exec mode to use', 'fast')
-  .action((script, options) => {
-    console.log('read config from %s', program.opts().config);
-    console.log('exec "%s" using %s mode and config %s', script, options.exec_mode, program.opts().config);
-  }).addHelpText('after', `
-Examples:
-  $ deploy exec sequential
-  $ deploy exec async`
-  );
-
-program.parse(process.argv);
-```
-
-More samples can be found in the [examples](https://github.com/tj/commander.js/tree/master/examples) directory.
-
 ## Support
 
 The current version of Commander is fully supported on Long Term Support versions of Node.js, and requires at least v12.20.0.

package/lib/argument.js

@@ -49,7 +49,7 @@ class Argument {
 
   name() {
     return this._name;
-  };
+  }
 
   /**
    * @api private
@@ -75,7 +75,7 @@ class Argument {
     this.defaultValue = value;
     this.defaultValueDescription = description;
     return this;
-  };
+  }
 
   /**
    * Set the custom handler for processing CLI command arguments into argument values.
@@ -87,7 +87,7 @@ class Argument {
   argParser(fn) {
     this.parseArg = fn;
     return this;
-  };
+  }
 
   /**
    * Only allow argument value to be one of choices.
@@ -97,10 +97,10 @@ class Argument {
    */
 
   choices(values) {
-    this.argChoices = values;
+    this.argChoices = values.slice();
     this.parseArg = (arg, previous) => {
-      if (!values.includes(arg)) {
-        throw new InvalidArgumentError(`Allowed choices are ${values.join(', ')}.`);
+      if (!this.argChoices.includes(arg)) {
+        throw new InvalidArgumentError(`Allowed choices are ${this.argChoices.join(', ')}.`);
       }
       if (this.variadic) {
         return this._concatValue(arg, previous);
@@ -108,7 +108,7 @@ class Argument {
       return arg;
     };
     return this;
-  };
+  }
 
   /**
    * Make argument required.

package/lib/command.js

@@ -83,7 +83,7 @@ class Command extends EventEmitter {
    * (Used internally when adding a command using `.command()` so subcommands inherit parent settings.)
    *
    * @param {Command} sourceCommand
-   * @return {Command} returns `this` for executable command
+   * @return {Command} `this` command for chaining
    */
   copyInheritedSettings(sourceCommand) {
     this._outputConfiguration = sourceCommand._outputConfiguration;
@@ -157,7 +157,7 @@ class Command extends EventEmitter {
 
     if (desc) return this;
     return cmd;
-  };
+  }
 
   /**
    * Factory routine to create a new unattached command.
@@ -171,7 +171,7 @@ class Command extends EventEmitter {
 
   createCommand(name) {
     return new Command(name);
-  };
+  }
 
   /**
    * You can customise the help with a subclass of Help by overriding createHelp,
@@ -182,7 +182,7 @@ class Command extends EventEmitter {
 
   createHelp() {
     return Object.assign(new Help(), this.configureHelp());
-  };
+  }
 
   /**
    * You can customise the help by overriding Help properties using configureHelp(),
@@ -271,7 +271,7 @@ class Command extends EventEmitter {
     this.commands.push(cmd);
     cmd.parent = this;
     return this;
-  };
+  }
 
   /**
    * Factory routine to create a new unattached argument.
@@ -286,7 +286,7 @@ class Command extends EventEmitter {
 
   createArgument(name, description) {
     return new Argument(name, description);
-  };
+  }
 
   /**
    * Define argument syntax for command.
@@ -332,7 +332,7 @@ class Command extends EventEmitter {
       this.argument(detail);
     });
     return this;
-  };
+  }
 
   /**
    * Define argument syntax for command, adding a prepared argument.
@@ -374,7 +374,7 @@ class Command extends EventEmitter {
       this._helpCommandDescription = description || this._helpCommandDescription;
     }
     return this;
-  };
+  }
 
   /**
    * @return {boolean}
@@ -386,7 +386,7 @@ class Command extends EventEmitter {
       return this.commands.length && !this._actionHandler && !this._findCommand('help');
     }
     return this._addImplicitHelpCommand;
-  };
+  }
 
   /**
    * Add hook for life cycle event.
@@ -430,7 +430,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       };
     }
     return this;
-  };
+  }
 
   /**
    * Call process.exit, and _exitCallback if defined.
@@ -448,7 +448,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       // Expecting this line is not reached.
     }
     process.exit(exitCode);
-  };
+  }
 
   /**
    * Register callback `fn` for the command.
@@ -481,7 +481,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     };
     this._actionHandler = listener;
     return this;
-  };
+  }
 
   /**
    * Factory routine to create a new unattached option.
@@ -496,7 +496,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   createOption(flags, description) {
     return new Option(flags, description);
-  };
+  }
 
   /**
    * Add an option.
@@ -538,7 +538,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         } catch (err) {
           if (err.code === 'commander.invalidArgument') {
             const message = `${invalidValueMessage} ${err.message}`;
-            this._displayError(err.exitCode, err.code, message);
+            this.error(message, { exitCode: err.exitCode, code: err.code });
           }
           throw err;
         }
@@ -654,7 +654,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   option(flags, description, fn, defaultValue) {
     return this._optionEx({}, flags, description, fn, defaultValue);
-  };
+  }
 
   /**
   * Add a required option which must have a value after parsing. This usually means
@@ -671,7 +671,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   requiredOption(flags, description, fn, defaultValue) {
     return this._optionEx({ mandatory: true }, flags, description, fn, defaultValue);
-  };
+  }
 
   /**
    * Alter parsing of short flags with optional values.
@@ -686,7 +686,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   combineFlagAndOptionalValue(combine = true) {
     this._combineFlagAndOptionalValue = !!combine;
     return this;
-  };
+  }
 
   /**
    * Allow unknown options on the command line.
@@ -697,7 +697,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   allowUnknownOption(allowUnknown = true) {
     this._allowUnknownOption = !!allowUnknown;
     return this;
-  };
+  }
 
   /**
    * Allow excess command-arguments on the command line. Pass false to make excess arguments an error.
@@ -708,7 +708,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   allowExcessArguments(allowExcess = true) {
     this._allowExcessArguments = !!allowExcess;
     return this;
-  };
+  }
 
   /**
    * Enable positional options. Positional means global options are specified before subcommands which lets
@@ -720,7 +720,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   enablePositionalOptions(positional = true) {
     this._enablePositionalOptions = !!positional;
     return this;
-  };
+  }
 
   /**
    * Pass through options that come after command-arguments rather than treat them as command-options,
@@ -737,7 +737,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       throw new Error('passThroughOptions can not be used without turning on enablePositionalOptions for parent command(s)');
     }
     return this;
-  };
+  }
 
   /**
     * Whether to store option values as properties on command object,
@@ -753,7 +753,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       throw new Error('call .storeOptionsAsProperties() before adding options');
     }
     return this;
-  };
+  }
 
   /**
    * Retrieve option value.
@@ -767,7 +767,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       return this[key];
     }
     return this._optionValues[key];
-  };
+  }
 
   /**
    * Store option value.
@@ -784,7 +784,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this._optionValues[key] = value;
     }
     return this;
-  };
+  }
 
   /**
    * Store option value and where the value came from.
@@ -811,7 +811,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   getOptionValueSource(key) {
     return this._optionValueSources[key];
-  };
+  }
 
   /**
    * Get user arguments from implied or explicit arguments.
@@ -889,7 +889,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     this._parseCommand([], userArgs);
 
     return this;
-  };
+  }
 
   /**
    * Parse `argv`, setting options and invoking commands when defined.
@@ -915,7 +915,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     await this._parseCommand([], userArgs);
 
     return this;
-  };
+  }
 
   /**
    * Execute a sub-command executable.
@@ -1041,7 +1041,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
     // Store the reference to the child process
     this.runningCommand = proc;
-  };
+  }
 
   /**
    * @api private
@@ -1056,7 +1056,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     } else {
       return subCommand._parseCommand(operands, unknown);
     }
-  };
+  }
 
   /**
    * Check this.args against expected this._args.
@@ -1078,7 +1078,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     if (this.args.length > this._args.length) {
       this._excessArguments(this.args);
     }
-  };
+  }
 
   /**
    * Process this.args using this._args and save as this.processedArgs!
@@ -1096,7 +1096,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         } catch (err) {
           if (err.code === 'commander.invalidArgument') {
             const message = `error: command-argument value '${value}' is invalid for argument '${argument.name()}'. ${err.message}`;
-            this._displayError(err.exitCode, err.code, message);
+            this.error(message, { exitCode: err.exitCode, code: err.code });
           }
           throw err;
         }
@@ -1266,7 +1266,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this._processArguments();
       // fall through for caller to handle after calling .parse()
     }
-  };
+  }
 
   /**
    * Find matching command.
@@ -1276,7 +1276,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   _findCommand(name) {
     if (!name) return undefined;
     return this.commands.find(cmd => cmd._name === name || cmd._aliases.includes(name));
-  };
+  }
 
   /**
    * Return an option matching `arg` if any.
@@ -1288,7 +1288,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   _findOption(arg) {
     return this.options.find(option => option.is(arg));
-  };
+  }
 
   /**
    * Display an error message if a mandatory option does not have a value.
@@ -1306,7 +1306,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         }
       });
     }
-  };
+  }
 
   /**
    * Parse options from `argv` removing known options,
@@ -1438,10 +1438,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
 
     return { operands, unknown };
-  };
+  }
 
   /**
-   * Return an object containing options as key-value pairs
+   * Return an object containing local option values as key-value pairs.
    *
    * @return {Object}
    */
@@ -1459,14 +1459,31 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
 
     return this._optionValues;
-  };
+  }
 
   /**
-   * Internal bottleneck for handling of parsing errors.
+   * Return an object containing merged local and global option values as key-value pairs.
    *
-   * @api private
+   * @return {Object}
    */
-  _displayError(exitCode, code, message) {
+  optsWithGlobals() {
+    // globals overwrite locals
+    return getCommandAndParents(this).reduce(
+      (combinedOptions, cmd) => Object.assign(combinedOptions, cmd.opts()),
+      {}
+    );
+  }
+
+  /**
+   * Display error message and exit (or call exitOverride).
+   *
+   * @param {string} message
+   * @param {Object} [errorOptions]
+   * @param {string} [errorOptions.code] - an id string representing the error
+   * @param {number} [errorOptions.exitCode] - used with process.exit
+   */
+  error(message, errorOptions) {
+    // output handling
     this._outputConfiguration.outputError(`${message}\n`, this._outputConfiguration.writeErr);
     if (typeof this._showHelpAfterError === 'string') {
       this._outputConfiguration.writeErr(`${this._showHelpAfterError}\n`);
@@ -1474,6 +1491,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this._outputConfiguration.writeErr('\n');
       this.outputHelp({ error: true });
     }
+
+    // exit handling
+    const config = errorOptions || {};
+    const exitCode = config.exitCode || 1;
+    const code = config.code || 'commander.error';
     this._exit(exitCode, code, message);
   }
 
@@ -1510,8 +1532,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   missingArgument(name) {
     const message = `error: missing required argument '${name}'`;
-    this._displayError(1, 'commander.missingArgument', message);
-  };
+    this.error(message, { code: 'commander.missingArgument' });
+  }
 
   /**
    * `Option` is missing an argument.
@@ -1522,8 +1544,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   optionMissingArgument(option) {
     const message = `error: option '${option.flags}' argument missing`;
-    this._displayError(1, 'commander.optionMissingArgument', message);
-  };
+    this.error(message, { code: 'commander.optionMissingArgument' });
+  }
 
   /**
    * `Option` does not have a value, and is a mandatory option.
@@ -1534,8 +1556,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   missingMandatoryOptionValue(option) {
     const message = `error: required option '${option.flags}' not specified`;
-    this._displayError(1, 'commander.missingMandatoryOptionValue', message);
-  };
+    this.error(message, { code: 'commander.missingMandatoryOptionValue' });
+  }
 
   /**
    * Unknown option `flag`.
@@ -1563,8 +1585,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
 
     const message = `error: unknown option '${flag}'${suggestion}`;
-    this._displayError(1, 'commander.unknownOption', message);
-  };
+    this.error(message, { code: 'commander.unknownOption' });
+  }
 
   /**
    * Excess arguments, more than expected.
@@ -1580,8 +1602,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
     const s = (expected === 1) ? '' : 's';
     const forSubcommand = this.parent ? ` for '${this.name()}'` : '';
     const message = `error: too many arguments${forSubcommand}. Expected ${expected} argument${s} but got ${receivedArgs.length}.`;
-    this._displayError(1, 'commander.excessArguments', message);
-  };
+    this.error(message, { code: 'commander.excessArguments' });
+  }
 
   /**
    * Unknown command.
@@ -1604,8 +1626,8 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
 
     const message = `error: unknown command '${unknownName}'${suggestion}`;
-    this._displayError(1, 'commander.unknownCommand', message);
-  };
+    this.error(message, { code: 'commander.unknownCommand' });
+  }
 
   /**
    * Set the program version to `str`.
@@ -1634,7 +1656,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this._exit(0, 'commander.version', str);
     });
     return this;
-  };
+  }
 
   /**
    * Set the description to `str`.
@@ -1650,7 +1672,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       this._argsDescription = argsDescription;
     }
     return this;
-  };
+  }
 
   /**
    * Set an alias for the command.
@@ -1675,7 +1697,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
     command._aliases.push(alias);
     return this;
-  };
+  }
 
   /**
    * Set aliases for the command.
@@ -1692,7 +1714,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
     aliases.forEach((alias) => this.alias(alias));
     return this;
-  };
+  }
 
   /**
    * Set / get the command usage `str`.
@@ -1717,7 +1739,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
     this._usage = str;
     return this;
-  };
+  }
 
   /**
    * Get or set the name of the command.
@@ -1730,7 +1752,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     if (str === undefined) return this._name;
     this._name = str;
     return this;
-  };
+  }
 
   /**
    * Set the name of the command from script filename, such as process.argv[1],
@@ -1767,7 +1789,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     if (path === undefined) return this._executableDir;
     this._executableDir = path;
     return this;
-  };
+  }
 
   /**
    * Return program help documentation.
@@ -1782,7 +1804,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
       helper.helpWidth = (contextOptions && contextOptions.error) ? this._outputConfiguration.getErrHelpWidth() : this._outputConfiguration.getOutHelpWidth();
     }
     return helper.formatHelp(this, helper);
-  };
+  }
 
   /**
    * @api private
@@ -1833,7 +1855,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     this.emit(this._helpLongFlag); // deprecated
     this.emit('afterHelp', context);
     getCommandAndParents(this).forEach(command => command.emit('afterAllHelp', context));
-  };
+  }
 
   /**
    * You can pass in flags and a description to override the help
@@ -1858,7 +1880,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     this._helpLongFlag = helpFlags.longFlag;
 
     return this;
-  };
+  }
 
   /**
    * Output help information and exit.
@@ -1876,7 +1898,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     // message: do not have all displayed text available so only passing placeholder.
     this._exit(exitCode, 'commander.help', '(outputHelp)');
-  };
+  }
 
   /**
    * Add additional text to be displayed with the built-in help.
@@ -1909,7 +1931,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     });
     return this;
   }
-};
+}
 
 /**
  * Output help information if help flags specified

package/lib/help.js

@@ -98,7 +98,7 @@ class Help {
     // If there are any arguments with a description then return all the arguments.
     if (cmd._args.find(argument => argument.description)) {
       return cmd._args;
-    };
+    }
     return [];
   }
 
@@ -152,7 +152,7 @@ class Help {
     return helper.visibleCommands(cmd).reduce((max, command) => {
       return Math.max(max, helper.subcommandTerm(command).length);
     }, 0);
-  };
+  }
 
   /**
    * Get the longest option term length.
@@ -166,7 +166,7 @@ class Help {
     return helper.visibleOptions(cmd).reduce((max, option) => {
       return Math.max(max, helper.optionTerm(option).length);
     }, 0);
-  };
+  }
 
   /**
    * Get the longest argument term length.
@@ -180,7 +180,7 @@ class Help {
     return helper.visibleArguments(cmd).reduce((max, argument) => {
       return Math.max(max, helper.argumentTerm(argument).length);
     }, 0);
-  };
+  }
 
   /**
    * Get the command usage to be displayed at the top of the built-in help.
@@ -262,7 +262,7 @@ class Help {
     }
 
     return option.description;
-  };
+  }
 
   /**
    * Get the argument description to show in the list of arguments.
@@ -310,7 +310,7 @@ class Help {
         return helper.wrap(fullText, helpWidth - itemIndentWidth, termWidth + itemSeparatorWidth);
       }
       return term;
-    };
+    }
     function formatList(textArray) {
       return textArray.join('\n').replace(/^/gm, ' '.repeat(itemIndentWidth));
     }
@@ -365,7 +365,7 @@ class Help {
       helper.longestSubcommandTermLength(cmd, helper),
       helper.longestArgumentTermLength(cmd, helper)
     );
-  };
+  }
 
   /**
    * Wrap the given string to width characters per line, with lines after the first indented.

package/lib/option.js

@@ -47,7 +47,7 @@ class Option {
     this.defaultValue = value;
     this.defaultValueDescription = description;
     return this;
-  };
+  }
 
   /**
    * Preset to use when option used without option-argument, especially optional but also boolean and negated.
@@ -64,7 +64,7 @@ class Option {
   preset(arg) {
     this.presetArg = arg;
     return this;
-  };
+  }
 
   /**
    * Set environment variable to check for option value.
@@ -77,7 +77,7 @@ class Option {
   env(name) {
     this.envVar = name;
     return this;
-  };
+  }
 
   /**
    * Set the custom handler for processing CLI option arguments into option values.
@@ -89,7 +89,7 @@ class Option {
   argParser(fn) {
     this.parseArg = fn;
     return this;
-  };
+  }
 
   /**
    * Whether the option is mandatory and must have a value after parsing.
@@ -101,7 +101,7 @@ class Option {
   makeOptionMandatory(mandatory = true) {
     this.mandatory = !!mandatory;
     return this;
-  };
+  }
 
   /**
    * Hide option in help.
@@ -113,7 +113,7 @@ class Option {
   hideHelp(hide = true) {
     this.hidden = !!hide;
     return this;
-  };
+  }
 
   /**
    * @api private
@@ -135,10 +135,10 @@ class Option {
    */
 
   choices(values) {
-    this.argChoices = values;
+    this.argChoices = values.slice();
     this.parseArg = (arg, previous) => {
-      if (!values.includes(arg)) {
-        throw new InvalidArgumentError(`Allowed choices are ${values.join(', ')}.`);
+      if (!this.argChoices.includes(arg)) {
+        throw new InvalidArgumentError(`Allowed choices are ${this.argChoices.join(', ')}.`);
       }
       if (this.variadic) {
         return this._concatValue(arg, previous);
@@ -146,7 +146,7 @@ class Option {
       return arg;
     };
     return this;
-  };
+  }
 
   /**
    * Return option name.
@@ -159,7 +159,7 @@ class Option {
       return this.long.replace(/^--/, '');
     }
     return this.short.replace(/^-/, '');
-  };
+  }
 
   /**
    * Return option name, in a camelcase format that can be used
@@ -171,7 +171,7 @@ class Option {
 
   attributeName() {
     return camelcase(this.name().replace(/^no-/, ''));
-  };
+  }
 
   /**
    * Check if `arg` matches the short or long flag.
@@ -183,7 +183,7 @@ class Option {
 
   is(arg) {
     return this.short === arg || this.long === arg;
-  };
+  }
 
   /**
    * Return whether a boolean option.
@@ -196,7 +196,7 @@ class Option {
 
   isBoolean() {
     return !this.required && !this.optional && !this.negate;
-  };
+  }
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "9.0.0-0",
+  "version": "9.0.0-1",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -19,13 +19,14 @@
     "url": "https://github.com/tj/commander.js.git"
   },
   "scripts": {
-    "lint": "eslint index.js esm.mjs \"lib/*.js\" \"tests/**/*.js\"",
-    "typescript-lint": "eslint typings/*.ts tests/*.ts",
+    "lint": "npm run lint:javascript && npm run lint:typescript",
+    "lint:javascript": "eslint index.js esm.mjs \"lib/*.js\" \"tests/**/*.js\"",
+    "lint:typescript": "eslint typings/*.ts tests/*.ts",
     "test": "jest && npm run test-typings",
     "test-esm": "node --experimental-modules ./tests/esm-imports-test.mjs",
     "test-typings": "tsd",
     "typescript-checkJS": "tsc --allowJS --checkJS index.js lib/*.js --noEmit",
-    "test-all": "npm run test && npm run lint && npm run typescript-lint && npm run typescript-checkJS && npm run test-esm"
+    "test-all": "npm run test && npm run lint && npm run typescript-checkJS && npm run test-esm"
   },
   "files": [
     "index.js",
@@ -46,13 +47,16 @@
   "devDependencies": {
     "@types/jest": "^27.0.3",
     "@types/node": "^16.11.15",
-    "@typescript-eslint/eslint-plugin": "^4.27.0",
+    "@typescript-eslint/eslint-plugin": "^4.33.0",
     "@typescript-eslint/parser": "^4.27.0",
     "eslint": "^7.29.0",
     "eslint-config-standard": "^16.0.3",
+    "eslint-config-standard-with-typescript": "^21.0.1",
+    "eslint-plugin-import": "^2.25.3",
     "eslint-plugin-jest": "^24.3.6",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^5.2.0",
     "jest": "^27.0.4",
-    "standard": "^16.0.3",
     "ts-jest": "^27.0.3",
     "tsd": "^0.17.0",
     "typescript": "^4.3.4"

package/typings/index.d.ts

@@ -31,6 +31,13 @@ export class InvalidArgumentError extends CommanderError {
 }
 export { InvalidArgumentError as InvalidOptionArgumentError }; // deprecated old name
 
+export interface ErrorOptions { // optional parameter for error()
+  /** an id string representing the error */
+  code?: string;
+  /** suggested exit code which could be used with process.exit */
+  exitCode?: number;
+}
+
 export class Argument {
   description: string;
   required: boolean;
@@ -61,7 +68,7 @@ export class Argument {
   /**
    * Only allow argument value to be one of choices.
    */
-  choices(values: string[]): this;
+  choices(values: readonly string[]): this;
 
   /**
    * Make argument required.
@@ -72,7 +79,7 @@ export class Argument {
    * Make argument optional.
    */
   argOptional(): this;
-  }
+}
 
 export class Option {
   flags: string;
@@ -109,7 +116,7 @@ export class Option {
    * new Option('--donate [amount]').preset('20').argParser(parseFloat);
    * ```
    */
-   preset(arg: unknown): this;
+  preset(arg: unknown): this;
 
   /**
    * Set environment variable to check for option value.
@@ -140,7 +147,7 @@ export class Option {
   /**
    * Only allow option value to be one of choices.
    */
-  choices(values: string[]): this;
+  choices(values: readonly string[]): this;
 
   /**
    * Return option name.
@@ -158,8 +165,7 @@ export class Option {
    *
    * Options are one of boolean, negated, required argument, or optional argument.
    */
-   isBoolean(): boolean;
-
+  isBoolean(): boolean;
 }
 
 export class Help {
@@ -340,8 +346,8 @@ export class Command {
    *
    * @returns `this` command for chaining
    */
-    argument<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
-    argument(name: string, description?: string, defaultValue?: unknown): this;
+  argument<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
+  argument(name: string, description?: string, defaultValue?: unknown): this;
 
   /**
    * Define argument syntax for command, adding a prepared argument.
@@ -388,6 +394,11 @@ export class Command {
    */
   exitOverride(callback?: (err: CommanderError) => never|void): this;
 
+  /**
+   * Display error message and exit (or call exitOverride).
+   */
+  error(message: string, errorOptions?: ErrorOptions): never;
+
   /**
    * You can customise the help with a subclass of Help by overriding createHelp,
    * or by overriding Help properties using configureHelp().
@@ -439,7 +450,7 @@ export class Command {
    */
   showSuggestionAfterError(displaySuggestion?: boolean): this;
 
-   /**
+  /**
    * Register callback `fn` for the command.
    *
    * @example
@@ -562,7 +573,7 @@ export class Command {
    */
   getOptionValueSource(key: string): OptionValueSource;
 
-   /**
+  /**
    * Alter parsing of short flags with optional values.
    *
    * @example
@@ -626,7 +637,7 @@ export class Command {
    *
    * @returns `this` command for chaining
    */
-  parse(argv?: string[], options?: ParseOptions): this;
+  parse(argv?: readonly string[], options?: ParseOptions): this;
 
   /**
    * Parse `argv`, setting options and invoking commands when defined.
@@ -645,7 +656,7 @@ export class Command {
    *
    * @returns Promise
    */
-  parseAsync(argv?: string[], options?: ParseOptions): Promise<this>;
+  parseAsync(argv?: readonly string[], options?: ParseOptions): Promise<this>;
 
   /**
    * Parse options from `argv` removing known options,
@@ -660,10 +671,15 @@ export class Command {
   parseOptions(argv: string[]): ParseOptionsResult;
 
   /**
-   * Return an object containing options as key-value pairs
+   * Return an object containing local option values as key-value pairs
    */
   opts<T extends OptionValues>(): T;
 
+  /**
+   * Return an object containing merged local and global option values as key-value pairs.
+   */
+  optsWithGlobals<T extends OptionValues>(): T;
+
   /**
    * Set the description.
    *
@@ -698,7 +714,7 @@ export class Command {
    *
    * @returns `this` command for chaining
    */
-  aliases(aliases: string[]): this;
+  aliases(aliases: readonly string[]): this;
   /**
    * Get aliases for the command.
    */
@@ -759,7 +775,7 @@ export class Command {
    */
   executableDir(): string;
 
-   /**
+  /**
    * Output help information for this command.
    *
    * Outputs built-in help, and custom text added using `.addHelpText()`.