@pyrologic/pyrologjs/dist/pyrolog.d.ts

Lightweight JavaScript logger

/**
 * logging levels
 */
declare enum Level {
    /** logs everything  */
    ALL = 0,
    /** TRACE level */
    TRACE = 1,
    /** DEBUG level */
    DEBUG = 2,
    /** INFO level */
    INFO = 3,
    /** WARN level */
    WARN = 4,
    /** ERROR level */
    ERROR = 5,
    /** FATAL level */
    FATAL = 6,
    /** loggers at this level do not log at all */
    OFF = 7
}
/**
 * a string collection of all supported logging levels
 */
type LevelStrings = keyof typeof Level;
/**
 * retrieves the name of a logging level
 * @param level logging level
 * @returns the corresponding name (string)
 */
declare function Level2String(level: Level): string;
/**
 * converts a logging level into the matching level identifier
 * @param level the logging level
 * @returns the matching level identifier
 */
declare function Level2LevelString(level: Level): LevelStrings;
/**
 * converts an arbitrary string into a valid level identifier
 * @param s arbitrary string
 * @returns the corresponding level identifier
 */
declare function String2LevelString(s: string): LevelStrings;
/**
 * converts a string providing a level name into the corresponding Level enumeration value
 * @param s string providing a level name
 * @returns the corresponding Level enumeration value
 */
declare function String2Level(s: string): Level;
/**
 * executes a callback function for each logging level
 * @param f the callback function
 */
declare function forEachLevel(f: (level: Level) => void): void;

/**
 * styling of logging messages
 * see https://developer.chrome.com/docs/devtools/console/format-style
 */

/**
 * color reference
 */
interface ColorRef {
    /** foreground color reference */
    readonly fgRef: number;
    /** background color reference */
    readonly bgRef: number;
}
/**
 * all supported color values
 */
declare const Colors: {
    readonly BLACK: ColorRef;
    readonly RED: ColorRef;
    readonly GREEN: ColorRef;
    readonly ORANGE: ColorRef;
    readonly DARKBLUE: ColorRef;
    readonly PURPLE: ColorRef;
    readonly TURQUOISE: ColorRef;
    readonly GRAY: ColorRef;
    readonly DARKGRAY: ColorRef;
    readonly LIGHTRED: ColorRef;
    readonly LIGHTGREEN: ColorRef;
    readonly YELLOW: ColorRef;
    readonly BLUE: ColorRef;
    readonly PINK: ColorRef;
    readonly CYAN: ColorRef;
    readonly WHITE: ColorRef;
    readonly NONE: ColorRef;
};
/**
 * supported text styles
 */
interface TextStyle {
    readonly bold: boolean;
    readonly italic: boolean;
    readonly underline: boolean;
    readonly linethrough: boolean;
}
/**
 * a logging style definition
 */
interface StyleDef {
    /** the foreground/text color */
    readonly color: ColorRef;
    /** the background color */
    readonly background: ColorRef;
    /** additional text style attributes */
    readonly styles: TextStyle;
}
/** a map providing style definitions for logging levels */
type LevelStyles = Map<LevelStrings, StyleDef>;

/**
 * configuration item
 */
interface ConfigItem {
    /** logger name */
    readonly name: string;
    /** logging level */
    readonly level: LevelStrings;
    /** flag whether to write the name of the calling function / method along with each output */
    readonly writeFnc: Boolean | null;
    /** level styles */
    readonly levelStyles: LevelStyles;
    /**
     * adds a level style definition or overrides an existing one
     * @param level the level
     * @param style the style definition
     */
    addLevelStyle(level: LevelStrings, style: StyleDef): void;
}

/**
 * the main logger interface
 */
