First version

CTOAsYouGo/node_modules/commander/typings/index.d.ts

@@ -1,8 +1,6 @@
 // Type definitions for commander
 // Original definitions by: Alan Agius <https://github.com/alan-agius4>, Marcelo Dezem <https://github.com/mdezem>, vvakame <https://github.com/vvakame>, Jules Randolph <https://github.com/sveinburne>
 
-///<reference types="node" />
-
 declare namespace commander {
 
   interface CommanderError extends Error {
@@ -11,7 +9,7 @@ declare namespace commander {
     message: string;
     nestedError?: string;
   }
-  type CommanderErrorConstructor = { new (exitCode: number, code: string, message: string): CommanderError };
+  type CommanderErrorConstructor = new (exitCode: number, code: string, message: string) => CommanderError;
 
   interface Option {
     flags: string;
@@ -23,29 +21,35 @@ declare namespace commander {
     long: string;
     description: string;
   }
-  type OptionConstructor = { new (flags: string, description?: string): Option };
+  type OptionConstructor = new (flags: string, description?: string) => Option;
 
-  interface Command extends NodeJS.EventEmitter {
+  interface ParseOptions {
+    from: 'node' | 'electron' | 'user';
+  }
+
+  interface Command {
     [key: string]: any; // options as properties
 
     args: string[];
 
+    commands: Command[];
+
     /**
-     * Set the program version to `str`. 
+     * Set the program version to `str`.
      *
      * This method auto-registers the "-V, --version" flag
      * which will print the version number when passed.
-     * 
+     *
      * You can optionally supply the  flags and description to override the defaults.
      */
-    version(str: string, flags?: string, description?: string): Command;
+    version(str: string, flags?: string, description?: string): this;
 
     /**
      * Define a command, implemented using an action handler.
-     * 
+     *
      * @remarks
      * The command description is supplied using `.description`, not as a parameter to `.command`.
-     * 
+     *
      * @example
      * ```ts
      *  program
@@ -55,52 +59,60 @@ declare namespace commander {
      *      console.log('clone command called');
      *    });
      * ```
-     * 
+     *
      * @param nameAndArgs - command name and arguments, args are  `<required>` or `[optional]` and last may also be `variadic...`
      * @param opts - configuration options
      * @returns new command
      */
-    command(nameAndArgs: string, opts?: CommandOptions): Command;
+    command(nameAndArgs: string, opts?: CommandOptions): ReturnType<this['createCommand']>;
     /**
      * Define a command, implemented in a separate executable file.
-     * 
+     *
      * @remarks
      * The command description is supplied as the second parameter to `.command`.
-     * 
+     *
      * @example
      * ```ts
      *  program
      *    .command('start <service>', 'start named service')
      *    .command('stop [service]', 'stop named serice, or all if no name supplied');
      * ```
-     * 
+     *
      * @param nameAndArgs - command name and arguments, args are  `<required>` or `[optional]` and last may also be `variadic...`
      * @param description - description of executable command
      * @param opts - configuration options
-     * @returns top level command for chaining more command definitions
+     * @returns `this` command for chaining
      */
-    command(nameAndArgs: string, description: string, opts?: commander.CommandOptions): Command;
+    command(nameAndArgs: string, description: string, opts?: commander.ExecutableCommandOptions): this;
 
     /**
-     * Define argument syntax for the top-level command.
+     * Factory routine to create a new unattached command.
      *
-     * @returns Command for chaining
+     * See .command() for creating an attached subcommand, which uses this routine to
+     * create the command. You can override createCommand to customise subcommands.
      */
-    arguments(desc: string): Command;
+    createCommand(name?: string): Command;
 
     /**
-    * Parse expected `args`.
+     * Add a prepared subcommand.
      *
-     * For example `["[type]"]` becomes `[{ required: false, name: 'type' }]`.
+     * See .command() for creating an attached subcommand which inherits settings from its parent.
      *
-     * @returns Command for chaining
+     * @returns `this` command for chaining
      */
-     parseExpectedArgs(args: string[]): Command;
+    addCommand(cmd: Command, opts?: CommandOptions): this;
+
+    /**
+     * Define argument syntax for command.
+     *
+     * @returns `this` command for chaining
+     */
+    arguments(desc: string): this;
 
     /**
      * Register callback to use as replacement for calling process.exit.
      */
-    exitOverride(callback?: (err: CommanderError) => never|void): Command;
+    exitOverride(callback?: (err: CommanderError) => never|void): this;
 
     /**
      * Register callback `fn` for the command.
@@ -113,9 +125,9 @@ declare namespace commander {
      *           // output help here
      *        });
      *
-     * @returns Command for chaining
+     * @returns `this` command for chaining
      */
-    action(fn: (...args: any[]) => void | Promise<void>): Command;
+    action(fn: (...args: any[]) => void | Promise<void>): this;
 
     /**
      * Define option with `flags`, `description` and optional
@@ -157,10 +169,11 @@ declare namespace commander {
      *     // optional argument
      *     program.option('-c, --cheese [type]', 'add cheese [marble]');
      *
-     * @returns Command for chaining
+     * @returns `this` command for chaining
      */
-    option(flags: string, description?: string, fn?: ((arg1: any, arg2: any) => void) | RegExp, defaultValue?: any): Command;
-    option(flags: string, description?: string, defaultValue?: any): Command;
+    option(flags: string, description?: string, defaultValue?: string | boolean): this;
+    option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this;
+    option<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
 
     /**
      * Define a required option, which must have a value after parsing. This usually means
@@ -168,52 +181,78 @@ declare namespace commander {
      *
      * The `flags` string should contain both the short and long flags, separated by comma, a pipe or space.
      */
-    requiredOption(flags: string, description?: string, fn?: ((arg1: any, arg2: any) => void) | RegExp, defaultValue?: any): Command;
-    requiredOption(flags: string, description?: string, defaultValue?: any): Command;
-
+    requiredOption(flags: string, description?: string, defaultValue?: string | boolean): this;
+    requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this;
+    requiredOption<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
 
     /**
      * Whether to store option values as properties on command object,
      * or store separately (specify false). In both cases the option values can be accessed using .opts().
      *
-     * @return Command for chaining
+     * @returns `this` command for chaining
      */
-    storeOptionsAsProperties(value?: boolean): Command;
+    storeOptionsAsProperties(value?: boolean): this;
 
     /**
      * Whether to pass command to action handler,
      * or just the options (specify false).
-     * 
-     * @return Command for chaining
+     *
+     * @returns `this` command for chaining
      */
-    passCommandToAction(value?: boolean): Command;
+    passCommandToAction(value?: boolean): this;
 
     /**
      * Allow unknown options on the command line.
      *
      * @param [arg] if `true` or omitted, no error will be thrown for unknown options.
-     * @returns Command for chaining
+     * @returns `this` command for chaining
      */
-    allowUnknownOption(arg?: boolean): Command;
+    allowUnknownOption(arg?: boolean): this;
 
     /**
      * Parse `argv`, setting options and invoking commands when defined.
      *
-     * @returns Command for chaining
+     * The default expectation is that the arguments are from node and have the application as argv[0]
+     * and the script being run in argv[1], with user parameters after that.
+     *
+     * Examples:
+     *
+     *      program.parse(process.argv);
+     *      program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
+     *      program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+     *
+     * @returns `this` command for chaining
      */
-    parse(argv: string[]): Command;
+    parse(argv?: string[], options?: ParseOptions): this;
 
     /**
      * Parse `argv`, setting options and invoking commands when defined.
-     * 
+     *
      * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise.
      *
+     * The default expectation is that the arguments are from node and have the application as argv[0]
+     * and the script being run in argv[1], with user parameters after that.
+     *
+     * Examples:
+     *
+     *      program.parseAsync(process.argv);
+     *      program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
+     *      program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+     *
      * @returns Promise
      */
-    parseAsync(argv: string[]): Promise<any>;
+    parseAsync(argv?: string[], options?: ParseOptions): Promise<this>;
 
     /**
-     * Parse options from `argv` returning `argv` void of these options.
+     * Parse options from `argv` removing known options,
+     * and return argv split into operands and unknown arguments.
+     *
+     * @example
+     *    argv => operands, unknown
+     *    --known kkk op => [op], []
+     *    op --known kkk => [op], []
+     *    sub --unknown uuu op => [sub], [--unknown uuu op]
+     *    sub -- --unknown uuu op => [sub --unknown uuu op], []
      */
     parseOptions(argv: string[]): commander.ParseOptionsResult;
 
@@ -224,10 +263,10 @@ declare namespace commander {
 
     /**
      * Set the description.
-     * 
-     * @returns Command for chaining
+     *
+     * @returns `this` command for chaining
      */
-    description(str: string, argsDescription?: {[argName: string]: string}): Command;
+    description(str: string, argsDescription?: {[argName: string]: string}): this;
     /**
      * Get the description.
      */
@@ -235,21 +274,36 @@ declare namespace commander {
 
     /**
      * Set an alias for the command.
-     * 
-     * @returns Command for chaining
+     *
+     * You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help.
+     *
+     * @returns `this` command for chaining
      */
-    alias(alias: string): Command;
+    alias(alias: string): this;
     /**
      * Get alias for the command.
      */
     alias(): string;
 
     /**
-     * Set the command usage.
-     * 
-     * @returns Command for chaining
+     * Set aliases for the command.
+     *
+     * Only the first alias is shown in the auto-generated help.
+     *
+     * @returns `this` command for chaining
      */
-    usage(str: string): Command;
+    aliases(aliases: string[]): this;
+    /**
+     * Get aliases for the command.
+     */
+    aliases(): string[];
+
+    /**
+     * Set the command usage.
+     *
+     * @returns `this` command for chaining
+     */
+    usage(str: string): this;
     /**
      * Get the command usage.
      */
@@ -257,10 +311,10 @@ declare namespace commander {
 
     /**
      * Set the name of the command.
-     * 
-     * @returns Command for chaining
+     *
+     * @returns `this` command for chaining
      */
-    name(str: string): Command;
+    name(str: string): this;
     /**
      * Get the name of the command.
      */
@@ -274,38 +328,59 @@ declare namespace commander {
      */
     outputHelp(cb?: (str: string) => string): void;
 
+    /**
+     * Return command help documentation.
+     */
+    helpInformation(): string;
+
     /**
      * You can pass in flags and a description to override the help
      * flags and help description for your command.
      */
-    helpOption(flags?: string, description?: string): Command;
+    helpOption(flags?: string, description?: string): this;
 
-    /** 
+    /**
      * Output help information and exit.
      */
     help(cb?: (str: string) => string): never;
+
+    /**
+     * Add a listener (callback) for when events occur. (Implemented using EventEmitter.)
+     *
+     * @example
+     *     program
+     *       .on('--help', () -> {
+     *         console.log('See web site for more information.');
+     *     });
+     */
+    on(event: string | symbol, listener: (...args: any[]) => void): this;
   }
-  type CommandConstructor = { new (name?: string): Command };
+  type CommandConstructor = new (name?: string) => Command;
 
+  interface CommandOptions {
+    noHelp?: boolean; // old name for hidden
+    hidden?: boolean;
+    isDefault?: boolean;
+  }
+  interface ExecutableCommandOptions extends CommandOptions {
+    executableFile?: string;
+  }
 
-    interface CommandOptions {
-        noHelp?: boolean;
-        isDefault?: boolean;
-        executableFile?: string;
-    }
+  interface ParseOptionsResult {
+    operands: string[];
+    unknown: string[];
+  }
 
-    interface ParseOptionsResult {
-        args: string[];
-        unknown: string[];
-    }
-
-    interface CommanderStatic extends Command {
-        Command: CommandConstructor;
-        Option: OptionConstructor;
-        CommanderError:CommanderErrorConstructor;
-      }
+  interface CommanderStatic extends Command {
+    program: Command;
+    Command: CommandConstructor;
+    Option: OptionConstructor;
+    CommanderError: CommanderErrorConstructor;
+  }
 
 }
 
+// Declaring namespace AND global
+// eslint-disable-next-line no-redeclare
 declare const commander: commander.CommanderStatic;
 export = commander;