@cirrusct/cli/src/types.ts

export type CliParsedCommandHandler = (parsed: ParsedCliCommand) => Promise<void | number> | void | number;
export type CliCommandHandler = <TOptions extends {} = {}, TArgs extends {} = {}>(
    args: TArgs,
    options: TOptions
) => Promise<void | number> | void | number;

export type CliValueType = 'boolean' | 'string' | 'number';
export type CliValue = boolean | string | number | undefined;

import { CliCommandDefinitionParameterPromptQuestion, CliPromptHandler } from './prompt';

export interface CliOptions {
    globalHandler?: CliParsedCommandHandler;
    showPrompts?: boolean;
}

export interface CliBaseCommandDefinition<TCliOptions extends {} = {}, TTransformedOptions extends {} = TCliOptions> {
    name: string;
    // syntax?: string;
    description?: string;
    options?: CliCommandDefinitionOption[];
    examples?: string[];
    transformOptions?: (options: TCliOptions) => TTransformedOptions;
}

export interface CliProgramDefinition extends CliBaseCommandDefinition {
    defaultCommandName?: string;
    commands?: CliCommandDefinition[];
}

export interface CliCommandDefinition<
    TCliOptions extends {} = {},
    TTransformedOptions extends {} = TCliOptions,
    TCliArgs extends {} = {},
    TTransformedArgs extends {} = TCliArgs
> extends CliBaseCommandDefinition<TCliOptions, TTransformedOptions> {
    arguments?: CliCommandDefinitionArgument[];
    handler?: CliCommandHandler;
    env?: { [name: string]: string };
    transformArguments?: (options: TCliArgs) => TTransformedArgs;
}

export type CliValueValidatorFunction = (value: CliValue) => boolean | string;

export interface CliCommandDefinitionParameter {
    name: string;
    description?: string;
    valueType?: CliValueType;
    default?: CliValue;
    transform?: (value: CliValue) => CliValue;
    validate?: CliValueValidatorFunction | RegExp;
    prompt?: CliCommandDefinitionParameterPromptQuestion;
}

export interface CliCommandDefinitionArgument extends CliCommandDefinitionParameter {
    isOptional?: boolean;
    isVariadic?: boolean;
}

export interface CliCommandDefinitionOption extends CliCommandDefinitionParameter {
    syntax?: string;
    flag?: string;
    commandHandler?: CliParsedCommandHandler;
}

export interface CliParsedCommandDefinitionArgument extends CliCommandDefinitionArgument {
    wasPassed: boolean;
    value: CliValue | CliValue[];
}

export interface CliParsedCommandDefinitionOption extends CliCommandDefinitionOption {
    wasPassed: boolean;
    value: CliValue;
}

export type ParserErrorType = 'command' | 'argument' | 'option';

export interface ParserErrors {
    commandErrors: string[];
    argumentErrors: string[];
    optionErrors: string[];
    allErrors: string[];
    hasErrors: boolean;
}

export interface ParsedCliCommand<TOptions extends {} = {}, TArgs extends {} = {}> {
    program: CliProgramDefinition;
    command: CliCommandDefinition;
    optionDefinitions: { [name: string]: CliCommandDefinitionOption };
    parsedOptions: { [name: string]: CliParsedCommandDefinitionOption };
    parsedArguments: { [name: string]: CliParsedCommandDefinitionArgument };
    parsedCommandName: string;
    arguments: TArgs;
    options: TOptions;
    passedArguments: string[];
    passedOptions: string[];
    errors: ParserErrors;
    version: string | undefined;
    env: { [name: string]: string };
    run: () => Promise<CliRunResult<TOptions, TArgs>>;
}

export interface CliRunResult<TOptions extends {} = {}, TArgs extends {} = {}> {
    parsedCommand: ParsedCliCommand<TOptions, TArgs>;
    exitCode: number | undefined;
}

export interface MriOpts {
    // An object of keys whose values are Strings or Array<String> of aliases. These will be added to the parsed output with matching values.
    alias?: { [name: string]: string | string[] };
    // Callback that is run when a parsed flag has not been defined as a known key or alias. Its only parameter is the unknown flag
    unknown?: (flag: string) => any;
    // An key:value object of defaults. If a default is provided for a key, its type (typeof) will be used to cast parsed arguments.
    default?: { [name: string]: string | boolean | number };
    // A single key (or array of keys) that should be parsed as Strings.
    string?: string | string[];
    // A single key (or array of keys) that should be parsed as Booleans.
    boolean?: string | string[];
    lazy?: boolean;
}