@nu-art/logger 0.401.1

package/Logger.d.ts

@@ -0,0 +1,237 @@
+import { LogLevel, LogParam } from './types.js';
+import { DebugFlag } from './debug-flags.js';
+/**
+ * Base logging class that provides structured logging with debug flag integration.
+ *
+ * Logger instances are associated with a DebugFlag that controls:
+ * - Whether logging is enabled for this logger
+ * - The minimum log level that will be output
+ *
+ * Logging is filtered at two levels:
+ * 1. Debug flag must be enabled (`_DEBUG_FLAG.isEnabled()`)
+ * 2. Log level must meet the minimum threshold (`_DEBUG_FLAG.canLog(level)`)
+ *
+ * If either check fails, the log message is silently dropped.
+ *
+ * @example
+ * ```typescript
+ * class MyService extends Logger {
+ *   constructor() {
+ *     super('MyService');
+ *   }
+ *
+ *   doSomething() {
+ *     this.logInfo('Doing something');
+ *     this.logDebug('Debug details');
+ *   }
+ * }
+ * ```
+ */
+export declare class Logger {
+    /** Logging tag/identifier for this logger */
+    readonly tag: string;
+    /** Default enabled state for new debug flags */
+    static defaultFlagState: boolean;
+    /** Debug flag that controls logging for this instance */
+    protected readonly _DEBUG_FLAG: DebugFlag;
+    /**
+     * Creates a new Logger instance.
+     *
+     * Automatically creates a DebugFlag with the tag name. The flag is enabled
+     * by default (controlled by `Logger.defaultFlagState`).
+     *
+     * @param tag - Optional tag name. If not provided, uses the class name
+     */
+    constructor(tag?: string);
+    /**
+     * Sets the minimum log level for this logger.
+     *
+     * Only log messages at or above this level will be output. Lower-level
+     * messages are silently dropped.
+     *
+     * @param minLevel - Minimum log level (Verbose < Debug < Info < Warning < Error)
+     */
+    setMinLevel(minLevel: LogLevel): void;
+    /**
+     * Changes the logging tag and updates the associated debug flag.
+     *
+     * @param tag - New tag name
+     */
+    protected setTag(tag: string): void;
+    /**
+     * Logs a verbose-level message (lowest priority, most detailed).
+     */
+    logVerbose(...toLog: LogParam[]): void;
+    /**
+     * Logs a debug-level message (development/debugging information).
+     */
+    logDebug(...toLog: LogParam[]): void;
+    /**
+     * Logs an info-level message (general informational messages).
+     */
+    logInfo(...toLog: LogParam[]): void;
+    /**
+     * Logs a warning-level message (potential issues that don't stop execution).
+     */
+    logWarning(...toLog: LogParam[]): void;
+    /**
+     * Logs an error-level message (errors that may affect functionality).
+     */
+    logError(...toLog: LogParam[]): void;
+    /**
+     * Logs a verbose-level message with bold formatting.
+     */
+    logVerboseBold(...toLog: LogParam[]): void;
+    /**
+     * Logs a debug-level message with bold formatting.
+     */
+    logDebugBold(...toLog: LogParam[]): void;
+    /**
+     * Logs an info-level message with bold formatting.
+     */
+    logInfoBold(...toLog: LogParam[]): void;
+    /**
+     * Logs a warning-level message with bold formatting.
+     */
+    logWarningBold(...toLog: LogParam[]): void;
+    /**
+     * Logs an error-level message with bold formatting.
+     */
+    logErrorBold(...toLog: LogParam[]): void;
+    /**
+     * Core logging method that performs the actual log output.
+     *
+     * Checks if logging is enabled and the level meets the threshold before
+     * delegating to the BeLogged system. If either check fails, the message
+     * is silently dropped.
+     *
+     * @param level - Log level (Verbose, Debug, Info, Warning, Error)
+     * @param bold - Whether to apply bold formatting
+     * @param toLog - Array of values to log (can be strings, objects, etc.)
+     */
+    log(level: LogLevel, bold: boolean, toLog: LogParam[]): void;
+    /**
+     * Checks if a log message at the given level should be printed.
+     *
+     * Returns false if:
+     * - The debug flag is not enabled, OR
+     * - The log level is below the minimum threshold
+     *
+     * @param level - Log level to check
+     * @returns true if the message should be logged, false otherwise
+     */
+    private assertCanPrint;
+}
+/**
+ * Static logging utility class for use cases where instance-based logging isn't needed.
+ *
+ * Provides the same logging interface as Logger but with static methods that require
+ * a tag parameter for each log call. Useful for utility functions or standalone code
+ * that doesn't have a class instance.
+ *
+ * All static loggers share a single debug flag named 'StaticLogger'.
+ *
+ * @example
+ * ```typescript
+ * function utilityFunction() {
+ *   StaticLogger.logInfo('UtilityFunction', 'Processing data');
+ *   StaticLogger.logError('UtilityFunction', 'Error occurred', error);
+ * }
+ * ```
+ */
+export declare abstract class StaticLogger {
+    /** Shared debug flag for all static logging */
+    protected static readonly _DEBUG_FLAG: any;
+    /**
+     * Sets the minimum log level for static logging.
+     *
+     * @param minLevel - Minimum log level
+     */
+    static setMinLevel(minLevel: LogLevel): void;
+    /**
+     * Logs a verbose-level message with the given tag.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logVerbose(tag: string, ...toLog: LogParam[]): void;
+    /**
+     * Logs a debug-level message with the given tag.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logDebug(tag: string, ...toLog: LogParam[]): void;
+    /**
+     * Logs an info-level message with the given tag.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logInfo(tag: string, ...toLog: LogParam[]): void;
+    /**
+     * Logs a warning-level message with the given tag.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logWarning(tag: string, ...toLog: LogParam[]): void;
+    /**
+     * Logs an error-level message with the given tag.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logError(tag: string, ...toLog: LogParam[]): void;
+    /**
+     * Logs a verbose-level message with bold formatting.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logVerboseBold(tag: string, ...toLog: LogParam[]): void;
+    /**
+     * Logs a debug-level message with bold formatting.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logDebugBold(tag: string, ...toLog: LogParam[]): void;
+    /**
+     * Logs an info-level message with bold formatting.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logInfoBold(tag: string, ...toLog: LogParam[]): void;
+    /**
+     * Logs a warning-level message with bold formatting.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logWarningBold(tag: string, ...toLog: LogParam[]): void;
+    /**
+     * Logs an error-level message with bold formatting.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logErrorBold(tag: string, ...toLog: LogParam[]): void;
+    /**
+     * Core static logging method.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param toLog - Array of values to log
+     */
+    static log(tag: string, level: LogLevel, bold: boolean, toLog: LogParam[]): void;
+    /**
+     * Checks if a log message at the given level should be printed.
+     *
+     * @param level - Log level to check
+     * @returns true if the message should be logged, false otherwise
+     */
+    private static assertCanPrint;
+}

