convoker 0.2.0 → 0.3.2

package/dist/error.d.ts

@@ -1,844 +1,107 @@
-/**
- * Command action function.
- */
-declare type ActionFn<T extends Input> = (input: InferInput<T>) => void | Promise<void>;
-
-/**
- * A basic input type.
- */
-declare type BasicKind = "boolean" | "string" | "number" | "bigint";
-
-/**
- * A basic input type.
- */
-declare type BasicKind_2 = "boolean" | "string" | "number" | "bigint";
-
-/**
- * Builder for commands.
- */
-declare type Builder = (c: Command<any>) => Command<any> | void;
-
-/**
- * A command.
- */
-declare class Command<T extends Input = Input> {
-    /**
-     * The names (aliases) of this command.
-     */
-    $names: string[];
-    /**
-     * The description of this command.
-     */
-    $description: string | undefined;
-    /**
-     * The theme of this command
-     */
-    $theme: Theme | undefined;
-    /**
-     * The version of this command.
-     */
-    $version: string | undefined;
-    /**
-     * The children of this command.
-     */
-    $children: Map<string, CommandAlias>;
-    /**
-     * The parent of this command.
-     */
-    $parent: Command<any> | undefined;
-    /**
-     * If this command allows unknown options.
-     */
-    $allowUnknownOptions: boolean;
-    /**
-     * If you should be able to surpass the amount of positional arguments defined in the input.
-     */
-    $allowSurpassArgLimit: boolean;
-    /**
-     * The input this command takes.
-     */
-    $input: T;
-    /**
-     * The action function of this command.
-     */
-    $fn: ActionFn<T> | undefined;
-    /**
-     * The error handler of this command.
-     */
-    $errorFn: ErrorFn<T> | undefined;
-    /**
-     * Creates a new command.
-     * @param names The names (aliases).
-     * @param desc The description.
-     * @param version The version.
-     */
-    constructor(names: string | string[], desc?: string, version?: string);
-    /**
-     * Adds a set of aliases to this command.
-     * @param aliases The aliases to add.
-     * @returns this
-     */
-    alias(...aliases: string[]): this;
-    /**
-     * Adds a description to this command.
-     * @param desc The description.
-     * @returns this
-     */
-    description(desc: string): this;
-    /**
-     * Adds a version to this command.
-     * @param version The version.
-     * @returns this
-     */
-    version(version: string): this;
-    /**
-     * Sets the input for this command.
-     * @param version The input.
-     * @returns this
-     */
-    input<TInput extends Input>(input: TInput): Command<TInput>;
-    /**
-     * Sets the action function for this command.
-     * @param fn The action.
-     * @returns this
-     */
-    action(fn: ActionFn<T>): this;
-    /**
-     * Sets the error function for this command.
-     * @param fn The error handler.
-     * @returns this
-     */
-    error(fn: ErrorFn<T>): this;
-    /**
-     * Adds an existing command to this.
-     * @param command The command.
-     * @returns this
-     */
-    add(command: Command<any>): this;
-    /**
-     * Creates a new subcommand and adds it.
-     * @param names The aliases of the subcommand.
-     * @param builder A builder to create the command.
-     */
-    subCommand(names: string | string[], builder: Builder): this;
-    /**
-     * Creates a new subcommand and adds it.
-     * @param names The aliases of the subcommand.
-     * @param desc The description of the subcommand.
-     * @param version The version of the subcommand.
-     */
-    subCommand(names: string | string[], desc?: string, version?: string): Command<any>;
-    /**
-     * Allows unknown options.
-     * @returns this
-     */
-    allowUnknownOptions(): this;
-    /**
-     * Parses a set of command-line arguments.
-     * @param argv The arguments to parse.
-     * @returns A parse result.
-     */
-    parse(argv: string[]): Promise<ParseResult<T>>;
-    private buildInputMap;
-    /**
-     * Gets the full command path (name including parents).
-     * @returns The full command path.
-     */
-    fullCommandPath(): string;
-    /**
-     * The default error screen.
-     * @param errors The errors.
-     */
-    defaultErrorScreen(errors: Error[]): void;
-    /**
-     * Handles a set of errors.
-     * @param errors The errors to handle.
-     * @param input The parsed input, if possible.
-     * @returns this
-     */
-    handleErrors(errors: Error[], input?: Partial<InferInput<T>>): Promise<this>;
-    /**
-     * Runs a command.
-     * @param argv The arguments to run the command with. Defaults to your runtime's `argv` equivalent.
-     * @returns this
-     */
-    run(argv?: string[]): Promise<this>;
-}
-
-/**
- * What the command is an alias for.
- */
-declare interface CommandAlias<T extends Input = Input> {
-    /**
-     * A pointer to the command.
-     */
-    command: Command<T>;
-    /**
-     * The name of the command this is an alias for.
-     */
-    alias?: string;
-}
-
-/**
- * A Convoker-related error. These are usually handled by default.
- */
-export declare class ConvokerError extends Error {
-    /**
-     * The command this error happened on.
-     */
-    command: Command<any>;
-    /**
-     * Creates a new Convoker error.
-     * @param message The message.
-     * @param command The command.
-     */
-    constructor(message: string, command: Command<any>);
-    /**
-     * Prints the error's message.
-     */
-    print(): void;
-}
-
-/**
- * A Convoker-related error. These are usually handled by default.
- */
-declare class ConvokerError_2 extends Error {
-    /**
-     * The command this error happened on.
-     */
-    command: Command<any>;
-    /**
-     * Creates a new Convoker error.
-     * @param message The message.
-     * @param command The command.
-     */
-    constructor(message: string, command: Command<any>);
-    /**
-     * Prints the error's message.
-     */
-    print(): void;
-}
-
-/**
- * Command error handler.
- */
-declare type ErrorFn<T extends Input> = (command: Command<T>, errors: Error[], input: Partial<InferInput<T>>) => void | Promise<void>;
-
-/**
- * When the user asks for help.
- */
-export declare class HelpAskedError extends ConvokerError {
-    /**
-     * Creates a new help asked error.
-     * @param command The command.
-     */
-    constructor(command: Command<any>);
-}
-
-/**
- * Infers a TypeScript type from an option or positional.
- */
-declare type InferEntry<T> = T extends {
-    $kind: infer TKind extends Kind;
-    $required: infer Required;
-    $list: infer List;
-} ? List extends true ? Required extends true ? TypeOf<TKind>[] : TypeOf<TKind>[] | undefined : Required extends true ? TypeOf<TKind> : TypeOf<TKind> | undefined : never;
-
-/**
- * Infers TypeScript types from an input object.
- */
-declare type InferInput<T extends Input> = {
-    [K in keyof T]: InferEntry<T[K]>;
-};
-
-/**
- * An input object.
- */
-declare interface Input {
-    [x: string]: Option_2<any, any, any> | Positional<any, any, any>;
-}
-
-/**
- * Thrown when the command fails to validate an input.
- */
-export declare class InputValidationError extends Error {
-    /**
-     * A list of messages.
-     */
-    messages: string[];
-    /**
-     * Creates a new input validation error.
-     * @param messages The messages.
-     */
-    constructor(messages: string[]);
-}
-
-/**
- * An input type.
- */
-declare type Kind = BasicKind | StandardSchemaV1<any, any>;
-
-/**
- * An input type.
- */
-declare type Kind_2 = BasicKind_2 | StandardSchemaV1_2<any, any>;
-
-export declare class MissingRequiredArgumentError extends ConvokerError {
-    /**
-     * The argument key.
-     */
-    key: string;
-    /**
-     * The argument entry.
-     */
-    entry: Positional_2<any, any, any>;
-    /**
-     * Creates a new missing required argument error.
-     * @param command The command.
-     * @param key The key.
-     * @param entry The entry.
-     */
-    constructor(command: Command<any>, key: string, entry: Positional_2<any, any, any>);
-}
-
-/**
- * When a required option is missing.
- */
-export declare class MissingRequiredOptionError extends ConvokerError {
-    /**
-     * The option key.
-     */
-    key: string;
-    /**
-     * The option entry.
-     */
-    entry: Option_2_2<any, any, any>;
-    /**
-     * Creates a new missing required option error.
-     * @param command The command.
-     * @param key The key.
-     * @param entry The entry.
-     */
-    constructor(command: Command<any>, key: string, entry: Option_2_2<any, any, any>);
-}
-
-/**
- * An option.
- */
-declare class Option_2<TKind extends Kind, TRequired extends boolean = true, TList extends boolean = false> {
-    /**
-     * The kind of this option.
-     */
-    $kind: TKind;
-    /**
-     * The aliases of this option.
-     */
-    $names: string[];
-    /**
-     * The description of this option.
-     */
-    $description: string | undefined;
-    /**
-     * The default value of this option.
-     */
-    $default: TypeOf<TKind> | undefined;
-    /**
-     * If this option is required.
-     */
-    $required: TRequired;
-    /**
-     * If this option is a list.
-     */
-    $list: TList;
-    /**
-     * A separator if this option is a list.
-     */
-    $separator: string | undefined;
-    /**
-     * Creates a new option.
-     * @param kind The type of this option.
-     * @param names The names of this option.
-     */
-    constructor(kind: TKind, names: string[]);
-    /**
-     * Makes this option a list.
-     * @returns this
-     */
-    list(separator?: string): Option_2<TKind, TRequired, true>;
-    /**
-     * Makes this option required.
-     * @returns this
-     */
-    required(): Option_2<TKind, true, TList>;
-    /**
-     * Makes this option optional.
-     * @returns this
-     */
-    optional(): Option_2<TKind, false, TList>;
-    /**
-     * Sets a default value.
-     * @param value The default value.
-     * @returns this
-     */
-    default(value: TypeOf<TKind>): this;
-    /**
-     * Sets a description.
-     * @param desc The description.
-     * @returns this
-     */
-    description(desc: string): this;
-}
-
-/**
- * An option.
- */
-declare class Option_2_2<TKind extends Kind_2, TRequired extends boolean = true, TList extends boolean = false> {
-    /**
-     * The kind of this option.
-     */
-    $kind: TKind;
-    /**
-     * The aliases of this option.
-     */
-    $names: string[];
-    /**
-     * The description of this option.
-     */
-    $description: string | undefined;
-    /**
-     * The default value of this option.
-     */
-    $default: TypeOf_2<TKind> | undefined;
-    /**
-     * If this option is required.
-     */
-    $required: TRequired;
-    /**
-     * If this option is a list.
-     */
-    $list: TList;
-    /**
-     * A separator if this option is a list.
-     */
-    $separator: string | undefined;
-    /**
-     * Creates a new option.
-     * @param kind The type of this option.
-     * @param names The names of this option.
-     */
-    constructor(kind: TKind, names: string[]);
-    /**
-     * Makes this option a list.
-     * @returns this
-     */
-    list(separator?: string): Option_2_2<TKind, TRequired, true>;
-    /**
-     * Makes this option required.
-     * @returns this
-     */
-    required(): Option_2_2<TKind, true, TList>;
-    /**
-     * Makes this option optional.
-     * @returns this
-     */
-    optional(): Option_2_2<TKind, false, TList>;
-    /**
-     * Sets a default value.
-     * @param value The default value.
-     * @returns this
-     */
-    default(value: TypeOf_2<TKind>): this;
-    /**
-     * Sets a description.
-     * @param desc The description.
-     * @returns this
-     */
-    description(desc: string): this;
-}
-
-/**
- * The result of the `Command.parse` function.
- */
-declare interface ParseResult<T extends Input> {
-    /**
-     * A pointer to the command to run.
-     */
-    command: Command<T>;
-    /**
-     * The input to pass into the command.
-     */
-    input: InferInput<T>;
-    /**
-     * Errors collected during parsing.
-     */
-    errors: ConvokerError_2[];
-    /**
-     * If this should result in displaying the version of the command.
-     */
-    isVersion: boolean;
-    /**
-     * If this should result in displaying a help screen.
-     */
-    isHelp: boolean;
-}
-
-/**
- * A positional argument.
- */
-declare class Positional<TKind extends Kind, TRequired extends boolean = true, TList extends boolean = false> {
-    /**
-     * The type of this argument.
-     */
-    $kind: TKind;
-    /**
-     * The default value of this argument.
-     */
-    $default: TypeOf<TKind> | undefined;
-    /**
-     * The description of this argument.
-     */
-    $description: string | undefined;
-    /**
-     * If this argument is required.
-     */
-    $required: TRequired;
-    /**
-     * If this argument is a list.
-     */
-    $list: TList;
-    /**
-     * Creates a new positional argument.
-     * @param kind The positional argument.
-     */
-    constructor(kind: TKind);
-    /**
-     * Makes this argument a list.
-     * @returns this
-     */
-    list(): Positional<TKind, TRequired, true>;
-    /**
-     * Makes this argument required.
-     * @returns this
-     */
-    required(): Positional<TKind, true, TList>;
-    /**
-     * Makes this argument optional.
-     * @returns this
-     */
-    optional(): Positional<TKind, false, TList>;
-    /**
-     * Sets a default value.
-     * @param value The default value.
-     * @returns this
-     */
-    default(value: TypeOf<TKind>): this;
-    /**
-     * Sets a description.
-     * @param desc The description.
-     * @returns this
-     */
-    description(desc: string): this;
-}
-
-/**
- * A positional argument.
- */
-declare class Positional_2<TKind extends Kind_2, TRequired extends boolean = true, TList extends boolean = false> {
-    /**
-     * The type of this argument.
-     */
-    $kind: TKind;
-    /**
-     * The default value of this argument.
-     */
-    $default: TypeOf_2<TKind> | undefined;
-    /**
-     * The description of this argument.
-     */
-    $description: string | undefined;
-    /**
-     * If this argument is required.
-     */
-    $required: TRequired;
-    /**
-     * If this argument is a list.
-     */
-    $list: TList;
-    /**
-     * Creates a new positional argument.
-     * @param kind The positional argument.
-     */
-    constructor(kind: TKind);
-    /**
-     * Makes this argument a list.
-     * @returns this
-     */
-    list(): Positional_2<TKind, TRequired, true>;
-    /**
-     * Makes this argument required.
-     * @returns this
-     */
-    required(): Positional_2<TKind, true, TList>;
-    /**
-     * Makes this argument optional.
-     * @returns this
-     */
-    optional(): Positional_2<TKind, false, TList>;
-    /**
-     * Sets a default value.
-     * @param value The default value.
-     * @returns this
-     */
-    default(value: TypeOf_2<TKind>): this;
-    /**
-     * Sets a description.
-     * @param desc The description.
-     * @returns this
-     */
-    description(desc: string): this;
-}
-
-/** The Standard Schema interface. */
-declare interface StandardSchemaV1<Input = unknown, Output = Input> {
-    /** The Standard Schema properties. */
-    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
-}
-
-declare namespace StandardSchemaV1 {
-    /** The Standard Schema properties interface. */
-    interface Props<Input = unknown, Output = Input> {
-        /** The version number of the standard. */
-        readonly version: 1;
-        /** The vendor name of the schema library. */
-        readonly vendor: string;
-        /** Validates unknown input values. */
-        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
-        /** Inferred types associated with the schema. */
-        readonly types?: Types<Input, Output> | undefined;
-    }
-    /** The result interface of the validate function. */
-    type Result<Output> = SuccessResult<Output> | FailureResult;
-    /** The result interface if validation succeeds. */
-    interface SuccessResult<Output> {
-        /** The typed output value. */
-        readonly value: Output;
-        /** The non-existent issues. */
-        readonly issues?: undefined;
-    }
-    /** The result interface if validation fails. */
-    interface FailureResult {
-        /** The issues of failed validation. */
-        readonly issues: ReadonlyArray<Issue>;
-    }
-    /** The issue interface of the failure output. */
-    interface Issue {
-        /** The error message of the issue. */
-        readonly message: string;
-        /** The path of the issue, if any. */
-        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
-    }
-    /** The path segment interface of the issue. */
-    interface PathSegment {
-        /** The key representing a path segment. */
-        readonly key: PropertyKey;
-    }
-    /** The Standard Schema types interface. */
-    interface Types<Input = unknown, Output = Input> {
-        /** The input type of the schema. */
-        readonly input: Input;
-        /** The output type of the schema. */
-        readonly output: Output;
-    }
-    /** Infers the input type of a Standard Schema. */
-    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
-    /** Infers the output type of a Standard Schema. */
-    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
-}
-
-/** The Standard Schema interface. */
-declare interface StandardSchemaV1_2<Input = unknown, Output = Input> {
-    /** The Standard Schema properties. */
-    readonly "~standard": StandardSchemaV1_2.Props<Input, Output>;
-}
-
-declare namespace StandardSchemaV1_2 {
-    /** The Standard Schema properties interface. */
-    interface Props<Input = unknown, Output = Input> {
-        /** The version number of the standard. */
-        readonly version: 1;
-        /** The vendor name of the schema library. */
-        readonly vendor: string;
-        /** Validates unknown input values. */
-        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
-        /** Inferred types associated with the schema. */
-        readonly types?: Types<Input, Output> | undefined;
-    }
-    /** The result interface of the validate function. */
-    type Result<Output> = SuccessResult<Output> | FailureResult;
-    /** The result interface if validation succeeds. */
-    interface SuccessResult<Output> {
-        /** The typed output value. */
-        readonly value: Output;
-        /** The non-existent issues. */
-        readonly issues?: undefined;
-    }
-    /** The result interface if validation fails. */
-    interface FailureResult {
-        /** The issues of failed validation. */
-        readonly issues: ReadonlyArray<Issue>;
-    }
-    /** The issue interface of the failure output. */
-    interface Issue {
-        /** The error message of the issue. */
-        readonly message: string;
-        /** The path of the issue, if any. */
-        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
-    }
-    /** The path segment interface of the issue. */
-    interface PathSegment {
-        /** The key representing a path segment. */
-        readonly key: PropertyKey;
-    }
-    /** The Standard Schema types interface. */
-    interface Types<Input = unknown, Output = Input> {
-        /** The input type of the schema. */
-        readonly input: Input;
-        /** The output type of the schema. */
-        readonly output: Output;
-    }
-    /** Infers the input type of a Standard Schema. */
-    type InferInput<Schema extends StandardSchemaV1_2> = NonNullable<Schema["~standard"]["types"]>["input"];
-    /** Infers the output type of a Standard Schema. */
-    type InferOutput<Schema extends StandardSchemaV1_2> = NonNullable<Schema["~standard"]["types"]>["output"];
-}
-
-/**
- * A theme.
- */
-declare interface Theme {
-    /**
-     * Wraps a string in a background ANSI code.
-     * @param a The string to wrap.
-     */
-    background?(a: string): string;
-    /**
-     * Wraps a string in a foreground ANSI code.
-     * @param a The string to wrap.
-     */
-    foreground?(a: string): string;
-    /**
-     * Wraps a string in a primary ANSI code.
-     * @param a The string to wrap.
-     */
-    primary(a: string): string;
-    /**
-     * Wraps a string in a secondary ANSI code.
-     * @param a The string to wrap.
-     */
-    secondary(a: string): string;
-    /**
-     * Wraps a string in a accent ANSI code.
-     * @param a The string to wrap.
-     */
-    accent?(a: string): string;
-    /**
-     * Wraps a string in a success ANSI code.
-     * @param a The string to wrap.
-     */
-    success(a: string): string;
-    /**
-     * Wraps a string in a warning ANSI code.
-     * @param a The string to wrap.
-     */
-    warning(a: string): string;
-    /**
-     * Wraps a string in a error ANSI code.
-     * @param a The string to wrap.
-     */
-    error(a: string): string;
-    /**
-     * Wraps a string in a info ANSI code.
-     * @param a The string to wrap.
-     */
-    info?(a: string): string;
-    /**
-     * Set of symbols for logging.
-     */
-    symbols?: {
-        /**
-         * Success message symbol.
-         */
-        success: string;
-        /**
-         * Error message symbol.
-         */
-        error: string;
-        /**
-         * Warning message symbol.
-         */
-        warning: string;
-        /**
-         * Information message symbol.
-         */
-        info?: string;
-    };
-    /**
-     * Optional styles.
-     */
-    styles?: {
-        /**
-         * Wraps a string in a bold ANSI code.
-         * @param a The string to wrap.
-         */
-        bold?(a: string): string;
-        /**
-         * Wraps a string in an italic ANSI code.
-         * @param a The string to wrap.
-         */
-        italic?(a: string): string;
-        /**
-         * Wraps a string in an underline ANSI code.
-         * @param a The string to wrap.
-         */
-        underline?(a: string): string;
-    };
-}
-
-/**
- * When you pass too many arguments.
- */
-export declare class TooManyArgumentsError extends ConvokerError {
-    /**
-     * Creates a new too many arguments error.
-     * @param command The command.
-     */
-    constructor(command: Command<any>);
-}
-
-/**
- * Converts a Kind to a TypeScript type.
- */
-declare type TypeOf<T extends Kind> = T extends StandardSchemaV1<any, infer Out> ? Out : T extends "boolean" ? boolean : T extends "string" ? string : T extends "number" ? number : T extends "bigint" ? bigint : never;
-
-/**
- * Converts a Kind to a TypeScript type.
- */
-declare type TypeOf_2<T extends Kind_2> = T extends StandardSchemaV1_2<any, infer Out> ? Out : T extends "boolean" ? boolean : T extends "string" ? string : T extends "number" ? number : T extends "bigint" ? bigint : never;
-
-/**
- * When you pass an unknown option, when unknown options aren't allowed.
- */
-export declare class UnknownOptionError extends ConvokerError {
-    /**
-     * The option key.
-     */
-    key: string;
-    /**
-     * Creates a new unknown option error.
-     * @param command The command.
-     * @param key The key.
-     */
-    constructor(command: Command<any>, key: string);
-}
-
-export { }
+import type { Command } from "./command";
+import type { Option, Positional } from "./input";
+/**
+ * Thrown when the command fails to validate an input.
+ */
+export declare class InputValidationError extends Error {
+    /**
+     * A list of messages.
+     */
+    messages: string[];
+    /**
+     * Creates a new input validation error.
+     * @param messages The messages.
+     */
+    constructor(messages: string[]);
+}
+/**
+ * A Convoker-related error. These are usually handled by default.
+ */
+export declare class ConvokerError extends Error {
+    /**
+     * The command this error happened on.
+     */
+    command: Command<any>;
+    /**
+     * Creates a new Convoker error.
+     * @param message The message.
+     * @param command The command.
+     */
+    constructor(message: string, command: Command<any>);
+    /**
+     * Prints the error's message.
+     */
+    print(): void;
+}
+/**
+ * When the user asks for help.
+ */
+export declare class HelpAskedError extends ConvokerError {
+    /**
+     * Creates a new help asked error.
+     * @param command The command.
+     */
+    constructor(command: Command<any>);
+}
+/**
+ * When you pass too many arguments.
+ */
+export declare class TooManyArgumentsError extends ConvokerError {
+    /**
+     * Creates a new too many arguments error.
+     * @param command The command.
+     */
+    constructor(command: Command<any>);
+}
+/**
+ * When you pass an unknown option, when unknown options aren't allowed.
+ */
+export declare class UnknownOptionError extends ConvokerError {
+    /**
+     * The option key.
+     */
+    key: string;
+    /**
+     * Creates a new unknown option error.
+     * @param command The command.
+     * @param key The key.
+     */
+    constructor(command: Command<any>, key: string);
+}
+/**
+ * When a required option is missing.
+ */
+export declare class MissingRequiredOptionError extends ConvokerError {
+    /**
+     * The option key.
+     */
+    key: string;
+    /**
+     * The option entry.
+     */
+    entry: Option<any, any, any>;
+    /**
+     * Creates a new missing required option error.
+     * @param command The command.
+     * @param key The key.
+     * @param entry The entry.
+     */
+    constructor(command: Command<any>, key: string, entry: Option<any, any, any>);
+}
+export declare class MissingRequiredArgumentError extends ConvokerError {
+    /**
+     * The argument key.
+     */
+    key: string;
+    /**
+     * The argument entry.
+     */
+    entry: Positional<any, any, any>;
+    /**
+     * Creates a new missing required argument error.
+     * @param command The command.
+     * @param key The key.
+     * @param entry The entry.
+     */
+    constructor(command: Command<any>, key: string, entry: Positional<any, any, any>);
+}