@handy-common-utils/misc-utils/dist/line-logger.js

Miscellaneous utilities

"use strict";
/* eslint-disable max-params */
/* eslint-disable @typescript-eslint/no-empty-function */
/* eslint-disable @typescript-eslint/ban-types */
Object.defineProperty(exports, "__esModule", { value: true });
exports.consoleLike = exports.consoleWithColour = exports.consoleWithoutColour = exports.LineLogger = void 0;
// eslint-disable-next-line valid-jsdoc
/**
 * A LineLogger logs/prints one entire line of text before advancing to another line.
 * This class is useful for encapsulating console.log/info/warn/error functions.
 * By having an abstraction layer, your code can switching to a different output with nearly no change.
 *
 * Please note that although the name contains "Logger", this class is not intended to be used as a generic logger.
 * It is intended for "logging for humans to read" scenario.
 *
 * `LineLogger.console()` and `LineLogger.consoleWithColour()` are ready to use convenient functions.
 * Or you can use the constructor to build your own wrappers.
 *
 * @example
 *
 * // Just a wrapper of console.log/info/warn/error
 * const consoleLogger = LineLogger.console();
 *
 * // Wrapper of console.log/info/warn/error but it mutes console.log
 * const lessVerboseConsoleLogger = LineLogger.console({debug: false});
 *
 * // Wrapper of console.log/info/warn/error but it mutes console.log and console.info
 * const lessVerboseConsoleLogger = LineLogger.console({quiet: true});
 *
 * // use chalk (chalk is not a dependency of this package, you need to add chalk as a dependency separately)
 * import chalk from 'chalk';
 * // this.flags is an object with properties "debug" and "quiet"
 * this.output = LineLogger.consoleWithColour(this.flags, chalk);
 * this.output.warn('Configuration file not found, default configuration would be used.');  // it would be printed out in yellow
 */
