From c06f886142ad02233db2b2ba82f2e606cbf57ccd Mon Sep 17 00:00:00 2001 From: Mael Le Guen Date: Sun, 19 Jul 2020 04:32:25 +0200 Subject: [PATCH] refactor(ts)!: ship yargs.d.ts (#1671) BREAKING CHANGE: yargs now ships with its own types --- lib/yargs.ts | 6 +- package.json | 1 + yargs.d.ts | 769 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 774 insertions(+), 2 deletions(-) create mode 100644 yargs.d.ts diff --git a/lib/yargs.ts b/lib/yargs.ts index ae6da41ba..65dbd7c36 100644 --- a/lib/yargs.ts +++ b/lib/yargs.ts @@ -1394,10 +1394,12 @@ export function Yargs (processArgs: string | string[] = [], cwd = process.cwd(), // rebase an absolute path to a relative one with respect to a base directory // exported for tests -export function rebase (base: string, dir: string) { - return path.relative(base, dir) +export interface RebaseFunction { + (base: string, dir: string): string } +export const rebase: RebaseFunction = (base, dir) => path.relative(base, dir) + /** Instance of the yargs module. */ export interface YargsInstance { $0: string diff --git a/package.json b/package.json index f9053dfc5..54453afbb 100644 --- a/package.json +++ b/package.json @@ -12,6 +12,7 @@ "files": [ "index.js", "yargs.js", + "yargs.d.ts", "build", "locales", "LICENSE" diff --git a/yargs.d.ts b/yargs.d.ts new file mode 100644 index 000000000..534cbff30 --- /dev/null +++ b/yargs.d.ts @@ -0,0 +1,769 @@ +import { YargsInstance, RebaseFunction } from './build/lib/yargs' +import { Parser, DetailedArguments, Configuration } from 'yargs-parser'; + +declare namespace yargs { + type BuilderCallback = ((args: YargsInstance) => PromiseLike>) | ((args: YargsInstance) => YargsInstance) | ((args: YargsInstance) => void); + + type ParserConfigurationOptions = Configuration & { + /** Sort commands alphabetically. Default is `false` */ + 'sort-commands': boolean; + }; + + /** + * The type parameter `T` is the expected shape of the parsed options. + * `Arguments` is those options plus `_` and `$0`, and an indexer falling + * back to `unknown` for unknown options. + * + * For the return type / `argv` property, we create a mapped type over + * `Arguments` to simplify the inferred type signature in client code. + */ + interface YargsInstance { + + /** + * Set key names as equivalent such that updates to a key will propagate to aliases and vice-versa. + * + * Optionally `.alias()` can take an object that maps keys to aliases. + * Each key of this object should be the canonical version of the option, and each value should be a string or an array of strings. + */ + // Aliases for previously declared options can inherit the types of those options. + alias(shortName: K1, longName: K2 | ReadonlyArray): YargsInstance; + alias(shortName: K2, longName: K1 | ReadonlyArray): YargsInstance; + alias(shortName: string | ReadonlyArray, longName: string | ReadonlyArray): YargsInstance; + alias(aliases: { [shortName: string]: string | ReadonlyArray }): YargsInstance; + + /** + * Get the arguments as a plain old object. + * + * Arguments without a corresponding flag show up in the `argv._` array. + * + * The script name or node command is available at `argv.$0` similarly to how `$0` works in bash or perl. + * + * If `yargs` is executed in an environment that embeds node and there's no script name (e.g. Electron or nw.js), + * it will ignore the first parameter since it expects it to be the script name. In order to override + * this behavior, use `.parse(process.argv.slice(1))` instead of .argv and the first parameter won't be ignored. + */ + argv: { [key in keyof Arguments]: Arguments[key] }; + + /** + * Tell the parser to interpret `key` as an array. + * If `.array('foo')` is set, `--foo foo bar` will be parsed as `['foo', 'bar']` rather than as `'foo'`. + * Also, if you use the option multiple times all the values will be flattened in one array so `--foo foo --foo bar` will be parsed as `['foo', 'bar']` + * + * When the option is used with a positional, use `--` to tell `yargs` to stop adding values to the array. + */ + array(key: K | ReadonlyArray): YargsInstance & { [key in K]: ToArray }>; + array(key: K | ReadonlyArray): YargsInstance | undefined }>; + + /** + * Interpret `key` as a boolean. If a non-flag option follows `key` in `process.argv`, that string won't get set as the value of `key`. + * + * `key` will default to `false`, unless a `default(key, undefined)` is explicitly set. + * + * If `key` is an array, interpret all the elements as booleans. + */ + boolean(key: K | ReadonlyArray): YargsInstance & { [key in K]: boolean | undefined }>; + boolean(key: K | ReadonlyArray): YargsInstance; + + /** + * Check that certain conditions are met in the provided arguments. + * @param func Called with two arguments, the parsed `argv` hash and an array of options and their aliases. + * If `func` throws or returns a non-truthy value, show the thrown error, usage information, and exit. + * @param global Indicates whether `check()` should be enabled both at the top-level and for each sub-command. + */ + check(func: (argv: Arguments, aliases: { [alias: string]: string }) => any, global?: boolean): YargsInstance; + + /** + * Limit valid values for key to a predefined set of choices, given as an array or as an individual value. + * If this method is called multiple times, all enumerated values will be merged together. + * Choices are generally strings or numbers, and value matching is case-sensitive. + * + * Optionally `.choices()` can take an object that maps multiple keys to their choices. + * + * Choices can also be specified as choices in the object given to `option()`. + */ + choices>(key: K, values: C): YargsInstance & { [key in K]: C[number] | undefined }>; + choices>(key: K, values: C): YargsInstance; + choices }>(choices: C): YargsInstance & { [key in keyof C]: C[key][number] | undefined }>; + + /** + * Provide a synchronous function to coerce or transform the value(s) given on the command line for `key`. + * + * The coercion function should accept one argument, representing the parsed value from the command line, and should return a new value or throw an error. + * The returned value will be used as the value for `key` (or one of its aliases) in `argv`. + * + * If the function throws, the error will be treated as a validation failure, delegating to either a custom `.fail()` handler or printing the error message in the console. + * + * Coercion will be applied to a value after all other modifications, such as `.normalize()`. + * + * Optionally `.coerce()` can take an object that maps several keys to their respective coercion function. + * + * You can also map the same function to several keys at one time. Just pass an array of keys as the first argument to `.coerce()`. + * + * If you are using dot-notion or arrays, .e.g., `user.email` and `user.password`, coercion will be applied to the final object that has been parsed + */ + coerce(key: K | ReadonlyArray, func: (arg: any) => V): YargsInstance & { [key in K]: V | undefined }>; + coerce(key: K | ReadonlyArray, func: (arg: any) => V): YargsInstance; + coerce any }>(opts: O): YargsInstance & { [key in keyof O]: ReturnType | undefined }>; + + /** + * Define the commands exposed by your application. + * @param command Should be a string representing the command or an array of strings representing the command and its aliases. + * @param description Use to provide a description for each command your application accepts (the values stored in `argv._`). + * Set `description` to false to create a hidden command. Hidden commands don't show up in the help output and aren't available for completion. + * @param [builder] Object to give hints about the options that your command accepts. + * Can also be a function. This function is executed with a yargs instance, and can be used to provide advanced command specific help. + * + * Note that when `void` is returned, the handler `argv` object type will not include command-specific arguments. + * @param [handler] Function, which will be executed with the parsed `argv` object. + */ + command(command: string | ReadonlyArray, description: string, builder?: BuilderCallback, handler?: (args: Arguments) => void): YargsInstance; + command(command: string | ReadonlyArray, description: string, builder?: O, handler?: (args: Arguments>) => void): YargsInstance; + command(command: string | ReadonlyArray, description: string, module: CommandModule): YargsInstance; + command(command: string | ReadonlyArray, showInHelp: false, builder?: BuilderCallback, handler?: (args: Arguments) => void): YargsInstance; + command(command: string | ReadonlyArray, showInHelp: false, builder?: O, handler?: (args: Arguments>) => void): YargsInstance; + command(command: string | ReadonlyArray, showInHelp: false, module: CommandModule): YargsInstance; + command(module: CommandModule): YargsInstance; + + // Advanced API + /** Apply command modules from a directory relative to the module calling this method. */ + commandDir(dir: string, opts?: RequireDirectoryOptions): YargsInstance; + + /** + * Enable bash/zsh-completion shortcuts for commands and options. + * + * If invoked without parameters, `.completion()` will make completion the command to output the completion script. + * + * @param [cmd] When present in `argv._`, will result in the `.bashrc` or `.zshrc` completion script being outputted. + * To enable bash/zsh completions, concat the generated script to your `.bashrc` or `.bash_profile` (or `.zshrc` for zsh). + * @param [description] Provide a description in your usage instructions for the command that generates the completion scripts. + * @param [func] Rather than relying on yargs' default completion functionality, which shiver me timbers is pretty awesome, you can provide your own completion method. + */ + completion(): YargsInstance; + completion(cmd: string, func?: AsyncCompletionFunction): YargsInstance; + completion(cmd: string, func?: SyncCompletionFunction): YargsInstance; + completion(cmd: string, func?: PromiseCompletionFunction): YargsInstance; + completion(cmd: string, description?: string | false, func?: AsyncCompletionFunction): YargsInstance; + completion(cmd: string, description?: string | false, func?: SyncCompletionFunction): YargsInstance; + completion(cmd: string, description?: string | false, func?: PromiseCompletionFunction): YargsInstance; + + /** + * Tells the parser that if the option specified by `key` is passed in, it should be interpreted as a path to a JSON config file. + * The file is loaded and parsed, and its properties are set as arguments. + * Because the file is loaded using Node's require(), the filename MUST end in `.json` to be interpreted correctly. + * + * If invoked without parameters, `.config()` will make --config the option to pass the JSON config file. + * + * @param [description] Provided to customize the config (`key`) option in the usage string. + * @param [explicitConfigurationObject] An explicit configuration `object` + */ + config(): YargsInstance; + config(key: string | ReadonlyArray, description?: string, parseFn?: (configPath: string) => object): YargsInstance; + config(key: string | ReadonlyArray, parseFn: (configPath: string) => object): YargsInstance; + config(explicitConfigurationObject: object): YargsInstance; + + /** + * Given the key `x` is set, the key `y` must not be set. `y` can either be a single string or an array of argument names that `x` conflicts with. + * + * Optionally `.conflicts()` can accept an object specifying multiple conflicting keys. + */ + conflicts(key: string, value: string | ReadonlyArray): YargsInstance; + conflicts(conflicts: { [key: string]: string | ReadonlyArray }): YargsInstance; + + /** + * Interpret `key` as a boolean flag, but set its parsed value to the number of flag occurrences rather than `true` or `false`. Default value is thus `0`. + */ + count(key: K | ReadonlyArray): YargsInstance & { [key in K]: number }>; + count(key: K | ReadonlyArray): YargsInstance; + + /** + * Set `argv[key]` to `value` if no option was specified in `process.argv`. + * + * Optionally `.default()` can take an object that maps keys to default values. + * + * The default value can be a `function` which returns a value. The name of the function will be used in the usage string. + * + * Optionally, `description` can also be provided and will take precedence over displaying the value in the usage instructions. + */ + default(key: K, value: V, description?: string): YargsInstance & { [key in K]: V }>; + default(key: K, value: V, description?: string): YargsInstance; + default(defaults: D, description?: string): YargsInstance & D>; + + /** + * @deprecated since version 6.6.0 + * Use '.demandCommand()' or '.demandOption()' instead + */ + demand(key: K | ReadonlyArray, msg?: string | true): YargsInstance>; + demand(key: K | ReadonlyArray, msg?: string | true): YargsInstance; + demand(key: string | ReadonlyArray, required?: boolean): YargsInstance; + demand(positionals: number, msg: string): YargsInstance; + demand(positionals: number, required?: boolean): YargsInstance; + demand(positionals: number, max: number, msg?: string): YargsInstance; + + /** + * @param key If is a string, show the usage information and exit if key wasn't specified in `process.argv`. + * If is an array, demand each element. + * @param msg If string is given, it will be printed when the argument is missing, instead of the standard error message. + * @param demand Controls whether the option is demanded; this is useful when using .options() to specify command line parameters. + */ + demandOption(key: K | ReadonlyArray, msg?: string | true): YargsInstance>; + demandOption(key: K | ReadonlyArray, msg?: string | true): YargsInstance; + demandOption(key: string | ReadonlyArray, demand?: boolean): YargsInstance; + + /** + * Demand in context of commands. + * You can demand a minimum and a maximum number a user can have within your program, as well as provide corresponding error messages if either of the demands is not met. + */ + demandCommand(): YargsInstance; + demandCommand(min: number, minMsg?: string): YargsInstance; + demandCommand(min: number, max?: number, minMsg?: string, maxMsg?: string): YargsInstance; + + /** + * Describe a `key` for the generated usage information. + * + * Optionally `.describe()` can take an object that maps keys to descriptions. + */ + describe(key: string | ReadonlyArray, description: string): YargsInstance; + describe(descriptions: { [key: string]: string }): YargsInstance; + + /** Should yargs attempt to detect the os' locale? Defaults to `true`. */ + detectLocale(detect: boolean): YargsInstance; + + /** + * Tell yargs to parse environment variables matching the given prefix and apply them to argv as though they were command line arguments. + * + * Use the "__" separator in the environment variable to indicate nested options. (e.g. prefix_nested__foo => nested.foo) + * + * If this method is called with no argument or with an empty string or with true, then all env vars will be applied to argv. + * + * Program arguments are defined in this order of precedence: + * 1. Command line args + * 2. Env vars + * 3. Config file/objects + * 4. Configured defaults + * + * Env var parsing is disabled by default, but you can also explicitly disable it by calling `.env(false)`, e.g. if you need to undo previous configuration. + */ + env(): YargsInstance; + env(prefix: string): YargsInstance; + env(enable: boolean): YargsInstance; + + /** A message to print at the end of the usage instructions */ + epilog(msg: string): YargsInstance; + /** A message to print at the end of the usage instructions */ + epilogue(msg: string): YargsInstance; + + /** + * Give some example invocations of your program. + * Inside `cmd`, the string `$0` will get interpolated to the current script name or node command for the present script similar to how `$0` works in bash or perl. + * Examples will be printed out as part of the help message. + */ + example(command: string, description: string): YargsInstance; + + /** Manually indicate that the program should exit, and provide context about why we wanted to exit. Follows the behavior set by `.exitProcess().` */ + exit(code: number, err: Error): void; + + /** + * By default, yargs exits the process when the user passes a help flag, the user uses the `.version` functionality, validation fails, or the command handler fails. + * Calling `.exitProcess(false)` disables this behavior, enabling further actions after yargs have been validated. + */ + exitProcess(enabled: boolean): YargsInstance; + + /** + * Method to execute when a failure occurs, rather than printing the failure message. + * @param func Is called with the failure message that would have been printed, the Error instance originally thrown and yargs state when the failure occurred. + */ + fail(func: (msg: string, err: Error, yargs: YargsInstance) => any): YargsInstance; + + /** + * Allows to programmatically get completion choices for any line. + * @param args An array of the words in the command line to complete. + * @param done The callback to be called with the resulting completions. + */ + getCompletion(args: ReadonlyArray, done: (completions: ReadonlyArray) => void): YargsInstance; + + /** + * Indicate that an option (or group of options) should not be reset when a command is executed + * + * Options default to being global. + */ + global(key: string | ReadonlyArray): YargsInstance; + + /** Given a key, or an array of keys, places options under an alternative heading when displaying usage instructions */ + group(key: string | ReadonlyArray, groupName: string): YargsInstance; + + /** Hides a key from the generated usage information. Unless a `--show-hidden` option is also passed with `--help` (see `showHidden()`). */ + hide(key: string): YargsInstance; + + /** + * Configure an (e.g. `--help`) and implicit command that displays the usage string and exits the process. + * By default yargs enables help on the `--help` option. + * + * Note that any multi-char aliases (e.g. `help`) used for the help option will also be used for the implicit command. + * If there are no multi-char aliases (e.g. `h`), then all single-char aliases will be used for the command. + * + * If invoked without parameters, `.help()` will use `--help` as the option and help as the implicit command to trigger help output. + * + * @param [description] Customizes the description of the help option in the usage string. + * @param [enableExplicit] If `false` is provided, it will disable --help. + */ + help(): YargsInstance; + help(enableExplicit: boolean): YargsInstance; + help(option: string, enableExplicit: boolean): YargsInstance; + help(option: string, description?: string, enableExplicit?: boolean): YargsInstance; + + /** + * Given the key `x` is set, it is required that the key `y` is set. + * y` can either be the name of an argument to imply, a number indicating the position of an argument or an array of multiple implications to associate with `x`. + * + * Optionally `.implies()` can accept an object specifying multiple implications. + */ + implies(key: string, value: string | ReadonlyArray): YargsInstance; + implies(implies: { [key: string]: string | ReadonlyArray }): YargsInstance; + + /** + * Return the locale that yargs is currently using. + * + * By default, yargs will auto-detect the operating system's locale so that yargs-generated help content will display in the user's language. + */ + locale(): string; + /** + * Override the auto-detected locale from the user's operating system with a static locale. + * Note that the OS locale can be modified by setting/exporting the `LC_ALL` environment variable. + */ + locale(loc: string): YargsInstance; + + /** + * Define global middleware functions to be called first, in list order, for all cli command. + * @param callbacks Can be a function or a list of functions. Each callback gets passed a reference to argv. + * @param [applyBeforeValidation] Set to `true` to apply middleware before validation. This will execute the middleware prior to validation checks, but after parsing. + */ + middleware(callbacks: MiddlewareFunction | ReadonlyArray>, applyBeforeValidation?: boolean): YargsInstance; + + /** + * The number of arguments that should be consumed after a key. This can be a useful hint to prevent parsing ambiguity. + * + * Optionally `.nargs()` can take an object of `key`/`narg` pairs. + */ + nargs(key: string, count: number): YargsInstance; + nargs(nargs: { [key: string]: number }): YargsInstance; + + /** The key provided represents a path and should have `path.normalize()` applied. */ + normalize(key: K | ReadonlyArray): YargsInstance & { [key in K]: ToString }>; + normalize(key: K | ReadonlyArray): YargsInstance; + + /** + * Tell the parser to always interpret key as a number. + * + * If `key` is an array, all elements will be parsed as numbers. + * + * If the option is given on the command line without a value, `argv` will be populated with `undefined`. + * + * If the value given on the command line cannot be parsed as a number, `argv` will be populated with `NaN`. + * + * Note that decimals, hexadecimals, and scientific notation are all accepted. + */ + number(key: K | ReadonlyArray): YargsInstance & { [key in K]: ToNumber }>; + number(key: K | ReadonlyArray): YargsInstance; + + /** + * Method to execute when a command finishes successfully. + * @param func Is called with the successful result of the command that finished. + */ + onFinishCommand(func: (result: any) => void): YargsInstance; + + /** + * This method can be used to make yargs aware of options that could exist. + * You can also pass an opt object which can hold further customization, like `.alias()`, `.demandOption()` etc. for that option. + */ + option(key: K, options: O): YargsInstance & { [key in K]: InferredOptionType }>; + option(key: K, options: O): YargsInstance }>; + option(options: O): YargsInstance & InferredOptionTypes>; + + /** + * This method can be used to make yargs aware of options that could exist. + * You can also pass an opt object which can hold further customization, like `.alias()`, `.demandOption()` etc. for that option. + */ + options(key: K, options: O): YargsInstance & { [key in K]: InferredOptionType }>; + options(key: K, options: O): YargsInstance }>; + options(options: O): YargsInstance & InferredOptionTypes>; + + /** + * Parse `args` instead of `process.argv`. Returns the `argv` object. `args` may either be a pre-processed argv array, or a raw argument string. + * + * Note: Providing a callback to parse() disables the `exitProcess` setting until after the callback is invoked. + * @param [context] Provides a useful mechanism for passing state information to commands + */ + parse(): { [key in keyof Arguments]: Arguments[key] }; + parse(arg: string | ReadonlyArray, context?: object, parseCallback?: ParseCallback): { [key in keyof Arguments]: Arguments[key] }; + + /** + * If the arguments have not been parsed, this property is `false`. + * + * If the arguments have been parsed, this contain detailed parsed arguments. + */ + parsed: DetailedArguments | false; + + /** Allows to configure advanced yargs features. */ + parserConfiguration(configuration: Partial): YargsInstance; + + /** + * Similar to `config()`, indicates that yargs should interpret the object from the specified key in package.json as a configuration object. + * @param [cwd] If provided, the package.json will be read from this location + */ + pkgConf(key: string | ReadonlyArray, cwd?: string): YargsInstance; + + /** + * Allows you to configure a command's positional arguments with an API similar to `.option()`. + * `.positional()` should be called in a command's builder function, and is not available on the top-level yargs instance. If so, it will throw an error. + */ + positional(key: K, opt: O): YargsInstance & { [key in K]: InferredOptionType }>; + positional(key: K, opt: O): YargsInstance }>; + + /** Should yargs provide suggestions regarding similar commands if no matching command is found? */ + recommendCommands(): YargsInstance; + + /** + * @deprecated since version 6.6.0 + * Use '.demandCommand()' or '.demandOption()' instead + */ + require(key: K | ReadonlyArray, msg?: string | true): YargsInstance>; + require(key: string, msg: string): YargsInstance; + require(key: string, required: boolean): YargsInstance; + require(keys: ReadonlyArray, msg: string): YargsInstance; + require(keys: ReadonlyArray, required: boolean): YargsInstance; + require(positionals: number, required: boolean): YargsInstance; + require(positionals: number, msg: string): YargsInstance; + + /** + * @deprecated since version 6.6.0 + * Use '.demandCommand()' or '.demandOption()' instead + */ + required(key: K | ReadonlyArray, msg?: string | true): YargsInstance>; + required(key: string, msg: string): YargsInstance; + required(key: string, required: boolean): YargsInstance; + required(keys: ReadonlyArray, msg: string): YargsInstance; + required(keys: ReadonlyArray, required: boolean): YargsInstance; + required(positionals: number, required: boolean): YargsInstance; + required(positionals: number, msg: string): YargsInstance; + + requiresArg(key: string | ReadonlyArray): YargsInstance; + + /** + * @deprecated since version 6.6.0 + * Use '.global()' instead + */ + reset(): YargsInstance; + + /** Set the name of your script ($0). Default is the base filename executed by node (`process.argv[1]`) */ + scriptName($0: string): YargsInstance; + + /** + * Generate a bash completion script. + * Users of your application can install this script in their `.bashrc`, and yargs will provide completion shortcuts for commands and options. + */ + showCompletionScript(): YargsInstance; + + /** + * Configure the `--show-hidden` option that displays the hidden keys (see `hide()`). + * @param option If `boolean`, it enables/disables this option altogether. i.e. hidden keys will be permanently hidden if first argument is `false`. + * If `string` it changes the key name ("--show-hidden"). + * @param description Changes the default description ("Show hidden options") + */ + showHidden(option?: string | boolean): YargsInstance; + showHidden(option: string, description?: string): YargsInstance; + + /** + * Print the usage data using the console function consoleLevel for printing. + * @param [consoleLevel='error'] + */ + showHelp(consoleLevel?: string): YargsInstance; + + /** + * Provide the usage data as a string. + * @param printCallback a function with a single argument. + */ + showHelp(printCallback: (s: string) => void): YargsInstance; + + /** + * By default, yargs outputs a usage string if any error is detected. + * Use the `.showHelpOnFail()` method to customize this behavior. + * @param enable If `false`, the usage string is not output. + * @param [message] Message that is output after the error message. + */ + showHelpOnFail(enable: boolean, message?: string): YargsInstance; + + /** Specifies either a single option key (string), or an array of options. If any of the options is present, yargs validation is skipped. */ + skipValidation(key: string | ReadonlyArray): YargsInstance; + + /** + * Any command-line argument given that is not demanded, or does not have a corresponding description, will be reported as an error. + * + * Unrecognized commands will also be reported as errors. + */ + strict(): YargsInstance; + strict(enabled: boolean): YargsInstance; + + /** + * Tell the parser logic not to interpret `key` as a number or boolean. This can be useful if you need to preserve leading zeros in an input. + * + * If `key` is an array, interpret all the elements as strings. + * + * `.string('_')` will result in non-hyphenated arguments being interpreted as strings, regardless of whether they resemble numbers. + */ + string(key: K | ReadonlyArray): YargsInstance & { [key in K]: ToString }>; + string(key: K | ReadonlyArray): YargsInstance; + + // Intended to be used with '.wrap()' + terminalWidth(): number; + + updateLocale(obj: { [key: string]: string }): YargsInstance; + + /** + * Override the default strings used by yargs with the key/value pairs provided in obj + * + * If you explicitly specify a locale(), you should do so before calling `updateStrings()`. + */ + updateStrings(obj: { [key: string]: string }): YargsInstance; + + /** + * Set a usage message to show which commands to use. + * Inside `message`, the string `$0` will get interpolated to the current script name or node command for the present script similar to how `$0` works in bash or perl. + * + * If the optional `description`/`builder`/`handler` are provided, `.usage()` acts an an alias for `.command()`. + * This allows you to use `.usage()` to configure the default command that will be run as an entry-point to your application + * and allows you to provide configuration for the positional arguments accepted by your program: + */ + usage(message: string): YargsInstance; + usage(command: string | ReadonlyArray, description: string, builder?: (args: YargsInstance) => YargsInstance, handler?: (args: Arguments) => void): YargsInstance; + usage(command: string | ReadonlyArray, showInHelp: boolean, builder?: (args: YargsInstance) => YargsInstance, handler?: (args: Arguments) => void): YargsInstance; + usage(command: string | ReadonlyArray, description: string, builder?: O, handler?: (args: Arguments>) => void): YargsInstance; + usage(command: string | ReadonlyArray, showInHelp: boolean, builder?: O, handler?: (args: Arguments>) => void): YargsInstance; + + /** + * Add an option (e.g. `--version`) that displays the version number (given by the version parameter) and exits the process. + * By default yargs enables version for the `--version` option. + * + * If no arguments are passed to version (`.version()`), yargs will parse the package.json of your module and use its version value. + * + * If the boolean argument `false` is provided, it will disable `--version`. + */ + version(): YargsInstance; + version(version: string): YargsInstance; + version(enable: boolean): YargsInstance; + version(optionKey: string, version: string): YargsInstance; + version(optionKey: string, description: string, version: string): YargsInstance; + + /** + * Format usage output to wrap at columns many columns. + * + * By default wrap will be set to `Math.min(80, windowWidth)`. Use `.wrap(null)` to specify no column limit (no right-align). + * Use `.wrap(yargs.terminalWidth())` to maximize the width of yargs' usage instructions. + */ + wrap(columns: number | null): YargsInstance; + } + + type Arguments = T & { + /** Non-option arguments */ + _: string[]; + /** The script name or node command */ + $0: string; + /** All remaining options */ + [argName: string]: unknown; + }; + + interface RequireDirectoryOptions { + /** Look for command modules in all subdirectories and apply them as a flattened (non-hierarchical) list. */ + recurse?: boolean; + /** The types of files to look for when requiring command modules. */ + extensions?: ReadonlyArray; + /** + * A synchronous function called for each command module encountered. + * Accepts `commandObject`, `pathToFile`, and `filename` as arguments. + * Returns `commandObject` to include the command; any falsy value to exclude/skip it. + */ + visit?: (commandObject: any, pathToFile?: string, filename?: string) => any; + /** Whitelist certain modules */ + include?: RegExp | ((pathToFile: string) => boolean); + /** Blacklist certain modules. */ + exclude?: RegExp | ((pathToFile: string) => boolean); + } + + interface Options { + /** string or array of strings, alias(es) for the canonical option key, see `alias()` */ + alias?: string | ReadonlyArray; + /** boolean, interpret option as an array, see `array()` */ + array?: boolean; + /** boolean, interpret option as a boolean flag, see `boolean()` */ + boolean?: boolean; + /** value or array of values, limit valid option arguments to a predefined set, see `choices()` */ + choices?: Choices; + /** function, coerce or transform parsed command line values into another value, see `coerce()` */ + coerce?: (arg: any) => any; + /** boolean, interpret option as a path to a JSON config file, see `config()` */ + config?: boolean; + /** function, provide a custom config parsing function, see `config()` */ + configParser?: (configPath: string) => object; + /** string or object, require certain keys not to be set, see `conflicts()` */ + conflicts?: string | ReadonlyArray | { [key: string]: string | ReadonlyArray }; + /** boolean, interpret option as a count of boolean flags, see `count()` */ + count?: boolean; + /** value, set a default value for the option, see `default()` */ + default?: any; + /** string, use this description for the default value in help content, see `default()` */ + defaultDescription?: string; + /** + * @deprecated since version 6.6.0 + * Use 'demandOption' instead + */ + demand?: boolean | string; + /** boolean or string, demand the option be given, with optional error message, see `demandOption()` */ + demandOption?: boolean | string; + /** string, the option description for help content, see `describe()` */ + desc?: string; + /** string, the option description for help content, see `describe()` */ + describe?: string; + /** string, the option description for help content, see `describe()` */ + description?: string; + /** boolean, indicate that this key should not be reset when a command is invoked, see `global()` */ + global?: boolean; + /** string, when displaying usage instructions place the option under an alternative group heading, see `group()` */ + group?: string; + /** don't display option in help output. */ + hidden?: boolean; + /** string or object, require certain keys to be set, see `implies()` */ + implies?: string | ReadonlyArray | { [key: string]: string | ReadonlyArray }; + /** number, specify how many arguments should be consumed for the option, see `nargs()` */ + nargs?: number; + /** boolean, apply path.normalize() to the option, see `normalize()` */ + normalize?: boolean; + /** boolean, interpret option as a number, `number()` */ + number?: boolean; + /** + * @deprecated since version 6.6.0 + * Use 'demandOption' instead + */ + require?: boolean | string; + /** + * @deprecated since version 6.6.0 + * Use 'demandOption' instead + */ + required?: boolean | string; + /** boolean, require the option be specified with a value, see `requiresArg()` */ + requiresArg?: boolean; + /** boolean, skips validation if the option is present, see `skipValidation()` */ + skipValidation?: boolean; + /** boolean, interpret option as a string, see `string()` */ + string?: boolean; + type?: "array" | "count" | PositionalOptionsType; + } + + interface PositionalOptions { + /** string or array of strings, see `alias()` */ + alias?: string | ReadonlyArray; + /** boolean, interpret option as an array, see `array()` */ + array?: boolean; + /** value or array of values, limit valid option arguments to a predefined set, see `choices()` */ + choices?: Choices; + /** function, coerce or transform parsed command line values into another value, see `coerce()` */ + coerce?: (arg: any) => any; + /** string or object, require certain keys not to be set, see `conflicts()` */ + conflicts?: string | ReadonlyArray | { [key: string]: string | ReadonlyArray }; + /** value, set a default value for the option, see `default()` */ + default?: any; + /** boolean or string, demand the option be given, with optional error message, see `demandOption()` */ + demandOption?: boolean | string; + /** string, the option description for help content, see `describe()` */ + desc?: string; + /** string, the option description for help content, see `describe()` */ + describe?: string; + /** string, the option description for help content, see `describe()` */ + description?: string; + /** string or object, require certain keys to be set, see `implies()` */ + implies?: string | ReadonlyArray | { [key: string]: string | ReadonlyArray }; + /** boolean, apply path.normalize() to the option, see normalize() */ + normalize?: boolean; + type?: PositionalOptionsType; + } + + /** Remove keys K in T */ + type Omit = { [key in Exclude]: T[key] }; + + /** Remove undefined as a possible value for keys K in T */ + type Defined = Omit & { [key in K]: Exclude }; + + /** Convert T to T[] and T | undefined to T[] | undefined */ + type ToArray = Array> | Extract; + + /** Gives string[] if T is an array type, otherwise string. Preserves | undefined. */ + type ToString = (Exclude extends any[] ? string[] : string) | Extract; + + /** Gives number[] if T is an array type, otherwise number. Preserves | undefined. */ + type ToNumber = (Exclude extends any[] ? number[] : number) | Extract; + + type InferredOptionType = + O extends { default: infer D } ? D : + O extends { type: "count" } ? number : + O extends { count: true } ? number : + O extends { required: string | true } ? RequiredOptionType : + O extends { require: string | true } ? RequiredOptionType : + O extends { demand: string | true } ? RequiredOptionType : + O extends { demandOption: string | true } ? RequiredOptionType : + RequiredOptionType | undefined; + + type RequiredOptionType = + O extends { type: "array", string: true } ? string[] : + O extends { type: "array", number: true } ? number[] : + O extends { type: "array", normalize: true } ? string[] : + O extends { type: "string", array: true } ? string[] : + O extends { type: "number", array: true } ? number[] : + O extends { string: true, array: true } ? string[] : + O extends { number: true, array: true } ? number[] : + O extends { normalize: true, array: true } ? string[] : + O extends { type: "array" } ? Array : + O extends { type: "boolean" } ? boolean : + O extends { type: "number" } ? number : + O extends { type: "string" } ? string : + O extends { array: true } ? Array : + O extends { boolean: true } ? boolean : + O extends { number: true } ? number : + O extends { string: true } ? string : + O extends { normalize: true } ? string : + O extends { choices: ReadonlyArray } ? C : + O extends { coerce: (arg: any) => infer T } ? T : + unknown; + + type InferredOptionTypes = { [key in keyof O]: InferredOptionType }; + + interface CommandModule { + /** array of strings (or a single string) representing aliases of `exports.command`, positional args defined in an alias are ignored */ + aliases?: ReadonlyArray | string; + /** object declaring the options the command accepts, or a function accepting and returning a yargs instance */ + builder?: CommandBuilder; + /** string (or array of strings) that executes this command when given on the command line, first string may contain positional args */ + command?: ReadonlyArray | string; + /** string used as the description for the command in help text, use `false` for a hidden command */ + describe?: string | false; + /** a function which will be passed the parsed argv. */ + handler: (args: Arguments) => void; + } + + type ParseCallback = (err: Error | undefined, argv: Arguments, output: string) => void; + type CommandBuilder = { [key: string]: Options } | ((args: YargsInstance) => YargsInstance) | ((args: YargsInstance) => PromiseLike>); + type SyncCompletionFunction = (current: string, argv: any) => string[]; + type AsyncCompletionFunction = (current: string, argv: any, done: (completion: ReadonlyArray) => void) => void; + type PromiseCompletionFunction = (current: string, argv: any) => Promise; + type MiddlewareFunction = (args: Arguments) => void; + type Choices = ReadonlyArray; + type PositionalOptionsType = "boolean" | "number" | "string"; + + // Aliases for old @types/yargs names + type Argv = YargsInstance; +} + +declare interface yargs { + (processArgs?: string | string[], cwd?: string, parentRequire?: NodeRequire): YargsInstance + rebase: RebaseFunction + Parser: Parser +} + +export = yargs;