interface Logger {
    /** logger name */
    readonly name: string;
    /** logging level of this instance */
    readonly level: Level;
    /** "write function name" flag */
    readonly writeFnc: boolean;
    /** the offset for the call stack used to get the name of the calling function */
    readonly fncOffset: number;
    /** the current "suspended" state of this logger */
    readonly suspended: boolean;
    /**
     * checks whether this logger is enabled for a specific logging level
     * @param l logging level
     * @returns true if this logger is enabled for the specified logging level; false otherwise
     */
    isEnabledFor(l: Level): boolean;
    /**
     * @returns true if this logger is enabled for logging at level DEBUG or above; false otherwise
     */
    isDebugEnabled(): boolean;
    /**
     * @returns true if this logger is enabled for logging at level TRACE or above; false otherwise
     */
    isTraceEnabled(): boolean;
    /**
     * writes a log message at the specified level
     * @param l logging level
     * @param data data to be logged
     */
    writeLog(l: Level, ...data: any[]): void;
    /**
     * writes a log message at level TRACE
     * @param data data to be logged
     */
    trace(...data: any[]): void;
    /**
     * writes a log message at level DEBUG
     * @param data data to be logged
     */
    debug(...data: any[]): void;
    /**
     * writes a log message at level INFO
     * @param data data to be logged
     */
    info(...data: any[]): void;
    /**
     * writes a log message at level WARN
     * @param data data to be logged
     */
    warn(...data: any[]): void;
    /**
     * writes a log message at level ERROR
     * @param data data to be logged
     */
    error(...data: any[]): void;
    /**
     * writes a log message at level FATAL
     * @param data data to be logged
     */
    fatal(...data: any[]): void;
    /**
     * logs the current stack trace
     * @param l logging level
     * @param skip number of stack entries to skip
     * @param message optional message text
     */
    writeStackTrace(l: Level, skip: number, message?: string): void;
    /**
     * sets an offset for the call stack used to get the name of the calling function
     * @param offs the offset use to get the name of the calling function
     */
    setFncOffset(offs: number): void;
    /**
     * sets the "suspended" state for this logger
     * @param suspended the "suspended" state for this logger
     */
    setSuspended(suspended: boolean): void;
    /**
     * adds a style definition for a logging level
     * @param level the logging level
     * @param style the style definition for this level
     */
    addStyle(level: Level, style: StyleDef): void;
}

/**
 * a generic data appender interface
 */
interface Appender {
    /**
     * performs further processing of logged data
     * @param logs logged data
     */
    appendLog(...logs: any): void;
}

interface PrefixGenerator {
    /**
     * creates a prefix text for a log message
     * @param logger the logger
     * @param level the logging level of the message to be logged
     * @returns the created prefix text
     */
    createPrefix(logger: Logger, level: Level): string;
}

/**
 * helper interface to avoid dependency cycles
 */

interface StyleProvider {
    /**
     * retrieves the style definition for a specific logger and the given logging level
     * @param name logger name
     * @param level logging level
     * @returns the style definition or undefined if there is no matching style definition
     */
    getStyleDef(name: string, level: Level): StyleDef | undefined;
}

