README.md (3234B)
1 # extra-typings for commander 2 3 [](https://www.npmjs.org/package/@commander-js/extra-typings) 4 [](https://npmcharts.com/compare/@commander-js/extra-typings?minimal=true) 5 6 This package offers experimental TypeScript typings for `commander` which infer strong types for: 7 8 - all the parameters of the action handler, including the options 9 - options returned by `.opts()` 10 11 The runtime is supplied by commander. This package is all about the typings. 12 13 Usage 14 15 - install `@commander-js/extra-typings` using your preferred package manager 16 - install `commander`, if not already installed (peer dependency) 17 - in code import from `@commander-js/extra-typings` instead of `commander` 18 19 The installed version of this package should match the major and minor version numbers of the installed commander package, but the patch version number is independent (following pattern used by [Definitely Typed](https://github.com/DefinitelyTyped/DefinitelyTyped#how-do-definitely-typed-package-versions-relate-to-versions-of-the-corresponding-library)). 20 21 Credit: this builds on work by @PaperStrike in <https://github.com/tj/commander.js/pull/1758> 22 23 ## Limitations 24 25 - the generics lead to some noisy types visible in editor and errors 26 - some minor code changes required for subclasses of `Command`, `Argument`, or `Option` (see [subclass.test-d.ts](./tests/subclass.test-d.ts)) 27 - chaining methods which do type inference return base class rather than `this` 28 - subclass of `Command` returns base class not subclass from `.command(name)` 29 - type parameter needed for class declaration of subclass of `Option` and `Argument` 30 31 ## Usage tips 32 33 The types are built up as the options and arguments are defined. The usage pattern for action handlers is easy. Just chain the action handler after the options and arguments. 34 35 ```typescript 36 import { program } from '@commander-js/extra-typings'; 37 38 program.command('print') 39 .argument('<file>') 40 .option('--double-sided') 41 .action((targetFile, options) => { 42 // command-arguments and options are fully typed 43 }); 44 ``` 45 46 For working with a single command without an action handler, the configuration need to be done at the same time as the variable is declared. 47 48 ```typescript 49 import { Command } from '@commander-js/extra-typings'; 50 51 // broken pattern 52 const program = new Command(); // program type does not include options or arguments 53 program.option('-d, --debug'); // adding option does not change type of program 54 const options = program.opts(); // dumb type 55 ``` 56 57 ```typescript 58 import { Command } from '@commander-js/extra-typings'; 59 60 // working pattern 61 const program = new Command() 62 .option('-d, --debug'); // program type includes chained options and arguments 63 const options = program.opts(); // smart type 64 ``` 65 66 Use a "const assertion" on the choices to narrow the option type from `string`: 67 68 ```typescript 69 const program = new Command() 70 .addOption(new Option('--drink-size <size>').choices(['small', 'medium', 'large'] as const)) 71 .parse(); 72 const drinkSize = program.opts().drinkSize; // "small" | "medium" | "large" | undefined 73 ```