@commander-js/extra-typings - npm Package Compare versions

Comparing version 13.1.0 to 14.0.0

index.d.ts

@@ -77,3 +77,3 @@ // eslint complains about {} as a type, but hard to be more accurate.
 // Resolve whether argument required, and strip []/<> from around value.
-type InferArgument<
+export type InferArgument<
   S extends string,
@@ -108,7 +108,8 @@ DefaultT = undefined,
 
-type InferArguments<S extends string> = S extends `${infer First} ${infer Rest}`
-  ? [InferArgument<First>, ...InferArguments<TrimLeft<Rest>>]
-  : [InferArgument<S>];
+export type InferArguments<S extends string> =
+  S extends `${infer First} ${infer Rest}`
+    ? [InferArgument<First>, ...InferArguments<TrimLeft<Rest>>]
+    : [InferArgument<S>];
 
-type InferCommandArguments<S extends string> =
+export type InferCommandArguments<S extends string> =
   S extends `${string} ${infer Args}` ? InferArguments<TrimLeft<Args>> : [];
@@ -277,3 +278,3 @@
 // Split up Usage into Flags and Value
-type InferOptions<
+export type InferOptions<
   Options,
@@ -374,2 +375,3 @@ Usage extends string,
   defaultValueDescription?: string;
+  parseArg?: <T>(value: string, previous: T) => T;
   argChoices?: string[];
@@ -447,2 +449,3 @@
   argChoices?: string[];
+  helpGroupHeading?: string;
 
@@ -543,2 +546,7 @@ constructor(flags: Usage, description?: string);
   /**
+   * Set the help group heading.
+   */
+  helpGroup(heading: string): this;
+
+  /**
    * Return whether a boolean option.
@@ -664,2 +672,16 @@ *
 
+  /**
+   * Format a list of items, given a heading and an array of formatted items.
+   */
+  formatItemList(heading: string, items: string[], helper: Help): string[];
+
+  /**
+   * Group items by their help group heading.
+   */
+  groupItems<T extends Command | Option>(
+    unsortedItems: T[],
+    visibleItems: T[],
+    getGroup: (item: T) => string,
+  ): Map<string, T[]>;
+
   /** Generate the built-in help text. */
@@ -824,3 +846,3 @@ formatHelp(cmd: CommandUnknownOpts, helper: Help): string;
     description: string,
-    fn: (value: string, previous: T) => T,
+    parseArg: (value: string, previous: T) => T,
   ): Command<[...Args, InferArgument<S, undefined, T>], Opts, GlobalOpts>;
@@ -830,3 +852,3 @@ argument<S extends string, T>(
     description: string,
-    fn: (value: string, previous: T) => T,
+    parseArg: (value: string, previous: T) => T,
     defaultValue: T,
@@ -1397,2 +1419,49 @@ ): Command<[...Args, InferArgument<S, T, T>], Opts, GlobalOpts>;
   /**
+   * Set the help group heading for this subcommand in parent command's help.
+   *
+   * @returns `this` command for chaining
+   */
+  helpGroup(heading: string): this;
+  /**
+   * Get the help group heading for this subcommand in parent command's help.
+   */
+  helpGroup(): string;
+
+  /**
+   * Set the default help group heading for subcommands added to this command.
+   * (This does not override a group set directly on the subcommand using .helpGroup().)
+   *
+   * @example
+   * program.commandsGroup('Development Commands:);
+   * program.command('watch')...
+   * program.command('lint')...
+   * ...
+   *
+   * @returns `this` command for chaining
+   */
+  commandsGroup(heading: string): this;
+  /**
+   * Get the default help group heading for subcommands added to this command.
+   */
+  commandsGroup(): string;
+
+  /**
+   * Set the default help group heading for options added to this command.
+   * (This does not override a group set directly on the option using .helpGroup().)
+   *
+   * @example
+   * program
+   *   .optionsGroup('Development Options:')
+   *   .option('-d, --debug', 'output extra debugging')
+   *   .option('-p, --profile', 'output profiling information')
+   *
+   * @returns `this` command for chaining
+   */
+  optionsGroup(heading: string): this;
+  /**
+   * Get the default help group heading for options added to this command.
+   */
+  optionsGroup(): string;
+
+  /**
    * Output help information for this command.
@@ -1399,0 +1468,0 @@ *

package.json

 {
   "name": "@commander-js/extra-typings",
-  "version": "13.1.0",
+  "version": "14.0.0",
   "description": "Infer strong typings for commander options and action handlers",
@@ -46,3 +46,3 @@ "main": "index.js",
   "peerDependencies": {
-    "commander": "~13.1.0"
+    "commander": "~14.0.0"
   },
@@ -52,3 +52,3 @@ "devDependencies": {
     "@types/node": "^22.10.1",
-    "commander": "~13.1.0",
+    "commander": "~14.0.0",
     "eslint": "^9.16.0",
@@ -55,0 +55,0 @@ "eslint-config-prettier": "^10.0.1",

README.md

@@ -19,3 +19,3 @@ # extra-typings for commander
 - install `commander`, if not already installed (peer dependency)
-- in code import from `@commander-js/extra-typings` instead of `commander`
+- in code import from `@commander-js/extra-typings` instead of `commander` (or set up an ambient module)
 
@@ -68,1 +68,24 @@ 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)).
 ```
+
+## Ambient module setup
+
+An alternative approach is to setup `@commander-js/extra-typings` as an ambient module and a development-only dependency. We only worked
+this out recently so it isn't being promoted as the suggested method yet!
+
+Add a simple ambient module file to your project to use the enhanced typings instead of the default typings:
+
+```typescript
+// commander.d.ts
+declare module "commander" {
+  export * from "@commander-js/extra-typings";
+}
+```
+
+Import from `commander` as usual and you hopefully get the extra typings from the ambient module without needing `extra-typings` at runtime:
+
+```typescript
+import { Command } from 'commander';
+const program = new Command()
+  .option('-d, --debug');
+const options = program.opts(); // smart type
+```

No alert changes

Improved metrics

Total package byte prevSize

53782

5.41%

Lines of code

1421

4.64%

Number of lines in readme file

90

34.33%

No dependency changes