@salesforce/command/lib/ux.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const kit_1 = require("@salesforce/kit");
const ts_types_1 = require("@salesforce/ts-types");
/*
 * Copyright (c) 2018, salesforce.com, inc.
 * All rights reserved.
 * SPDX-License-Identifier: BSD-3-Clause
 * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
 */
/**
 * A table option configuration type that can be the TableOptions as defined by
 * [oclif/cli-ux](https://github.com/oclif/cli-ux/blob/master/src/styled/table.ts) or a string array of table keys to be used as table headers
 * for simple tables.
 * @typedef {object} SfdxTableOptions
 * @property {TableOptions | string[]} options
 */
/**
 * A prompt option configuration as defined by
 * [oclif/cli-ux](https://github.com/oclif/cli-ux/blob/master/src/prompt.ts).
 * @typedef {object} IPromptOptions
 * @property {string} prompt The prompt string displayed to the user.
 * @property {'normal' | 'mask' | 'hide'} type `Normal` does not hide the user input, `mask` hides the user input after the user presses `ENTER`, and `hide` hides the user input as it is being typed.
 */
const core_1 = require("@salesforce/core");
const ts_types_2 = require("@salesforce/ts-types");
const chalk_1 = require("chalk");
const cli_ux_1 = require("cli-ux");
/**
 * Utilities for interacting with terminal I/O.
 */
