easy-cli-framework/dist/themes/progress/base.js

A framework for building CLI applications that are robust and easy to maintain. Supports theming, configuration files, interactive prompts, and more.

'use strict';

var cliProgress = require('cli-progress');

/**
 * Default options for the progress bar
 * @hidden
 */
const DEFAULT_PROGRESS_BAR_OPTIONS = {
    // Default options for the progress bar
    barDisplayOptions: {},
    // Whether to show the percentage complete
    showPercentage: true,
    // Display options for the percentage complete
    percentageDisplayOptions: {},
    // Whether to show the time elapsed
    showTimeElapsed: false,
    // Display options for the time elapsed
    timeElapsedDisplayOptions: {},
    // Whether to show the time left
    showTimeLeft: true,
    // Display options for the time left
    timeLeftDisplayOptions: {},
    // Whether to show the completed count
    showCompleted: true,
    // Display options for the completed count
    completedDisplayOptions: {},
};
/**
 * A themed progress bar, can be overridden to add additional functionality
 * @template T
 * @class ThemedProgressBar
 * @param {EasyCLITheme} theme The theme to use
 * @param {string} name The name of the progress bar
 * @param {DisplayOptions} displayOptions The display options for the progress bar
 * @param {ThemedProgressBarOptions} [progressBarOptions=DEFAULT_PROGRESS_BAR_OPTIONS] The options for the progress bar
 *
 * @example
 * ```typescript
 * const progressBar = new ThemedProgressBar(theme, 'progress', displayOptions, {
 *   showPercentage: true,
 *   percentageDisplayOptions: 'info',
 *   showTimeElapsed: true,
 *   timeElapsedDisplayOptions: 'info',
 *   showTimeLeft: true,
 *   timeLeftDisplayOptions: 'info',
 *   showCompleted: true,
 *   completedDisplayOptions: 'info',
 * });
 * ```
 *
 */
class ThemedProgressBar {
    /**
     * Creates an instance of ThemedProgressBar
     *
     * @param {EasyCLITheme} theme The theme to use
     * @param {string} name The name of the progress bar
     * @param {DisplayOptions} displayOptions The display options for the progress bar
     * @param {ThemedProgressBarOptions} [progressBarOptions=DEFAULT_PROGRESS_BAR_OPTIONS] The options for the progress bar
     *
     * @example
     * ```typescript
     * const progressBar = new ThemedProgressBar(theme, 'progress', displayOptions, {
     *  showPercentage: true,
     *  percentageDisplayOptions: 'info',
     * });
     * ```
     */
    constructor(theme, name, displayOptions, progressBarOptions = DEFAULT_PROGRESS_BAR_OPTIONS) {
        this.theme = theme;
        this.name = name;
        this.displayOptions = displayOptions;
        this.progressBarOptions = {
            ...DEFAULT_PROGRESS_BAR_OPTIONS,
            ...progressBarOptions,
        };
    }
    /**
     * An internal method to get the options for the progress bar
     *
     * @returns {Options} The options for the progress bar
     */
    getOptions() {
        const { barDisplayOptions, showPercentage, percentageDisplayOptions, showTimeElapsed, timeElapsedDisplayOptions, showTimeLeft, timeLeftDisplayOptions, showCompleted, completedDisplayOptions, } = this.progressBarOptions;
        const format = `${this.name} ${this.theme.formattedString('[{bar}]', barDisplayOptions !== null && barDisplayOptions !== undefined ? barDisplayOptions : {})}`;
        const additions = [];
        if (showPercentage)
            additions.push(this.theme.formattedString('{percentage}%', percentageDisplayOptions !== null && percentageDisplayOptions !== undefined ? percentageDisplayOptions : {}));
        if (showTimeElapsed)
            additions.push(this.theme.formattedString('{duration_formatted} elapsed', timeElapsedDisplayOptions !== null && timeElapsedDisplayOptions !== undefined ? timeElapsedDisplayOptions : {}));
        if (showTimeLeft)
            additions.push(this.theme.formattedString('ETA: {eta_formatted}', timeLeftDisplayOptions !== null && timeLeftDisplayOptions !== undefined ? timeLeftDisplayOptions : {}));
        if (showCompleted)
            additions.push(this.theme.formattedString('{value}/{total}', completedDisplayOptions !== null && completedDisplayOptions !== undefined ? completedDisplayOptions : {}));
        return {
            format: this.theme.formattedString(`${format} ${additions.join(' | ')}`, this.displayOptions),
            hideCursor: true,
            fps: 60,
            stopOnComplete: true,
            clearOnComplete: true,
        };
    }
    /**
     * Starts the progress bar
     *
     * @param {number} initial The initial number of items processed
     * @param {number} total The total number of items to process
     * @param {Record<string, any>} payload The payload to pass to the progress bar
     * @param {Options} options A set of options for the progress bar
     *
     * @returns {SingleBar} The progress bar
     *
     * @example
     * ```typescript
     *  progressBar.start(0, 100);
     * ```
     *
     */
    start(initial, total, payload = {}, options = {}) {
        if (this.progressBar)
            return this.progressBar;
        this.progressBar = new cliProgress.SingleBar(options);
        this.progressBar.start(total, initial, payload);
        return this.progressBar;
    }
    /**
     * Stops the progress bar
     *
     * @example
     * ```typescript
     * progressBar.stop();
     * ```
     */
    stop() {
        var _a;
        (_a = this.progressBar) === null || _a === undefined ? undefined : _a.stop();
        this.progressBar = null;
    }
}

exports.DEFAULT_PROGRESS_BAR_OPTIONS = DEFAULT_PROGRESS_BAR_OPTIONS;
exports.ThemedProgressBar = ThemedProgressBar;