refactor(ts): move and tsify most of root yargs.js to lib/yargs (#1670)

Author: mleguen

lib/apply-extends.ts

@@ -32,7 +32,7 @@ function mergeDeep (config1: Dictionary, config2: Dictionary) {
   return target
 }
 
-export function applyExtends (config: Dictionary, cwd: string, mergeExtends: boolean) {
+export function applyExtends (config: Dictionary, cwd: string, mergeExtends = false): Dictionary {
   let defaultConfig = {}
 
   if (Object.prototype.hasOwnProperty.call(config, 'extends')) {

lib/command.ts

@@ -1,4 +1,4 @@
-import { Dictionary, assertNotUndefined, assertNotTrue } from './common-types'
+import { Dictionary, assertNotStrictEqual } from './common-types'
 import { isPromise } from './is-promise'
 import { applyMiddleware, commandMiddlewareFactory, Middleware } from './middleware'
 import { parseCommand, Positional } from './parse-command'
@@ -7,9 +7,7 @@ import { RequireDirectoryOptions } from 'require-directory'
 import { UsageInstance } from './usage'
 import { inspect } from 'util'
 import { ValidationInstance } from './validation'
-import { YargsInstance, isYargsInstance, Options, OptionDefinition } from './yargs-types'
-import { DetailedArguments, Arguments } from 'yargs-parser'
-import { Context } from 'vm'
+import { YargsInstance, isYargsInstance, Options, OptionDefinition, Context, Configuration, Arguments, DetailedArguments } from './yargs'
 import requireDirectory = require('require-directory')
 import whichModule = require('which-module')
 import Parser = require('yargs-parser')
@@ -148,7 +146,7 @@ export function command (
   function extractDesc ({ describe, description, desc }: CommandHandlerDefinition) {
     for (const test of [describe, description, desc]) {
       if (typeof test === 'string' || test === false) return test
-      assertNotTrue(test)
+      assertNotStrictEqual(test, true as true)
     }
     return false
   }
@@ -161,7 +159,7 @@ export function command (
 
   self.runCommand = function runCommand (command, yargs, parsed, commandIndex) {
     let aliases = parsed.aliases
-    const commandHandler = handlers[command] || handlers[aliasMap[command]] || defaultCommand
+    const commandHandler = handlers[command!] || handlers[aliasMap[command!]] || defaultCommand
     const currentContext = yargs.getContext()
     let numFiles = currentContext.files.length
     const parentCommands = currentContext.commands.slice()
@@ -186,7 +184,7 @@ export function command (
         )
       }
       innerArgv = innerYargs._parseArgs(null, null, true, commandIndex)
-      aliases = innerYargs.parsed.aliases
+      aliases = (innerYargs.parsed as DetailedArguments).aliases
     } else if (isCommandBuilderOptionDefinitions(builder)) {
       // as a short hand, an object can instead be provided, specifying
       // the options that a command takes.
@@ -201,19 +199,26 @@ export function command (
         innerYargs.option(key, builder[key])
       })
       innerArgv = innerYargs._parseArgs(null, null, true, commandIndex)
-      aliases = innerYargs.parsed.aliases
+      aliases = (innerYargs.parsed as DetailedArguments).aliases
     }
 
     if (!yargs._hasOutput()) {
-      positionalMap = populatePositionals(commandHandler, innerArgv, currentContext)
+      positionalMap = populatePositionals(commandHandler, innerArgv as Arguments, currentContext)
     }
 
     const middlewares = globalMiddleware.slice(0).concat(commandHandler.middlewares)
     applyMiddleware(innerArgv, yargs, middlewares, true)
 
     // we apply validation post-hoc, so that custom
     // checks get passed populated positional arguments.
-    if (!yargs._hasOutput()) yargs._runValidation(innerArgv, aliases, positionalMap, yargs.parsed.error, !command)
+    if (!yargs._hasOutput()) {
+      yargs._runValidation(
+      innerArgv as Arguments,
+      aliases,
+      positionalMap,
+      (yargs.parsed as DetailedArguments).error,
+      !command)
+    }
 
     if (commandHandler.handler && !yargs._hasOutput()) {
       yargs._setHasOutput()
@@ -279,7 +284,7 @@ export function command (
   }
 
   self.runDefaultBuilderOn = function (yargs) {
-    assertNotUndefined(defaultCommand)
+    assertNotStrictEqual(defaultCommand, undefined)
     if (shouldUpdateUsage(yargs)) {
       // build the root-level command string from the default string.
       const commandString = DEFAULT_MARKER.test(defaultCommand.original)
@@ -360,7 +365,7 @@ export function command (
     // short-circuit parse.
     if (!unparsed.length) return
 
-    const config = Object.assign({}, options.configuration, {
+    const config: Configuration = Object.assign({}, options.configuration, {
       'populate--': true
     })
     const parsed = Parser.detailed(unparsed, Object.assign({}, options, {
@@ -440,7 +445,7 @@ export function command (
   }
   self.unfreeze = () => {
     const frozen = frozens.pop()
-    assertNotUndefined(frozen)
+    assertNotStrictEqual(frozen, undefined)
     ;({
       handlers,
       aliasMap,
@@ -475,7 +480,7 @@ export interface CommandInstance {
   getCommands (): string[]
   hasDefaultCommand (): boolean
   reset (): CommandInstance
-  runCommand (command: string, yargs: YargsInstance, parsed: DetailedArguments, commandIndex: number): void
+  runCommand (command: string | null, yargs: YargsInstance, parsed: DetailedArguments, commandIndex?: number): Arguments | Promise<Arguments>
   runDefaultBuilderOn (yargs: YargsInstance): void
   unfreeze(): void
 }
@@ -546,3 +551,7 @@ type FrozenCommandInstance = {
   aliasMap: Dictionary<string>
   defaultCommand: CommandHandler | undefined
 }
+
+export interface FinishCommandHandler {
+  (handlerResult: any): any
+}

lib/common-types.ts

@@ -1,13 +1,48 @@
-import { notStrictEqual } from 'assert'
+import { notStrictEqual, strictEqual } from 'assert'
 
+/**
+ * An object whose all properties have the same type.
+ */
 export type Dictionary<T = any> = { [key: string]: T }
 
+/**
+ * Returns the keys of T that match Dictionary<U> and are not arrays.
+ */
+export type DictionaryKeyof<T, U = any> = Exclude<KeyOf<T, Dictionary<U>>, KeyOf<T, any[]>>
+
+/**
+ * Returns the keys of T that match U.
+ */
+export type KeyOf<T, U> = Exclude<{ [K in keyof T]: T[K] extends U ? K : never }[keyof T], undefined>
+
+/**
+ * An array whose first element is not undefined.
+ */
 export type NotEmptyArray<T = any> = [T, ...T[]]
 
-export function assertNotTrue<T = any> (actual: T | true): asserts actual is T {
-  notStrictEqual(actual, true)
+/**
+ * Returns the type of a Dictionary or array values.
+ */
+export type ValueOf<T> = T extends (infer U)[] ? U : T[keyof T];
+
+/**
+ * Typing wrapper around assert.notStrictEqual()
+ */
+export function assertNotStrictEqual<N, T> (actual: T|N, expected: N, message ?: string | Error)
+: asserts actual is Exclude<T, N> {
+  notStrictEqual(actual, expected, message)
+}
+
+/**
+ * Asserts actual is a single key, not a key array or a key map.
+ */
+export function assertSingleKey (actual: string | string[] | Dictionary): asserts actual is string {
+  strictEqual(typeof actual, 'string')
 }
 
-export function assertNotUndefined<T = any> (actual: T | undefined): asserts actual is T {
-  notStrictEqual(actual, undefined)
+/**
+ * Typing wrapper around Object.keys()
+ */
+export function objectKeys<T> (object: T) {
+  return Object.keys(object) as (keyof T)[]
 }

lib/completion.ts

@@ -4,8 +4,9 @@ import { isPromise } from './is-promise'
 import { parseCommand } from './parse-command'
 import * as path from 'path'
 import { UsageInstance } from './usage'
-import { YargsInstance } from './yargs-types'
+import { YargsInstance } from './yargs'
 import { Arguments, DetailedArguments } from 'yargs-parser'
+import { assertNotStrictEqual } from './common-types'
 
 // add bash completions to your
 //  yargs-powered applications.
@@ -31,7 +32,9 @@ export function completion (yargs: YargsInstance, usage: UsageInstance, command:
 
     // a custom completion function can be provided
     // to completion().
-    if (completionFunction) {
+    function runCompletionFunction (argv: Arguments) {
+      assertNotStrictEqual(completionFunction, null)
+
       if (isSyncCompletionFunction(completionFunction)) {
         const result = completionFunction(current, argv)
 
@@ -54,6 +57,10 @@ export function completion (yargs: YargsInstance, usage: UsageInstance, command:
       }
     }
 
+    if (completionFunction) {
+      return isPromise(argv) ? argv.then(runCompletionFunction) : runCompletionFunction(argv)
+    }
+
     const handlers = command.getCommandHandlers()
     for (let i = 0, ii = args.length; i < ii; ++i) {
       if (handlers[args[i]] && handlers[args[i]].builder) {
@@ -137,15 +144,15 @@ export function completion (yargs: YargsInstance, usage: UsageInstance, command:
 }
 
 /** Instance of the completion module. */
-interface CompletionInstance {
+export interface CompletionInstance {
   completionKey: string
   generateCompletionScript($0: string, cmd: string): string
   getCompletion(args: string[], done: (completions: string[]) => any): any
   registerFunction(fn: CompletionFunction): void
   setParsed(parsed: DetailedArguments): void
 }
 
-type CompletionFunction = SyncCompletionFunction | AsyncCompletionFunction
+export type CompletionFunction = SyncCompletionFunction | AsyncCompletionFunction
 
 interface SyncCompletionFunction {
   (current: string, argv: Arguments): string[] | Promise<string[]>

lib/middleware.ts

@@ -1,7 +1,6 @@
 import { argsert } from './argsert'
 import { isPromise } from './is-promise'
-import { YargsInstance } from './yargs-types'
-import { Arguments } from 'yargs-parser'
+import { YargsInstance, Arguments } from './yargs'
 
 export function globalMiddlewareFactory<T> (globalMiddleware: Middleware[], context: T) {
   return function (callback: MiddlewareCallback | MiddlewareCallback[], applyBeforeValidation = false) {
@@ -31,38 +30,38 @@ export function commandMiddlewareFactory (commandMiddleware?: MiddlewareCallback
 }
 
 export function applyMiddleware (
-  argv: Arguments,
+  argv: Arguments | Promise<Arguments>,
   yargs: YargsInstance,
   middlewares: Middleware[],
   beforeValidation: boolean
 ) {
   const beforeValidationError = new Error('middleware cannot return a promise when applyBeforeValidation is true')
   return middlewares
-    .reduce<Arguments | Promise<Arguments>>((accumulation, middleware) => {
+    .reduce<Arguments | Promise<Arguments>>((acc, middleware) => {
       if (middleware.applyBeforeValidation !== beforeValidation) {
-        return accumulation
+        return acc
       }
 
-      if (isPromise(accumulation)) {
-        return accumulation
+      if (isPromise(acc)) {
+        return acc
           .then(initialObj =>
             Promise.all<Arguments, Partial<Arguments>>([initialObj, middleware(initialObj, yargs)])
           )
           .then(([initialObj, middlewareObj]) =>
             Object.assign(initialObj, middlewareObj)
           )
       } else {
-        const result = middleware(argv, yargs)
+        const result = middleware(acc, yargs)
         if (beforeValidation && isPromise(result)) throw beforeValidationError
 
         return isPromise(result)
-          ? result.then(middlewareObj => Object.assign(accumulation, middlewareObj))
-          : Object.assign(accumulation, result)
+          ? result.then(middlewareObj => Object.assign(acc, middlewareObj))
+          : Object.assign(acc, result)
       }
     }, argv)
 }
 
-interface MiddlewareCallback {
+export interface MiddlewareCallback {
   (argv: Arguments, yargs: YargsInstance): Partial<Arguments> | Promise<Partial<Arguments>>
 }
 

lib/obj-filter.ts

@@ -1,8 +1,11 @@
-import { Dictionary } from './common-types'
+import { objectKeys } from './common-types'
 
-export function objFilter<T = any> (original: Dictionary<T>, filter: (k: string, v: T) => boolean = () => true) {
-  const obj: Dictionary<T> = {}
-  Object.keys(original || {}).forEach((key) => {
+export function objFilter<T extends object> (
+  original = {} as T,
+  filter: (k: keyof T, v: T[keyof T]) => boolean = () => true
+) {
+  const obj = {} as T
+  objectKeys(original).forEach((key) => {
     if (filter(key, original[key])) {
       obj[key] = original[key]
     }

lib/typings/require-main-filename.d.ts

@@ -0,0 +1,21 @@
+// TODO: either create @types/require-main-filename or or convert require-main-filename to typescript
+
+/**
+ * Returns the entry point of the current application.
+ *
+ * `require.main.filename` is great for figuring out the entry point for the current application.
+ * This can be combined with a module like pkg-conf to, as if by magic, load top-level configuration.
+ *
+ * Unfortunately, `require.main.filename` sometimes fails when an application is executed
+ * with an alternative process manager, e.g., iisnode.
+ *
+ * `require-main-filename` is a shim that addresses this problem.
+ *
+ * @param _require require function
+ * @returns hash of modules in specified directory
+ */
+declare function requireMainFilename(_require: NodeRequire): string;
+
+declare module 'require-main-filename' {
+    export = requireMainFilename;
+}

lib/typings/y18n.d.ts

@@ -1,59 +1,64 @@
 // TODO: either update @types/y18n with this or convert y18n to typescript
 // Forked from: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/a9cb5fa/types/y18n/index.d.ts
 
-interface Config {
-  /**
-   * The locale directory, default ./locales.
-   */
-  directory: string;
-  /**
-   * Should newly observed strings be updated in file, default true.
-   */
-  updateFiles: boolean;
-  /**
-   * What locale should be used.
-   */
-  locale: string;
-  /**
-   * Should fallback to a language-only file (e.g. en.json) be allowed
-   * if a file matching the locale does not exist (e.g. en_US.json), default true.
-   */
-  fallbackToLanguage: boolean;
-}
+/* eslint no-redeclare: "off" */
+declare namespace y18n {
+  interface Config {
+    /**
+     * The locale directory, default ./locales.
+     */
+    directory?: string;
+    /**
+     * Should newly observed strings be updated in file, default true.
+     */
+    updateFiles?: boolean;
+    /**
+     * What locale should be used.
+     */
+    locale?: string;
+    /**
+     * Should fallback to a language-only file (e.g. en.json) be allowed
+     * if a file matching the locale does not exist (e.g. en_US.json), default true.
+     */
+    fallbackToLanguage?: boolean;
+  }
+
+  export class Y18N {
+    /**
+     * Create an instance of y18n with the config provided
+     */
+    constructor(config?: Config);
+
+    /**
+     * Print a localized string, %s will be replaced with args.
+     */
+    __(str: string, arg1?: string, arg2?: string, arg3?: string): string;
+
+    /**
+     * Print a localized string with appropriate pluralization.
+     * If %d is provided in the string, the quantity will replace this placeholder.
+     */
+    __n(singular: string, plural: string, quantity: number, ...param: any[]): string;
 
-declare class Y18N {
-  /**
-   * Create an instance of y18n with the config provided
-   */
-  constructor(config?: Config);
-
-  /**
-   * Print a localized string, %s will be replaced with args.
-   */
-  __(str: string, arg1?: string, arg2?: string, arg3?: string): string;
-
-  /**
-   * Print a localized string with appropriate pluralization.
-   * If %d is provided in the string, the quantity will replace this placeholder.
-   */
-  __n(singular: string, plural: string, quantity: number, ...param: any[]): string;
-
-  /**
-   * Set the current locale being used.
-   */
-  setLocale(str: string): void;
-
-  /**
-   * What locale is currently being used?
-   */
-  getLocale(): string;
-
-  /**
-   * Update the current locale with the key value pairs in obj.
-   */
-  updateLocale(obj: object): void;
+    /**
+     * Set the current locale being used.
+     */
+    setLocale(str: string): void;
+
+    /**
+     * What locale is currently being used?
+     */
+    getLocale(): string;
+
+    /**
+     * Update the current locale with the key value pairs in obj.
+     */
+    updateLocale(obj: { [key: string]: string }): void;
+  }
 }
 
+declare function y18n (opts?: y18n.Config): y18n.Y18N;
+
 declare module 'y18n' {
-  export = Y18N;
+  export = y18n;
 }

lib/typings/yargs-parser.d.ts

@@ -0,0 +1,124 @@
+// TODO: either update @types/yargs-parser with this or convert yargs-parser to typescript
+// Forked from: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/699b8159a6f571a14ef6d1d07b956cf78c8e729c/types/yargs-parser/index.d.ts
+
+/* eslint no-redeclare: "off" */
+declare namespace yargsParser {
+    interface Arguments {
+        /** Non-option arguments */
+        _: string[];
+        /** All remaining options */
+        [argName: string]: any;
+    }
+
+    interface DetailedArguments {
+        /** An object representing the parsed value of `args` */
+        argv: Arguments;
+        /** Populated with an error object if an exception occurred during parsing. */
+        error: Error | null;
+        /** The inferred list of aliases built by combining lists in opts.alias. */
+        aliases: { [alias: string]: string[] };
+        /** Any new aliases added via camel-case expansion. */
+        newAliases: { [alias: string]: boolean };
+        /** The configuration loaded from the yargs stanza in package.json. */
+        configuration: Configuration;
+    }
+
+    interface Configuration {
+        /** Should variables prefixed with --no be treated as negations? Default is `true` */
+        'boolean-negation': boolean;
+        /** Should hyphenated arguments be expanded into camel-case aliases? Default is `true` */
+        'camel-case-expansion': boolean;
+        /** Should arrays be combined when provided by both command line arguments and a configuration file. Default is `false`  */
+        'combine-arrays': boolean;
+        /** Should keys that contain . be treated as objects? Default is `true` */
+        'dot-notation': boolean;
+        /** Should arguments be coerced into an array when duplicated. Default is `true` */
+        'duplicate-arguments-array': boolean;
+        /** Should array arguments be coerced into a single array when duplicated. Default is `true` */
+        'flatten-duplicate-arrays': boolean;
+        /** Should arrays consume more than one positional argument following their flag? Default is `true` */
+        'greedy-arrays': boolean;
+        /** Should parsing stop at the first text argument? This is similar to how e.g. ssh parses its command line. Default is `false` */
+        'halt-at-non-option': boolean;
+        /** Should nargs consume dash options as well as positional arguments? Default is `false` */
+        'nargs-eats-options': boolean;
+        /** The prefix to use for negated boolean variables. Default is `'no-'` */
+        'negation-prefix': string;
+        /** Should keys that look like numbers be treated as such? Default is `true` */
+        'parse-numbers': boolean;
+        /** Should unparsed flags be stored in -- or _. Default is `false` */
+        'populate--': boolean;
+        /** Should a placeholder be added for keys not set via the corresponding CLI argument? Default is `false` */
+        'set-placeholder-key': boolean;
+        /** Should a group of short-options be treated as boolean flags? Default is `true` */
+        'short-option-groups': boolean;
+        /** Should aliases be removed before returning results? Default is `false` */
+        'strip-aliased': boolean;
+        /** Should dashed keys be removed before returning results? This option has no effect if camel-case-expansion is disabled. Default is `false` */
+        'strip-dashed': boolean;
+        /** Should unknown options be treated like regular arguments? An unknown option is one that is not configured in opts. Default is `false` */
+        'unknown-options-as-args': boolean;
+    }
+
+    type ArrayOption = string | { key: string; string?: boolean, boolean?: boolean, number?: boolean, integer?: boolean };
+
+    interface Options {
+        /** An object representing the set of aliases for a key: `{ alias: { foo: ['f']} }`. */
+        alias: { [key: string]: string | string[] };
+        /**
+         * Indicate that keys should be parsed as an array: `{ array: ['foo', 'bar'] }`.
+         * Indicate that keys should be parsed as an array and coerced to booleans / numbers:
+         * { array: [ { key: 'foo', boolean: true }, {key: 'bar', number: true} ] }`.
+         */
+        array: ArrayOption | ArrayOption[];
+        /** Arguments should be parsed as booleans: `{ boolean: ['x', 'y'] }`. */
+        boolean: string | string[];
+        /** Indicate a key that represents a path to a configuration file (this file will be loaded and parsed). */
+        config: string | string[] | { [key: string]: boolean | ConfigCallback };
+        /** configuration objects to parse, their properties will be set as arguments */
+        configObjects: Array<{ [key: string]: any }>;
+        /** Provide configuration options to the yargs-parser. */
+        configuration: Partial<Configuration>;
+        /**
+         * Provide a custom synchronous function that returns a coerced value from the argument provided (or throws an error), e.g.
+         * `{ coerce: { foo: function (arg) { return modifiedArg } } }`.
+         */
+        coerce: { [key: string]: CoerceCallback };
+        /** Indicate a key that should be used as a counter, e.g., `-vvv = {v: 3}`. */
+        count: string | string[];
+        /** Provide default values for keys: `{ default: { x: 33, y: 'hello world!' } }`. */
+        default: { [key: string]: any };
+        /** Environment variables (`process.env`) with the prefix provided should be parsed. */
+        envPrefix: string;
+        /** Specify that a key requires n arguments: `{ narg: {x: 2} }`. */
+        narg: { [key: string]: number };
+        /** `path.normalize()` will be applied to values set to this key. */
+        normalize: string | string[];
+        /** Keys should be treated as strings (even if they resemble a number `-x 33`). */
+        string: string | string[];
+        /** Keys should be treated as numbers. */
+        number: string | string[];
+        /** i18n handler, defaults to util.format */
+        __: (format: any, ...param: any[]) => string;
+        /** alias lookup table defaults */
+        key: { [key: string]: any };
+    }
+
+    interface CoerceCallback {
+        (arg: any): any
+    }
+
+    interface ConfigCallback {
+        (configPath: string): { [key: string]: any }
+    }
+
+    interface Parser {
+        (args: string | any[], opts?: Partial<Options>): Arguments;
+        detailed(args: string | any[], opts?: Partial<Options>): DetailedArguments;
+    }
+}
+
+declare var yargsParser: yargsParser.Parser
+declare module 'yargs-parser' {
+    export = yargsParser;
+}

lib/usage.ts

@@ -1,14 +1,15 @@
 // this file handles outputting usage instructions,
 // failures, etc. keeps logging in one place.
-import { Dictionary, assertNotUndefined } from './common-types'
+import { Dictionary, assertNotStrictEqual } from './common-types'
 import { objFilter } from './obj-filter'
 import * as path from 'path'
-import { YargsInstance } from './yargs-types'
+import { YargsInstance } from './yargs'
 import { YError } from './yerror'
+import { Y18N } from 'y18n'
+import { DetailedArguments } from 'yargs-parser'
 import decamelize = require('decamelize')
 import setBlocking = require('set-blocking')
 import stringWidth = require('string-width')
-import Y18N = require('y18n')
 
 export function usage (yargs: YargsInstance, y18n: Y18N) {
   const __ = y18n.__
@@ -111,8 +112,12 @@ export function usage (yargs: YargsInstance, y18n: Y18N) {
   self.getCommands = () => commands
 
   let descriptions: Dictionary<string | undefined> = {}
-  self.describe = function describe (keyOrKeys: string | Dictionary<string>, desc?: string) {
-    if (typeof keyOrKeys === 'object') {
+  self.describe = function describe (keyOrKeys: string | string[] | Dictionary<string>, desc?: string) {
+    if (Array.isArray(keyOrKeys)) {
+      keyOrKeys.forEach((k) => {
+        self.describe(k, desc)
+      })
+    } else if (typeof keyOrKeys === 'object') {
       Object.keys(keyOrKeys).forEach((k) => {
         self.describe(k, keyOrKeys[k])
       })
@@ -128,7 +133,7 @@ export function usage (yargs: YargsInstance, y18n: Y18N) {
   }
 
   let wrapSet = false
-  let wrap: number | undefined
+  let wrap: number | null | undefined
   self.wrap = (cols) => {
     wrapSet = true
     wrap = cols
@@ -245,9 +250,9 @@ export function usage (yargs: YargsInstance, y18n: Y18N) {
     // perform some cleanup on the keys array, making it
     // only include top-level keys not their aliases.
     const aliasKeys = (Object.keys(options.alias) || [])
-      .concat(Object.keys(yargs.parsed.newAliases) || [])
+      .concat(Object.keys((yargs.parsed as DetailedArguments).newAliases) || [])
 
-    keys = keys.filter(key => !yargs.parsed.newAliases[key] && aliasKeys.every(alias => (options.alias[alias] || []).indexOf(key) === -1))
+    keys = keys.filter(key => !(yargs.parsed as DetailedArguments).newAliases[key] && aliasKeys.every(alias => (options.alias[alias] || []).indexOf(key) === -1))
 
     // populate 'Options:' group with any keys that have not
     // explicitly had a group set.
@@ -309,7 +314,7 @@ export function usage (yargs: YargsInstance, y18n: Y18N) {
         if (~options.array.indexOf(key)) type = `[${__('array')}]`
         if (~options.number.indexOf(key)) type = `[${__('number')}]`
 
-        const deprecatedExtra = (deprecated: string | boolean) => typeof deprecated === 'string'
+        const deprecatedExtra = (deprecated?: string | boolean) => typeof deprecated === 'string'
           ? `[${__('deprecated: %s', deprecated)}]`
           : `[${__('deprecated')}]`
 
@@ -378,7 +383,7 @@ export function usage (yargs: YargsInstance, y18n: Y18N) {
 
   // return the maximum width of a string
   // in the left-hand column of a table.
-  function maxWidth (table: [string, ...any[]][] | Dictionary<string>, theWrap?: number, modifier?: string) {
+  function maxWidth (table: [string, ...any[]][] | Dictionary<string>, theWrap?: number | null, modifier?: string) {
     let width = 0
 
     // table might be of the form [leftColumn],
@@ -457,7 +462,7 @@ export function usage (yargs: YargsInstance, y18n: Y18N) {
   }
 
   function filterHiddenOptions (key: string) {
-    return yargs.getOptions().hiddenOptions.indexOf(key) < 0 || yargs.parsed.argv[yargs.getOptions().showHiddenOpt]
+    return yargs.getOptions().hiddenOptions.indexOf(key) < 0 || (yargs.parsed as DetailedArguments).argv[yargs.getOptions().showHiddenOpt]
   }
 
   self.showHelp = (level: 'error' | 'log' | ((message: string) => void)) => {
@@ -564,7 +569,7 @@ export function usage (yargs: YargsInstance, y18n: Y18N) {
   }
   self.unfreeze = function unfreeze () {
     const frozen = frozens.pop()
-    assertNotUndefined(frozen)
+    assertNotStrictEqual(frozen, undefined)
     ;({
       failMessage,
       failureOutput,
@@ -586,8 +591,7 @@ export interface UsageInstance {
   clearCachedHelpMessage(): void
   command(cmd: string, description: string | undefined, isDefault: boolean, aliases: string[], deprecated?: boolean): void
   deferY18nLookup(str: string): string
-  describe(key: string, desc?: string): void
-  describe(keys: Dictionary<string>): void
+  describe(keys: string | string[] | Dictionary<string>, desc?: string): void
   epilog(msg: string): void
   example(cmd: string, description?: string): void
   fail(msg?: string | null, err?: YError | string): void
@@ -601,19 +605,17 @@ export interface UsageInstance {
   getUsageDisabled(): boolean
   help(): string
   reset(localLookup: Dictionary<boolean>): UsageInstance
-  showHelp(level: 'error' | 'log'): void
-  showHelp(level: (message: string) => void): void
-  showHelpOnFail(message?: string): UsageInstance
-  showHelpOnFail(enabled: boolean, message: string): UsageInstance
+  showHelp(level: 'error' | 'log' | ((message: string) => void)): void
+  showHelpOnFail (enabled?: boolean | string, message?: string): UsageInstance
   showVersion(): void
   stringifiedValues(values?: any[], separator?: string): string
   unfreeze(): void
   usage(msg: string | null, description?: string | false): UsageInstance
   version(ver: any): void
-  wrap(cols: number): void
+  wrap(cols: number | null | undefined): void
 }
 
-interface FailureFunction {
+export interface FailureFunction {
   (msg: string | undefined | null, err: YError | string | undefined, usage: UsageInstance): void
 }
 

lib/validation.ts

@@ -1,11 +1,11 @@
 import { argsert } from './argsert'
-import { Dictionary, assertNotUndefined } from './common-types'
+import { Dictionary, assertNotStrictEqual } from './common-types'
 import { levenshtein as distance } from './levenshtein'
 import { objFilter } from './obj-filter'
 import { UsageInstance } from './usage'
-import { YargsInstance } from './yargs-types'
-import { Arguments, DetailedArguments } from 'yargs-parser'
-import Y18N = require('y18n')
+import { YargsInstance, Arguments } from './yargs'
+import { DetailedArguments } from 'yargs-parser'
+import { Y18N } from 'y18n'
 const specialKeys = ['$0', '--', '_']
 
 // validation-type-stuff, missing params,
@@ -84,7 +84,7 @@ export function validation (yargs: YargsInstance, usage: UsageInstance, y18n: Y1
   // make sure all the required arguments are present.
   self.requiredArguments = function requiredArguments (argv) {
     const demandedOptions = yargs.getDemandedOptions()
-    let missing: Dictionary<string> | null = null
+    let missing: Dictionary<string | undefined> | null = null
 
     for (const key of Object.keys(demandedOptions)) {
       if (!Object.prototype.hasOwnProperty.call(argv, key) || typeof argv[key] === 'undefined') {
@@ -179,7 +179,7 @@ export function validation (yargs: YargsInstance, usage: UsageInstance, y18n: Y1
     if (!Object.prototype.hasOwnProperty.call(aliases, key)) {
       return false
     }
-    const newAliases = yargs.parsed.newAliases
+    const newAliases = (yargs.parsed as DetailedArguments).newAliases
     for (const a of [key, ...aliases[key]]) {
       if (!Object.prototype.hasOwnProperty.call(newAliases, a) || !newAliases[key]) {
         return true
@@ -254,7 +254,7 @@ export function validation (yargs: YargsInstance, usage: UsageInstance, y18n: Y1
 
   // check implications, argument foo implies => argument bar.
   let implied: Dictionary<KeyOrPos[]> = {}
-  self.implies = function implies (key: string | Dictionary<KeyOrPos | KeyOrPos[]>, value?: KeyOrPos | KeyOrPos[]) {
+  self.implies = function implies (key, value) {
     argsert('<string|object> [array|number|string]', [key, value], arguments.length)
 
     if (typeof key === 'object') {
@@ -269,6 +269,7 @@ export function validation (yargs: YargsInstance, usage: UsageInstance, y18n: Y1
       if (Array.isArray(value)) {
         value.forEach((i) => self.implies(key, i))
       } else {
+        assertNotStrictEqual(value, undefined)
         implied[key].push(value)
       }
     }
@@ -325,7 +326,7 @@ export function validation (yargs: YargsInstance, usage: UsageInstance, y18n: Y1
   }
 
   let conflicting: Dictionary<(string | undefined)[]> = {}
-  self.conflicts = function conflicts (key: string | Dictionary<string | string []>, value?: string | string[]) {
+  self.conflicts = function conflicts (key, value) {
     argsert('<string|object> [array|string]', [key, value], arguments.length)
 
     if (typeof key === 'object') {
@@ -393,7 +394,7 @@ export function validation (yargs: YargsInstance, usage: UsageInstance, y18n: Y1
   }
   self.unfreeze = function unfreeze () {
     const frozen = frozens.pop()
-    assertNotUndefined(frozen)
+    assertNotStrictEqual(frozen, undefined)
     ;({
       implied,
       checks,
@@ -408,15 +409,13 @@ export function validation (yargs: YargsInstance, usage: UsageInstance, y18n: Y1
 export interface ValidationInstance {
   check(f: CustomCheck['func'], global: boolean): void
   conflicting(argv: Arguments): void
-  conflicts(key: string, value: string | string[]): void
-  conflicts(key: Dictionary<string | string[]>): void
+  conflicts(key: string | Dictionary<string | string[]>, value?: string | string[]): void
   customChecks(argv: Arguments, aliases: DetailedArguments['aliases']): void
   freeze(): void
   getConflicting(): Dictionary<(string | undefined)[]>
   getImplied(): Dictionary<KeyOrPos[]>
   implications(argv: Arguments): void
-  implies(key: string, value: KeyOrPos | KeyOrPos[]): void
-  implies(key: Dictionary<KeyOrPos | KeyOrPos[]>): void
+  implies(key: string | Dictionary<KeyOrPos | KeyOrPos[]>, value?: KeyOrPos | KeyOrPos[]): void
   isValidAndSomeAliasIsNotNew(key: string, aliases: DetailedArguments['aliases']): boolean
   limitedChoices(argv: Arguments): void
   nonOptionCount(argv: Arguments): void
@@ -445,4 +444,4 @@ interface FrozenValidationInstance {
   conflicting: Dictionary<(string | undefined)[]>
 }
 
-type KeyOrPos = string | number | undefined
+export type KeyOrPos = string | number

lib/yargs-types.ts

@@ -13,7 +13,6 @@
     "index.js",
     "yargs.js",
     "build",
-    "lib/**/*.js",
     "locales",
     "LICENSE"
   ],
@@ -34,7 +33,6 @@
     "@types/chai": "^4.2.11",
     "@types/mocha": "^7.0.2",
     "@types/node": "^10.0.3",
-    "@types/yargs-parser": "^15.0.0",
     "@typescript-eslint/eslint-plugin": "^3.0.0",
     "@typescript-eslint/parser": "^3.0.0",
     "c8": "^7.0.0",

lib/yargs.ts

@@ -3631,4 +3631,19 @@ describe('usage tests', () => {
       )
     })
   })
+
+  it('should allow setting the same description for several keys', () => {
+    const r = checkUsage(() => yargs('--help')
+      .describe(['big', 'small'], 'Packet size')
+      .parse()
+    )
+
+    r.logs[0].split('\n').should.deep.equal([
+      'Options:',
+      '  --help     Show help                                                 [boolean]',
+      '  --version  Show version number                                       [boolean]',
+      '  --big      Packet size',
+      '  --small    Packet size'
+    ])
+  })
 })