declare class LoggerFactory implements StyleProvider {
    private readonly _loggers;
    private _defLevel;
    private _writeFnc;
    private _config;
    private _appender;
    private _pfxGenerator;
    /**
     * constructs the instance
     */
    constructor();
    /**
     * returns the logger factory instance
     * @returns {LoggerFactory} the logger factory instance
     */
    static getInstance(): LoggerFactory;
    /**
     * the name of the default configuration item
     */
    get defaultName(): string;
    /**
     * the default level for new loggers
     */
    get defaultLevel(): Level;
    /**
     * sets the default level
     */
    set defaultLevel(l: Level);
    /**
     * flag whether to write the name of the calling function / method along with each output
     * @returns {Boolean | null} true if new loggers should write the function name along with each log output; false if not; null if not specified
     */
    get writeFnc(): Boolean | null;
    /**
     * sets the "write function name" flag
     */
    set writeFnc(wf: Boolean | null);
    /**
     * returns a logger
     * @param name logger name
     * @returns {Logger} the logger
     */
    getLogger(name: string): Logger;
    /**
     * retrieves a logger configuration item
     * @param name logger name
     * @returns the matching configuration item or null if no matching configuration item was found
     */
    private _getConfig;
    /**
     * retrieves the parent configuration item of a configuration item
     * @param config configuration item
     * @returns the parent configuration item of the given item or null if there's no parent item
     */
    private _getParentConfig;
    /**
     * retrieves the effective "write function name" setting
     * @param wf logger's "write function name" flag
     * @returns the effective "write function name" setting
     */
    private _getEffWriteFnc;
    /**
     * retrieves the configured level of a logger
     * @param name logger name
     * @returns the level for that logger; if no configuration exists for the specified logger then the default level is returned
     */
    getLevel(name: string): Level;
    /**
     * retrieves the "write function name" flag for the specified logger
     * @param name logger name
     * @returns true if the specified logger should write the function name along with each log output; false if not; null if not specified
     */
    getWriteFnc(name: string): Boolean | null;
    /**
     * @override
     */
    getStyleDef(name: string, level: Level): StyleDef | undefined;
    /**
     * creates a new callback appender
     * @param cf callback function
     * @param set flag whether to set this appender immediately
     * @returns the created appender
     */
    createAppender(cf: Function, set: boolean): Appender;
    /**
     * sets a new appender
     * @param appender the new appender, may be null
     */
    setAppender(appender: Appender | null): void;
    /**
     * sets a new prefix generator
     * @param generator new prefix generator
     */
    setPrefixGenerator(generator: PrefixGenerator | null): void;
    /**
     * creates a prefix generator
     * @param fn actual prefix generator function
     * @param set flag whether to set this prefix generator immediately as current prefix generator
     * @returns the created prefix generator instance
     */
    createPrefixGenerator(fn: (logger: Logger, level: Level) => string, set: boolean): PrefixGenerator;
    /**
     * @returns the default prefix generator
     */
    get prefixGenerator(): PrefixGenerator;
    /**
     * creates a level style descriptor
     * @param param0
     * @returns the level style descriptor
     */
    createLevelStyle({ color, background, bold, italic, underline, linethrough }: {
        color?: ColorRef | undefined;
        background?: ColorRef | undefined;
        bold?: boolean | undefined;
        italic?: boolean | undefined;
        underline?: boolean | undefined;
        linethrough?: boolean | undefined;
    }): StyleDef;
    /**
     * creates a configuration item
     * @param name logger name
     * @param level logging level
     * @param wf flag whether to write the name of the calling function / method
     * @returns the created configuration item
     */
    createConfigItem(name: string, level: LevelStrings, wf: Boolean | null): ConfigItem;
    /**
     * applies a logger configuration
     * @param config array of configuration items
     */
    applyConfiguration(config: ConfigItem[]): void;
}

/**
 * general utility class
 */
declare class Utils {
    private static _can_console_styles;
    /**
     * indicates whether styled console output is possible
     * @returns true if styled console output is possible; false otherwise
     */
    static canConsoleStyles(): boolean;
    /**
     * checks whether the specified object is a real, non-empty string
     * @param str the object supposed to be a string
     * @returns true if the given object is a non-empty string; false other wise
     */
    static isString(str: unknown): boolean;
    /**
     * ensures that a string is returned
     * @param str the object supposed to be a string
     * @returns the given string if it is a valid string; an empty string otherwise
     */
    static ensureString(str: unknown): string;
    /**
     * checks whether the given name parameter is a valid string; throws an error if not
     * @param name a string specifying a name
     * @returns the given string
     */
    static ensureName(name: unknown): string;
    /**
     * checks whether all elements of the given array are valid strings; throws an error if not
     * @param names array of strings to be
     * @param errmsg optional error message that's thrown in the case of an error
     */
    static checkNames(names: any[], errmsg?: string): string[];
    /**
     * splits a path string into parts
     * @param path the path string
     * @returns {string[]} the configuration path
     */
    static splitPath(path: string): string[];
    /**
     * splits a logger name into a configuration path
     * @param {string} name logger name
     * @returns {string[]} the configuration path
     */
    static getPath(name: string): string[];
    /**
     * normalizes a logger name or path
     * @param name the logger name or path
     * @returns the normalized logger path
     */
    static normalizePath(name: string): string;
    /**
     * retrieves the stack trace
     * @param skip number of stack entries to skip
     * @returns the stack trace as string
     */
    static getStack(skip?: number): string;
    /**
     * retrieves the name of the calling function
     * @param skip number of stack entries to skip; 0 used default
     * @param separator optional separator character that replaces '.'
     * @returns the name of the calling function
     */
    static getFunctionName(skip?: number, separator?: string): string;
}

