argzod/dist/index.d.mts

Minimalistic typescript-first CLI parser powerd with Zod

import { z, ZodError } from 'zod';

type BaseOptionDef = {
    description?: string;
    name: Array<string> | string;
    schema?: z.ZodType<any>;
};
type BooleanOptionDef = BaseOptionDef & {
    parse: (typeof OptionParseType)['Boolean'];
};
type SingleOptionDef = BaseOptionDef & {
    parse: (typeof OptionParseType)['Single'];
};
type ManyOptionDef = BaseOptionDef & {
    parse: (typeof OptionParseType)['Many'];
    maxValues?: number;
};
type OptionDef = BooleanOptionDef | SingleOptionDef | ManyOptionDef;

type ParsedOption = {
    type: (typeof EntryType)['Option'];
    variant: OptionVariant;
    name: string;
    value: string[];
    fullName: string;
    valueStyle?: OptionValueStyle;
    original: string;
    bunled?: {
        fullName: string;
        opts: string[];
    };
};
type OptionParsedReturnType = {
    [OptionParseType.Boolean]: boolean;
    [OptionParseType.Single]: string | undefined;
    [OptionParseType.Many]: string[];
};
type OptionValidationInput<T extends keyof OptionParsedReturnType | undefined = undefined> = T extends string ? OptionParsedReturnType[T] : ObjectValues<OptionParsedReturnType>;
type ValidatedOption = {
    value: OptionValidationInput;
    options: ParsedOption[];
    definition: OptionDef;
};
type ParsedPositionalArgument = {
    type: (typeof EntryType)['Argument'];
    value: string;
};
type ParsedEntry = ParsedOption | ParsedPositionalArgument;
type ArgumentDefinition = {
    description?: string;
    schema: z.ZodType<any>;
};

type CommandName<T extends string = string> = undefined | T;
type ActionFn<TArgs extends Array<any> = Array<any>, TOpts extends Record<string, any> = Record<string, any>> = (actionData: ActionData<TArgs, TOpts>) => void;
type ActionData<TArgs extends Array<any> = Array<any>, TOpts extends Record<string, any> = Record<string, any>> = {
    options: TOpts;
    args: TArgs;
    parsedEntries: ParsedEntry[];
    unknownOptions: ParsedOption[];
};
type CommandOptions = Record<string, OptionDef> & Partial<{
    help: OptionDef;
}>;
type CommandArguments = Array<ArgumentDefinition>;
type CommandDefinition<TName extends CommandName = CommandName<string>, TArgs extends CommandArguments = never[], TOpts extends CommandOptions = Record<string, never>> = {
    name?: TName;
    description?: string;
    args?: TArgs;
    options?: TOpts;
    action: ActionFn<InferCommandArguments<TArgs>, InferCommandOptions<TOpts>>;
};

type InferCommandArguments<TArgs extends CommandArguments> = {
    [K in keyof TArgs]: z.infer<TArgs[K]['schema']>;
};
type InferCommandOptions<TOpts extends CommandOptions> = {
    [K in keyof TOpts]: TOpts[K]['schema'] extends z.ZodType<any> ? z.infer<TOpts[K]['schema']> : OptionParsedReturnType[TOpts[K]['parse']];
};
type ObjectValues<T extends Record<string, any>> = T[keyof T];

declare const OptionVariant: {
    readonly Long: "long";
    readonly Short: "short";
};
type OptionVariant = ObjectValues<typeof OptionVariant>;
declare const EntryType: {
    readonly Argument: "argument";
    readonly Option: "option";
};
type EntryType = ObjectValues<typeof EntryType>;
declare const OptionValueStyle: {
    readonly Inline: "inline";
    readonly SpaceSeparated: "space";
    readonly Attached: "attached";
};
type OptionValueStyle = ObjectValues<typeof OptionValueStyle>;
declare const ErrorLevel: {
    readonly Error: "error";
    readonly Warn: "warn";
    readonly Ignore: "ignore";
};
type ErrorLevel = ObjectValues<typeof ErrorLevel>;
declare const OptionParseType: {
    readonly Boolean: "boolean";
    readonly Single: "single";
    readonly Many: "many";
};
type OptionParseType = ObjectValues<typeof OptionParseType>;

declare const errorMessageMap: {
    "zod-parse": (error: ZodError) => string;
    "command-not-found": (commandName?: string) => string;
    "unknown-option": string;
    "invalid-opt-value": ({ shouldBe }: {
        shouldBe: OptionParseType;
    }) => "Expected no values but got values" | "Expected single value but got multiple or no values" | "Expected multiple values but got single or no values";
    "option-not-defined": string;
    internal: string;
    "invalid-args": string;
    "invalid-definitions": string;
};

type MessageMap = Partial<typeof errorMessageMap>;
type GroupedErrors = Record<ErrorLevel, ArgzodError[]>;

declare const ErrorCode: {
    readonly Internal: "internal";
    readonly Validation: "zod-parse";
    readonly InvalidOption: "unknown-option";
    readonly OptionNotDefined: "option-not-defined";
    readonly InvalidArguments: "invalid-args";
    readonly CommandNotFound: "command-not-found";
    readonly InvalidDefinitions: "invalid-definitions";
    readonly InvalidOptionValue: "invalid-opt-value";
};
type ErrorCode = ObjectValues<typeof ErrorCode>;

