Merge release/13.x

CHANGELOG.md

@@ -9,6 +9,26 @@ The version numbering does not follow semantic versioning but instead aligns wit
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
+## [13.0.0] (2024-12-31)
+
+### Added
+
+- strongly type `.optsWithGlobals()` to include inferred globals ([#78])
+- weakly type `.getOptionValueSourceWithGlobals()` to include inferred globals ([#78])
+- infer narrow types for choices, so no longer need to specify as `const` ([#79])
+
+### Changed
+
+- *Breaking:* Typescript 5.0 or higher is required ([#79])
+
+## [13.0.0-1] (2024-12-08)
+
+(Released in 13.0.0)
+
+## 13.0.0-0 (2024-12-08) [YANKED]
+
+Published from wrong branch.
+
 ## [12.1.0] (2024-05-18)
 
 ### Changed
@@ -168,6 +188,8 @@ The version numbering does not follow semantic versioning but instead aligns wit
 - inferred types for `.action()`
 - inferred types for `.opts()`
 
+[13.0.0]: https://github.com/commander-js/extra-typings/compare/v12.1.0...v13.0.0
+[13.0.0-1]: https://github.com/commander-js/extra-typings/compare/v12.1.0...v13.0.0-1
 [12.1.0]: https://github.com/commander-js/extra-typings/compare/v12.0.1...v12.1.0
 [12.0.1]: https://github.com/commander-js/extra-typings/compare/v12.0.0...v12.0.1
 [12.0.0]: https://github.com/commander-js/extra-typings/compare/v11.0.0...v12.0.0
@@ -197,7 +219,8 @@ The version numbering does not follow semantic versioning but instead aligns wit
 [#49]: https://github.com/commander-js/extra-typings/pull/49
 [#50]: https://github.com/commander-js/extra-typings/pull/50
 [#59]: https://github.com/commander-js/extra-typings/pull/59
-
 [#65]: https://github.com/commander-js/extra-typings/pull/65
 [#66]: https://github.com/commander-js/extra-typings/pull/66
 [#70]: https://github.com/commander-js/extra-typings/pull/70
+[#78]: https://github.com/commander-js/extra-typings/pull/78
+[#79]: https://github.com/commander-js/extra-typings/pull/79

README.md

@@ -8,6 +8,8 @@ This package offers TypeScript typings for `commander` which infer strong types
 - all the parameters of the action handler, including the options
 - options returned by `.opts()`
 
+This package requires TypeScript 5.0 or higher.
+
 The runtime is supplied by commander. This package is all about the typings.
 
 Usage
@@ -62,16 +64,3 @@ const program = new Command()
   .option('-d, --debug'); // program type includes chained options and arguments
 const options = program.opts(); // smart type
 ```
-
-Use a "const assertion" on the choices to narrow the option type from `string`:
-
-```typescript
-const program = new Command()
-  .addOption(
-    new Option('--drink-size <size>')
-      .choices(['small', 'medium', 'large'] as const)
-      // if you want to provide a default option, also add a const assertion to it
-      .default('medium' as const)
-  ).parse();
-const drinkSize = program.opts().drinkSize; // "small" | "medium" | "large" | undefined
-```

eslint.config.js

@@ -3,26 +3,15 @@ const esLintjs = require('@eslint/js');
 const jest = require('eslint-plugin-jest');
 const tseslint = require('typescript-eslint');
 const prettier = require('eslint-config-prettier');
-//const jsdoc = require('eslint-plugin-jsdoc');
 
-// Only run tseslint on the files that we have included for TypeScript.
+// Simpler setup than in Commander as not running TypeScript over .js files.
 const tsconfigTsFiles = ['**/*.{ts,mts}'];
-const tsconfigJsFiles = ['**.{js,mjs}'];
 
 // Using tseslint.config adds some type safety and `extends` to simplify customising config array.
 module.exports = tseslint.config(
   // Add recommended rules.
   esLintjs.configs.recommended,
-  // jsdoc.configs['flat/recommended'],
   jest.configs['flat/recommended'],
-  // tseslint with different setup for js/ts
-  {
-    files: tsconfigJsFiles,
-    extends: [...tseslint.configs.recommended],
-    rules: {
-      '@typescript-eslint/no-var-requires': 'off', // (tseslint does not autodetect commonjs context )
-    },
-  },
   {
     files: tsconfigTsFiles,
     extends: [...tseslint.configs.recommended],
@@ -34,11 +23,6 @@ module.exports = tseslint.config(
     files: ['**/*.{js,mjs,cjs}', '**/*.{ts,mts,cts}'],
     rules: {
       'no-else-return': ['error', { allowElseIf: false }],
-
-      // 'jsdoc/tag-lines': 'off',
-      // 'jsdoc/require-jsdoc': 'off',
-      // 'jsdoc/require-param-description': 'off',
-      // 'jsdoc/require-returns-description': 'off',
     },
     languageOptions: {
       globals: {
@@ -59,7 +43,7 @@ module.exports = tseslint.config(
     },
   },
   {
-    files: [...tsconfigTsFiles, ...tsconfigJsFiles],
+    files: [...tsconfigTsFiles],
     rules: {
       '@typescript-eslint/no-unused-vars': 'off',
       '@typescript-eslint/ban-ts-comment': [

examples/assemble-program.ts

@@ -0,0 +1,11 @@
+import { Command } from '../index.js';
+
+// Example of strongly typed globals in a subcommand which is added to program using .addCommand().
+// Declare factory function for root Command in separate file from adding subcommands to avoid circular dependencies.
+
+export function createProgram() {
+  const program = new Command().option('-g, --global');
+  return program;
+}
+
+export type ProgramOpts = ReturnType<ReturnType<typeof createProgram>['opts']>;

examples/assemble-sub.ts

@@ -0,0 +1,14 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+
+// Example of strongly typed globals in a subcommand which is added to program using .addCommand().
+
+import { Command } from '../index.js';
+import { type ProgramOpts } from './assemble-program.js';
+
+export function createSub() {
+  const program = new Command<[], {}, ProgramOpts>('sub').option('-l, --local');
+  const optsWithGlobals = program.optsWithGlobals();
+  return program;
+}
+
+export type SubOpts = ReturnType<typeof createSub>['opts'];

examples/assemble.ts

@@ -0,0 +1,11 @@
+import { createProgram, type ProgramOpts } from './assemble-program';
+import { createSub, type SubOpts } from './assemble-sub';
+
+// Example of strongly typed globals in a subcommand which is added to program using .addCommand().
+
+export function AssembleProgram() {
+  const program = createProgram();
+  const subCommand = createSub();
+  program.addCommand(subCommand);
+  return program;
+}