convoker 0.1.0

package/dist/command.d.ts

@@ -0,0 +1,527 @@
+/**
+ * Command action function.
+ */
+export declare type ActionFn<T extends Input> = (input: InferInput<T>) => void | Promise<void>;
+
+/**
+ * A basic input type.
+ */
+declare type BasicKind = "boolean" | "string" | "number" | "bigint";
+
+/**
+ * Builder for commands.
+ */
+export declare type Builder = (c: Command<any>) => Command<any> | void;
+
+/**
+ * A command.
+ */
+export 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;
+    /**
+     * 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.
+ */
+export 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;
+}
+
+/**
+ * Command error handler.
+ */
+export declare type ErrorFn<T extends Input> = (command: Command<T>, errors: Error[], input: Partial<InferInput<T>>) => void | Promise<void>;
+
+/**
+ * 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>;
+}
+
+/**
+ * An input type.
+ */
+declare type Kind = BasicKind | StandardSchemaV1<any, any>;
+
+/**
+ * A LunarCLI-related error. These are usually handled by default.
+ */
+declare class LunarCLIError extends Error {
+    /**
+     * The command this error happened on.
+     */
+    command: Command<any>;
+    /**
+     * Creates a new LunarCLI error.
+     * @param message The message.
+     * @param command The command.
+     */
+    constructor(message: string, command: Command<any>);
+    /**
+     * Prints the error's message.
+     */
+    print(): void;
+}
+
+/**
+ * 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;
+    /**
+     * 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(): 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;
+}
+
+/**
+ * The result of the `Command.parse` function.
+ */
+export 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: LunarCLIError[];
+    /**
+     * 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;
+}
+
+/** 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"];
+}
+
+/**
+ * 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;
+    };
+}
+
+/**
+ * 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;
+
+export { }