declare class ArgzodError<TCode extends ErrorCode = ErrorCode, TMessage extends (typeof errorMessageMap)[NoInfer<TCode>] = (typeof errorMessageMap)[NoInfer<TCode>]> extends Error {
    #private;
    level: ErrorLevel;
    path?: string;
    private ctx;
    constructor(data: TMessage extends (...args: any) => string ? {
        code: TCode;
        ctx: Parameters<TMessage>;
        path?: string;
        level?: ErrorLevel;
    } : {
        code: TCode;
        path?: string;
        level?: ErrorLevel;
    } | TCode);
    get code(): TCode;
    /**
     * Using given message map updates error message if finds appropriate code in a map
     * @param messageMap Map of user defined custom messages
     * @returns void
     */
    __applyMessageMap(messageMap?: MessageMap): void;
    __setPath(path: string): void;
}

type ProgramConfig = {
    name: string;
    description?: string;
    messages?: MessageMap;
    onError?: (errors: GroupedErrors) => void;
    undefinedOptionsBehavior?: ErrorLevel;
};

declare const createProgram: (config?: ProgramConfig) => Program<string>;

declare class Program<T extends string = string> {
    _id: string;
    private commands;
    private config;
    private errors;
    constructor(config?: ProgramConfig);
    run(args?: string[]): void;
    command<const TArgs extends CommandArguments, const TOpts extends CommandOptions>(options: CommandDefinition<T, TArgs, TOpts>): Command;
    attachCommand(command: Command): this;
    private matchCommand;
    private logHelp;
    private logErrors;
    _registerError(error: ArgzodError): void;
    _registerError(error: ArgzodError, exit: 'exit'): never;
    _registerError<T>(operation: () => T): T | void;
    _registerError<T>(operation: () => T, exit: 'exit'): T;
    _errorExit(): void;
    private cleanUp;
}

declare const createCommand: <const TArgs extends CommandArguments = CommandArguments, const TOpts extends CommandOptions = CommandOptions>(options: CommandDefinition<string, TArgs, TOpts> & {
    program: Program;
}) => Command;

declare class Command {
    program: Program;
    name: CommandName<string>;
    description?: string;
    action: (arg: ActionData<InferCommandArguments<CommandArguments>, InferCommandOptions<CommandOptions>>) => void;
    options: CommandOptions;
    args: CommandArguments;
    constructor(opts: CommandDefinition<string, CommandArguments, CommandOptions> & {
        program: Program;
    });
    process(entries: string[]): {
        entries: string[];
        parsedEntries: ParsedEntry[];
        resolvedEntries: ParsedEntry[];
        validatedOptions: {
            validated: Record<string, ValidatedOption>;
            unknown: ParsedOption[];
        };
        validatedArgs: unknown[];
    };
    private attachBuiltIns;
}

type argzod_ArgumentDefinition = ArgumentDefinition;
type argzod_ArgzodError<TCode extends ErrorCode = ErrorCode, TMessage extends (typeof errorMessageMap)[NoInfer<TCode>] = (typeof errorMessageMap)[NoInfer<TCode>]> = ArgzodError<TCode, TMessage>;
declare const argzod_ArgzodError: typeof ArgzodError;
type argzod_BooleanOptionDef = BooleanOptionDef;
type argzod_Command = Command;
declare const argzod_Command: typeof Command;
type argzod_EntryType = EntryType;
type argzod_ErrorCode = ErrorCode;
type argzod_ErrorLevel = ErrorLevel;
type argzod_ManyOptionDef = ManyOptionDef;
type argzod_OptionDef = OptionDef;
type argzod_OptionParseType = OptionParseType;
type argzod_OptionParsedReturnType = OptionParsedReturnType;
type argzod_OptionValidationInput<T extends keyof OptionParsedReturnType | undefined = undefined> = OptionValidationInput<T>;
type argzod_OptionValueStyle = OptionValueStyle;
type argzod_OptionVariant = OptionVariant;
type argzod_ParsedEntry = ParsedEntry;
type argzod_ParsedOption = ParsedOption;
type argzod_ParsedPositionalArgument = ParsedPositionalArgument;
type argzod_Program<T extends string = string> = Program<T>;
declare const argzod_Program: typeof Program;
type argzod_ProgramConfig = ProgramConfig;
type argzod_SingleOptionDef = SingleOptionDef;
type argzod_ValidatedOption = ValidatedOption;
declare const argzod_createCommand: typeof createCommand;
declare const argzod_createProgram: typeof createProgram;
declare namespace argzod {
  export { type argzod_ArgumentDefinition as ArgumentDefinition, argzod_ArgzodError as ArgzodError, type argzod_BooleanOptionDef as BooleanOptionDef, argzod_Command as Command, type argzod_EntryType as EntryType, type argzod_ErrorCode as ErrorCode, type argzod_ErrorLevel as ErrorLevel, type argzod_ManyOptionDef as ManyOptionDef, type argzod_OptionDef as OptionDef, type argzod_OptionParseType as OptionParseType, type argzod_OptionParsedReturnType as OptionParsedReturnType, type argzod_OptionValidationInput as OptionValidationInput, type argzod_OptionValueStyle as OptionValueStyle, type argzod_OptionVariant as OptionVariant, type argzod_ParsedEntry as ParsedEntry, type argzod_ParsedOption as ParsedOption, type argzod_ParsedPositionalArgument as ParsedPositionalArgument, argzod_Program as Program, type argzod_ProgramConfig as ProgramConfig, type argzod_SingleOptionDef as SingleOptionDef, type argzod_ValidatedOption as ValidatedOption, argzod_createCommand as createCommand, argzod_createProgram as createProgram };
}

export { type ArgumentDefinition, ArgzodError, type BooleanOptionDef, Command, EntryType, ErrorCode, ErrorLevel, type ManyOptionDef, type OptionDef, OptionParseType, type OptionParsedReturnType, type OptionValidationInput, OptionValueStyle, OptionVariant, type ParsedEntry, type ParsedOption, type ParsedPositionalArgument, Program, type ProgramConfig, type SingleOptionDef, type ValidatedOption, argzod, createCommand, createProgram, argzod as default };