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

Comparing version 12.1.0 to 13.0.0-0

index.d.ts

@@ -0,1 +1,4 @@
+// eslint complains about {} as a type, but hard to be more accurate.
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+
 type TrimRight<S extends string> = S extends `${infer R} ` ? TrimRight<R> : S;
@@ -108,3 +111,3 @@ type TrimLeft<S extends string> = S extends ` ${infer R}` ? TrimLeft<R> : S;
 
-type InferCommmandArguments<S extends string> =
+type InferCommandArguments<S extends string> =
   S extends `${string} ${infer Args}` ? InferArguments<TrimLeft<Args>> : [];
@@ -317,8 +320,6 @@
 
-export type CommandUnknownOpts = Command<unknown[], OptionValues>;
+export type CommandUnknownOpts = Command<unknown[], OptionValues, OptionValues>;
 
 // ----- full copy of normal commander typings from here down, with extra type inference -----
 
-// Using method rather than property for method-signature-style, to document method overloads separately. Allow either.
-/* eslint-disable @typescript-eslint/method-signature-style */
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -389,3 +390,3 @@
    */
-  default<T>(
+  default<const T>(
     value: T,
@@ -405,3 +406,3 @@ description?: string,
    */
-  choices<T extends readonly string[]>(
+  choices<const T extends readonly string[]>(
     values: T,
@@ -452,3 +453,3 @@ ): Argument<Usage, DefaultT, undefined, ArgRequired, T[number]>; // setting CoerceT to undefined because choices overrides argParser
    */
-  default<T>(
+  default<const T>(
     value: T,
@@ -468,3 +469,5 @@ description?: string,
    */
-  preset<T>(arg: T): Option<Usage, T, DefaultT, CoerceT, Mandatory, ChoicesT>;
+  preset<const T>(
+    arg: T,
+  ): Option<Usage, T, DefaultT, CoerceT, Mandatory, ChoicesT>;
 
@@ -525,3 +528,3 @@ /**
    */
-  choices<T extends readonly string[]>(
+  choices<const T extends readonly string[]>(
     values: T,
@@ -537,3 +540,3 @@ ): Option<Usage, PresetT, DefaultT, undefined, Mandatory, T[number]>; // setting CoerceT to undefined becuase choices overrides argParser
    * Return option name, in a camelcase format that can be used
-   * as a object attribute key.
+   * as an object attribute key.
    */
@@ -553,2 +556,3 @@ attributeName(): string;
   helpWidth?: number;
+  minWidthToWrap: number;
   sortSubcommands: boolean;
@@ -560,2 +564,14 @@ sortOptions: boolean;
 
+  /*
+   * prepareContext is called by Commander after applying overrides from `Command.configureHelp()`
+   * and just before calling `formatHelp()`.
+   *
+   * Commander just uses the helpWidth and the others are provided for subclasses.
+   */
+  prepareContext(contextOptions: {
+    error?: boolean;
+    helpWidth?: number;
+    outputHasColors?: boolean;
+  }): void;
+
   /** Get the command term to show in the list of subcommands. */
@@ -596,2 +612,32 @@ subcommandTerm(cmd: CommandUnknownOpts): string;
   longestArgumentTermLength(cmd: CommandUnknownOpts, helper: Help): number;
+
+  /** Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations. */
+  displayWidth(str: string): number;
+
+  /** Style the titles. Called with 'Usage:', 'Options:', etc. */
+  styleTitle(title: string): string;
+
+  /** Usage: <str> */
+  styleUsage(str: string): string;
+  /** Style for command name in usage string.  */
+  styleCommandText(str: string): string;
+
+  styleCommandDescription(str: string): string;
+  styleOptionDescription(str: string): string;
+  styleSubcommandDescription(str: string): string;
+  styleArgumentDescription(str: string): string;
+  /** Base style used by descriptions. */
+  styleDescriptionText(str: string): string;
+
+  styleOptionTerm(str: string): string;
+  styleSubcommandTerm(str: string): string;
+  styleArgumentTerm(str: string): string;
+
+  /** Base style used in terms and usage for options. */
+  styleOptionText(str: string): string;
+  /** Base style used in terms and usage for subcommands. */
+  styleSubcommandText(str: string): string;
+  /** Base style used in terms and usage for arguments. */
+  styleArgumentText(str: string): string;
+
   /** Calculate the pad width from the maximum term length. */
@@ -601,10 +647,22 @@ padWidth(cmd: CommandUnknownOpts, helper: Help): number;
   /**
-   * Wrap the given string to width characters per line, with lines after the first indented.
-   * Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted.
+   * Wrap a string at whitespace, preserving existing line breaks.
+   * Wrapping is skipped if the width is less than `minWidthToWrap`.
    */
-  wrap(
-    str: string,
-    width: number,
-    indent: number,
-    minColumnWidth?: number,
+  boxWrap(str: string, width: number): string;
+
+  /** Detect manually wrapped and indented strings by checking for line break followed by whitespace. */
+  preformatted(str: string): boolean;
+
+  /**
+   * Format the "item", which consists of a term and description. Pad the term and wrap the description, indenting the following lines.
+   *
+   * So "TTT", 5, "DDD DDDD DD DDD" might be formatted for this.helpWidth=17 like so:
+   *   TTT    DDD DDDD
+   *          DD DDD
+   */
+  formatItem(
+    term: string,
+    termWidth: number,
+    description: string,
+    helper: Help,
   ): string;
@@ -632,5 +690,10 @@
   writeErr?(str: string): void;
+  outputError?(str: string, write: (str: string) => void): void;
+
   getOutHelpWidth?(): number;
   getErrHelpWidth?(): number;
-  outputError?(str: string, write: (str: string) => void): void;
+
+  getOutHasColors?(): boolean;
+  getErrHasColors?(): boolean;
+  stripColor?(str: string): string;
 }
@@ -647,5 +710,7 @@
 
-// eslint unimpressed with `OptionValues = {}`, but not sure what to use instead.
-// eslint-disable-next-line @typescript-eslint/ban-types
-export class Command<Args extends any[] = [], Opts extends OptionValues = {}> {
+export class Command<
+  Args extends any[] = [],
+  Opts extends OptionValues = {},
+  GlobalOpts extends OptionValues = {},
+> {
   args: string[];
@@ -696,3 +761,3 @@ processedArgs: Args;
     opts?: CommandOptions,
-  ): Command<[...InferCommmandArguments<Usage>]>;
+  ): Command<[...InferCommandArguments<Usage>], {}, Opts & GlobalOpts>;
   /**
@@ -768,3 +833,3 @@ * Define a command, implemented in a separate executable file.
     fn: (value: string, previous: T) => T,
-  ): Command<[...Args, InferArgument<S, undefined, T>], Opts>;
+  ): Command<[...Args, InferArgument<S, undefined, T>], Opts, GlobalOpts>;
   argument<S extends string, T>(
@@ -775,7 +840,7 @@ flags: S,
     defaultValue: T,
-  ): Command<[...Args, InferArgument<S, T, T>], Opts>;
+  ): Command<[...Args, InferArgument<S, T, T>], Opts, GlobalOpts>;
   argument<S extends string>(
     usage: S,
     description?: string,
-  ): Command<[...Args, InferArgument<S, undefined>], Opts>;
+  ): Command<[...Args, InferArgument<S, undefined>], Opts, GlobalOpts>;
   argument<S extends string, DefaultT>(
@@ -785,3 +850,3 @@ usage: S,
     defaultValue: DefaultT,
-  ): Command<[...Args, InferArgument<S, DefaultT>], Opts>;
+  ): Command<[...Args, InferArgument<S, DefaultT>], Opts, GlobalOpts>;
 
@@ -803,3 +868,4 @@ /**
     [...Args, InferArgument<Usage, DefaultT, CoerceT, ArgRequired, ChoicesT>],
-    Opts
+    Opts,
+    GlobalOpts
   >;
@@ -821,3 +887,3 @@
     args: Names,
-  ): Command<[...Args, ...InferArguments<Names>], Opts>;
+  ): Command<[...Args, ...InferArguments<Names>], Opts, GlobalOpts>;
 
@@ -961,3 +1027,7 @@ /**
     description?: string,
-  ): Command<Args, InferOptions<Opts, S, undefined, undefined, false>>;
+  ): Command<
+    Args,
+    InferOptions<Opts, S, undefined, undefined, false>,
+    GlobalOpts
+  >;
   option<S extends string, DefaultT extends string | boolean | string[] | []>(
@@ -967,3 +1037,7 @@ usage: S,
     defaultValue?: DefaultT,
-  ): Command<Args, InferOptions<Opts, S, DefaultT, undefined, false>>;
+  ): Command<
+    Args,
+    InferOptions<Opts, S, DefaultT, undefined, false>,
+    GlobalOpts
+  >;
   option<S extends string, T>(
@@ -973,3 +1047,3 @@ usage: S,
     parseArg: (value: string, previous: T) => T,
-  ): Command<Args, InferOptions<Opts, S, undefined, T, false>>;
+  ): Command<Args, InferOptions<Opts, S, undefined, T, false>, GlobalOpts>;
   option<S extends string, T>(
@@ -980,3 +1054,3 @@ usage: S,
     defaultValue?: T,
-  ): Command<Args, InferOptions<Opts, S, T, T, false>>;
+  ): Command<Args, InferOptions<Opts, S, T, T, false>, GlobalOpts>;
 
@@ -992,3 +1066,7 @@ /**
     description?: string,
-  ): Command<Args, InferOptions<Opts, S, undefined, undefined, true>>;
+  ): Command<
+    Args,
+    InferOptions<Opts, S, undefined, undefined, true>,
+    GlobalOpts
+  >;
   requiredOption<
@@ -1001,3 +1079,7 @@ S extends string,
     defaultValue?: DefaultT,
-  ): Command<Args, InferOptions<Opts, S, DefaultT, undefined, true>>;
+  ): Command<
+    Args,
+    InferOptions<Opts, S, DefaultT, undefined, true>,
+    GlobalOpts
+  >;
   requiredOption<S extends string, T>(
@@ -1007,3 +1089,3 @@ usage: S,
     parseArg: (value: string, previous: T) => T,
-  ): Command<Args, InferOptions<Opts, S, undefined, T, true>>;
+  ): Command<Args, InferOptions<Opts, S, undefined, T, true>, GlobalOpts>;
   requiredOption<S extends string, T, D extends T>(
@@ -1014,3 +1096,3 @@ usage: S,
     defaultValue?: D,
-  ): Command<Args, InferOptions<Opts, S, D, T, true>>;
+  ): Command<Args, InferOptions<Opts, S, D, T, true>, GlobalOpts>;
 
@@ -1045,3 +1127,4 @@ /**
     Args,
-    InferOptions<Opts, Usage, DefaultT, CoerceT, Mandatory, PresetT, ChoicesT>
+    InferOptions<Opts, Usage, DefaultT, CoerceT, Mandatory, PresetT, ChoicesT>,
+    GlobalOpts
   >;
@@ -1098,3 +1181,3 @@
    */
-  getOptionValueSourceWithGlobals<K extends keyof Opts>(
+  getOptionValueSourceWithGlobals<K extends keyof (Opts & GlobalOpts)>(
     key: K,
@@ -1209,3 +1292,3 @@ ): OptionValueSource | undefined;
    */
-  optsWithGlobals<T extends OptionValues>(): T;
+  optsWithGlobals(): Resolve<Opts & GlobalOpts>;
 
@@ -1212,0 +1295,0 @@ /**

index.js

@@ -21,5 +21,2 @@ const commander = require('commander');
 
-// In Commander, the create routines end up being aliases for the matching
-// methods on the global program due to the (deprecated) legacy default export.
-// Here we roll our own, the way Commander might in future.
 exports.createCommand = (name) => new commander.Command(name);
@@ -26,0 +23,0 @@ exports.createOption = (flags, description) =>

package.json

 {
   "name": "@commander-js/extra-typings",
-  "version": "12.1.0",
+  "version": "13.0.0-0",
   "description": "Infer strong typings for commander options and action handlers",
@@ -46,11 +46,11 @@ "main": "index.js",
   "peerDependencies": {
-    "commander": "~12.1.0"
+    "commander": "~13.0.0-0"
   },
   "devDependencies": {
-    "@types/jest": "^29.2.6",
-    "@types/node": "^20.11.7",
-    "commander": "~12.1.0",
-    "eslint": "^8.57.0",
+    "@jest/globals": "^29.3.1",
+    "@types/node": "^22.10.1",
+    "commander": "~13.0.0-0",
+    "eslint": "^9.16.0",
     "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-jest": "^27.9.0",
+    "eslint-plugin-jest": "^28.9.0",
     "globals": "^15.0.0",
@@ -60,6 +60,6 @@ "jest": "^29.3.1",
     "ts-jest": "^29.0.5",
-    "tsd": "^0.30.4",
+    "tsd": "^0.31.2",
     "typescript": "^5.3.3",
-    "typescript-eslint": "^7.5.0"
+    "typescript-eslint": "^8.11.0"
   }
 }

README.md

@@ -11,2 +11,4 @@ # extra-typings for commander
 
+This package requires TypeScript 5.0 or higher.
+
 The runtime is supplied by commander. This package is all about the typings.
@@ -66,10 +68,1 @@
 ```
-
-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))
-  .parse();
-const drinkSize = program.opts().drinkSize; // "small" | "medium" | "large" | undefined
-```

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Improved metrics

Total package byte prevSize

50381

3.6%

Lines of code

1344

5.25%

Worsened metrics

Number of low quality alerts

1

Infinity%

Number of lines in readme file

67

-9.46%

No dependency changes