Improve command option types

[bschlenk]

Pull Request

⚠️ For discussion only ⚠️

Use TypeScript's new template literal types to improve the command option types. This allows the option flags to be parsed at the type level, giving accurate types to the resulting program object instead of falling back on { [key: string]: any }.

• camelCase properties
• distinguish between true / false / undefined values
• handle option and requiredOption differently
• update commander-tests.ts to pass
• handle --no- prefixed options
• handle .storeOptionsAsProperties(false)
• handle .opts()
• handle .addOption() Enhance Option class to allow hiding help, specifying choices, and change how default value displayed in help #1331

Problem

Currently there is no real type checking for options, so I might access an option that doesn't exist.

Solution

TypeScript recently added template literal types, allowing types to match patterns in strings. This allows us to parse the option name, and whether it has a required/optional value. Note that this feature is not released yet, but could be released with TypeScript 4.1.0.

See a working example on the typescript playground. Scroll to the bottom and hover the program variable.

TypeScript will fail to compile if the option flags are not in the right format.

To get the right behavior, the result of chaining off of commander needs to be assigned to a new variable, since the type is built up as a result of the chaining.

ChangeLog

[shadowspawn]

Related: #1245

[shadowspawn]

Very cool, thanks for sharing! There will be lots of challenges to making the inferred typing accurate. There is also:

• .storeOptionsAsProperties(false)
• .opts()
• .addOption() Enhance Option class to allow hiding help, specifying choices, and change how default value displayed in help #1331

Removing the option-keys from the program type when .storeOptionsAsProperties(false) would be a big win on its own, as there is currently no TypeScript assistance for detecting incorrect routine names because of the generic typing for the option-keys.

[bschlenk]

Another challenge is the --no- prefix. The way I'm doing this now, where the extracted type of each .option call is &ed with this ends up breaking if you have both --cheese and --no-cheese. It ends up doing { cheese?: string | true } & { cheese?: boolean }, which typescript merges as { cheese?: undefined }. We'd need to use something like this stackoverflow answer, but hopefully simpler.

[shadowspawn]

For interest, I did some quick research on whether possible to support multiple versions of TypeScript

• https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html#version-selection-with-typesversions

[shadowspawn]

This PR is not active, but has demonstrated some pretty interesting possibilities.

It will be hard to do an accurate representation of the options due to the flexible ways they are described and added, and not easily cover all use cases (e.g. the typings will not be trivially available for parameter of an action handler). But deduced typings may be looked at again in future.

Thank you for your contributions.

[shadowspawn]

For some experimental strong inferred typing see: https://github.com/commander-js/extra-typings