commander 7.0.0 → 7.1.0

package/CHANGELOG.md

@@ -8,6 +8,26 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
+## [7.1.0] (2021-02-15)
+
+### Added
+
+- support for named imports from ECMAScript modules ([#1440])
+- add `.cjs` to list of expected script file extensions ([#1449])
+- allow using option choices and variadic together ([#1454])
+
+### Fixed
+
+- replace use of deprecated `process.mainModule` ([#1448])
+- regression for legacy `command('*')` and call when command line includes options ([#1464])
+- regression for `on('command:*', ...)` and call when command line includes unknown options ([#1464])
+- display best error for combination of unknown command and unknown option (i.e. unknown command) ([#1464])
+
+### Changed
+
+- make TypeScript typings tests stricter ([#1453])
+- improvements to README and tests
+
 ## [7.0.0] (2021-01-15)
 
 ### Added
@@ -53,7 +73,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - *Breaking:* `.passCommandToAction()` ([#1409])
     - no longer needed as action handler is passed options and command
 - *Breaking:* "extra arguments" parameter to action handler ([#1409])
-    - if being used to detect excess arguments, there is now an error displayed by default
+    - if being used to detect excess arguments, there is now an error available by setting `.allowExcessArguments(false)`
 
 ### Migration Tips
 
@@ -376,8 +396,17 @@ to expand `-fb` to `-f -b` rather than `-f b`.
 [#1403]: https://github.com/tj/commander.js/pull/1403
 [#1409]: https://github.com/tj/commander.js/pull/1409
 [#1427]: https://github.com/tj/commander.js/pull/1427
+[#1440]: https://github.com/tj/commander.js/pull/1440
+[#1448]: https://github.com/tj/commander.js/pull/1448
+[#1449]: https://github.com/tj/commander.js/pull/1449
+[#1453]: https://github.com/tj/commander.js/pull/1453
+[#1454]: https://github.com/tj/commander.js/pull/1454
+[#1464]: https://github.com/tj/commander.js/pull/1464
+
+
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[7.1.0]: https://github.com/tj/commander.js/compare/v7.0.0...v7.1.0
 [7.0.0]: https://github.com/tj/commander.js/compare/v6.2.1...v7.0.0
 [7.0.0-2]: https://github.com/tj/commander.js/compare/v7.0.0-1...v7.0.0-2
 [7.0.0-1]: https://github.com/tj/commander.js/compare/v7.0.0-0...v7.0.0-1

package/Readme.md

@@ -39,7 +39,6 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [Legacy options as properties](#legacy-options-as-properties)
     - [TypeScript](#typescript)
     - [createCommand()](#createcommand)
-    - [Import into ECMAScript Module](#import-into-ecmascript-module)
     - [Node options such as `--harmony`](#node-options-such-as---harmony)
     - [Debugging stand-alone executable subcommands](#debugging-stand-alone-executable-subcommands)
     - [Override exit and output handling](#override-exit-and-output-handling)
@@ -74,6 +73,23 @@ const program = new Command();
 program.version('0.0.1');
 ```
 
+For named imports in ECMAScript modules, import from `commander/esm.mjs`.
+
+```js
+// index.mjs
+import { Command } from 'commander/esm.mjs';
+const program = new Command();
+```
+
+And in TypeScript:
+
+```ts
+// index.ts
+import { Command } from 'commander';
+const program = new Command();
+```
+
+
 ## Options
 
 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 ('|').
@@ -655,7 +671,7 @@ You can execute custom actions by listening to command and option events.
 
 ```js
 program.on('option:verbose', function () {
-  process.env.VERBOSE = this.verbose;
+  process.env.VERBOSE = this.opts().verbose;
 });
 
 program.on('command:*', function (operands) {
@@ -740,8 +756,6 @@ program
 
 ### TypeScript
 
-The Commander package includes its TypeScript Definition file.
-
 If you use `ts-node` and  stand-alone executable subcommands written as `.ts` files, you need to call your program through node to get the subcommands called correctly. e.g.
 
 ```bash
@@ -761,17 +775,6 @@ const program = createCommand();
 when creating subcommands using `.command()`, and you may override it to
 customise the new subcommand (example file [custom-command-class.js](./examples/custom-command-class.js)).
 
-### Import into ECMAScript Module
-
-Commander is currently a CommonJS package, and the default export can be imported into an ES Module:
-
-```js
-// index.mjs
-import commander from 'commander';
-const program = commander.program;
-const newCommand = new commander.Command();
-```
-
 ### Node options such as `--harmony`
 
 You can enable `--harmony` option in two ways:

package/esm.mjs

@@ -0,0 +1,4 @@
+import commander from './index.js';
+
+// wrapper to provide named exports for ESM.
+export const { program, Option, Command, CommanderError, InvalidOptionArgumentError, Help, createCommand } = commander;

package/index.js

@@ -425,6 +425,18 @@ class Option {
     return this;
   };
 
+  /**
+   * @api private
+   */
+
+  _concatValue(value, previous) {
+    if (previous === this.defaultValue || !Array.isArray(previous)) {
+      return [value];
+    }
+
+    return previous.concat(value);
+  }
+
   /**
    * Only allow option value to be one of choices.
    *
@@ -434,10 +446,13 @@ class Option {
 
   choices(values) {
     this.argChoices = values;
-    this.parseArg = (arg) => {
+    this.parseArg = (arg, previous) => {
       if (!values.includes(arg)) {
         throw new InvalidOptionArgumentError(`Allowed choices are ${values.join(', ')}.`);
       }
+      if (this.variadic) {
+        return this._concatValue(arg, previous);
+      }
       return arg;
     };
     return this;
@@ -976,11 +991,7 @@ class Command extends EventEmitter {
           throw err;
         }
       } else if (val !== null && option.variadic) {
-        if (oldValue === defaultValue || !Array.isArray(oldValue)) {
-          val = [val];
-        } else {
-          val = oldValue.concat(val);
-        }
+        val = option._concatValue(val, oldValue);
       }
 
       // unassigned or boolean value
@@ -1270,10 +1281,8 @@ class Command extends EventEmitter {
       default:
         throw new Error(`unexpected parse option { from: '${parseOptions.from}' }`);
     }
-    // @ts-ignore: unknown property
-    if (!this._scriptPath && process.mainModule) {
-      // @ts-ignore: unknown property
-      this._scriptPath = process.mainModule.filename;
+    if (!this._scriptPath && require.main) {
+      this._scriptPath = require.main.filename;
     }
 
     // Guess name, used in usage in help.
@@ -1319,7 +1328,7 @@ class Command extends EventEmitter {
   _executeSubCommand(subcommand, args) {
     args = args.slice();
     let launchWithNode = false; // Use node for source targets so do not need to get permissions correct, and on Windows.
-    const sourceExt = ['.js', '.ts', '.tsx', '.mjs'];
+    const sourceExt = ['.js', '.ts', '.tsx', '.mjs', '.cjs'];
 
     // Not checking for help first. Unlikely to have mandatory and executable, and can't robustly test for help flags in external command.
     this._checkForMissingMandatoryOptions();
@@ -1327,10 +1336,8 @@ class Command extends EventEmitter {
     // Want the entry script as the reference for command name and directory for searching for other files.
     let scriptPath = this._scriptPath;
     // Fallback in case not set, due to how Command created or called.
-    // @ts-ignore: unknown property
-    if (!scriptPath && process.mainModule) {
-      // @ts-ignore: unknown property
-      scriptPath = process.mainModule.filename;
+    if (!scriptPath && require.main) {
+      scriptPath = require.main.filename;
     }
 
     let baseDir;
@@ -1468,12 +1475,17 @@ class Command extends EventEmitter {
 
       outputHelpIfRequested(this, parsed.unknown);
       this._checkForMissingMandatoryOptions();
-      if (parsed.unknown.length > 0) {
-        this.unknownOption(parsed.unknown[0]);
-      }
+
+      // We do not always call this check to avoid masking a "better" error, like unknown command.
+      const checkForUnknownOptions = () => {
+        if (parsed.unknown.length > 0) {
+          this.unknownOption(parsed.unknown[0]);
+        }
+      };
 
       const commandEvent = `command:${this.name()}`;
       if (this._actionHandler) {
+        checkForUnknownOptions();
         // Check expected arguments and collect variadic together.
         const args = this.args.slice();
         this._args.forEach((arg, i) => {
@@ -1491,19 +1503,24 @@ class Command extends EventEmitter {
         this._actionHandler(args);
         if (this.parent) this.parent.emit(commandEvent, operands, unknown); // legacy
       } else if (this.parent && this.parent.listenerCount(commandEvent)) {
+        checkForUnknownOptions();
         this.parent.emit(commandEvent, operands, unknown); // legacy
       } else if (operands.length) {
-        if (this._findCommand('*')) { // legacy
+        if (this._findCommand('*')) { // legacy default command
           this._dispatchSubcommand('*', operands, unknown);
         } else if (this.listenerCount('command:*')) {
+          // skip option check, emit event for possible misspelling suggestion
           this.emit('command:*', operands, unknown);
         } else if (this.commands.length) {
           this.unknownCommand();
+        } else {
+          checkForUnknownOptions();
         }
       } else if (this.commands.length) {
         // This command has subcommands and nothing hooked up at this level, so display help.
         this.help({ error: true });
       } else {
+        checkForUnknownOptions();
         // fall through for caller to handle after calling .parse()
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -19,18 +19,21 @@
     "url": "https://github.com/tj/commander.js.git"
   },
   "scripts": {
-    "lint": "eslint index.js \"tests/**/*.js\"",
+    "lint": "eslint index.js esm.mjs \"tests/**/*.js\"",
     "typescript-lint": "eslint typings/*.ts",
     "test": "jest && npm run test-typings",
-    "test-typings": "tsc -p tsconfig.json",
+    "test-esm": "node --experimental-modules ./tests/esm-test.mjs",
+    "test-typings": "tsd",
     "typescript-checkJS": "tsc --allowJS --checkJS index.js --noEmit",
-    "test-all": "npm run test && npm run lint && npm run typescript-lint && npm run typescript-checkJS"
+    "test-all": "npm run test && npm run lint && npm run typescript-lint && npm run typescript-checkJS && npm run test-esm"
   },
-  "main": "index",
+  "main": "./index.js",
   "files": [
     "index.js",
+    "esm.mjs",
     "typings/index.d.ts"
   ],
+  "type": "commonjs",
   "dependencies": {},
   "devDependencies": {
     "@types/jest": "^26.0.20",
@@ -42,9 +45,10 @@
     "eslint-plugin-jest": "^24.1.3",
     "jest": "^26.6.3",
     "standard": "^16.0.3",
+    "tsd": "^0.14.0",
     "typescript": "^4.1.2"
   },
-  "typings": "typings/index.d.ts",
+  "types": "typings/index.d.ts",
   "jest": {
     "collectCoverage": true
   },