argumental/dist/types.d.ts

Framework for building CLI apps with Node.js

export declare namespace Argumental {
    /**
    * Action handler with destructuring params.
    * @param params Action handler parameters object.
    */
    type ActionHandlerWithDestructuringParams = (params: ActionHandlerParams) => any | Promise<any>;
    /**
    * Action handler.
    * @param args Parsed arguments for the command.
    * @param opts Parsed options for the command.
    * @param cmd The name of the invoked command.
    * @param suspend Suspends next actions handlers (if any).
    */
    type ActionHandler = (args: List<any>, opts: List<any>, cmd: string, suspend: () => void) => any | Promise<any>;
    interface ActionHandlerParams {
        /** Parsed arguments for the command. */
        args: List<any>;
        /** Parsed options for the command. */
        opts: List<any>;
        /** The name of the invoked command. */
        cmd: string;
        /** Suspends next actions handlers (if any). */
        suspend: () => void;
    }
    /**
    * Argument or option validator.
    * If validation fails, this method should throw an error with a message.
    * This method may return a promise for async execution.
    * This method may change the value by returning a new one (directly or with promise).
    * @param params Validator parameters object.
    */
    type ValidatorWithDestructuringParams = (params: ValidatorParams) => any;
    /**
    * Argument or option validator.
    * If validation fails, this method should throw an error with a message.
    * This method may return a promise for async execution.
    * This method may change the value by returning a new one (directly or with promise).
    * @param value The validation target.
    * @param name The argument or option name.
    * @param arg Boolean indicating if the value is an argument or an option.
    * @param cmd Command name.
    * @param suspend Suspends next validators (if any).
    */
    type Validator = (value: any, name: string, arg: boolean, cmd: string, suspend: () => void) => any;
    interface ValidatorParams {
        /** The validation target. */
        value: any;
        /** The argument or option name. */
        name: string;
        /** Boolean indicating if the value is an argument or an option. */
        arg: boolean;
        /** Command name. */
        cmd: string;
        /** Suspends next validators (if any). */
        suspend: () => void;
    }
    interface CallbackFunction<T> {
        /** Indicates callback parameters type. */
        destructuringParams: boolean;
        /** The callback function. */
        callback: T;
    }
    interface SharedDeclaration {
        /** Shared/global argument declarations. */
        arguments: CommandArgumentDeclaration[];
        /** Shared/global option declarations. */
        options: OptionDeclaration[];
        /** Shared/global action handlers. */
        actions: CallbackFunction<ActionHandler | ActionHandlerWithDestructuringParams>[];
        /** Shared/global event declarations. */
        events: EventDeclarations;
    }
    interface CommandDeclaration {
        /** Command name. */
        name: string;
        /** Command description. */
        description: string;
        /** List of registered command aliases. */
        aliases: string[];
        /** Argument declarations for this command. */
        arguments: CommandArgumentDeclaration[];
        /** Option declarations for this command. */
        options: OptionDeclaration[];
        /** Action handlers of this command. */
        actions: CallbackFunction<ActionHandler | ActionHandlerWithDestructuringParams>[];
        /** Determines whether this command definition is in its original state (used for top command). */
        original?: boolean;
        /** Order number to sort commands with. */
        order: number;
        /** Event declarations for this command. */
        events: EventDeclarations;
    }
    /**
    * Event handler.
    * @param data Event data.
    */
    type EventHandler<T = any> = (data: T) => any | Promise<any>;
    interface EventDeclarations {
        /** Runs before validators, defaults, and action handlers. */
        'validators:before': EventHandler[];
        /** Runs after validators and before defaults and action handlers. */
        'validators:after': EventHandler[];
        /** Runs before defaults and action handlers. */
        'defaults:before': EventHandler[];
        /** Runs after defaults and before action handlers. */
        'defaults:after': EventHandler[];
        /** Runs before action handlers. */
        'actions:before': EventHandler[];
        /** Runs after action handlers. */
        'actions:after': EventHandler[];
    }
    interface EventData<T> {
        /** Parsed arguments for the command at the current stage. */
        args: List<T>;
        /** Parsed options for the command at the current stage. */
        opts: List<T | boolean>;
        /** The name of the invoked command. */
        cmd: string;
    }
    interface OptionDeclaration {
        /** Option's short name. */
        shortName: string;
        /** Option's long name. */
        longName: string;
        /** Option's long name in camel case. */
        apiName: string;
        /** Option description. */
        description: string;
        /** Whether this option is required or not. */
        required: boolean;
        /** Option's argument. */
        argument: ArgumentDeclaration;
        /** Whether this option can be provided more than once. */
        multi: boolean;
        /** Whether to stop parsing other components and run the action handlers when this option is provided (e.g. --help). */
        immediate: boolean;
    }
    interface ArgumentDeclaration {
        /** Argument name. */
        name: string;
        /** Argument name in camel case. */
        apiName: string;
        /** Whether this argument is required or not. */
        required: boolean;
        /** Argument validators. */
        validators: Array<CallbackFunction<Validator | ValidatorWithDestructuringParams> | RegExp>;
        /** Argument's default value (if optional). */
        default: string | number | boolean;
    }
    interface CommandArgumentDeclaration extends ArgumentDeclaration {
        /** Argument description. */
        description: string;
        /** Whether this argument captures all values provided on and after. */
        rest: boolean;
    }
    interface List<T> {
        [key: string]: T;
    }
    interface ParsedArguments {
        cmd: string;
        /** NOTE: Missing arguments would be null. */
        args: List<string | string[]>;
        /** NOTE: For options with argument, missing options would be undefined,
        options with missing argument value would be null, and string otherwise.
        * For options without argument, missing options would be false, and true otherwise.
        */
        opts: List<boolean | string | string[]>;
    }
    interface Options {
        /** Controls logs colors (default: true). */
        colors?: boolean;
        /** Display help when top-level command was invoked without any arguments or options. */
        topLevelPlainHelp?: boolean;
        /** Custom help renderer function to run instead of the built-in help renderer (default: null). */
        help?: (definitions: List<CommandDeclaration>, cmd: string) => void;
    }
}