@decaf-ts/logging 0.15.0 → 0.17.0

package/lib/types/filters/LogFilter.d.cts

@@ -0,0 +1,43 @@
+import { Logger, LoggingConfig, LoggingFilter } from "../types.cjs";
+import { LoggedClass } from "../LoggedClass.cjs";
+/**
+ * @description A base class for message filters that can be plugged into the logging pipeline.
+ * @summary This class extends {@link LoggedClass} to supply a scoped logger, and defines the contract that is required by {@link LoggingFilter} implementers that transform or drop log messages before emission.
+ * @class LogFilter
+ * @example
+ * class RedactSecretsFilter extends LogFilter {
+ *   filter(config: LoggingConfig, message: string): string {
+ *     return message.replace(/secret/gi, "***");
+ *   }
+ * }
+ *
+ * const filter = new RedactSecretsFilter();
+ * filter.filter({ ...DefaultLoggingConfig, verbose: 0 }, "secret token");
+ * @mermaid
+ * sequenceDiagram
+ *   participant Logger
+ *   participant Filter as LogFilter
+ *   participant Impl as ConcreteFilter
+ *   participant Output
+ *   Logger->>Filter: filter(config, message, context)
+ *   Filter->>Impl: delegate to subclass implementation
+ *   Impl-->>Filter: transformed message
+ *   Filter-->>Output: return filtered message
+ */
+export declare abstract class LogFilter extends LoggedClass implements LoggingFilter {
+    /**
+     * @description A scoped logger that excludes other filters from the chain.
+     * @summary This method returns a child logger that is dedicated to the filter, which prevents recursive filter invocation when emitting diagnostic messages.
+     * @return {Logger} A context-aware logger for the filter instance.
+     */
+    get log(): Logger;
+    /**
+     * @description Transforms or suppresses a log message.
+     * @summary This method inspects the provided message and context to produce the value that will be forwarded to subsequent filters or emitters.
+     * @param {LoggingConfig} config - The active logging configuration.
+     * @param {string} message - The original log message payload.
+     * @param {string[]} context - The context values that are attached to the message.
+     * @return {string} The filtered message to pass to downstream processing.
+     */
+    abstract filter(config: LoggingConfig, message: string, context: string[]): string;
+}

package/lib/types/filters/LogFilter.d.mts

@@ -0,0 +1,43 @@
+import { Logger, LoggingConfig, LoggingFilter } from "../types.js";
+import { LoggedClass } from "../LoggedClass.js";
+/**
+ * @description A base class for message filters that can be plugged into the logging pipeline.
+ * @summary This class extends {@link LoggedClass} to supply a scoped logger, and defines the contract that is required by {@link LoggingFilter} implementers that transform or drop log messages before emission.
+ * @class LogFilter
+ * @example
+ * class RedactSecretsFilter extends LogFilter {
+ *   filter(config: LoggingConfig, message: string): string {
+ *     return message.replace(/secret/gi, "***");
+ *   }
+ * }
+ *
+ * const filter = new RedactSecretsFilter();
+ * filter.filter({ ...DefaultLoggingConfig, verbose: 0 }, "secret token");
+ * @mermaid
+ * sequenceDiagram
+ *   participant Logger
+ *   participant Filter as LogFilter
+ *   participant Impl as ConcreteFilter
+ *   participant Output
+ *   Logger->>Filter: filter(config, message, context)
+ *   Filter->>Impl: delegate to subclass implementation
+ *   Impl-->>Filter: transformed message
+ *   Filter-->>Output: return filtered message
+ */
+export declare abstract class LogFilter extends LoggedClass implements LoggingFilter {
+    /**
+     * @description A scoped logger that excludes other filters from the chain.
+     * @summary This method returns a child logger that is dedicated to the filter, which prevents recursive filter invocation when emitting diagnostic messages.
+     * @return {Logger} A context-aware logger for the filter instance.
+     */
+    get log(): Logger;
+    /**
+     * @description Transforms or suppresses a log message.
+     * @summary This method inspects the provided message and context to produce the value that will be forwarded to subsequent filters or emitters.
+     * @param {LoggingConfig} config - The active logging configuration.
+     * @param {string} message - The original log message payload.
+     * @param {string[]} context - The context values that are attached to the message.
+     * @return {string} The filtered message to pass to downstream processing.
+     */
+    abstract filter(config: LoggingConfig, message: string, context: string[]): string;
+}

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

@@ -0,0 +1,56 @@
+import { LogFilter } from "./LogFilter.cjs";
+import { LoggingConfig } from "../types.cjs";
+/**
+ * @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/PatternFilter.d.mts

@@ -0,0 +1,56 @@
+import { LogFilter } from "./LogFilter.js";
+import { LoggingConfig } from "../types.js";
+/**
+ * @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.cts

@@ -0,0 +1,7 @@
+/**
+ * @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.cjs";
+export * from "./PatternFilter.cjs";

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

@@ -0,0 +1,7 @@
+/**
+ * @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.js";
+export * from "./PatternFilter.js";

package/lib/types/index.d.cts

@@ -0,0 +1,34 @@
+/**
+ * @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/index.cjs";
+export * from "./constants.cjs";
+export * from "./decorators.cjs";
+export * from "./environment.cjs";
+export * from "./LoggedClass.cjs";
+export * from "./logging.cjs";
+export * from "./logParameters.cjs";
+export * from "./text.cjs";
+export * from "./time.cjs";
+export * from "./types.cjs";
+export * from "./web.cjs";
+export * from "./utils.cjs";
+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/index.d.mts

@@ -0,0 +1,34 @@
+/**
+ * @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/index.js";
+export * from "./constants.js";
+export * from "./decorators.js";
+export * from "./environment.js";
+export * from "./LoggedClass.js";
+export * from "./logging.js";
+export * from "./logParameters.js";
+export * from "./text.js";
+export * from "./time.js";
+export * from "./types.js";
+export * from "./web.js";
+export * from "./utils.js";
+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.cts

@@ -0,0 +1,56 @@
+import { LogLevel } from "./constants.cjs";
+import { LogMeta, LoggingConfig } from "./types.cjs";
+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/logParameters.d.mts

@@ -0,0 +1,56 @@
+import { LogLevel } from "./constants.js";
+import { LogMeta, LoggingConfig } from "./types.js";
+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;