termost/dist/index.d.ts

Get the most of your terminal

type CommandName = string;
type ObjectLikeConstraint = Record<string, any>;
type EmptyObject = {};
/**
 * Raw CLI arguments parsed from user inputs.
 */
type ArgumentValues = {
    command: CommandName;
    operands: string[];
    options: Record<string, boolean | number | string>;
};
type PackageMetadata = {
    name: string;
    description: string;
    version: string;
};
type Context<Values extends ObjectLikeConstraint> = Values;
type InstructionParameters<Values extends ObjectLikeConstraint, ExtraParameters extends ObjectLikeConstraint = EmptyObject> = ExtraParameters & {
    skip?: (context: Context<Values>, argv: ArgumentValues) => boolean;
};
type InstructionKey<Key> = {
    /**
     * Makes the method output available in the context object.
     * By default, if no provided key, the output is not included in the context.
     */
    key: Key;
};
type Label<Values extends ObjectLikeConstraint> = string | ((context: Context<Values>, argv: ArgumentValues) => string);

type TaskParameters<Values extends ObjectLikeConstraint, Key extends keyof Values | undefined = undefined> = InstructionParameters<Values, Partial<InstructionKey<Key>> & {
    label?: Label<Values>;
    handler: (context: Context<Values>, argv: ArgumentValues) => Key extends keyof Values ? Promise<Values[Key]> | Values[Key] : Promise<void> | void;
}>;

type CommandParameters = {
    name: string;
    description: string;
};

type OptionParameters<Values extends ObjectLikeConstraint, Key extends keyof Values> = InstructionParameters<Values, InstructionKey<Key> & {
    name: string | {
        long: string;
        short: string;
    };
    description: string;
    defaultValue?: Values[Key];
}>;

type InputParameters<Values extends ObjectLikeConstraint, Key extends keyof Values> = InstructionParameters<Values, InstructionKey<Key> & ({
    label: Label<Values>;
    defaultValue?: Values[Key] extends boolean ? Values[Key] : never;
    type: "confirm";
} | {
    label: Label<Values>;
    defaultValue?: Values[Key] extends string ? Values[Key] : never;
    options: Values[Key] extends string ? Values[Key][] : never;
    type: "select";
} | {
    label: Label<Values>;
    defaultValue?: Values[Key] extends string ? Values[Key] : never;
    type: "text";
} | {
    label: Label<Values>;
    defaultValue?: Values[Key] extends string[] ? Values[Key] : never;
    options: Values[Key] extends string[] ? Values[Key] : never;
    type: "multiselect";
})>;

/**
 * The termost fluent interface API.
 */
type Termost<Values extends ObjectLikeConstraint = EmptyObject> = {
    /**
     * Allows to attach a new sub-command to the program.
     * @param name - The CLI command name.
     * @param description - The CLI command description.
     * @returns The Command API.
     */
    command: <CommandValues extends ObjectLikeConstraint = EmptyObject>(parameters: CommandParameters) => Termost<CommandValues & Values>;
    input: <Key extends keyof Values>(parameters: InputParameters<Values, Key>) => Termost<Values>;
    option: <Key extends keyof Values>(parameters: OptionParameters<Values, Key>) => Termost<Values>;
    task: <Key extends keyof Values | undefined = undefined>(parameters: TaskParameters<Values, Key>) => Termost<Values>;
};
declare function termost<Values extends ObjectLikeConstraint = EmptyObject>({ name, description, onException, onShutdown, version, }: PackageMetadata & TerminationCallbacks): Termost<Values>;
type TerminationCallbacks = Partial<{
    onException: ((error: Error) => void) | undefined;
    onShutdown: (() => void) | undefined;
}>;

declare const helpers: {
    exec: (command: string, options?: {
        cwd?: string;
        hasLiveOutput?: boolean;
    }) => Promise<string>;
    format: (message: string, options?: {
        color?: "black" | "blue" | "cyan" | "green" | "grey" | "magenta" | "red" | "white" | "yellow";
        modifiers?: ("bold" | "italic" | "lowercase" | "strikethrough" | "underline" | "uppercase")[];
    }) => string;
    message: (content: Error | string, { label: optionLabel, lineBreak: optionlineBreak, type: optionType, }?: {
        label?: string | false;
        lineBreak?: {
            end: boolean;
            start: boolean;
        } | boolean;
        type?: "error" | "information" | "success" | "warning";
    }) => void;
};

export { type Termost, helpers, termost };