@decaf-ts/logging 0.15.0 → 0.16.0

package/lib/types/logging.d.cts

@@ -0,0 +1,373 @@
+import { LoggerFactory, LoggingConfig, LoggingContext, LoggingFilter, LogMeta, StringLike, Theme, Logger } from "./types.cjs";
+import { LogLevel } from "./constants.cjs";
+import { LogParameterDescriptor } from "./logParameters.cjs";
+import { LoggedEnvironment } from "./environment.cjs";
+export declare const ROOT_CONTEXT_SYMBOL: unique symbol;
+/**
+ * @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.
+ * @param {string[]} [baseContext=[]] - The base context for the logger.
+ * @class MiniLogger
+ * @example
+ * // Create a new logger for a class
+ * const logger = new MiniLogger('MyClass');
+ *
+ * // 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 conf?: Partial<LoggingConfig> | undefined;
+    protected context: string[];
+    protected baseContext: string[];
+    constructor(context?: string, conf?: Partial<LoggingConfig> | undefined, baseContext?: string[]);
+    protected config<K extends keyof LoggingConfig>(key: K): LoggingConfig[K];
+    for(config: Partial<LoggingConfig>): this;
+    for(method: string | ((...args: any[]) => any) | {
+        new (...args: any[]): any;
+    } | object): this;
+    for(method: string | ((...args: any[]) => any) | {
+        new (...args: any[]): any;
+    } | object | Partial<LoggingConfig>, config: Partial<LoggingConfig>, ...args: any[]): this;
+    protected getConfigSnapshot(): LoggingConfig;
+    protected getContextSegments(): string[];
+    protected resolveFilters(config: LoggingConfig): LoggingFilter[];
+    protected applyFilters(message: string, context: string[], config: LoggingConfig): string;
+    /**
+     * @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.
+     */
+    protected createLog(level: LogLevel, message: StringLike | Error, error?: Error, meta?: LogMeta): string;
+    private formatMeta;
+    protected normalizePatternSpacing(value: string): string;
+    /**
+     * @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}
+     */
+    protected log(level: LogLevel, msg: StringLike | Error, error?: Error, meta?: LogMeta): void;
+    /**
+     * @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.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    benchmark(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @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.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    silly(msg: StringLike, verbosityOrMeta?: number | LogMeta, meta?: LogMeta): void;
+    /**
+     * @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.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    verbose(msg: StringLike, verbosityOrMeta?: number | LogMeta, meta?: LogMeta): void;
+    /**
+     * @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.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    info(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @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.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    debug(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @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|object} [e] - Optional error or metadata to include in the log.
+     * @param {object} [meta] - Optional metadata to include with the entry when an error is supplied.
+     * @return {void}
+     */
+    error(msg: StringLike | Error, e?: Error | LogMeta, meta?: LogMeta): void;
+    /**
+     * @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.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    warn(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @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.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    trace(msg: StringLike, meta?: LogMeta): 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;
+    get root(): string[];
+    /**
+     * @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;
+}
+/**
+ * @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
+ * 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 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 Logger used for global logging.
+     */
+    private static global?;
+    /**
+     * @description Factory function for creating logger instances.
+     * @summary A function that creates new Logger instances. By default, it creates a MiniLogger.
+     */
+    private static _factory;
+    private static _config;
+    private 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.
+     * @return {void}
+     */
+    static setFactory(factory: LoggerFactory): void;
+    /**
+     * @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(): typeof LoggedEnvironment;
+    /**
+     * @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 {Logger} The global Logger instance.
+     */
+    static get(): Logger;
+    /**
+     * @description Logs a verbose message.
+     * @summary Delegates the verbose logging to the global logger instance.
+     * @param {StringLike} msg - The message to be logged.
+     * @param {number|object} [verbosity] - The verbosity level or metadata object.
+     * @param {object} [meta] - Optional metadata applied when a verbosity level is provided.
+     * @return {void}
+     */
+    static verbose(msg: StringLike, verbosityOrMeta?: number | LogMeta, meta?: LogMeta): void;
+    /**
+     * @description Logs an info message.
+     * @summary Delegates the info logging to the global logger instance.
+     * @param {StringLike} msg - The message to be logged.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    static info(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs a trace message.
+     * @summary Delegates the trace logging to the global logger instance.
+     * @param {StringLike} msg - The message to be logged.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    static trace(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs a debug message.
+     * @summary Delegates the debug logging to the global logger instance.
+     * @param {StringLike} msg - The message to be logged.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    static debug(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs a benchmark message.
+     * @summary Delegates the benchmark logging to the global logger instance.
+     * @param {StringLike} msg - The message to be logged.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    static benchmark(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs a silly message.
+     * @summary Delegates the silly logging to the global logger instance.
+     * @param {StringLike} msg - The message to be logged.
+     * @param {number|object} [verbosity] - The verbosity level or metadata object.
+     * @param {object} [meta] - Optional metadata applied when a verbosity level is provided.
+     * @return {void}
+     */
+    static silly(msg: StringLike, verbosityOrMeta?: number | LogMeta, meta?: LogMeta): void;
+    /**
+     * @description Logs a warning message.
+     * @summary Delegates the warning logging to the global logger instance.
+     * @param {StringLike} msg - The message to be logged.
+     * @param {object} [meta] - Optional metadata to include with the entry.
+     * @return {void}
+     */
+    static warn(msg: StringLike, meta?: LogMeta): void;
+    /**
+     * @description Logs an error message.
+     * @summary Delegates the error logging to the global logger instance.
+     * @param {StringLike | Error} msg - The message to be logged.
+     * @param {Error|object} [e] - Optional error or metadata to include in the log.
+     * @param {object} [meta] - Optional metadata to include with the entry when an error is supplied.
+     * @return {void}
+     */
+    static error(msg: StringLike | Error, e?: Error | LogMeta, meta?: LogMeta): 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 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: string, id?: string): Logger;
+    private static baseContext;
+    private static attachRootContext;
+    private static ensureRoot;
+    /**
+     * @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
+     *   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;
+    static register(descriptor: LogParameterDescriptor): import("./logParameters.cjs").LogParameterRegistry;
+    static unregister(key: string): import("./logParameters.cjs").LogParameterRegistry;
+}