node-ansi-logger/dist/logger.d.ts

Enhanced Ansi Color Logging and Stringify for Node.js in type script

/**
 * This file contains the AnsiLogger .
 *
 * @file logger.ts
 * @author Luca Liguori
 * @created 2023-06-01
 * @version 3.0.2
 * @license Apache-2.0
 *
 * Copyright 2024, 2025, 2026 Luca Liguori.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
export declare const RESET = "\u001B[40;0m";
export declare const BRIGHT = "\u001B[1m";
export declare const DIM = "\u001B[2m";
export declare const NORMAL = "\u001B[22m";
export declare const UNDERLINE = "\u001B[4m";
export declare const UNDERLINEOFF = "\u001B[24m";
export declare const BLINK = "\u001B[5m";
export declare const BLINKOFF = "\u001B[25m";
export declare const REVERSE = "\u001B[7m";
export declare const REVERSEOFF = "\u001B[27m";
export declare const HIDDEN = "\u001B[8m";
export declare const HIDDENOFF = "\u001B[28m";
export declare const CURSORSAVE = "\u001B[s";
export declare const CURSORRESTORE = "\u001B[u";
export declare const BLACK = "\u001B[30m";
export declare const RED = "\u001B[31m";
export declare const GREEN = "\u001B[32m";
export declare const YELLOW = "\u001B[33m";
export declare const BLUE = "\u001B[34m";
export declare const MAGENTA = "\u001B[35m";
export declare const CYAN = "\u001B[36m";
export declare const LIGHT_GREY = "\u001B[37m";
export declare const GREY = "\u001B[90m";
export declare const WHITE = "\u001B[97m";
export declare const db = "\u001B[38;5;245m";
export declare const nf = "\u001B[38;5;252m";
export declare const nt = "\u001B[38;5;2m";
export declare const wr = "\u001B[38;5;220m";
export declare const er = "\u001B[38;5;1m";
export declare const ft = "\u001B[38;5;9m";
export declare const rs = "\u001B[40;0m";
export declare const rk = "\u001B[K";
export declare const dn = "\u001B[38;5;33m";
export declare const gn = "\u001B[38;5;35m";
export declare const idn = "\u001B[48;5;21m\u001B[38;5;255m";
export declare const ign = "\u001B[48;5;22m\u001B[38;5;255m";
export declare const zb = "\u001B[38;5;207m";
export declare const hk = "\u001B[38;5;79m";
export declare const pl = "\u001B[32m";
export declare const id = "\u001B[37;44m";
export declare const or = "\u001B[38;5;208m";
/**
 * LogLevel enumeration to specify the logging level.
 */
export declare const enum LogLevel {
    NONE = "",
    DEBUG = "debug",
    INFO = "info",
    NOTICE = "notice",
    WARN = "warn",
    ERROR = "error",
    FATAL = "fatal"
}
/**
 * Logger interface for custom loggers that can be passed to AnsiLogger for output instead of console output.
 */
export interface Logger {
    debug: (...data: any[]) => void;
    info: (...data: any[]) => void;
    notice: (...data: any[]) => void;
    warn: (...data: any[]) => void;
    error: (...data: any[]) => void;
    fatal: (...data: any[]) => void;
    log: (level: LogLevel, message: string, ...parameters: any[]) => void;
}
/**
 * TimestampFormat enumeration to specify the format of timestamps in log messages.
 */
export declare const enum TimestampFormat {
    ISO = 0,
    LOCAL_DATE = 1,
    LOCAL_TIME = 2,
    LOCAL_DATE_TIME = 3,
    TIME_MILLIS = 4,
    HOMEBRIDGE = 5,
    CUSTOM = 6
}
/**
 * Parameters for configuring an AnsiLogger instance.
 */
export interface AnsiLoggerParams {
    extLog?: Logger;
    logName?: string;
    logDebug?: boolean;
    logLevel?: LogLevel;
    logWithColors?: boolean;
    logTimestampFormat?: TimestampFormat;
    logCustomTimestampFormat?: string;
}
export type AnsiLoggerCallback = (level: string, time: string, name: string, message: string) => void;
/**
 * AnsiLogger provides a customizable logging utility with ANSI color support.
 * It allows for various configurations such as enabling debug logs, customizing log name, and more.
 */
