argparse-ts/es/types.d.ts

Modern CLI arguments parser for node.js

import { ParsedArgumentsCollection } from "./classes";
/**
 * Represents the type of argument.
 *
 * @category Types
 */
export type ArgType = 'string' | 'number' | 'boolean';
/**
 * The type of nargs. It can be a number, or one of the following symbols:
 * - `?`: The argument is optional.
 * - `*`: The argument is optional and can appear multiple times.
 * - `+`: The argument is required and can appear multiple times.
 *
 * @category Types
 */
export type NArgs = number | '?' | '*' | '+';
/**
 * Predefined actions for the argument parser.
 *
 * @category Types
 */
export type PredefinedAction = 'version' | 'help';
/**
 * A function that takes a value and does something with it.
 *
 * @category Types
 */
export type ActionFunction = ((value: unknown, parsed: ParsedArgumentsCollection, parser: ArgsParserInterface) => void);
/**
 * An action that can be used with the argument parser.
 * It can be a predefined action or a function that takes a value
 * and does something with it.
 *
 * @category Types
 */
export type Action = PredefinedAction | ActionFunction;
/**
 * Router action function.
 */
export type RouterAction = (parser: ArgsParserInterface, args: string[]) => (void | Promise<void>);
/**
 * Configuration for the argument parser.
 *
 * @category Types
 */
export type ArgParserConfig = {
    /**
     * The name of the program.
     */
    name?: string;
    /**
     * The version of the program.
     */
    version?: string;
    /**
     * Whether to exit the program on error (true by default).
     */
    exitOnError?: boolean;
    /**
     * Whether to exit the program on StopException (true by default).
     */
    exitOnStop?: boolean;
    /**
     * Whether to ignore unrecognized arguments (false by default).
     */
    ignoreUnrecognized?: boolean;
};
/**
 * Configuration for an argument.
 *
 * @category Types
 */
export type ArgConfig = {
    /**
     * The type of the argument.
     */
    type: ArgType;
    /**
     * The name of the argument.
     */
    name: string;
    /**
     * An optional alias for the argument.
     */
    alias?: string;
    /**
     * A description of the argument.
     */
    description?: string;
    /**
     * Whether the argument is required.
     */
    nargs?: NArgs;
    /**
     * Whether the argument is required.
     */
    required?: boolean;
    /**
     * The default value of the argument.
     */
    default?: unknown;
    /**
     * A constant value for the argument.
     */
    const?: unknown;
    /**
     * Allowed values for the argument.
     */
    choices?: unknown[];
    /**
     * A custom action for the argument.
     */
    action?: Action;
    /**
     * A custom validator function for the argument value.
     */
    validator?: (value: unknown) => boolean;
};
/**
 * Configuration for an action used with the argument parser.
 *
 * @category Types
 */
export type ActionConfig = {
    /**
     * The name of the action.
     */
    name: string;
    /**
     * An optional alias for the action.
     */
    alias?: string;
    /**
     * A description of the action.
     */
    description?: string;
    /**
     * The action to be performed.
     */
    action: Action;
};
/**
 * ArgConfig extension.
 *
 * @category Types
 */
export type ArgExtraConfig = {
    /**
     * If the argument is positional.
     */
    positional: boolean;
    /**
     * If the argument is multiple.
     */
    multiple: boolean;
    /**
     * If the argument is required.
     */
    required: boolean;
    /**
     * If the argument is allowed to be empty.
     */
    allowEmpty: boolean;
    /**
     * The minimum number of times the argument is allowed to appear.
     */
    minValuesCount: number;
    /**
     * The number of times the argument is allowed to appear.
     * If not defined, it means the argument can appear any number of times.
     */
    valuesCount?: number;
};
/**
 * Extended configuration for an argument, combining both input and extra configurations.
 *
 * @category Types
 */
export type ArgConfigExtended = ArgConfig & ArgExtraConfig;
/**
 * Interface for a collection of parsed arguments.
 *
 * @category Interfaces
 */
export interface ParsedArgumentsCollectionInterface {
    /**
     * All positional arguments as a record.
     */
    readonly positional: Record<string, unknown>;
    /**
     * All optional arguments as a record.
     */
    readonly options: Record<string, unknown>;
    /**
     * Retrieves an argument value by name.
     *
     * @param name - The name of the argument.
     *
     * @returns The value of the argument.
     */
    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, false otherwise.
     */
    has(name: string): boolean;
}
/**
 * Interface for an argument parser.
 *
 * @category Interfaces
 */
export interface ArgsParserInterface {
    /**
     * The configuration of the argument parser.
     */
    readonly config: ArgParserConfig;
    /**
     * The help message for the arguments.
     */
    readonly help: string;
    /**
     * Adds an argument configuration to the parser.
     *
     * @param config - The argument configuration.
     *
     * @returns The updated parser.
     */
    addArgument(config: ArgConfig): ArgsParserInterface;
    /**
     * Adds an action configuration to the parser.
     *
     * @param config - The action configuration.
     *
     * @returns The updated parser.
     */
    addAction(config: ActionConfig): ArgsParserInterface;
    /**
     * 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): ArgsParserInterface;
    /**
     * 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): ArgsParserInterface;
    /**
     * Parses the given argument string and returns a collection of parsed arguments.
     *
     * @param argv - The argument string.
     *
     * @returns A ParsedArgumentsCollection containing the parsed arguments.
     */
    parse(argv: string[]): ParsedArgumentsCollectionInterface;
}
/**
 * Interface for a value validator.
 *
 * @category Interfaces
 */
export interface ValueValidatorInterface {
    /**
     * Validates the argument value before casting.
     *
     * @param value - The value to validate.
     * @param isset - Whether the value is set.
     *
     * @throws ArgumentValueError if the value is invalid.
     */
    validateBeforeCast(value: string[], isset: boolean): void;
    /**
     * Validates the argument value after casting.
     *
     * @param value - The value to validate.
     *
     * @throws ArgumentValueError if the value is invalid.
     */
    validateAfterCast(value: string[]): void;
}
/**
 * Interface for a value caster.
 *
 * @template T - The expected type of the argument value.
 *
 * @category Interfaces
 */
export interface ValueCasterInterface<T> {
    /**
     * Casts the argument value to the expected type.
     *
     * @param value - The value to cast.
     * @param isset - Whether the value is set.
     *
     * @returns The casted value.
     */
    cast(value: string[], isset: boolean): T | undefined;
}
/**
 * Interface for a router.
 *
 * @category Interfaces
 * @category Router
 */
export interface RouterInterface {
    /**
     * 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>;
}