argparse-ts
Version:
Modern CLI arguments parser for node.js
304 lines (303 loc) • 9.35 kB
TypeScript
import { ActionConfig, ArgConfig, ArgParserConfig, ArgsParserInterface, ParsedArgumentsCollectionInterface, RouterAction, RouterInterface } from "./types";
/**
* A collection of parsed arguments.
*
* @category Classes
*/
export declare class ParsedArgumentsCollection implements ParsedArgumentsCollectionInterface {
/**
* A collection of parsed positional arguments.
*/
private readonly positionalArgs;
/**
* A collection of parsed optional arguments.
*/
private readonly optionArgs;
/**
* Returns positional arguments as a record.
*/
get positional(): Record<string, unknown>;
/**
* Returns options as a record.
*/
get options(): Record<string, unknown>;
/**
* Retrieves an argument value.
* @param name - The name of the argument.
* @returns The value of the argument, or undefined if not found.
*/
get<T = unknown>(name: string): T;
/**
* Checks if an argument exists in the collection.
* @param name - The name of the argument.
* @returns True if the argument exists, otherwise false.
*/
has(name: string): boolean;
/**
* Adds a new argument to the collection.
* @param name - The name of the argument.
* @param value - The value of the argument.
* @returns The instance of ParsedArgumentsCollection for chaining.
*/
add(name: string, value: unknown): this;
/**
* Formats the argument name by removing leading dashes.
* @param name - The argument name.
* @returns The formatted name.
*/
private formatName;
/**
* Checks if the argument is positional.
* @param name - The argument name.
* @returns True if the argument is positional, otherwise false.
*/
private isPositional;
}
/**
* Parser for command-line arguments.
*
* @category Classes
*/
export declare class ArgsParser implements ArgsParserInterface {
/**
* Configuration options for the parser.
*/
readonly config: ArgParserConfig;
/**
* Maps argument names to their configuration.
*/
private readonly argsMap;
/**
* Maps argument aliases to their corresponding names.
*/
private readonly aliasMap;
/**
* Tracks used argument names and aliases to prevent duplicates.
*/
private readonly usedArgs;
/**
* Constructs an instance of ArgsParser with the provided argument configurations.
*
* @param config - Configuration options for the parser.
* @param args - An array of argument configurations.
*/
constructor(config: ArgParserConfig, args?: ArgConfig[]);
/**
* Retrieves the help message.
*/
get help(): string;
/**
* Adds a new argument configuration to the parser.
*
* @param config - The argument configuration.
* @returns The instance of ArgsParser for chaining.
*
* @example
* ```
* const parser = new ArgsParser();
* parser.addArgument({
* name: '--flag',
* alias: '-f',
* type: 'boolean',
* const: true,
* default: false,
* });
* ```
*/
addArgument(config: ArgConfig): ArgsParser;
/**
* Adds an action configuration to the parser.
*
* @param config - The action configuration.
*
* @returns The updated parser.
*/
addAction(config: ActionConfig): ArgsParser;
/**
* Adds a help action to the parser.
*
* @param name - The name of the help action.
* @param alias - The alias of the help action.
*
* @returns The updated parser.
*/
addHelpAction(name?: string, alias?: string): ArgsParser;
/**
* Adds a version action to the parser.
*
* @param name - The name of the version action.
* @param alias - The alias of the version action.
*
* @returns The updated parser.
*/
addVersionAction(name?: string, alias?: string): ArgsParser;
/**
* Parses the given argument string and returns a collection of parsed arguments.
*
* @param argv - The argument string.
*
* @returns A ParsedArgumentsCollection containing the parsed arguments.
*
* @example
* ```
* const parser = new ArgsParser([
* {
* name: 'action',
* description: 'Action to perform',
* type: 'string',
* },
* {
* name: '--flag',
* description: 'Flag',
* alias: '-f',
* type: 'boolean',
* const: true,
* default: false,
* },
* {
* name: '--values',
* description: 'Values',
* alias: '-v',
* type: 'string',
* nargs: '*',
* default: [],
* }
* ]);
*
* const argv = ['make', '--flag', '-v', 'a', 'b', 'c'];
* const parsedArgs = parser.parse(argv);
*
* console.log(parsedArgs.positional); // { action: 'make' }
* console.log(parsedArgs.optional); // { flag: true, values: ['a', 'b', 'c'] }
* console.log(parsedArgs.get('--values')); // ['a', 'b', 'c']
* ```
*/
parse(argv: string[]): ParsedArgumentsCollection;
/**
* Processes positional arguments.
*
* @param parsedValues - A parsed array of positional argument values.
* @param argConfigs - An array of extended argument configurations.
* @param result - The collection where parsed arguments will be added.
*
* @returns The number of positional arguments processed.
*/
private processPositionalArgs;
/**
* Processes optional arguments.
*
* @param parsedValuesMap - A map of parsed optional argument keys to their string values.
* @param argConfigs - An array of extended argument configurations.
* @param result - The collection where parsed arguments will be added.
*
* @returns The number of optional arguments processed.
*/
private processOptions;
private processException;
private processExit;
/**
* Processes a single argument value.
*
* @param value - The value(s) being processed.
* @param argConfig - The configuration of the argument.
* @param parsed - The parsed result
* @param isset - Whether the argument is set.
*
* @returns The processed value, or undefined if the argument is not set.
*/
private processArgValue;
private processAction;
/**
* Retrieves the positional arguments.
*
* @returns An array of positional argument configurations.
*/
private getPositionalArguments;
/**
* Retrieves the optional arguments.
*
* @returns An array of optional argument configurations.
*/
private getOptionArguments;
/**
* Retrieves a set of used argument names and aliases.
*
* @returns A set of used argument names and aliases.
*/
private getUsedArgs;
/**
* Retrieves a map of argument configurations for the given keys.
*
* @param keys - The keys to retrieve.
*
* @returns A map of argument configurations, where each key is one of the given keys and the value
* is the corresponding ArgConfigExtended.
*/
private getArgConfigMap;
/**
* Retrieves the argument configuration for a given key.
*
* @param key - The argument key.
*
* @returns The corresponding ArgConfigExtended.
*/
private getArgConfig;
/**
* Extends an argument configuration with extra information.
*
* @param config - The argument configuration.
*
* @returns The argument configuration extended with extra information.
*/
private extendArgConfig;
/**
* Reads the value of the positional argument based on the nargs configuration.
*
* @param parsedValues - The parsed positional arguments.
* @param argConfig - The argument configuration.
* @param remainingArgConfigs - The remaining argument configurations.
*
* @returns The value of the positional argument.
*/
private readPositionalArgValues;
/**
* Determines the number of arguments to read based on the nargs configuration.
*
* @param argConfig - The configuration specifying how many arguments can be read.
* @param remainingArgConfigs - The remaining arguments to read.
* @param values - The total number of available arguments.
*
* @returns The number of arguments to read.
*/
private getArgsCountToRead;
private formatConfig;
}
/**
* A class representing a router for command-line arguments.
*
* @category Classes
* @category Router
*/
export declare class Router implements RouterInterface {
private readonly routes;
private readonly parser;
/**
* Creates a new Router instance.
*
* @param config - The configuration for the router.
* @param routes - The routes for the router.
*/
constructor(config: ArgParserConfig, routes: Record<string, RouterAction>);
/**
* Runs the router.
*
* @param argv - The argument string.
*/
run(argv?: string[]): void;
/**
* Runs the router asynchronously.
*
* @param argv - The argument string.
*/
runAsync(argv?: string[]): Promise<void>;
}