export declare class AnsiLogger {
    private _extLog;
    private _logName;
    private _logFilePath;
    private _logFileSize;
    private _logLevel;
    private _logWithColors;
    private _logTimestampFormat;
    private _logCustomTimestampFormat;
    private _logTimeStampColor;
    private _logNameColor;
    private _maxFileSize;
    private logStartTime;
    private callback;
    /**
     * Constructs a new AnsiLogger instance with optional configuration parameters.
     *
     * @param {AnsiLoggerParams} params - Configuration options for the logger.
     */
    constructor(params: AnsiLoggerParams);
    /**
     * Gets the name of the logger.
     *
     * @returns {string} The logger name.
     */
    get logName(): string;
    /**
     * Sets the log name for the logger.
     *
     * @param {string} name - The logger name to set.
     */
    set logName(name: string);
    /**
     * Gets the log level of the logger.
     *
     * @returns {LogLevel} The log level.
     */
    get logLevel(): LogLevel;
    /**
     * Sets the log level for the logger.
     *
     * @param {LogLevel} logLevel - The log level to set.
     */
    set logLevel(logLevel: LogLevel);
    /**
     * Gets the logWithColors flag of the logger.
     *
     * @returns {boolean} The logWithColors parameter.
     */
    get logWithColors(): boolean;
    /**
     * Sets the logWithColors flag of the logger.
     *
     * @param {boolean} logWithColors - The logWithColors parameter to set.
     */
    set logWithColors(logWithColors: boolean);
    /**
     * Gets the log name color string of the logger.
     *
     * @returns {string} The log name color string.
     */
    get logNameColor(): string;
    /**
     * Sets the log name color string for the logger.
     *
     * @param {string} color - The logger name color string to set.
     */
    set logNameColor(color: string);
    /**
     * Gets the log timestamp format of the logger.
     *
     * @returns {TimestampFormat} The log timestamp format.
     */
    get logTimestampFormat(): TimestampFormat;
    /**
     * Sets the log timestamp format for the logger.
     *
     * @param {TimestampFormat} logTimestampFormat - The log timestamp format to set.
     */
    set logTimestampFormat(logTimestampFormat: TimestampFormat);
    /**
     * Gets the custom log timestamp format of the logger.
     *
     * @returns {string} The custom log timestamp format.
     */
    get logCustomTimestampFormat(): string;
    /**
     * Sets the custom log timestamp format for the logger.
     *
     * @param {string} logCustomTimestampFormat - The custom log timestamp format to set.
     */
    set logCustomTimestampFormat(logCustomTimestampFormat: string);
    /**
     * Gets the file path of the log.
     *
     * @returns {string | undefined} The file path of the log, or undefined if not set.
     */
    get logFilePath(): string | undefined;
    /**
     * Sets the file path for logging.
     *
     * @param {string | undefined} filePath - The file path to set for logging.
     */
    set logFilePath(filePath: string | undefined);
    /**
     * Gets the size of log file.
     *
     * @returns {number | undefined} The size of log file, or undefined if not set.
     */
    get logFileSize(): number | undefined;
    /**
     * Gets the max file size of the file loggers.
     *
     * @returns {number} The current maxFileSize.
     */
    get maxFileSize(): number;
    /**
     * Sets the max file size of the file loggers.
     *
     * @param {number} maxFileSize - The maxFileSize to set.
     */
    set maxFileSize(maxFileSize: number);
    /**
     * Starts a timer with an optional message.
     *
     * @param {string} message - The message to log when starting the timer.
     */
    startTimer(message: string): void;
    /**
     * Stops the timer started by startTimer and logs the elapsed time.
     *
     * @param {string} message - The message to log along with the elapsed time.
     */
    stopTimer(message: string): void;
    /**
     * Sets the callback function to be used by the logger.
     *
     * @param {AnsiLoggerCallback} callback - The callback function.
     */
    setCallback(callback: AnsiLoggerCallback | undefined): void;
    /**
     * Gets the callback function currently used by the logger.
     *
     * @returns {AnsiLoggerCallback | undefined} The callback function.
     */
    getCallback(): AnsiLoggerCallback | undefined;
    /**
     * Sets the global callback function to be used by the logger.
     *
     * @param {AnsiLoggerCallback | undefined} callback - The callback function.
     * @param {LogLevel} [callbackLevel]  - The log level of the log file (default LogLevel.DEBUG).
     *
     * @returns {AnsiLoggerCallback | undefined} The path name of the log file.
     */
    static setGlobalCallback(callback: AnsiLoggerCallback | undefined, callbackLevel?: LogLevel): AnsiLoggerCallback | undefined;
    /**
     * Gets the global callback function currently used by the logger.
     *
     * @returns {AnsiLoggerCallback | undefined} The callback function.
     */
    static getGlobalCallback(): AnsiLoggerCallback | undefined;
    /**
     * Gets the global callback log level used by the logger.
     *
     * @returns {LogLevel | undefined} The log level of the global callback.
     */
    static getGlobalCallbackLevel(): LogLevel | undefined;
    /**
     * Sets the global callback log level for the logger.
     *
     * @param {LogLevel} logLevel - The log level to set. Defaults to LogLevel.DEBUG.
     *
     * @returns {LogLevel | undefined} The log level that was set.
     */
    static setGlobalCallbackLevel(logLevel?: LogLevel): LogLevel | undefined;
    /**
     * Sets the global logfile to be used by the logger.
     *
     * @param {string} logfilePath - The path name of the log file.
     * @param {LogLevel} logfileLevel - Optional: the log level of the log file. Default LogLevel.DEBUG.
     * @param {boolean} unlink - Optional: whether to unlink (delete) the log file if it exists. Default false.
     *
     * @returns {string | undefined} The absolute path name of the log file.
     */
    static setGlobalLogfile(logfilePath: string | undefined, logfileLevel?: LogLevel, unlink?: boolean): string | undefined;
    /**
     * Gets the global logfile currently used by the logger.
     *
     * @returns {string | undefined} The path name of the log file.
     */
    static getGlobalLogfile(): string | undefined;
    /**
     * Gets the global logfile log level used by the loggers.
     *
     * @returns {LogLevel | undefined} The log level of the global logfile.
     */
    static getGlobalLogfileLevel(): LogLevel | undefined;
    /**
     * Sets the global logfile log level used by the loggers.
     *
     * @param {LogLevel} logfileLevel - The global logfile log level used by the loggers.
     *
     * @returns {LogLevel | undefined} The log level of the global logfile.
     */
    static setGlobalLogfileLevel(logfileLevel: LogLevel): LogLevel | undefined;
    /**
     * Determines whether a log message with the given level should be logged based on the configured log level.
     *
     * @param {LogLevel} level - The level of the log message.
     * @param {LogLevel | undefined} configuredLevel - The configured log level.
     *
     * @returns {boolean} A boolean indicating whether the log message should be logged.
     */
    private shouldLog;
    /**
     * Formats a Date object into a custom string format.
     *
     * @param {Date} date - The Date object to format.
     * @param {string} formatString - The string format to use.
     * @returns {string} The formatted date.
     * It only handles years, months, days, hours, minutes, and seconds
     * with this format 'yyyy-MM-dd HH:mm:ss'
     */
    private formatCustomTimestamp;
    /**
     * Returns the current timestamp as a string.
     *
     * @returns {string} The current timestamp.
     */
    now(): string;
    /**
     * Returns the timestamp based on the configured format.
     * If the log start time is set, it returns the time passed since the start time.
     * Otherwise, it returns the current timestamp based on the configured format.
     *
     * @returns {string} The timestamp string.
     */
    private getTimestamp;
    /**
     * Writes a log message to a file.
     *
     * @param {string} filePath - The path of the file to write the log message to.
     * @param {LogLevel} level - The log level of the message.
     * @param {string} message - The log message.
     * @param {...any[]} parameters - Additional parameters to include in the log message.
     * @returns {number} - The length of the log message including the appended newline character.
     */
    private logToFile;
    /**
     * Logs a message with a specific level (e.g. debug, info, notice, warn, error, fatal) and additional parameters.
     * This method formats the log message with ANSI colors based on the log level and other logger settings.
     * It supports dynamic parameters for more detailed and formatted logging.
     *
     * @param {LogLevel} level - The severity level of the log message.
     * @param {string} message - The primary log message to be displayed.
     * @param {...any[]} parameters - Additional parameters to be logged. Supports any number of parameters.
     */
    log(level: LogLevel, message: string, ...parameters: any[]): void;
    /**
     * Logs a debug message if debug logging is enabled. This is a convenience method that delegates to the `log` method with the `LogLevel.DEBUG` level.
     *
     * @param {string} message - The message to log.
     * @param {...any[]} parameters - Additional parameters to be included in the log message. Supports any number of parameters.
     */
    debug(message: string, ...parameters: any[]): void;
    /**
     * Logs an informational message. This is a convenience method that delegates to the `log` method with the `LogLevel.INFO` level.
     *
     * @param {string} message - The message to log.
     * @param {...any[]} parameters - Additional parameters to be included in the log message. Supports any number of parameters.
     */
    info(message: string, ...parameters: any[]): void;
    /**
     * Logs a notice message. This is a convenience method that delegates to the `log` method with the `LogLevel.NOTICE` level.
     *
     * @param {string} message - The message to log.
     * @param {...any[]} parameters - Additional parameters to be included in the log message. Supports any number of parameters.
     */
    notice(message: string, ...parameters: any[]): void;
    /**
     * Logs a warning message. This is a convenience method that delegates to the `log` method with the `LogLevel.WARN` level.
     *
     * @param {string} message - The message to log.
     * @param {...any[]} parameters - Additional parameters to be included in the log message. Supports any number of parameters.
     */
    warn(message: string, ...parameters: any[]): void;
    /**
     * Logs an error message. This is a convenience method that delegates to the `log` method with the `LogLevel.ERROR` level.
     *
     * @param {string} message - The message to log.
     * @param {...any[]} parameters - Additional parameters to be included in the log message. Supports any number of parameters.
     */
    error(message: string, ...parameters: any[]): void;
    /**
     * Logs a fatal message. This is a convenience method that delegates to the `log` method with the `LogLevel.FATAL` level.
     *
     * @param {string} message - The message to log.
     * @param {...any[]} parameters - Additional parameters to be included in the log message. Supports any number of parameters.
     */
    fatal(message: string, ...parameters: any[]): void;
}
//# sourceMappingURL=logger.d.ts.map