easy-cli-framework
Version:
A framework for building CLI applications that are robust and easy to maintain. Supports theming, configuration files, interactive prompts, and more.
195 lines (194 loc) • 6.4 kB
TypeScript
/**
* @packageDocumentation A framework for building CLI applications that are robust and easy to maintain. Supports theming, configuration files, interactive prompts, and more.
* @module easy-cli
*/
import yargs from 'yargs';
import { CommandOption, CommandOptionObject, EasyCLICommand } from './commands/command';
import { EasyCLITheme } from './themes';
import { EasyCLIConfigFile } from './config-files';
/**
* @interface EasyCLIConfig
* The configuration for the EasyCLI
*
* @template TGlobalParams An object representing the global params for the CLI
*
* @property {string} [executionName] The name to display in the help menu and error messages for the CLI
* @property {string} [defaultCommand] The default command to run if no command is provided (defaults to 'help')
* @property {EasyCLICommand[]} [commands] The commands to add to the CLI
* @property {CommandOptionObject} [globalFlags] The global flags to add to the CLI
*/
export type EasyCLIConfig<TGlobalParams extends Record<string, any> = Record<string, any>> = {
executionName?: string;
defaultCommand?: string;
commands?: EasyCLICommand<any, TGlobalParams>[];
globalFlags?: CommandOptionObject<{}, TGlobalParams>;
};
/**
* @class EasyCLI
* The primary class for composing and running an EasyCLI application.
* This class is responsible for managing the commands, global flags, and themes for the CLI.
* It also handles the parsing of the arguments and executing the commands.
*
* @template TGlobalParams The global params for the CLI
*
* @example
* ```typescript
* const cli = new EasyCLI({
* executionName: 'my-cli',
* });
*
* const command = new EasyCLICommand(...);
* cli.addCommand(command);
*
* cli.execute();
* ```
*/
export declare class EasyCLI<TGlobalParams extends Record<string, any> = Record<string, any>> {
private executionName;
private defaultCommand;
private commands;
private theme?;
private globalFlags;
private verboseFlag;
private configFlag;
private configFile;
/**
* Creates a new EasyCLI instance
*
* @param {EasyCLIConfig} [config={}] The configuration for the CLI
*/
constructor(config?: EasyCLIConfig<TGlobalParams>);
/**
* Set the theme for the CLI, will overwrite any existing theme, and this theme will be passed to all commands unless overridden.
*
* @param {EasyCLITheme} theme The theme to use
*
* @returns {EasyCLI} The EasyCLI instance
*
* @example
* ```typescript
* const theme = new EasyCLITheme();
*
* const cli = new EasyCLI();
* cli.setTheme(theme);
* ```
*/
setTheme(theme: EasyCLITheme): EasyCLI<TGlobalParams>;
/**
* Set the configuration file for the CLI
*
* @param {EasyCLIConfigFile} config The configuration file to use
*
* @returns {EasyCLI} The EasyCLI instance
*
* @example
* ```typescript
* const configFile = new EasyCLIConfigFile({
* ...
* });
*
* const cli = new EasyCLI();
* cli.setConfigFile(configFile);
* ```
*/
setConfigFile(config: EasyCLIConfigFile): EasyCLI<TGlobalParams>;
/**
* Dangerously sets all the commands for the CLI, overwriting any existing commands.
*
* @param {EasyCLICommand[]} commands The commands to add to the CLI
*
* @returns {EasyCLI} The EasyCLI instance
*
* @example
* ```typescript
* const command = new EasyCLICommand(...);
* const cli = new EasyCLI();
* cli.setCommands([command]);
* ```
*/
setCommands(commands: EasyCLICommand<{}, TGlobalParams>[]): EasyCLI<TGlobalParams>;
/**
* Adds a command to the CLI
*
* @template TParams The params that this command accepts.
*
* @param {EasyCLICommand} command The command to add
*
* @returns {EasyCLI} The EasyCLI instance
*
* @example
* ```typescript
* const command = new EasyCLICommand(...);
* const cli = new EasyCLI();
* cli.addCommand(command);
* ```
*/
addCommand<TParams extends Record<string, any> = Record<string, any>>(command: EasyCLICommand<TParams, TGlobalParams>): EasyCLI<TGlobalParams>;
/**
* Manage the verbose flag for the CLI
*
* @param {number} [defaultVerbosity=0] The default verbosity level
* @param {Partial<CommandOption & { name: string }>} [overrides={}] Any overrides for the verbose flag
*
* @returns {EasyCLI} The EasyCLI instance
*
* @example
* ```typescript
* const cli = new EasyCLI();
* cli.handleVerboseFlag(0, { ... });
* ```
*/
handleVerboseFlag(defaultVerbosity?: number, overrides?: Partial<CommandOption & {
name: string;
}>): EasyCLI<TGlobalParams>;
/**
* Manage the configuration file flag for the CLI
*
* @param {Partial<CommandOption & { name: string }>} [overrides={}] Any overrides for the configuration file flag
*
* @returns {EasyCLI} The EasyCLI instance
*
* @example
* ```typescript
* const cli = new EasyCLI();
*
* // This will add a `--config` flag to the CLI
* cli.handleConfigFileFlag();
*
* // This will add a `--my-config` flag to the CLI
* cli.handleConfigFileFlag({ name: 'my-config' });
* ```
*
*/
handleConfigFileFlag(overrides?: Partial<CommandOption & {
name: string;
}>): EasyCLI<TGlobalParams>;
/**
* An internal method to get the default values for the global flags
*
* @returns The default values for the global flags
*/
private getDefaults;
/**
* @returns A middleware function to load the configuration file
*/
private configMiddleware;
/**
* @returns A middleware function to set the verbosity level
*/
private verboseMiddleware;
/**
* Run the CLI with the provided arguments.
*
* @param {((app: typeof yargs) => typeof yargs) | null} [callback=null] A callback to add additional configuration to the CLI via yargs
*
* @returns {Promise<void>} A promise that resolves when the CLI has finished executing
*
* @example
* ```typescript
* const cli = new EasyCLI(...);
* cli.execute();
* ```
*/
execute(callback?: ((app: typeof yargs) => typeof yargs) | null): Promise<void>;
}