class LineLogger {
    /**
     * Build an instance with console.log/info/warn/error.
     * @param flags           The flag object that contains fields for knowning whether debug is enabled and whether quiet mode is enabled.
     * Values of those fields are evaluated only once within this function.
     * They are not evaluated when debug/info/warn/error functions are called.
     * @param debugFlagName   Name of the debug field in the flags object
     * @param quietFlagName   Name of the quiet field in the flags object
     * @returns An instance that uses console.log/info/warn/error.
     */
    static console(flags = {}, debugFlagName = 'debug', quietFlagName = 'quiet') {
        return new LineLogger(console.log, console.info, console.warn, console.error, flags[debugFlagName], flags[quietFlagName]);
    }
    /**
     * Build an instance with console.log/info/warn/error and chalk/colors/cli-color.
     * This package does not depend on chalk or colors or cli-color,
     * you need to add them as dependencies separately.
     *
     * @param flags           The flag object that contains fields for knowning whether debug is enabled and whether quiet mode is enabled.
     * Values of those fields are evaluated only once within this function.
     * They are not evaluated when debug/info/warn/error functions are called.
     * @param colourer              Supplier of the colouring function, such as chalk or colors or cli-color
     * @param debugColourFuncName   Name of the function within colourer that will be used to add colour to debug messages, or null if colouring is not desired.
     * @param infoColourFuncName    Name of the function within colourer that will be used to add colour to info messages, or null if colouring is not desired.
     * @param warnColourFuncName    Name of the function within colourer that will be used to add colour to warn messages, or null if colouring is not desired.
     * @param errorColourFuncName   Name of the function within colourer that will be used to add colour to error messages, or null if colouring is not desired.
     * @param debugFlagName   Name of the debug field in the flags object
     * @param quietFlagName   Name of the quiet field in the flags object
     * @returns An instance that uses console.log/info/warn/error and also adds colour to the messages using chalk/colors/cli-color.
     */
    static consoleWithColour(flags, 
    // eslint-disable-next-line default-param-last
    colourer, debugColourFuncName = 'grey', infoColourFuncName, warnColourFuncName = 'yellow', errorColourFuncName = 'red', debugFlagName = 'debug', quietFlagName = 'quiet') {
        return new LineLogger(
        // debug
        (message, ...optionalParams) => {
            console.log(debugColourFuncName == null || typeof message !== 'string' ? message : colourer[debugColourFuncName](message), ...optionalParams);
        }, 
        // info
        (message, ...optionalParams) => {
            console.info(infoColourFuncName == null || typeof message !== 'string' ? message : colourer[infoColourFuncName](message), ...optionalParams);
        }, 
        // warn
        (message, ...optionalParams) => {
            console.warn(warnColourFuncName == null || typeof message !== 'string' ? message : colourer[warnColourFuncName](message), ...optionalParams);
        }, 
        // error
        (message, ...optionalParams) => {
            console.error(errorColourFuncName == null || typeof message !== 'string' ? message : colourer[errorColourFuncName](message), ...optionalParams);
        }, flags[debugFlagName], flags[quietFlagName]);
    }
    /**
     * Build an instance from 'log' (https://github.com/medikoo/log).
     * `info` of the LineLogger is mapped to `notice` of the medikoo log.
     * @param log instance of the logger
     * @returns instance of LineLogger that is actually ConsoleLineLogger type
     */
    static consoleLike(log) {
        return new LineLogger(
        // debug
        (message, ...optionalParams) => {
            log.debug(message, ...optionalParams);
        }, 
        // info
        (message, ...optionalParams) => {
            log.notice(message, ...optionalParams);
        }, 
        // warn
        (message, ...optionalParams) => {
            log.warning(message, ...optionalParams);
        }, 
        // error
        (message, ...optionalParams) => {
            log.error(message, ...optionalParams);
        }, true, false);
    }
    /**
     * Constructor
     * @param debugFunction   function for outputting debug information
     * @param infoFunction    function for outputting info information
     * @param warnFunction    function for outputting warn information
     * @param errorFunction   function for outputting error information
     * @param isDebug         is debug output enabled or not, it could be overriden by isQuiet
     * @param isQuiet         is quiet mode enabled or not. When quiet mode is enabled, both debug and info output would be discarded.
     */
    constructor(debugFunction, infoFunction, warnFunction, errorFunction, isDebug = false, isQuiet = false) {
        this.isDebug = isDebug;
        this.isQuiet = isQuiet;
        this.info = LineLogger.NO_OP_FUNC;
        this.debug = LineLogger.NO_OP_FUNC;
        this.warn = LineLogger.NO_OP_FUNC;
        this.error = LineLogger.NO_OP_FUNC;
        if (isDebug === true && isQuiet !== true) {
            this.debug = debugFunction;
        }
        if (isQuiet !== true) {
            this.info = infoFunction;
        }
        this.warn = warnFunction;
        this.error = errorFunction;
    }
}
exports.LineLogger = LineLogger;
LineLogger.NO_OP_FUNC = function () { };
/**
 * Build an encapsulation of console output functions with console.log/info/warn/error.
 * @param flags           The flag object that contains fields for knowning whether debug is enabled and whether quiet mode is enabled.
 * Values of those fields are evaluated only once within this function.
 * They are not evaluated when debug/info/warn/error functions are called.
 * @param debugFlagName   Name of the debug field in the flags object
 * @param quietFlagName   Name of the quiet field in the flags object. Quiet flag can override debug flag.
 * @returns An LineLogger instance that uses console.log/info/warn/error.
 */
exports.consoleWithoutColour = LineLogger.console;
/**
 * Build an encapsulation of console output functions with console.log/info/warn/error and chalk/colors/cli-color.
 * @param flags           The flag object that contains fields for knowning whether debug is enabled and whether quiet mode is enabled.
 * Values of those fields are evaluated only once within this function.
 * They are not evaluated when debug/info/warn/error functions are called.
 * @param colourer              Supplier of the colouring function, such as chalk or colors or cli-color
 * @param debugColourFuncName   Name of the function within colourer that will be used to add colour to debug messages, or null if colouring is not desired.
 * @param infoColourFuncName    Name of the function within colourer that will be used to add colour to info messages, or null if colouring is not desired.
 * @param warnColourFuncName    Name of the function within colourer that will be used to add colour to warn messages, or null if colouring is not desired.
 * @param errorColourFuncName   Name of the function within colourer that will be used to add colour to error messages, or null if colouring is not desired.
 * @param debugFlagName   Name of the debug field in the flags object
 * @param quietFlagName   Name of the quiet field in the flags object. Quiet flag can override debug flag.
 * @returns An LineLogger instance that uses console.log/info/warn/error and also adds colour to the messages using chalk/colors/cli-color.
*/
exports.consoleWithColour = LineLogger.consoleWithColour;
/**
 * Build an instance from 'log' (https://github.com/medikoo/log).
 * `info` of the LineLogger is mapped to `notice` of the medikoo log.
 * @param log instance of the logger
 * @returns instance of LineLogger that is actually ConsoleLineLogger type
 */
exports.consoleLike = LineLogger.consoleLike;