package/Logger.js

@@ -0,0 +1,316 @@
+/*
+ * @nu-art/logger - Flexible logging infrastructure with multiple output targets
+ * Copyright (C) 2024 Adam van der Kruk aka TacB0sS
+ * Licensed under the Apache License, Version 2.0
+ */
+import { LogLevel } from './types.js';
+import { BeLogged } from './BeLogged.js';
+import { DebugFlags } from './debug-flags.js';
+/**
+ * Base logging class that provides structured logging with debug flag integration.
+ *
+ * Logger instances are associated with a DebugFlag that controls:
+ * - Whether logging is enabled for this logger
+ * - The minimum log level that will be output
+ *
+ * Logging is filtered at two levels:
+ * 1. Debug flag must be enabled (`_DEBUG_FLAG.isEnabled()`)
+ * 2. Log level must meet the minimum threshold (`_DEBUG_FLAG.canLog(level)`)
+ *
+ * If either check fails, the log message is silently dropped.
+ *
+ * @example
+ * ```typescript
+ * class MyService extends Logger {
+ *   constructor() {
+ *     super('MyService');
+ *   }
+ *
+ *   doSomething() {
+ *     this.logInfo('Doing something');
+ *     this.logDebug('Debug details');
+ *   }
+ * }
+ * ```
+ */
+export class Logger {
+    /** Logging tag/identifier for this logger */
+    tag;
+    /** Default enabled state for new debug flags */
+    static defaultFlagState = true;
+    /** Debug flag that controls logging for this instance */
+    _DEBUG_FLAG;
+    /**
+     * Creates a new Logger instance.
+     *
+     * Automatically creates a DebugFlag with the tag name. The flag is enabled
+     * by default (controlled by `Logger.defaultFlagState`).
+     *
+     * @param tag - Optional tag name. If not provided, uses the class name
+     */
+    constructor(tag) {
+        this.tag = tag ?? this.constructor['name'];
+        this._DEBUG_FLAG = DebugFlags.createFlag(this.tag);
+        this._DEBUG_FLAG.enable(Logger.defaultFlagState);
+    }
+    /**
+     * Sets the minimum log level for this logger.
+     *
+     * Only log messages at or above this level will be output. Lower-level
+     * messages are silently dropped.
+     *
+     * @param minLevel - Minimum log level (Verbose < Debug < Info < Warning < Error)
+     */
+    setMinLevel(minLevel) {
+        this._DEBUG_FLAG.setMinLevel(minLevel);
+    }
+    /**
+     * Changes the logging tag and updates the associated debug flag.
+     *
+     * @param tag - New tag name
+     */
+    setTag(tag) {
+        // @ts-ignore
+        this['tag'] = tag;
+        this._DEBUG_FLAG.rename(tag);
+    }
+    /**
+     * Logs a verbose-level message (lowest priority, most detailed).
+     */
+    logVerbose(...toLog) {
+        this.log(LogLevel.Verbose, false, toLog);
+    }
+    /**
+     * Logs a debug-level message (development/debugging information).
+     */
+    logDebug(...toLog) {
+        this.log(LogLevel.Debug, false, toLog);
+    }
+    /**
+     * Logs an info-level message (general informational messages).
+     */
+    logInfo(...toLog) {
+        this.log(LogLevel.Info, false, toLog);
+    }
+    /**
+     * Logs a warning-level message (potential issues that don't stop execution).
+     */
+    logWarning(...toLog) {
+        this.log(LogLevel.Warning, false, toLog);
+    }
+    /**
+     * Logs an error-level message (errors that may affect functionality).
+     */
+    logError(...toLog) {
+        this.log(LogLevel.Error, false, toLog);
+    }
+    /**
+     * Logs a verbose-level message with bold formatting.
+     */
+    logVerboseBold(...toLog) {
+        this.log(LogLevel.Verbose, true, toLog);
+    }
+    /**
+     * Logs a debug-level message with bold formatting.
+     */
+    logDebugBold(...toLog) {
+        this.log(LogLevel.Debug, true, toLog);
+    }
+    /**
+     * Logs an info-level message with bold formatting.
+     */
+    logInfoBold(...toLog) {
+        this.log(LogLevel.Info, true, toLog);
+    }
+    /**
+     * Logs a warning-level message with bold formatting.
+     */
+    logWarningBold(...toLog) {
+        this.log(LogLevel.Warning, true, toLog);
+    }
+    /**
+     * Logs an error-level message with bold formatting.
+     */
+    logErrorBold(...toLog) {
+        this.log(LogLevel.Error, true, toLog);
+    }
+    /**
+     * Core logging method that performs the actual log output.
+     *
+     * Checks if logging is enabled and the level meets the threshold before
+     * delegating to the BeLogged system. If either check fails, the message
+     * is silently dropped.
+     *
+     * @param level - Log level (Verbose, Debug, Info, Warning, Error)
+     * @param bold - Whether to apply bold formatting
+     * @param toLog - Array of values to log (can be strings, objects, etc.)
+     */
+    log(level, bold, toLog) {
+        if (!this.assertCanPrint(level))
+            return;
+        // @ts-ignore
+        BeLogged.logImpl(this.tag, level, bold, toLog);
+    }
+    /**
+     * Checks if a log message at the given level should be printed.
+     *
+     * Returns false if:
+     * - The debug flag is not enabled, OR
+     * - The log level is below the minimum threshold
+     *
+     * @param level - Log level to check
+     * @returns true if the message should be logged, false otherwise
+     */
+    assertCanPrint(level) {
+        if (!this._DEBUG_FLAG.isEnabled())
+            return false;
+        return this._DEBUG_FLAG.canLog(level);
+    }
+}
+/**
+ * Static logging utility class for use cases where instance-based logging isn't needed.
+ *
+ * Provides the same logging interface as Logger but with static methods that require
+ * a tag parameter for each log call. Useful for utility functions or standalone code
+ * that doesn't have a class instance.
+ *
+ * All static loggers share a single debug flag named 'StaticLogger'.
+ *
+ * @example
+ * ```typescript
+ * function utilityFunction() {
+ *   StaticLogger.logInfo('UtilityFunction', 'Processing data');
+ *   StaticLogger.logError('UtilityFunction', 'Error occurred', error);
+ * }
+ * ```
+ */
+export class StaticLogger {
+    /** Shared debug flag for all static logging */
+    static _DEBUG_FLAG = DebugFlags.createFlag('StaticLogger');
+    static {
+        StaticLogger._DEBUG_FLAG.enable(Logger.defaultFlagState);
+    }
+    /**
+     * Sets the minimum log level for static logging.
+     *
+     * @param minLevel - Minimum log level
+     */
+    static setMinLevel(minLevel) {
+        this._DEBUG_FLAG.setMinLevel(minLevel);
+    }
+    /**
+     * Logs a verbose-level message with the given tag.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logVerbose(tag, ...toLog) {
+        this.log(tag, LogLevel.Verbose, false, toLog);
+    }
+    /**
+     * Logs a debug-level message with the given tag.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logDebug(tag, ...toLog) {
+        this.log(tag, LogLevel.Debug, false, toLog);
+    }
+    /**
+     * Logs an info-level message with the given tag.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logInfo(tag, ...toLog) {
+        this.log(tag, LogLevel.Info, false, toLog);
+    }
+    /**
+     * Logs a warning-level message with the given tag.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logWarning(tag, ...toLog) {
+        this.log(tag, LogLevel.Warning, false, toLog);
+    }
+    /**
+     * Logs an error-level message with the given tag.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logError(tag, ...toLog) {
+        this.log(tag, LogLevel.Error, false, toLog);
+    }
+    /**
+     * Logs a verbose-level message with bold formatting.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logVerboseBold(tag, ...toLog) {
+        this.log(tag, LogLevel.Verbose, true, toLog);
+    }
+    /**
+     * Logs a debug-level message with bold formatting.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logDebugBold(tag, ...toLog) {
+        this.log(tag, LogLevel.Debug, true, toLog);
+    }
+    /**
+     * Logs an info-level message with bold formatting.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logInfoBold(tag, ...toLog) {
+        this.log(tag, LogLevel.Info, true, toLog);
+    }
+    /**
+     * Logs a warning-level message with bold formatting.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logWarningBold(tag, ...toLog) {
+        this.log(tag, LogLevel.Warning, true, toLog);
+    }
+    /**
+     * Logs an error-level message with bold formatting.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param toLog - Values to log
+     */
+    static logErrorBold(tag, ...toLog) {
+        this.log(tag, LogLevel.Error, true, toLog);
+    }
+    /**
+     * Core static logging method.
+     *
+     * @param tag - Tag identifier for this log message
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param toLog - Array of values to log
+     */
+    static log(tag, level, bold, toLog) {
+        if (!this.assertCanPrint(level))
+            return;
+        // @ts-ignore
+        BeLogged.logImpl(tag, level, bold, toLog);
+    }
+    /**
+     * Checks if a log message at the given level should be printed.
+     *
+     * @param level - Log level to check
+     * @returns true if the message should be logged, false otherwise
+     */
+    static assertCanPrint(level) {
+        if (!this._DEBUG_FLAG.isEnabled())
+            return false;
+        return this._DEBUG_FLAG.canLog(level);
+    }
+}