class UX {
    /**
     * Do not directly construct instances of this class -- use {@link UX.create} instead.
     */
    constructor(logger, isOutputEnabled, ux) {
        this.logger = logger;
        this.cli = ux || cli_ux_1.cli;
        if (ts_types_2.isBoolean(isOutputEnabled)) {
            this.isOutputEnabled = isOutputEnabled;
        }
        else {
            // Respect the --json flag and SFDX_CONTENT_TYPE for consumers who don't explicitly check
            const isContentTypeJSON = kit_1.env.getString('SFDX_CONTENT_TYPE', '').toUpperCase() === 'JSON';
            this.isOutputEnabled = !(process.argv.find(arg => arg === '--json') || isContentTypeJSON);
        }
    }
    /**
     * Formats a deprecation warning for display to `stderr`, `stdout`, and/or logs.
     *
     * @param {DeprecationDefinition} def The definition for the deprecated object.
     * @returns {string} The formatted deprecation message.
     */
    static formatDeprecationWarning(def) {
        let msg;
        if (ts_types_2.has(def, 'version')) {
            const version = ts_types_2.isString(def.version) ? parseInt(def.version, 10) : def.version || 0;
            const type = ts_types_1.ensure(def.type);
            const name = ts_types_1.ensure(def.name);
            msg = `The ${type} "${name}" has been deprecated and will be removed in v${version + 1}.0 or later.`;
        }
        else {
            msg = def.messageOverride;
        }
        if (def.to) {
            msg += ` Use "${def.to}" instead.`;
        }
        if (def.message) {
            msg += ` ${def.message}`;
        }
        return msg;
    }
    /**
     * Create a `UX` instance.
     *
     * @returns {Promise<UX>} A `Promise` of the created `UX` instance.
     */
    static async create() {
        return new UX(await core_1.Logger.child('UX'));
    }
    /**
     * Logs at `INFO` level and conditionally writes to `stdout` if stream output is enabled.
     *
     * @param {...any[]} args The messages or objects to log.
     * @returns {UX}
     */
    log(...args) {
        if (this.isOutputEnabled) {
            this.cli.log(...args);
        }
        // log to sfdx.log after the console as log filtering mutates the args.
        this.logger.info(...args);
        return this;
    }
    /**
     * Log JSON to stdout and to the log file with log level info.
     *
     * @param {object} obj The object to log -- must be serializable as JSON.
     * @returns {UX}
     * @throws {TypeError} If the object is not JSON-serializable.
     */
    logJson(obj) {
        this.cli.styledJSON(obj);
        // log to sfdx.log after the console as log filtering mutates the args.
        this.logger.info(obj);
        return this;
    }
    /**
     * Prompt the user for input.
     * @param {string} name The string that the user sees when prompted for information.
     * @param {IPromptOptions} options A prompt option configuration.
     * @returns {Promise<string>} The user input to the prompt.
     */
    async prompt(name, options = {}) {
        return this.cli.prompt(name, options);
    }
    /**
     * Prompt the user for confirmation.
     * @param {string} message The message displayed to the user.
     * @returns {Promise<boolean>} Returns `true` if the user inputs 'y' or 'yes', and `false` if the user inputs 'n' or 'no'.
     */
    async confirm(message) {
        return this.cli.confirm(message);
    }
    /**
     * Start a spinner action after displaying the given message.
     * @param {string} message The message displayed to the user.
     */
    startSpinner(message) {
        if (this.isOutputEnabled) {
            this.cli.action.start(message);
        }
    }
    /**
     * Pause the spinner and call the given function.
     * @param {function} fn The function to be called in the pause.
     * @param {string} icon The string displayed to the user.
     * @returns {T} The result returned by the passed in function.
     */
    pauseSpinner(fn, icon) {
        if (this.isOutputEnabled) {
            return this.cli.action.pause(fn, icon);
        }
    }
    /**
     * Update the spinner status.
     * @param {string} status The message displayed to the user.
     */
    setSpinnerStatus(status) {
        if (this.isOutputEnabled) {
            this.cli.action.status = status;
        }
    }
    /**
     * Get the spinner status.
     * @returns {Optional<string>}
     */
    getSpinnerStatus() {
        if (this.isOutputEnabled) {
            return this.cli.action.status;
        }
    }
    /**
     * Stop the spinner action.
     * @param {string} message The message displayed to the user.
     */
    stopSpinner(message) {
        if (this.isOutputEnabled) {
            this.cli.action.stop(message);
        }
    }
    /**
     * Logs a warning as `WARN` level and conditionally writes to `stderr` if the log
     * level is `WARN` or above and stream output is enabled.  The message is added
     * to the static {@link UX.warnings} set if stream output is _not_ enabled, for later
     * consumption and manipulation.
     *
     * @param {string} message The warning message to output.
     * @returns {UX}
     * @see UX.warnings
     */
    warn(message) {
        const warning = chalk_1.default.yellow('WARNING:');
        // Necessarily log to sfdx.log.
        this.logger.warn(warning, message);
        if (this.logger.shouldLog(core_1.LoggerLevel.WARN)) {
            if (!this.isOutputEnabled) {
                UX.warnings.add(message);
            }
            else {
                console.warn(`${warning} ${message}`);
            }
        }
        return this;
    }
    /**
     * Logs an error at `ERROR` level and conditionally writes to `stderr` if stream
     * output is enabled.
     *
     * @param {...any[]} args The errors to log.
     * @returns {UX}
     */
    error(...args) {
        if (this.isOutputEnabled) {
            console.error(...args);
        }
        this.logger.error(...args);
        return this;
    }
    /**
     * Logs an object as JSON at `ERROR` level and to `stderr`.
     *
     * @param {object} obj The error object to log -- must be serializable as JSON.
     * @returns {UX}
     * @throws {TypeError} If the object is not JSON-serializable.
     */
    errorJson(obj) {
        const err = JSON.stringify(obj, null, 4);
        console.error(err);
        this.logger.error(err);
        return this;
    }
    /**
     * Logs at `INFO` level and conditionally writes to `stdout` in a table format if
     * stream output is enabled.
     *
     * @param {object[]} rows The rows of data to be output in table format.
     * @param {SfdxTableOptions} options The {@link SfdxTableOptions} to use for formatting.
     * @returns {UX}
     */
    // tslint:disable-next-line no-any (matches oclif)
    table(rows, options = {}) {
        if (this.isOutputEnabled) {
            // This is either an array of column names or an already built Partial<OclifTableOptions>
            if (ts_types_2.isArray(options)) {
                const tableColumns = [];
                for (const col of options) {
                    tableColumns.push({
                        key: col,
                        label: col
                            .split(/(?=[A-Z])|[-_\s]/)
                            .map(w => w.toUpperCase())
                            .join(' ')
                    });
                }
                this.cli.table(rows, { columns: tableColumns });
            }
            else {
                this.cli.table(rows, options);
            }
        }
        // Log after table output as log filtering mutates data.
        this.logger.info(rows);
        return this;
    }
    /**
     * Logs at `INFO` level and conditionally writes to `stdout` in a styled object format if
     * stream output is enabled.
     *
     * @param {object} obj The object to be styled for stdout.
     * @param {string[]} [keys] The object keys to be written to stdout.
     * @returns {UX}
     */
    styledObject(obj, keys) {
        this.logger.info(obj);
        if (this.isOutputEnabled) {
            this.cli.styledObject(obj, keys);
        }
        return this;
    }
    /**
     * Log at `INFO` level and conditionally write to `stdout` in styled JSON format if
     * stream output is enabled.
     *
     * @param {object} obj The object to be styled for stdout.
     * @returns {UX}
     */
    styledJSON(obj) {
        this.logger.info(obj);
        if (this.isOutputEnabled) {
            this.cli.styledJSON(obj);
        }
        return this;
    }
    /**
     * Logs at `INFO` level and conditionally writes to `stdout` in a styled header format if
     * stream output is enabled.
     *
     * @param {string} header The header to be styled.
     * @returns {UX}
     */
    styledHeader(header) {
        this.logger.info(header);
        if (this.isOutputEnabled) {
            this.cli.styledHeader(header);
        }
        return this;
    }
}
/**
 * Collection of warnings that can be accessed and manipulated later.
 * @type {Set<string>}
 */
UX.warnings = new Set();
exports.UX = UX;
//# sourceMappingURL=ux.js.map