declare class PyroLogger implements Logger {
    private readonly _options;
    private readonly _styles;
    private readonly _styleProvider;
    private _level;
    private _name;
    private _writeFnc;
    private _fncOffset;
    private _suspended;
    private _pfxGenerator;
    private _appender;
    /**
     * constructs a new instance
     * @param n logger name
     * @param l initial logging level
     * @param wf flag whether to write the name of the calling function / method
     * @param a the optional appender
     */
    constructor(n: string, l: Level, wf: boolean, pg: PrefixGenerator, sp: StyleProvider, a: Appender | null);
    /**
     * @returns the name of this logger
     */
    get name(): string;
    /**
     * @returns {Level} the current logging level of this logger
     */
    get level(): Level;
    /**
     * @returns the flag whether to write the name of the calling function / method along with each logging output
     */
    get writeFnc(): boolean;
    /**
     * @returns the offset for the call stack used to get the name of the calling function
     */
    get fncOffset(): number;
    /**
     * @returns the "suspended" state of this logger
     */
    get suspended(): boolean;
    /**
     * sets a new logging level of this logger
     * @param {Level} l new logging level of this logger
     */
    setLevel(l: Level): void;
    /**
     * sets a new appender
     * @param a the new appender; may be null
     */
    setAppender(a: Appender | null): void;
    /**
     * sets a new prefix generator
     * @param pg the new prefix generator; must not be null
     */
    setPrefixGenerator(pg: PrefixGenerator): void;
    /**
     * sets the flag whether to write the name of the calling function / method along with each logging output
     * @param wf new value
     */
    setWriteFnc(wf: boolean): void;
    /**
     * updates the style definitions for this logger
     */
    updateStyles(): void;
    /**
     * @returns {String} a short informational string about this logger
     */
    toString(): string;
    /**
     * @override
     */
    isEnabledFor(l: Level): boolean;
    /**
     * @override
     */
    isDebugEnabled(): boolean;
    /**
     * @override
     */
    isTraceEnabled(): boolean;
    /**
     * creates the prefix text that's prepended to each logging output
     * @param l logging level
     * @returns the prefix text
     */
    private _getPrefix;
    /**
     * @returns true if this logger is currently suspended; false otherwise
     */
    private get _isSuspended();
    /**
     * adds a style value to the given style descriptor
     * @param dsc the current style descriptor
     * @param value the style value
     * @returns the new style descriptor
     */
    private _addStyleDsc;
    /**
     * creates a style descriptor from a style definition
     * @param style the style definition
     * @returns the style descriptor
     */
    private _createStyleDescriptor;
    /**
     * applies the style definition to the data to be logged
     * @param style the style definition
     * @param prefix the prefix text
     * @param data data to be logged
     * @returns the styled data to be logged
     */
    private _applyStyle;
    /**
     * @override
     */
    writeLog(l: Level, ...data: any[]): void;
    /**
     * @override
     */
    trace(...data: any[]): void;
    /**
     * @override
     */
    debug(...data: any[]): void;
    /**
     * @override
     */
    info(...data: any[]): void;
    /**
     * @override
     */
    warn(...data: any[]): void;
    /**
     * @override
     */
    error(...data: any[]): void;
    /**
     * @override
     */
    fatal(...data: any[]): void;
    /**
     * @override
     */
    writeStackTrace(l: Level, skip: number, message?: string): void;
    /**
     * @override
     */
    setFncOffset(offs: number): void;
    /**
     * @override
     */
    setSuspended(suspended: boolean): void;
    /**
     * @override
     */
    addStyle(level: Level, style: StyleDef): void;
}

