@decaf-ts/logging 0.20.0 → 0.21.1

package/lib/types/filters/PatternFilter.d.ts

@@ -1,56 +0,0 @@
-import { LogFilter } from "./LogFilter";
-import { LoggingConfig } from "../types";
-/**
- * @description A replacement callback that is used to transform RegExp matches.
- * @summary This function receives the matched substring and additional capture arguments, and returns the replacement text that will be injected into the log message.
- * @typedef {function(string, ...any): string} ReplacementFunction
- * @memberOf module:Logging
- */
-export type ReplacementFunction = (substring: string, ...args: any[]) => string;
-/**
- * @description A filter that patches log messages using regular expressions.
- * @summary This class applies a configured {@link RegExp} and replacement strategy to redact, mask, or restructure log payloads before they are emitted.
- * @param {RegExp} regexp - The expression to use for detecting sensitive or formatted text.
- * @param {(string|ReplacementFunction)} replacement - The replacement string or a callback that is invoked for each match.
- * @class PatternFilter
- * @example
- * const filter = new PatternFilter(/token=[^&]+/g, "token=***");
- * const sanitized = filter.filter(config, "token=123&user=tom", []);
- * // sanitized === "token=***&user=tom"
- * @mermaid
- * sequenceDiagram
- *   participant Logger
- *   participant Filter as PatternFilter
- *   participant RegExp
- *   Logger->>Filter: filter(config, message, context)
- *   Filter->>RegExp: execute match()
- *   alt match found
- *     RegExp-->>Filter: captures
- *     Filter->>RegExp: replace(message, replacement)
- *     RegExp-->>Filter: transformed message
- *   else no match
- *     RegExp-->>Filter: null
- *   end
- *   Filter-->>Logger: sanitized message
- */
-export declare class PatternFilter extends LogFilter {
-    protected readonly regexp: RegExp;
-    protected readonly replacement: string | ReplacementFunction;
-    constructor(regexp: RegExp, replacement: string | ReplacementFunction);
-    /**
-     * @description Ensures deterministic RegExp matching.
-     * @summary This method runs the configured expression, then resets its state so that repeated invocations behave consistently.
-     * @param {string} message - The message to test for matches.
-     * @return {(RegExpExecArray|null)} The match result, or null if no match is found.
-     */
-    protected match(message: string): RegExpExecArray | null;
-    /**
-     * @description Applies the replacement strategy to the incoming message.
-     * @summary This method executes {@link PatternFilter.match} and, when a match is found, replaces every occurrence using the configured replacement handler.
-     * @param {LoggingConfig} config - The active logging configuration (unused, but part of the filter contract).
-     * @param {string} message - The message to be sanitized.
-     * @param {string[]} context - The context entries that are associated with the log event.
-     * @return {string} The sanitized log message.
-     */
-    filter(config: LoggingConfig, message: string, context: string[]): string;
-}

package/lib/types/filters/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * @description Exports for the filters module.
- * @summary This file exports all the necessary components for the filters functionality, including LogFilter and PatternFilter.
- * @module logging/filters
- */
-export * from "./LogFilter";
-export * from "./PatternFilter";

package/lib/types/index.d.ts

@@ -1,34 +0,0 @@
-/**
- * @module Logging
- * @description A comprehensive and versatile logging toolkit for both browser and Node.js environments.
- * @summary This module provides a complete logging solution, exposing {@link Logging} and {@link MiniLogger} for runtime logging. It also includes decorators like {@link log} for method instrumentation, and various utilities such as {@link PatternFilter}, {@link StopWatch}, and {@link LoggedEnvironment} to help build configurable and theme-aware log pipelines.
- */
-export * from "./filters";
-export * from "./constants";
-export * from "./decorators";
-export * from "./environment";
-export * from "./LoggedClass";
-export * from "./logging";
-export * from "./logParameters";
-export * from "./text";
-export * from "./time";
-export * from "./types";
-export * from "./web";
-export * from "./utils";
-export * from "styled-string-builder";
-/**
- * @description Current package version string.
- * @summary Stores the package version for diagnostics and compatibility checks.
- * @const VERSION
- * @type {string}
- * @memberOf module:Logging
- */
-export declare const VERSION: string;
-/**
- * @description Current package version string.
- * @summary Stores the package version for diagnostics and compatibility checks.
- * @const PACKAGE_NAME
- * @type {string}
- * @memberOf module:Logging
- */
-export declare const PACKAGE_NAME: string;

package/lib/types/logParameters.d.ts

