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.
238 lines (237 loc) • 8.15 kB
TypeScript
import { DisplayOptions, EasyCLITheme } from '..';
/**
* Supported log types
* @typedef {'log' | 'info' | 'warn' | 'error' | 'success'} SupportedLogType
*
* @type {string}
*/
export type SupportedLogType = 'log' | 'info' | 'warn' | 'error' | 'success';
/**
* A response from a logger
* This is used to allow for forcing a log to be output using the `force` method
*
* @class EasyCLILoggerResponses
* @property {string} log - The log that was output
* @property {SupportedLogType} type - The type of log that was output
* @property {boolean} logged - Whether the log was output
* @property {function} force - Forces the log to be output
*
* @example
* ```typescript
* const logger = new EasyCLILogger({ theme: new EasyCLITheme(), verbosity: 0 });
* logger.log('Hello, world!'); // Won't be logged because verbosity is 0
* logger.log('Hello, world!').force(); // Will be logged
* ```
*/
export declare class EasyCLILoggerResponse {
private log;
private type;
private logged;
constructor(log: string, type: SupportedLogType, logged?: boolean);
/**
* Forces the log to be output. This is useful if you want to output a log even if the verbosity is too low.
*
* @example
* ```typescript
* const logger = new EasyCLILogger({ theme: new EasyCLITheme(), verbosity: 0 });
* logger.log('Hello, world!'); // Won't be logged because verbosity is 0
* logger.log('Hello, world!').force(); // Will be logged
* ```
*/
force: () => void;
}
/**
* The properties for the logger
* @param {EasyCLITheme} options.theme - The theme to use for the logger
* @param {number} [options.verbosity=0] - The verbosity level to use (Default: 0)
* @param {Record<SupportedLogType, number>} [options.verbosityThresholds] - The verbosity thresholds to use
* @param {boolean} [options.timestamp=true] - Whether to include a timestamp in the execution logs (Default: true)
*
* @example
* ```typescript
* {
* theme: new EasyCLITheme(),
* verbosity?: 0,
* verbosityThresholds?: {
* error: 0,
* success: 0,
* warn: 1,
* log: 2,
* info: 3,
* },
* timestamp?: true,
* }
* ```
*/
export type EasyCLILoggerProps = {
theme: EasyCLITheme;
verbosity?: number;
verbosityThresholds?: Record<SupportedLogType, number>;
timestamp?: boolean;
};
/**
* A logger for use with CLI applicatiions. This logger allows for logging with different verbosity levels and themes
*
* @class EasyCLILogger
*
* @example
* ```typescript
* const logger = new EasyCLILogger({ theme: new EasyCLITheme(), verbosity: 0, timestamp: false });
* logger.log('Hello, world!'); // Won't be logged because verbosity is 0
* logger.log('Hello, world!').force(); // Will be logged due to force
* logger.warn('This is a warning!'); // Won't be logged because verbosity is 0
* logger.error('This is an error!') // Will be logged
*
* const logs = logger.getExecutionLogs();
*
* ```
*/
export declare class EasyCLILogger {
private logs;
private verbosity;
private verbosityThresholds;
private theme;
private timestamp;
/**
* Instantiates a new logger with the given theme and verbosity level.
*
* @param {EasyCLILoggerProps} options - The configuration props for the logger
*
* @example
* ```typescript
* {
* theme: new EasyCLITheme(),
* verbosity?: 0,
* verbosityThresholds?: {
* error: 0, // Always log errors
* success: 0, // Always log success
* warn: 1, // Log warnings when verbosity is 1 or higher
* log: 2, // Log logs when verbosity is 2 or higher
* info: 3, // Log info when verbosity is 3 or higher
* },
* }
* ```
*/
constructor({ theme, verbosity, verbosityThresholds, timestamp, }: EasyCLILoggerProps);
/**
* Converts the arguments to strings, to be able to handle similar to how console.log works.
*
* @param args Converts the arguments to a string, removing circular references.
* @returns The arguments as a string.
*/
private convertArgArrayToString;
/**
* Saves a log to the internal log array for use with the `getExecutionLogs` method.
*
* @param {SupportedLogType} type - The type of log to save
* @param {string} message - The message to save
*/
private saveLog;
/**
* An internal method to process a log, saving it and outputting it to the console if the verbosity is high enough.
*
* @param {SupportedLogType} type - The type of log to process
* @param {unknown[]} args - The arguments to process
* @returns {EasyCLILoggerResponse} - The response from the logger
*/
private processLog;
/**
* Writes a log to the console depending on the verbosity level, using the log display options.
*
* @param {unknown[]} args - The arguments to log
* @returns {EasyCLILoggerResponse} - The response from the logger
*
* @example
* ```typescript
* logger.log('Hello, world!');
* ```
*/
log(...args: unknown[]): EasyCLILoggerResponse;
/**
*Writes a warning to the console depending on the verbosity level, using the log display options.
*
* @param {unknown[]} args - The arguments to log
*
* @returns {EasyCLILoggerResponse} - The response from the logger
* @example
* ```typescript
* logger.warn('Hello, world!');
* ```
*/
warn(...args: unknown[]): EasyCLILoggerResponse;
/**
* Writes an info message to the console depending on the verbosity level, using the log display options.
*
* @param {unknown[]} args - The arguments to log
*
* @returns {EasyCLILoggerResponse} - The response from the logger
*
* @example
* ```typescript
* logger.info('Hello, world!');
* ```
*/
info(...args: unknown[]): EasyCLILoggerResponse;
/**
* Writes an error to the console depending on the verbosity level, using the log display options.
*
* @param {unknown[]} args - The arguments to log
*
* @returns {EasyCLILoggerResponse} - The response from the logger
*
* @example
* ```typescript
* logger.error('Hello, world!');
* ```
*/
error(...args: unknown[]): EasyCLILoggerResponse;
/**
* Writes a success to the console depending on the verbosity level, using the log display options.
*
* @param {unknown[]} args - The arguments to log
*
* @returns {EasyCLILoggerResponse} - The response from the logger
*
* @example
* ```typescript
* logger.success('Hello, world!');
* ```
*/
success(...args: unknown[]): EasyCLILoggerResponse;
/**
* Takes a list of arguments and prints them to the console in the format provided.
*
* @param {(string | { text: string; format: DisplayOptions })[]} args - The arguments to print
*
* @example
* ```typescript
* // Prints Hello World! in the default format and then in the info format
* logger.printFormattedString('Hello, world!', { text: 'Hello, world!', format: 'info' });
* ```
*/
printFormattedString(...args: (string | {
text: string;
format: DisplayOptions;
})[]): void;
/**
* Gets the execution logs, including logs that were not output due to verbosity.
* This is useful for debugging and logging to a file after execution.
*
* @returns {string[]} - The execution logs
*
* @example
* ```typescript
* const logger = new EasyCLILogger({ theme: new EasyCLITheme(), verbosity: 0 });
* logger.log('Hello, world!'); // Won't be logged because verbosity is 0
* logger.log('Hello, world!').force(); // Will be logged
* logger.warn('This is a warning!'); // Won't be logged because verbosity is 0
* logger.error('This is an error!') // Will be logged
*
* const logs = logger.getExecutionLogs();
*
* console.log(logs);
* // Will display, all logs, including those that weren't output.
* ```
*/
getExecutionLogs(): string[];
}