argumental/dist/lib/argumental.d.ts

Framework for building CLI apps with Node.js

import { BuiltInValidators } from './validators';
import { Argumental } from '../types';
export declare class ArgumentalApp extends BuiltInValidators {
    constructor(exitOnError?: boolean);
    /** Global declaration flag. */
    private _global;
    /** Global declarations to prepend to all future command declarations (including top-level). */
    private _globalDeclaration;
    /** Shared declaration flag. */
    private _shared;
    /** Shared declarations to prepend to all future command declarations (excluding top-level). */
    private _sharedDeclaration;
    /** Command declarations. */
    private _commands;
    /** Current command declaration. */
    private _currentCommand;
    /** Current component type of the current command. */
    private _currentComponent;
    /** List of all command names and aliases for quick conflict checks. */
    private _conflicts;
    /** Application version. */
    private _version;
    /** Application name. */
    private _name;
    /** Parser. */
    private _parser;
    /** Logger. */
    private _log;
    /** Flag for displaying help without the --help option for plain top-level command. */
    private _topLevelPlainHelp;
    /** The last command order set. */
    private _lastCommandOrder;
    /** Custom event declarations. */
    private _events;
    /** Shared data object throughout the application. */
    private _data;
    /** Whether to end process on error or not. */
    private _exitOnError;
    /**
    * Attaches an array of validators to the given component (argument or option's argument).
    * @param component A reference to an argument or and option declaration.
    * @param validators The array of validators.
    * @param destructuringParams Whether the validators are defined with destructuring parameters.
    */
    private _attachValidator;
    /**
    * Sets validators for an option or an argument.
    * @param validators A single or an array of validators.
    * @param destructuringParams Whether to use destructuring params for the validators.
    */
    private _validate;
    /**
    * Mounts an action handler to the current command (or globally).
    * @param handler The action handler to attach.
    * @param destructuringParams Whether to use destructuring params for the validators.
    */
    private _action;
    /**
    * Determines if argument already exists considering the global and shared flags.
    * @param argument The argument declaration.
    */
    private _doesArgumentAlreadyExist;
    /**
    * Determines if option already exists considering the global and shared flags.
    * @param option The option declaration.
    */
    private _doesOptionAlreadyExist;
    /**
    * Merges two event declarations (does not mutate objects).
    * @param a First event declarations.
    * @param b Second event declarations.
    */
    private _mergeEvents;
    /**
    * Returns true if event is a default event.
    * @param event The event name to check.
    */
    private _isEventDefault;
    /**
    * Emits a context-based default event for a command.
    * @param event The default event name.
    * @param cmd The command name.
    * @param data The event data.
    */
    private _emitDefault;
    /** Logs error and exits the process with code 1. */
    private _exitWithError;
    /** Shared data object throughout the application. */
    data<T = any>(): T;
    /**
    * Configures Argumental with the provided options.
    * @param options The configuration options.
    */
    config(options: Argumental.Options): ArgumentalApp;
    /**
    * Sets the application version and defines the top-level option `-v --version`.
    * @param version The application version.
    */
    version(version: string): ArgumentalApp;
    /**
    * Makes any following argument, option, and action declaration globally applied to all commands (appended to previously declared commands and prepended to future command declarations) unless the command() function is called.
    */
    get shared(): ArgumentalApp;
    /**
    * Makes any following argument, option, and action declaration globally applied to all commands excluding top-level (appended to previously declared commands and prepended to future command declarations) unless the command() function is called.
    */
    get global(): ArgumentalApp;
    /**
    * Makes any following argument, option, and action declaration applied to top-level.
    */
    get top(): ArgumentalApp;
    /**
    * Sets the description for a command, option, or argument.
    * @param text The description text to display in help.
    */
    description(text: string): ArgumentalApp;
    /**
    * Sets the required flag on an option.
    * @param value The required flag value (defaults to true).
    */
    required(value?: boolean): ArgumentalApp;
    /**
    * Sets the multi flag on an option.
    * @param value The multi flag value (defaults to true).
    */
    multi(value?: boolean): ArgumentalApp;
    /**
    * Sets the default value for an option or an argument.
    * @param value The default value.
    */
    default(value: any): ArgumentalApp;
    /**
    * Sets the immediate flag on an option.
    * @param value The immediate flag value (defaults to true).
    */
    immediate(value?: boolean): ArgumentalApp;
    /**
    * Sets validators for an option or an argument.
    * @param validators A single or an array of validators.
    */
    validate(validators: RegExp | Argumental.Validator | Array<RegExp | Argumental.Validator>): ArgumentalApp;
    /**
    * Alias for <code>validate()</code>.
    */
    sanitize(sanitizers: RegExp | Argumental.Validator | Array<RegExp | Argumental.Validator>): ArgumentalApp;
    /**
    * Mounts an action handler to the current command (or globally).
    * @param handler The action handler to attach.
    */
    action(handler: Argumental.ActionHandler): ArgumentalApp;
    /**
    * Sets validators for an option or an argument.
    * @param validators A single or an array of validators.
    */
    validateDestruct(validators: RegExp | Argumental.ValidatorWithDestructuringParams | Array<RegExp | Argumental.ValidatorWithDestructuringParams>): ArgumentalApp;
    /**
    * Alias for <code>validate()</code>.
    */
    sanitizeDestruct(sanitizers: RegExp | Argumental.ValidatorWithDestructuringParams | Array<RegExp | Argumental.ValidatorWithDestructuringParams>): ArgumentalApp;
    /**
    * Mounts an action handler to the current command (or globally).
    * @param handler The action handler to attach.
    */
    actionDestruct(handler: Argumental.ActionHandlerWithDestructuringParams): ArgumentalApp;
    /**
    * Defines a command. Any following argument, option, alias, or action declaration will be used for this command unless this function is called again.
    * @param name Command name (can contain spaces).
    * @param description The command description to display in help.
    */
    command(name: string): ArgumentalApp;
    command(name: string, description: string): ArgumentalApp;
    /**
    * Defines an alias for the current command.
    * @param name The alias name.
    */
    alias(name: string): ArgumentalApp;
    /**
    * Defines an argument for the current command (or globally).
    * @param syntax The argument syntax (e.g. "&lt;argument&gt;", "[argument]").
    * @param description The argument description to display in help.
    * @param validators A single or an array of validators.
    * @param defaultValue A default value to use for the argument (when argument is optional).
    */
    argument(syntax: string): ArgumentalApp;
    argument(syntax: string, description: string): ArgumentalApp;
    argument(syntax: string, description: string, validators: Argumental.Validator | RegExp | Array<RegExp | Argumental.Validator>): ArgumentalApp;
    argument(syntax: string, description: string, validators: Argumental.Validator | RegExp | Array<RegExp | Argumental.Validator>, defaultValue: any): ArgumentalApp;
    /**
    * Defines an option for the current command (or globally).
    * @param syntax The option syntax (e.g. "--no-color", "-p --port <port_number>", "-l --logs [level]").
    * @param description The option description to display in help.
    * @param required A boolean indicating if option is required.
    * @param validators A single or an array of validators.
    * @param multi A boolean indicating whether this option can be repeated more than once (only practical for options with argument).
    * @param defaultValue A default value to use for the option's argument (if defined).
    * @param immediate Whether to stop parsing other components and run the action handlers when this option is provided (e.g. --help).
    */
    option(syntax: string): ArgumentalApp;
    option(syntax: string, description: string): ArgumentalApp;
    option(syntax: string, description: string, required: boolean): ArgumentalApp;
    option(syntax: string, description: string, required: boolean, validators: Argumental.Validator | RegExp | Array<RegExp | Argumental.Validator>): ArgumentalApp;
    option(syntax: string, description: string, required: boolean, validators: Argumental.Validator | RegExp | Array<RegExp | Argumental.Validator>, multi: boolean): ArgumentalApp;
    option(syntax: string, description: string, required: boolean, validators: Argumental.Validator | RegExp | Array<RegExp | Argumental.Validator>, multi: boolean, defaultValue: any): ArgumentalApp;
    option(syntax: string, description: string, required: boolean, validators: Argumental.Validator | RegExp | Array<RegExp | Argumental.Validator>, multi: boolean, defaultValue: any, immediate: boolean): ArgumentalApp;
    /**
    * Registers an event handler.
    * @param event The event name (case insensitive).
    * @param handler The event handler to register.
    */
    on(event: 'validators:before', handler: Argumental.EventHandler<Argumental.EventData<string>>): ArgumentalApp;
    on(event: Exclude<keyof Argumental.EventDeclarations, 'validators:before'>, handler: Argumental.EventHandler<Argumental.EventData<any>>): ArgumentalApp;
    on(event: string, handler: Argumental.EventHandler): ArgumentalApp;
    /**
    * Emits a custom event within the current context.
    * @param event The event name (case insensitive).
    * @param data The custom event data.
    */
    emit(event: string, data?: any): Promise<void>;
    /**
    * Displays an error message in the console.
    @param message An error message or object.
    */
    error(message: string | Error): void;
    /**
    * Parses the process arguments (argv) and runs the app.
    * @param argv Process arguments to parse.
    */
    parse(argv: string[]): Promise<void>;
}