@@ -1,56 +0,0 @@
-import { LogLevel } from "./constants";
-import { LogMeta, LoggingConfig } from "./types";
-export type LogParameterPayload = {
-    config: LoggingConfig;
-    level: LogLevel;
-    context: string[];
-    timestamp?: string;
-    app?: string;
-    separator?: string;
-    correlationId?: string;
-    rawMessage: string;
-    filteredMessage: string;
-    meta?: LogMeta;
-    metaString?: string;
-    stack?: string;
-    stackLabel?: string;
-    applyTheme(value: string, type: string): string;
-};
-export interface LogParameterDescriptor {
-    key: string;
-    render(payload: LogParameterPayload): string | undefined;
-    style?(rendered: string, payload: LogParameterPayload): string;
-    shouldInclude?(payload: LogParameterPayload): boolean;
-}
-export interface LogPatternLiteralSegment {
-    type: "literal";
-    value: string;
-}
-export interface LogPatternParameterSegment {
-    type: "parameter";
-    key: string;
-}
-export interface LogPatternOptionalSegment {
-    type: "optional";
-    prefix: string;
-    suffix: string;
-    children: LogPatternSegment[];
-}
-export type LogPatternSegment = LogPatternLiteralSegment | LogPatternParameterSegment | LogPatternOptionalSegment;
-export type LogPatternDefinition = {
-    pattern: string;
-    segments: LogPatternSegment[];
-    keys: string[];
-    includesMeta: boolean;
-};
-export declare class LogParameterRegistry {
-    private readonly descriptors;
-    register(descriptor: LogParameterDescriptor): this;
-    unregister(key: string): this;
-    get(key: string): LogParameterDescriptor | undefined;
-    render(payload: LogParameterPayload, keys: string[]): Record<string, string>;
-    keys(): string[];
-}
-export declare function compileLogPattern(pattern: string): LogPatternDefinition;
-export declare function renderPattern(definition: LogPatternDefinition, rendered: Record<string, string>): string;
-export declare const logParameterRegistry: LogParameterRegistry;

package/lib/types/logging.d.ts

@@ -1,373 +0,0 @@
-import { LoggerFactory, LoggingConfig, LoggingContext, LoggingFilter, LogMeta, StringLike, Theme, Logger } from "./types";
-import { LogLevel } from "./constants";
-import { LogParameterDescriptor } from "./logParameters";
-import { LoggedEnvironment } from "./environment";
-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").LogParameterRegistry;
-    static unregister(key: string): import("./logParameters").LogParameterRegistry;
-}

package/lib/types/pino/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * @module Pino
- * @description This module provides an adapter for the Pino logger.
- * @summary This module exports the {@link PinoLogger} class.
- * @memberOf module:Logging
- */
-export * from "./pino";

package/lib/types/pino/pino.d.ts

@@ -1,29 +0,0 @@
-import { Logger as PinoBaseLogger } from "pino";
-import { MiniLogger } from "../logging";
-import { Logger, LoggerFactory, LogMeta, LoggingConfig, StringLike } from "../types";
-import { LogLevel } from "../constants";
-/**
- * @description A logger that is powered by the Pino logging library.
- * @summary This class extends {@link MiniLogger} and uses Pino as its underlying logging engine.
- * @param {string} [context] - The context (typically the class name) that this logger is associated with.
- * @param {Partial<LoggingConfig>} [conf] - Optional configuration to override global settings.
- * @param {PinoBaseLogger} [driver] - An optional, pre-existing Pino logger instance to use.
- * @class PinoLogger
- */
-export declare class PinoLogger extends MiniLogger implements Logger {
-    protected pino: PinoBaseLogger;
-    constructor(context?: string, conf?: Partial<LoggingConfig>, driver?: PinoBaseLogger);
-    protected log(level: LogLevel, msg: StringLike | Error, error?: Error, meta?: LogMeta): void;
-    fatal(msg: StringLike | Error, error?: Error, meta?: LogMeta): void;
-    child(bindings?: Record<string, unknown>, options?: Record<string, unknown>): PinoLogger;
-    flush(): void | Promise<void>;
-    get level(): string | undefined;
-    set level(value: string | undefined);
-}
-/**
- * @description A factory for creating {@link PinoLogger} instances.
- * @summary This factory function creates a new {@link PinoLogger} instance, and can optionally accept a pre-existing Pino logger instance.
- * @const {LoggerFactory} PinoFactory
- * @memberOf module:Logging
- */
-export declare const PinoFactory: LoggerFactory;