declare class PyroLog {
    private _lf;
    private constructor();
    static _create(): PyroLog;
    /**
     * returns the singleton instance
     * @returns the singleton instance
     */
    static getInstance(): PyroLog;
    /**
     * the logger factory instance
     */
    get Factory(): LoggerFactory;
    /**
     * the name of the default configuration item
     */
    get defaultName(): string;
    /**
     * the default level for new loggers
     */
    get defaultLevel(): Level;
    /**
     * the stack trace as string
     */
    get stackTrace(): string;
    /**
     * the name of the calling function as string
     */
    get functionName(): string;
    /**
     * returns a logger
     * @param name logger name
     * @returns {Logger} the logger
     */
    getLogger(name: string): Logger;
    /**
     * sets global options
     * @param o an object providing one or more global options
     */
    setGlobalOptions(o: any): void;
    /**
     * creates a level style descriptor
     * @param param0
     * @returns the level style descriptor
     */
    createLevelStyle({ color, background, bold, italic, underline, linethrough }: {
        color?: ColorRef | undefined;
        background?: ColorRef | undefined;
        bold?: boolean | undefined;
        italic?: boolean | undefined;
        underline?: boolean | undefined;
        linethrough?: boolean | undefined;
    }): StyleDef;
    /**
     * creates a new callback appender
     * @param cf callback function
     * @param set flag whether to set this appender immediately
     * @returns the created appender
     */
    createAppender(cf: Function, set: boolean): Appender;
    /**
     * sets a new appender
     * @param appender the new appender, may be null
     */
    setAppender(appender: Appender | null): void;
    /**
     * sets a new prefix generator
     * @param generator new prefix generator
     */
    setPrefixGenerator(generator: PrefixGenerator | null): void;
    /**
     * creates a prefix generator
     * @param fn actual prefix generator function
     * @param set flag whether to set this prefix generator immediately as current prefix generator
     * @returns the created prefix generator instance
     */
    createPrefixGenerator(fn: (logger: Logger, level: Level) => string, set: boolean): PrefixGenerator;
    /**
     * creates a logger configuration item
     * @param name logger name
     * @param level logging level
     * @param wf flag whether to write the name of the calling function / method
     * @returns the created configuration item
     */
    createConfigItem(name: string, level: LevelStrings, wf?: Boolean | null): ConfigItem;
    /**
     * applies a logger configuration
     * @param config array of configuration items
     */
    applyConfiguration(config: ConfigItem[]): void;
    /**
     * sets the global style definition for a logging level
     * @param level the logging level
     * @param style the global style definition
     */
    setLevelStyle(level: Level, style: StyleDef): void;
    /**
     * writes the current stack trace to the specified logger
     * @param logger target logger
     * @param level logging level
     * @param message optional message text
     */
    writeStackTrace(logger: Logger, level: LevelStrings, message?: string): void;
}
declare const JsLevel: Readonly<{
    ALL: Level.ALL;
    TRACE: Level.TRACE;
    DEBUG: Level.DEBUG;
    INFO: Level.INFO;
    WARN: Level.WARN;
    ERROR: Level.ERROR;
    FATAL: Level.FATAL;
    OFF: Level.OFF;
}>;

export { Colors, JsLevel, Level, Level2LevelString, Level2String, PyroLog, Utils as PyroLogUtils, PyroLogger, String2Level, String2LevelString, forEachLevel };
export type { Appender, ColorRef, ConfigItem, LevelStrings, LevelStyles, Logger, PrefixGenerator, StyleDef, TextStyle };