package/debug-flags.d.ts

@@ -0,0 +1,145 @@
+import { LogLevel } from './types.js';
+/**
+ * Represents a debug flag that controls logging for a specific logger tag.
+ *
+ * Each DebugFlag controls two aspects of logging:
+ * 1. **Enabled state**: Whether logging is active for this flag
+ * 2. **Minimum log level**: The lowest log level that will be output
+ *
+ * DebugFlags are automatically registered with the DebugFlags singleton when created.
+ * They are typically created automatically by Logger instances using the logger's tag.
+ *
+ * @example
+ * ```typescript
+ * // Created automatically by Logger
+ * const logger = new Logger('MyService');
+ * // logger._DEBUG_FLAG is a DebugFlag with key 'MyService'
+ *
+ * // Or manually
+ * const flag = DebugFlags.createFlag('CustomTag', LogLevel.Debug);
+ * flag.enable();
+ * flag.setMinLevel(LogLevel.Warning);
+ * ```
+ */
+export declare class DebugFlag {
+    /** Default minimum log level for new debug flags */
+    static DefaultLogLevel: LogLevel;
+    /** Unique identifier for this debug flag (typically matches logger tag) */
+    private key;
+    /** Minimum log level that will be output when this flag is enabled */
+    private minLogLevel;
+    /**
+     * Creates a new DebugFlag and automatically registers it with DebugFlags.
+     *
+     * @param key - Unique identifier for this flag
+     * @param minLogLevel - Minimum log level (defaults to DebugFlag.DefaultLogLevel)
+     */
+    private constructor();
+    /**
+     * Sets the minimum log level for this flag.
+     *
+     * Only log messages at or above this level will be output when the flag is enabled.
+     *
+     * @param minLogLevel - Minimum log level (Verbose < Debug < Info < Warning < Error)
+     */
+    setMinLevel(minLogLevel: LogLevel): void;
+    /**
+     * Renames this debug flag (updates the key).
+     *
+     * Useful when a logger's tag changes. Updates the registration in DebugFlags.
+     *
+     * @param newKey - New key/identifier for this flag
+     */
+    rename(newKey: string): void;
+    /**
+     * Gets the unique key/identifier for this flag.
+     */
+    getKey(): string;
+    /**
+     * Enables or disables this debug flag.
+     *
+     * When disabled, all logging for this flag is suppressed regardless of log level.
+     * When enabled, logging is controlled by the minimum log level.
+     *
+     * @param enable - If true, enables the flag. If false, disables it. Defaults to true.
+     */
+    enable(enable?: boolean): void;
+    /**
+     * Checks if this debug flag is currently enabled.
+     *
+     * @returns true if enabled, false otherwise
+     */
+    isEnabled(): boolean;
+    /**
+     * Checks if a log message at the given level should be output.
+     *
+     * Returns true if:
+     * - The flag is enabled, AND
+     * - The log level is at or above the minimum log level
+     *
+     * @param level - Log level to check
+     * @returns true if the message should be logged, false otherwise
+     */
+    canLog(level: LogLevel): boolean;
+    /**
+     * Enables this flag by adding it to the active flags list.
+     */
+    private _enable;
+    /**
+     * Disables this flag by removing it from the active flags list.
+     */
+    private _disable;
+}
+/**
+ * Singleton manager for all debug flags in the application.
+ *
+ * Maintains a registry of all DebugFlag instances and tracks which flags are
+ * currently active (enabled). Provides factory methods for creating flags.
+ *
+ * DebugFlags are used throughout the application to control logging granularity
+ * - you can enable/disable logging for specific modules or services by toggling
+ * their associated debug flags.
+ */
+export declare class DebugFlags {
+    /** Singleton instance of DebugFlags */
+    static readonly instance: DebugFlags;
+    /** Registry of all debug flags, keyed by their identifier */
+    readonly AllDebugFlags: {
+        [k: string]: DebugFlag;
+    };
+    /** List of keys for currently enabled (active) debug flags */
+    readonly ActiveDebugFlags: string[];
+    /**
+     * Private constructor enforces singleton pattern.
+     */
+    private constructor();
+    /**
+     * Creates a new DebugFlag and registers it.
+     *
+     * This is the only way to create DebugFlag instances (constructor is private).
+     * The flag is automatically registered in AllDebugFlags.
+     *
+     * @param key - Unique identifier for the flag
+     * @param minLogLevel - Minimum log level (defaults to DebugFlag.DefaultLogLevel)
+     * @returns The newly created DebugFlag
+     */
+    static createFlag(key: string, minLogLevel?: LogLevel): any;
+    /**
+     * Registers a debug flag in the AllDebugFlags registry.
+     *
+     * Called automatically when a DebugFlag is created. Should not be called directly.
+     *
+     * @param flag - DebugFlag to register
+     */
+    static add(flag: DebugFlag): void;
+    /**
+     * Renames a debug flag by updating its key in the registry.
+     *
+     * Moves the flag from the old key to the new key in AllDebugFlags.
+     * Also updates the flag's internal key via the flag's rename method.
+     *
+     * @param previousKey - Current key of the flag
+     * @param newKey - New key for the flag
+     */
+    static rename(previousKey: string, newKey: string): void;
+}