Allow dynamically updating version number and version option flags and description

[aweebit]

Problem

// demo.js
const { Command } = require('commander');

const flags = '-v, --my-version';
const description = 'custom version option description';

var program = new Command();
program
  .version('1.0.0')
  .version('2.0.0', flags, description); // expectation: the version number and option's flags and description are updated
program.outputHelp(); // reality: a new option is added

var program = new Command();
program
  .version('1.0.0')
  .version('2.0.0'); // expectation: the version number is updated
program.outputHelp(); // reality: a new option is added

var program = new Command();
program
  .version('1.0.0')
  .version(program._version, flags); // expectation: the version option's flags are updated
program.outputHelp(); // reality: a new option is added

var program = new Command();
program
  .version('1.0.0')
  .version(program._version, undefined, description); // expectation: the version option's description is updated
program.outputHelp(); // reality: a new option is added

var program = new Command();
const result = program
  .version('1.0.0')
  .version(undefined, flags, description); // expectation: the version option's flags and description are updated
program.outputHelp(); // reality: the flags are not updated
console.log(result); // the version number is returned instead

// A real-world example
var program = new Command();
program.version('1.0.0');
if ('EARLY_ADOPTER' in process.env) {
  program.version('2.0.0'); // expectation: the version number is simply updated
}
program.outputHelp(); // reality: contains version option twice if early adopter
program.parse(['--version'], { from: 'user' }); // output is always '1.0.0'

EARLY_ADOPTER= node demo.js

Solution

Rework version() to make all the above examples behave as expected.

Includes various improvements to the code for the version option, including the type fix from #1930. For reasoning behind those improvements, see the commit descriptions.

ChangeLog

Added

• support for dynamically updating version number and version option flags and description via .version()

Fixed

• (from #1930) .version() optional parameter type

Peer PRs

…solving similar problems

• Use createOption() in helpOption() to support custom option flag extraction (+ various improvements) #1929 and it's extensions (storing the help option instance in _helpOption instead of only the individual flags in _helpShortFlag and _helpLongFlag)

[shadowspawn]

A quick reaction. I don't think being able to call .version() twice is important. On a related note in terms of early detection by author that it does not work that way, there is the PR open to add an error for overlapping option flags.

[aweebit]

I don't think being able to call .version() twice is important.

The last example in the demo code shows it could be important.

Being able to call .version() twice with new flags and description is not that important, but added for completeness and to provide meaning to calls that currently don't have any well-defined meaning at all.

On a related note in terms of early detection by author that it does not work that way, there is the PR open to add an error for overlapping option flags.

If you mean #1923, I updated it a few hours ago so that version option flag conflicts are handled, too. But it solves a different problem.

[shadowspawn]

I was quite surprised this refactor did not break the typescript-checkJS run-script. At one time I am pretty sure we were getting errors for JavaScript properties which were not declared/set in the constructor.

TypeScript may have removed that check as too strict for real-world JavaScript.

microsoft/TypeScript#22896

[shadowspawn]

I do not currently want this functionality or refactor of Option, thanks. The .version() support is a simple convenience to add a version option with an event handler to display the version.

I see one commit was initialising this._version and this._versionOption in the constructor. That is consistent with our normal pattern if you want to suggest that separately.

(.version() started out looking like a getter/setter for a "version" property, including returning it in .opts(). Now I don't think it should be acting as a getter and I don't want to store _version or _versionOption, so I should declare that behaviour deprecated!)

[shadowspawn]

I see one commit was initialising this._version and this._versionOption in the constructor. That is consistent with our normal pattern if you want to suggest that separately.

Actually, no. I'll leave it undeclared and deprecate it as moving in the preferred direction.

[edit] Opened #1954