@decaf-ts/utils/lib/esm/cli/command.d.ts

module management utils for decaf-ts

import { ParseArgsResult } from "../input/types";
import { CommandOptions } from "./types";
import { DefaultCommandValues } from "./constants";
import { Logger, LoggingConfig } from "@decaf-ts/logging";
/**
 * @class Command
 * @abstract
 * @template I - The type of input options for the command.
 * @template R - The return type of the command execution.
 * @memberOf module:utils
 * @description Abstract base class for command implementation.
 * @summary Provides a structure for creating command-line interface commands with input handling, logging, and execution flow.
 *
 * @param {string} name - The name of the command.
 * @param {CommandOptions<I>} [inputs] - The input options for the command.
 * @param {string[]} [requirements] - The list of required dependencies for the command.
 */
export declare abstract class Command<I, R> {
    protected name: string;
    protected inputs: CommandOptions<I>;
    protected requirements: string[];
    /**
     * @static
     * @description Static logger for the Command class.
     * @type {Logger}
     */
    static log: Logger;
    /**
     * @protected
     * @description Instance logger for the command.
     * @type {Logger}
     */
    protected log: Logger;
    protected constructor(name: string, inputs?: CommandOptions<I>, requirements?: string[]);
    /**
     * @protected
     * @async
     * @description Checks if all required dependencies are present.
     * @summary Retrieves the list of dependencies and compares it against the required dependencies for the command.
     * @returns {Promise<void>} A promise that resolves when the check is complete.
     *
     * @mermaid
     * sequenceDiagram
     *   participant Command
     *   participant getDependencies
     *   participant Set
     *   Command->>getDependencies: Call
     *   getDependencies-->>Command: Return {prod, dev, peer}
     *   Command->>Set: Create Set from prod, dev, peer
     *   Set-->>Command: Return unique dependencies
     *   Command->>Command: Compare against requirements
     *   alt Missing dependencies
     *     Command->>Command: Add to missing list
     *   end
     *   Note over Command: If missing.length > 0, handle missing dependencies
     */
    protected checkRequirements(): Promise<void>;
    /**
     * @protected
     * @description Provides help information for the command.
     * @summary This method should be overridden in derived classes to provide specific help information.
     * @param {ParseArgsResult} args - The parsed command-line arguments.
     * @returns {void}
     */
    protected help(args: ParseArgsResult): void;
    /**
     * @protected
     * @abstract
     * @description Runs the command with the provided arguments.
     * @summary This method should be implemented in derived classes to define the command's behavior.
     * @param {ParseArgsResult} answers - The parsed command-line arguments.
     * @returns {Promise<R | string | void>} A promise that resolves with the command's result.
     */
    protected abstract run<R>(answers: LoggingConfig & typeof DefaultCommandValues & {
        [k in keyof I]: unknown;
    }): Promise<R | string | void>;
    /**
     * @async
     * @description Executes the command.
     * @summary This method handles the overall execution flow of the command, including parsing arguments,
     * setting up logging, checking for version or help requests, and running the command.
     * @returns {Promise<R | string | void>} A promise that resolves with the command's result.
     *
     * @mermaid
     * sequenceDiagram
     *   participant Command
     *   participant UserInput
     *   participant Logging
     *   participant getPackageVersion
     *   participant printBanner
     *   Command->>UserInput: parseArgs(inputs)
     *   UserInput-->>Command: Return ParseArgsResult
     *   Command->>Command: Process options
     *   Command->>Logging: setConfig(options)
     *   alt version requested
     *     Command->>getPackageVersion: Call
     *     getPackageVersion-->>Command: Return version
     *   else help requested
     *     Command->>Command: help(args)
     *   else banner requested
     *     Command->>printBanner: Call
     *   end
     *   Command->>Command: run(args)
     *   alt error occurs
     *     Command->>Command: Log error
     *   end
     *   Command-->>Command: Return result
     */
    execute(): Promise<R | string | void>;
}