@decaf-ts/logging 0.10.0 → 0.10.2

package/lib/logging.cjs

@@ -1,18 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Logging = exports.MiniLogger = void 0;
+exports.Logging = exports.MiniLogger = exports.ROOT_CONTEXT_SYMBOL = void 0;
 const styled_string_builder_1 = require("styled-string-builder");
 const constants_1 = require("./constants.cjs");
 const text_1 = require("./text.cjs");
 const environment_1 = require("./environment.cjs");
 const utils_1 = require("./utils.cjs");
+exports.ROOT_CONTEXT_SYMBOL = Symbol("MiniLoggerRootContext");
 /**
  * @description A minimal logger implementation.
- * @summary MiniLogger is a lightweight logging class that implements the Logger interface.
- * It provides basic logging functionality with support for different log levels, verbosity,
- * context-aware logging, and customizable formatting.
- * @param {string} context - The context (typically class name) this logger is associated with
- * @param {Partial<LoggingConfig>} conf - Optional configuration to override global settings
+ * @summary MiniLogger is a lightweight logging class that implements the Logger interface. It provides basic logging functionality with support for different log levels, verbosity, context-aware logging, and customizable formatting.
+ * @param {string} [context] - The context (typically class name) this logger is associated with.
+ * @param {Partial<LoggingConfig>} [conf] - Optional configuration to override global settings.
+ * @param {string[]} [baseContext=[]] - The base context for the logger.
  * @class MiniLogger
  * @example
  * // Create a new logger for a class
@@ -31,9 +31,13 @@ const utils_1 = require("./utils.cjs");
  * logger.for('specialMethod', { style: true }).info('Styled message');
  */
 class MiniLogger {
-    constructor(context, conf) {
-        this.context = context;
+    constructor(context, conf, baseContext = []) {
         this.conf = conf;
+        this.baseContext = Array.isArray(baseContext) ? [...baseContext] : [];
+        if (context)
+            this.baseContext.push(context);
+        this.context = [...this.baseContext];
+        this[exports.ROOT_CONTEXT_SYMBOL] = [...this.baseContext];
     }
     config(key) {
         if (this.conf && key in this.conf)
@@ -41,17 +45,28 @@ class MiniLogger {
         return Logging.getConfig()[key];
     }
     /**
-     * @description Creates a child logger for a specific method or context
-     * @summary Returns a new logger instance with the current context extended by the specified method name
-     * @param {string | Function} method - The method name or function to create a logger for
-     * @param {Partial<LoggingConfig>} config - Optional configuration to override settings
-     * @param {...any[]} args - Additional arguments to pass to the logger factory
-     * @return {Logger} A new logger instance for the specified method
+     * @description Creates a child logger for a specific method or context.
+     * @summary Returns a new logger instance with the current context extended by the specified method name.
+     * @param {string | Function | object | Partial<LoggingConfig>} [method] - The method name, function, or configuration to create a logger for.
+     * @param {Partial<LoggingConfig>} [config] - Optional configuration to override settings.
+     * @param {...any[]} args - Additional arguments to pass to the logger factory.
+     * @return {Logger} A new logger instance for the specified method.
      */
     for(method, config, ...args // eslint-disable-line @typescript-eslint/no-unused-vars
     ) {
         let contextName;
         let childConfig = config;
+        const parentContext = Array.isArray(this.context)
+            ? [...this.context]
+            : typeof this.context === "string" && this.context
+                ? [this.context]
+                : [];
+        const rootCandidate = this[exports.ROOT_CONTEXT_SYMBOL];
+        const baseContext = Array.isArray(rootCandidate)
+            ? [...rootCandidate]
+            : Array.isArray(this.baseContext)
+                ? [...this.baseContext]
+                : [];
         if (typeof method === "string") {
             contextName = method;
         }
@@ -63,6 +78,9 @@ class MiniLogger {
                 childConfig = method;
             }
         }
+        let contextSegments = contextName
+            ? [...parentContext, contextName]
+            : [...parentContext];
         return new Proxy(this, {
             get: (target, p, receiver) => {
                 const result = Reflect.get(target, p, receiver);
@@ -75,37 +93,65 @@ class MiniLogger {
                             }
                             return Reflect.apply(target, receiver, argArray);
                         },
-                        get: (target, p) => {
-                            if (childConfig && p in childConfig)
-                                return childConfig[p];
-                            return Reflect.get(target, p, receiver);
+                        get: (target, key) => {
+                            if (childConfig && key in childConfig)
+                                return childConfig[key];
+                            return Reflect.get(target, key, receiver);
                         },
                     });
                 }
-                if (p === "context" && contextName) {
-                    return [result, contextName].join(".");
+                if (p === "clear") {
+                    return () => {
+                        contextSegments = [...baseContext];
+                        childConfig = undefined;
+                        return receiver;
+                    };
+                }
+                if (p === "context") {
+                    return contextSegments;
+                }
+                if (p === "root") {
+                    return [...baseContext];
+                }
+                if (p === exports.ROOT_CONTEXT_SYMBOL) {
+                    return baseContext;
+                }
+                if (p === "for") {
+                    return (...innerArgs) => {
+                        const originalContext = Array.isArray(target.context)
+                            ? [...target.context]
+                            : typeof target.context === "string" && target.context
+                                ? [target.context]
+                                : [];
+                        target.context = [...contextSegments];
+                        try {
+                            // eslint-disable-next-line prefer-spread
+                            return target.for.apply(target, innerArgs);
+                        }
+                        finally {
+                            target.context = originalContext;
+                        }
+                    };
                 }
                 return result;
             },
         });
     }
     /**
-     * @description Creates a formatted log string
-     * @summary Generates a log string with timestamp, colored log level, context, and message
-     * @param {LogLevel} level - The log level for this message
-     * @param {StringLike | Error} message - The message to log or an Error object
-     * @param {string} [error] - Optional error to extract stack trace to include in the log
-     * @return {string} A formatted log string with all components
+     * @description Creates a formatted log string.
+     * @summary Generates a log string with timestamp, colored log level, context, and message.
+     * @param {LogLevel} level - The log level for this message.
+     * @param {StringLike | Error} message - The message to log or an Error object.
+     * @param {Error} [error] - Optional error to extract stack trace to include in the log.
+     * @return {string} A formatted log string with all components.
      */
     createLog(level, message, error) {
         const log = {};
         const style = this.config("style");
         const separator = this.config("separator");
-        const app = this.config("app");
+        const app = Logging.getConfig().app;
         if (app)
-            log.app = style
-                ? Logging.theme(app, "app", level)
-                : app;
+            log.app = style ? Logging.theme(app, "app", level) : app;
         if (separator)
             log.separator = style
                 ? Logging.theme(separator, "separator", level)
@@ -122,10 +168,16 @@ class MiniLogger {
             log.level = lvl.toUpperCase();
         }
         if (this.config("context")) {
-            const context = style
-                ? Logging.theme(this.context, "class", level)
-                : this.context;
-            log.context = context;
+            const contextSegments = Array.isArray(this.context)
+                ? this.context
+                : typeof this.context === "string" && this.context
+                    ? [this.context]
+                    : [];
+            if (contextSegments.length) {
+                const joined = contextSegments.join(this.config("contextSeparator") || ".");
+                const context = style ? Logging.theme(joined, "class", level) : joined;
+                log.context = context;
+            }
         }
         if (this.config("correlationId")) {
             {
@@ -168,12 +220,11 @@ class MiniLogger {
         }
     }
     /**
-     * @description Logs a message with the specified log level
-     * @summary Checks if the message should be logged based on the current log level,
-     * then uses the appropriate console method to output the formatted log
-     * @param {LogLevel} level - The log level of the message
-     * @param {StringLike | Error} msg - The message to be logged or an Error object
-     * @param {string} [error] - Optional stack trace to include in the log
+     * @description Logs a message with the specified log level.
+     * @summary Checks if the message should be logged based on the current log level, then uses the appropriate console method to output the formatted log.
+     * @param {LogLevel} level - The log level of the message.
+     * @param {StringLike | Error} msg - The message to be logged or an Error object.
+     * @param {Error} [error] - Optional stack trace to include in the log.
      * @return {void}
      */
     log(level, msg, error) {
@@ -210,19 +261,19 @@ class MiniLogger {
         method(this.createLog(level, msg, error));
     }
     /**
-     * @description Logs a message at the benchmark level
-     * @summary Logs a message at the benchmark level if the current verbosity setting allows it
-     * @param {StringLike} msg - The message to be logged
+     * @description Logs a message at the benchmark level.
+     * @summary Logs a message at the benchmark level if the current verbosity setting allows it.
+     * @param {StringLike} msg - The message to be logged.
      * @return {void}
      */
     benchmark(msg) {
         this.log(constants_1.LogLevel.benchmark, msg);
     }
     /**
-     * @description Logs a message at the silly level
-     * @summary Logs a message at the silly level if the current verbosity setting allows it
-     * @param {StringLike} msg - The message to be logged
-     * @param {number} [verbosity=0] - The verbosity level of the message
+     * @description Logs a message at the silly level.
+     * @summary Logs a message at the silly level if the current verbosity setting allows it.
+     * @param {StringLike} msg - The message to be logged.
+     * @param {number} [verbosity=0] - The verbosity level of the message.
      * @return {void}
      */
     silly(msg, verbosity = 0) {
@@ -230,10 +281,10 @@ class MiniLogger {
             this.log(constants_1.LogLevel.silly, msg);
     }
     /**
-     * @description Logs a message at the verbose level
-     * @summary Logs a message at the verbose level if the current verbosity setting allows it
-     * @param {StringLike} msg - The message to be logged
-     * @param {number} [verbosity=0] - The verbosity level of the message
+     * @description Logs a message at the verbose level.
+     * @summary Logs a message at the verbose level if the current verbosity setting allows it.
+     * @param {StringLike} msg - The message to be logged.
+     * @param {number} [verbosity=0] - The verbosity level of the message.
      * @return {void}
      */
     verbose(msg, verbosity = 0) {
@@ -241,67 +292,77 @@ class MiniLogger {
             this.log(constants_1.LogLevel.verbose, msg);
     }
     /**
-     * @description Logs a message at the info level
-     * @summary Logs a message at the info level for general application information
-     * @param {StringLike} msg - The message to be logged
+     * @description Logs a message at the info level.
+     * @summary Logs a message at the info level for general application information.
+     * @param {StringLike} msg - The message to be logged.
      * @return {void}
      */
     info(msg) {
         this.log(constants_1.LogLevel.info, msg);
     }
     /**
-     * @description Logs a message at the debug level
-     * @summary Logs a message at the debug level for detailed troubleshooting information
-     * @param {StringLike} msg - The message to be logged
+     * @description Logs a message at the debug level.
+     * @summary Logs a message at the debug level for detailed troubleshooting information.
+     * @param {StringLike} msg - The message to be logged.
      * @return {void}
      */
     debug(msg) {
         this.log(constants_1.LogLevel.debug, msg);
     }
     /**
-     * @description Logs a message at the error level
-     * @summary Logs a message at the error level for errors and exceptions
-     * @param {StringLike | Error} msg - The message to be logged or an Error object
-     * @param e
+     * @description Logs a message at the error level.
+     * @summary Logs a message at the error level for errors and exceptions.
+     * @param {StringLike | Error} msg - The message to be logged or an Error object.
+     * @param {Error} [e] - Optional error to include in the log.
      * @return {void}
      */
     error(msg, e) {
         this.log(constants_1.LogLevel.error, msg, e);
     }
     /**
-     * @description Logs a message at the error level
-     * @summary Logs a message at the error level for errors and exceptions
-     * @param {StringLike} msg - The message to be logged or an Error object
+     * @description Logs a message at the warning level.
+     * @summary Logs a message at the warning level for potential issues.
+     * @param {StringLike} msg - The message to be logged.
      * @return {void}
      */
     warn(msg) {
         this.log(constants_1.LogLevel.warn, msg);
     }
     /**
-     * @description Logs a message at the error level
-     * @summary Logs a message at the error level for errors and exceptions
-     * @param {StringLike} msg - The message to be logged or an Error object
+     * @description Logs a message at the trace level.
+     * @summary Logs a message at the trace level for tracing code execution.
+     * @param {StringLike} msg - The message to be logged.
      * @return {void}
      */
     trace(msg) {
         this.log(constants_1.LogLevel.trace, msg);
     }
     /**
-     * @description Updates the logger configuration
-     * @summary Merges the provided configuration with the existing configuration
-     * @param {Partial<LoggingConfig>} config - The configuration options to apply
+     * @description Updates the logger configuration.
+     * @summary Merges the provided configuration with the existing configuration.
+     * @param {Partial<LoggingConfig>} config - The configuration options to apply.
      * @return {void}
      */
     setConfig(config) {
         this.conf = { ...(this.conf || {}), ...config };
     }
+    get root() {
+        return [...this.baseContext];
+    }
+    /**
+     * @description Clears any contextual overrides applied by `for`.
+     * @summary Returns the same logger instance so more contexts can be chained afterwards.
+     * @return {this} The same logger instance.
+     */
+    clear() {
+        this.context = [...this.baseContext];
+        return this;
+    }
 }
 exports.MiniLogger = MiniLogger;
 /**
- * @description A static class for managing logging operations
- * @summary The Logging class provides a centralized logging mechanism with support for
- * different log levels, verbosity, and styling. It uses a singleton pattern to maintain a global
- * logger instance and allows creating specific loggers for different classes and methods.
+ * @description A static class for managing logging operations.
+ * @summary The Logging class provides a centralized logging mechanism with support for different log levels, verbosity, and styling. It uses a singleton pattern to maintain a global logger instance and allows creating specific loggers for different classes and methods.
  * @class Logging
  * @example
  * // Set global configuration
@@ -364,27 +425,31 @@ exports.MiniLogger = MiniLogger;
  */
 class Logging {
     /**
-     * @description Factory function for creating logger instances
+     * @description Factory function for creating logger instances.
      * @summary A function that creates new Logger instances. By default, it creates a MiniLogger.
      */
     static { this._factory = (object, config) => {
-        return new MiniLogger(object, config);
+        const base = typeof environment_1.LoggedEnvironment.app === "string"
+            ? [environment_1.LoggedEnvironment.app]
+            : [];
+        return new MiniLogger(object, config, base);
     }; }
     static { this._config = environment_1.LoggedEnvironment; }
     constructor() { }
     /**
-     * @description Sets the factory function for creating logger instances
-     * @summary Allows customizing how logger instances are created
-     * @param {LoggerFactory} factory - The factory function to use for creating loggers
+     * @description Sets the factory function for creating logger instances.
+     * @summary Allows customizing how logger instances are created.
+     * @param {LoggerFactory} factory - The factory function to use for creating loggers.
      * @return {void}
      */
     static setFactory(factory) {
         Logging._factory = factory;
+        this.global = undefined;
     }
     /**
-     * @description Updates the global logging configuration
-     * @summary Allows updating the global logging configuration with new settings
-     * @param {Partial<LoggingConfig>} config - The configuration options to apply
+     * @description Updates the global logging configuration.
+     * @summary Allows updating the global logging configuration with new settings.
+     * @param {Partial<LoggingConfig>} config - The configuration options to apply.
      * @return {void}
      */
     static setConfig(config) {
@@ -393,9 +458,9 @@ class Logging {
         });
     }
     /**
-     * @description Gets a copy of the current global logging configuration
-     * @summary Returns a copy of the current global logging configuration
-     * @return {LoggingConfig} A copy of the current configuration
+     * @description Gets a copy of the current global logging configuration.
+     * @summary Returns a copy of the current global logging configuration.
+     * @return {LoggingConfig} A copy of the current configuration.
      */
     static getConfig() {
         return this._config;
@@ -403,19 +468,17 @@ class Logging {
     /**
      * @description Retrieves or creates the global logger instance.
      * @summary Returns the existing global logger or creates a new one if it doesn't exist.
-     *
-     * @return The global VerbosityLogger instance.
+     * @return {Logger} The global Logger instance.
      */
     static get() {
-        this.global = this.global ? this.global : this._factory("Logging");
-        return this.global;
+        return this.ensureRoot();
     }
     /**
      * @description Logs a verbose message.
      * @summary Delegates the verbose logging to the global logger instance.
-     *
-     * @param msg - The message to be logged.
-     * @param verbosity - The verbosity level of the message (default: 0).
+     * @param {StringLike} msg - The message to be logged.
+     * @param {number} [verbosity=0] - The verbosity level of the message.
+     * @return {void}
      */
     static verbose(msg, verbosity = 0) {
         return this.get().verbose(msg, verbosity);
@@ -423,17 +486,17 @@ class Logging {
     /**
      * @description Logs an info message.
      * @summary Delegates the info logging to the global logger instance.
-     *
-     * @param msg - The message to be logged.
+     * @param {StringLike} msg - The message to be logged.
+     * @return {void}
      */
     static info(msg) {
         return this.get().info(msg);
     }
     /**
-     * @description Logs an info message.
-     * @summary Delegates the info logging to the global logger instance.
-     *
-     * @param msg - The message to be logged.
+     * @description Logs a trace message.
+     * @summary Delegates the trace logging to the global logger instance.
+     * @param {StringLike} msg - The message to be logged.
+     * @return {void}
      */
     static trace(msg) {
         return this.get().trace(msg);
@@ -441,8 +504,8 @@ class Logging {
     /**
      * @description Logs a debug message.
      * @summary Delegates the debug logging to the global logger instance.
-     *
-     * @param msg - The message to be logged.
+     * @param {StringLike} msg - The message to be logged.
+     * @return {void}
      */
     static debug(msg) {
         return this.get().debug(msg);
@@ -450,26 +513,26 @@ class Logging {
     /**
      * @description Logs a benchmark message.
      * @summary Delegates the benchmark logging to the global logger instance.
-     *
-     * @param msg - The message to be logged.
+     * @param {StringLike} msg - The message to be logged.
+     * @return {void}
      */
     static benchmark(msg) {
         return this.get().benchmark(msg);
     }
     /**
      * @description Logs a silly message.
-     * @summary Delegates the debug logging to the global logger instance.
-     *
-     * @param msg - The message to be logged.
+     * @summary Delegates the silly logging to the global logger instance.
+     * @param {StringLike} msg - The message to be logged.
+     * @return {void}
      */
     static silly(msg) {
         return this.get().silly(msg);
     }
     /**
-     * @description Logs a silly message.
-     * @summary Delegates the debug logging to the global logger instance.
-     *
-     * @param msg - The message to be logged.
+     * @description Logs a warning message.
+     * @summary Delegates the warning logging to the global logger instance.
+     * @param {StringLike} msg - The message to be logged.
+     * @return {void}
      */
     static warn(msg) {
         return this.get().warn(msg);
@@ -477,49 +540,71 @@ class Logging {
     /**
      * @description Logs an error message.
      * @summary Delegates the error logging to the global logger instance.
-     *
-     * @param msg - The message to be logged.
-     * @param e
+     * @param {StringLike | Error} msg - The message to be logged.
+     * @param {Error} [e] - Optional error to include in the log.
+     * @return {void}
      */
     static error(msg, e) {
         return this.get().error(msg, e);
     }
     /**
-     * @description Creates a logger for a specific object or context
-     * @summary Creates a new logger instance for the given object or context using the factory function
-     * @param {LoggingContext} object - The object, class, or context to create a logger for
-     * @param {Partial<LoggingConfig>} [config] - Optional configuration to override global settings
-     * @param {...any} args - Additional arguments to pass to the logger factory
-     * @return {Logger} A new logger instance for the specified object or context
+     * @description Creates a logger for a specific object or context.
+     * @summary Creates a new logger instance for the given object or context using the factory function.
+     * @param {LoggingContext} object - The object, class, or context to create a logger for.
+     * @param {Partial<LoggingConfig>} [config] - Optional configuration to override global settings.
+     * @param {...any} args - Additional arguments to pass to the logger factory.
+     * @return {Logger} A new logger instance for the specified object or context.
      */
     static for(object, config, ...args) {
-        object =
-            typeof object === "string"
-                ? object
-                : object.constructor
-                    ? object.constructor.name
-                    : object.name;
-        return this._factory(object, config, ...args);
+        const root = this.global ? this.global : this.ensureRoot(args);
+        const callArgs = config !== undefined ? [object, config] : [object];
+        return root.for(...callArgs);
     }
     /**
-     * @description Creates a logger for a specific reason or correlation context
-     * @summary Utility to quickly create a logger labeled with a free-form reason and optional identifier
-     * so that ad-hoc operations can be traced without tying the logger to a class or method name.
-     * @param {string} reason - A textual reason or context label for this logger instance
-     * @param {string} [id] - Optional identifier to help correlate related log entries
-     * @return {Logger} A new logger instance labeled with the provided reason and id
+     * @description Creates a logger for a specific reason or correlation context.
+     * @summary Utility to quickly create a logger labeled with a free-form reason and optional identifier so that ad-hoc operations can be traced without tying the logger to a class or method name.
+     * @param {string} reason - A textual reason or context label for this logger instance.
+     * @param {string} [id] - Optional identifier to help correlate related log entries.
+     * @return {Logger} A new logger instance labeled with the provided reason and id.
      */
     static because(reason, id) {
-        return this._factory(reason, this._config, id);
+        const root = this.ensureRoot();
+        let logger = root.for(reason, this._config);
+        if (id)
+            logger = logger.for(id);
+        return logger;
+    }
+    static baseContext() {
+        const app = this._config.app;
+        return typeof app === "string" && app.length ? [app] : [];
+    }
+    static attachRootContext(logger) {
+        const base = logger.root && Array.isArray(logger.root)
+            ? [...logger.root]
+            : this.baseContext();
+        if (!logger.context ||
+            (Array.isArray(logger.context) &&
+                logger.context.length === 0)) {
+            logger.context = [...base];
+        }
+        logger[exports.ROOT_CONTEXT_SYMBOL] = [...base];
+        return logger;
+    }
+    static ensureRoot(extras = []) {
+        if (!this.global) {
+            const instance = this._factory(undefined, undefined, ...extras);
+            this.global = this.attachRootContext(instance);
+        }
+        return this.global;
     }
     /**
-     * @description Applies theme styling to text
-     * @summary Applies styling (colors, formatting) to text based on the theme configuration
-     * @param {string} text - The text to style
-     * @param {string} type - The type of element to style (e.g., "class", "message", "logLevel")
-     * @param {LogLevel} loggerLevel - The log level to use for styling
-     * @param {Theme} [template=DefaultTheme] - The theme to use for styling
-     * @return {string} The styled text
+     * @description Applies theme styling to text.
+     * @summary Applies styling (colors, formatting) to text based on the theme configuration.
+     * @param {string} text - The text to style.
+     * @param type - The type of element to style (e.g., "class", "message", "logLevel").
+     * @param {LogLevel} loggerLevel - The log level to use for styling.
+     * @param {Theme} [template=DefaultTheme] - The theme to use for styling.
+     * @return {string} The styled text.
      * @mermaid
      * sequenceDiagram
      *   participant Caller