@decaf-ts/logging 0.2.3 → 0.3.0

package/lib/esm/logging.d.ts

@@ -2,121 +2,207 @@ import { LoggerFactory, LoggingConfig, LoggingContext, StringLike, Theme, Logger
 import { LogLevel } from "./constants";
 /**
  * @description A minimal logger implementation.
- * @summary MiniLogger is a lightweight logging class that implements the VerbosityLogger interface.
- * It provides basic logging functionality with support for different log levels and verbosity.
+ * @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
+ * @class MiniLogger
+ * @example
+ * // Create a new logger for a class
+ * const logger = new MiniLogger('MyClass');
  *
- * @class
+ * // Log messages at different levels
+ * logger.info('This is an info message');
+ * logger.debug('This is a debug message');
+ * logger.error('Something went wrong');
+ *
+ * // Create a child logger for a specific method
+ * const methodLogger = logger.for('myMethod');
+ * methodLogger.verbose('Detailed information', 2);
+ *
+ * // Log with custom configuration
+ * logger.for('specialMethod', { style: true }).info('Styled message');
  */
 export declare class MiniLogger implements Logger {
     protected context: string;
     protected conf?: Partial<LoggingConfig> | undefined;
-    /**
-     * @description Creates a new MiniLogger instance.
-     * @summary Initializes a MiniLogger with the given class name, optional configuration, and method name.
-     *
-     * @param context - The name of the class using this logger.
-     * @param [conf] - Optional logging configuration. Defaults to Info level and verbosity 0.
-     * @param [id] - Optional unique identifier for the logger instance.
-     */
     constructor(context: string, conf?: Partial<LoggingConfig> | undefined);
     protected config(key: keyof LoggingConfig): LoggingConfig[keyof LoggingConfig];
-    for(method?: string | ((...args: any[]) => any), config?: Partial<LoggingConfig>, ...args: any[]): Logger;
     /**
-     * @description Creates a formatted log string.
-     * @summary Generates a log string with timestamp, colored log level, and message.
-     *
-     * @param level - The log level as a string.
-     * @param message
-     * @param stack
-     * @return A formatted log string.
+     * @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
+     */
+    for(method?: string | ((...args: any[]) => any), config?: Partial<LoggingConfig>): Logger;
+    /**
+     * @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} [stack] - Optional stack trace to include in the log
+     * @return {string} A formatted log string with all components
      */
     protected createLog(level: LogLevel, message: StringLike | Error, stack?: string): string;
     /**
-     * @description Logs a message with the specified log level.
+     * @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 log.
-     *
-     * @param level - The log level of the message.
-     * @param msg - The message to be logged.
-     * @param stack
+     * 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} [stack] - Optional stack trace to include in the log
+     * @return {void}
      */
     protected log(level: LogLevel, msg: StringLike | Error, stack?: string): void;
     /**
-     * @description LLogs a `way too verbose` or a silly message.
-     * @summary Logs a message at the Silly level if the current verbosity allows it.
-     *
-     * @param msg - The message to be logged.
-     * @param verbosity - The verbosity level of the message (default: 0).
+     * @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: StringLike, verbosity?: number): void;
     /**
-     * @description Logs a verbose message.
-     * @summary Logs a message at the Verbose level if the current verbosity allows it.
-     *
-     * @param msg - The message to be logged.
-     * @param verbosity - The verbosity level of the message (default: 0).
+     * @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: StringLike, verbosity?: number): void;
     /**
-     * @description Logs an info message.
-     * @summary Logs a message at the Info level.
-     *
-     * @param 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: StringLike): void;
     /**
-     * @description Logs a debug message.
-     * @summary Logs a message at the Debug level.
-     *
-     * @param 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: StringLike): void;
     /**
-     * @description Logs an error message.
-     * @summary Logs a message at the Error level.
-     *
-     * @param msg - The message to be logged.
+     * @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
+     * @return {void}
      */
     error(msg: StringLike | Error): void;
+    /**
+     * @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: Partial<LoggingConfig>): void;
 }
 /**
- * @description A static class for managing logging operations.
+ * @description A static class for managing logging operations
  * @summary The Logging class provides a centralized logging mechanism with support for
- * different log levels and verbosity. It uses a singleton pattern to maintain a global
+ * 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
+ * Logging.setConfig({ level: LogLevel.debug, style: true });
+ *
+ * // Get a logger for a specific class
+ * const logger = Logging.for('MyClass');
+ *
+ * // Log messages at different levels
+ * logger.info('Application started');
+ * logger.debug('Processing data...');
+ *
+ * // Log with context
+ * const methodLogger = Logging.for('MyClass.myMethod');
+ * methodLogger.verbose('Detailed operation information', 1);
+ *
+ * // Log errors
+ * try {
+ *   // some operation
+ * } catch (error) {
+ *   logger.error(error);
+ * }
+ * @mermaid
+ * classDiagram
+ *   class Logger {
+ *     <<interface>>
+ *     +for(method, config, ...args)
+ *     +silly(msg, verbosity)
+ *     +verbose(msg, verbosity)
+ *     +info(msg)
+ *     +debug(msg)
+ *     +error(msg)
+ *     +setConfig(config)
+ *   }
+ *
+ *   class Logging {
+ *     -global: Logger
+ *     -_factory: LoggerFactory
+ *     -_config: LoggingConfig
+ *     +setFactory(factory)
+ *     +setConfig(config)
+ *     +getConfig()
+ *     +get()
+ *     +verbose(msg, verbosity)
+ *     +info(msg)
+ *     +debug(msg)
+ *     +silly(msg)
+ *     +error(msg)
+ *     +for(object, config, ...args)
+ *     +because(reason, id)
+ *     +theme(text, type, loggerLevel, template)
+ *   }
  *
- * @class
+ *   class MiniLogger {
+ *     +constructor(context, conf?)
+ *   }
+ *
+ *   Logging ..> Logger : creates
+ *   Logging ..> MiniLogger : creates by default
  */
 export declare class Logging {
     /**
-     * @description The global logger instance.
-     * @summary A singleton instance of VerbosityLogger used for global logging.
+     * @description The global logger instance
+     * @summary A singleton instance of Logger used for global logging
      */
     private static global?;
     /**
-     * @description Factory function for creating logger instances.
-     * @summary A function that creates new VerbosityLogger instances. By default, it creates a MiniLogger.
+     * @description Factory function for creating logger instances
+     * @summary A function that creates new Logger instances. By default, it creates a MiniLogger.
      */
     private static _factory;
     /**
-     * @description Configuration for the logging system.
-     * @summary Stores the global verbosity level and log level settings.
+     * @description Configuration for the logging system
+     * @summary Stores the global logging configuration including verbosity, log level, styling, and formatting settings
      */
     private static _config;
+    private constructor();
     /**
-     * @description Private constructor to prevent instantiation.
-     * @summary Ensures that the Logging class cannot be instantiated as it's designed to be used statically.
+     * @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}
      */
-    private constructor();
     static setFactory(factory: LoggerFactory): void;
     /**
-     * @description Setter for the logging configuration.
-     * @summary Allows updating the global logging configuration.
-     *
-     * @param config - An object containing verbosity and log level settings.
+     * @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: Partial<LoggingConfig>): void;
+    /**
+     * @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(): LoggingConfig;
     /**
      * @description Retrieves or creates the global logger instance.
@@ -161,6 +247,14 @@ export declare class Logging {
      * @param msg - The message to be logged.
      */
     static error(msg: StringLike): void;
+    /**
+     * @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: LoggingContext, config?: Partial<LoggingConfig>, ...args: any[]): Logger;
     /**
      * @description Creates a logger for a specific reason or context.
@@ -173,5 +267,38 @@ export declare class Logging {
      * @returns A new VerbosityLogger or ClassLogger instance.
      */
     static because(reason: string, id?: string): Logger;
+    /**
+     * @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
+     * @mermaid
+     * sequenceDiagram
+     *   participant Caller
+     *   participant Theme as Logging.theme
+     *   participant Apply as apply function
+     *   participant Style as styled-string-builder
+     *
+     *   Caller->>Theme: theme(text, type, loggerLevel)
+     *   Theme->>Theme: Check if styling is enabled
+     *   alt styling disabled
+     *     Theme-->>Caller: return original text
+     *   else styling enabled
+     *     Theme->>Theme: Get theme for type
+     *     alt theme not found
+     *       Theme-->>Caller: return original text
+     *     else theme found
+     *       Theme->>Theme: Determine actual theme based on log level
+     *       Theme->>Apply: Apply each style property
+     *       Apply->>Style: Apply colors and formatting
+     *       Style-->>Apply: Return styled text
+     *       Apply-->>Theme: Return styled text
+     *       Theme-->>Caller: Return final styled text
+     *     end
+     *   end
+     */
     static theme(text: string, type: keyof Theme | keyof LogLevel, loggerLevel: LogLevel, template?: Theme): string;
 }