@nu-art/logger 0.401.1

package/debug-flags.js

@@ -0,0 +1,196 @@
+/*
+ * @nu-art/logger - Flexible logging infrastructure with multiple output targets
+ * Copyright (C) 2024 Adam van der Kruk aka TacB0sS
+ * Licensed under the Apache License, Version 2.0
+ */
+import { LogLevel, LogLevelOrdinal } from './types.js';
+/**
+ * Represents a debug flag that controls logging for a specific logger tag.
+ *
+ * Each DebugFlag controls two aspects of logging:
+ * 1. **Enabled state**: Whether logging is active for this flag
+ * 2. **Minimum log level**: The lowest log level that will be output
+ *
+ * DebugFlags are automatically registered with the DebugFlags singleton when created.
+ * They are typically created automatically by Logger instances using the logger's tag.
+ *
+ * @example
+ * ```typescript
+ * // Created automatically by Logger
+ * const logger = new Logger('MyService');
+ * // logger._DEBUG_FLAG is a DebugFlag with key 'MyService'
+ *
+ * // Or manually
+ * const flag = DebugFlags.createFlag('CustomTag', LogLevel.Debug);
+ * flag.enable();
+ * flag.setMinLevel(LogLevel.Warning);
+ * ```
+ */
+export class DebugFlag {
+    /** Default minimum log level for new debug flags */
+    static DefaultLogLevel = LogLevel.Info;
+    /** Unique identifier for this debug flag (typically matches logger tag) */
+    key;
+    /** Minimum log level that will be output when this flag is enabled */
+    minLogLevel;
+    /**
+     * Creates a new DebugFlag and automatically registers it with DebugFlags.
+     *
+     * @param key - Unique identifier for this flag
+     * @param minLogLevel - Minimum log level (defaults to DebugFlag.DefaultLogLevel)
+     */
+    constructor(key, minLogLevel = DebugFlag.DefaultLogLevel) {
+        this.key = key;
+        this.minLogLevel = minLogLevel;
+        DebugFlags.add(this);
+    }
+    /**
+     * Sets the minimum log level for this flag.
+     *
+     * Only log messages at or above this level will be output when the flag is enabled.
+     *
+     * @param minLogLevel - Minimum log level (Verbose < Debug < Info < Warning < Error)
+     */
+    setMinLevel(minLogLevel) {
+        this.minLogLevel = minLogLevel;
+    }
+    /**
+     * Renames this debug flag (updates the key).
+     *
+     * Useful when a logger's tag changes. Updates the registration in DebugFlags.
+     *
+     * @param newKey - New key/identifier for this flag
+     */
+    rename(newKey) {
+        const oldKey = this.key;
+        DebugFlags.rename(oldKey, newKey);
+        this.key = newKey;
+        // Update ActiveDebugFlags if the flag is enabled
+        const activeIndex = DebugFlags.instance.ActiveDebugFlags.indexOf(oldKey);
+        if (activeIndex > -1) {
+            DebugFlags.instance.ActiveDebugFlags[activeIndex] = newKey;
+        }
+    }
+    /**
+     * Gets the unique key/identifier for this flag.
+     */
+    getKey() {
+        return this.key;
+    }
+    /**
+     * Enables or disables this debug flag.
+     *
+     * When disabled, all logging for this flag is suppressed regardless of log level.
+     * When enabled, logging is controlled by the minimum log level.
+     *
+     * @param enable - If true, enables the flag. If false, disables it. Defaults to true.
+     */
+    enable(enable = true) {
+        if (this.isEnabled() === enable)
+            return;
+        if (enable)
+            this._enable();
+        else
+            this._disable();
+    }
+    /**
+     * Checks if this debug flag is currently enabled.
+     *
+     * @returns true if enabled, false otherwise
+     */
+    isEnabled() {
+        return DebugFlags.instance.ActiveDebugFlags.includes(this.key);
+    }
+    /**
+     * Checks if a log message at the given level should be output.
+     *
+     * Returns true if:
+     * - The flag is enabled, AND
+     * - The log level is at or above the minimum log level
+     *
+     * @param level - Log level to check
+     * @returns true if the message should be logged, false otherwise
+     */
+    canLog(level) {
+        if (!this.isEnabled())
+            return false;
+        return LogLevelOrdinal.indexOf(level) >= LogLevelOrdinal.indexOf(this.minLogLevel);
+    }
+    /**
+     * Enables this flag by adding it to the active flags list.
+     */
+    _enable() {
+        DebugFlags.instance.ActiveDebugFlags.push(this.key);
+    }
+    /**
+     * Disables this flag by removing it from the active flags list.
+     */
+    _disable() {
+        const index = DebugFlags.instance.ActiveDebugFlags.indexOf(this.key);
+        if (index > -1)
+            DebugFlags.instance.ActiveDebugFlags.splice(index, 1);
+    }
+}
+/**
+ * Singleton manager for all debug flags in the application.
+ *
+ * Maintains a registry of all DebugFlag instances and tracks which flags are
+ * currently active (enabled). Provides factory methods for creating flags.
+ *
+ * DebugFlags are used throughout the application to control logging granularity
+ * - you can enable/disable logging for specific modules or services by toggling
+ * their associated debug flags.
+ */
+export class DebugFlags {
+    /** Singleton instance of DebugFlags */
+    static instance = new DebugFlags();
+    /** Registry of all debug flags, keyed by their identifier */
+    AllDebugFlags = {};
+    /** List of keys for currently enabled (active) debug flags */
+    ActiveDebugFlags = [];
+    /**
+     * Private constructor enforces singleton pattern.
+     */
+    constructor() {
+    }
+    /**
+     * Creates a new DebugFlag and registers it.
+     *
+     * This is the only way to create DebugFlag instances (constructor is private).
+     * The flag is automatically registered in AllDebugFlags.
+     *
+     * @param key - Unique identifier for the flag
+     * @param minLogLevel - Minimum log level (defaults to DebugFlag.DefaultLogLevel)
+     * @returns The newly created DebugFlag
+     */
+    static createFlag(key, minLogLevel = DebugFlag.DefaultLogLevel) {
+        // @ts-ignore
+        return new DebugFlag(key, minLogLevel);
+    }
+    /**
+     * Registers a debug flag in the AllDebugFlags registry.
+     *
+     * Called automatically when a DebugFlag is created. Should not be called directly.
+     *
+     * @param flag - DebugFlag to register
+     */
+    static add(flag) {
+        this.instance.AllDebugFlags[flag.getKey()] = flag;
+    }
+    /**
+     * Renames a debug flag by updating its key in the registry.
+     *
+     * Moves the flag from the old key to the new key in AllDebugFlags.
+     * Also updates the flag's internal key via the flag's rename method.
+     *
+     * @param previousKey - Current key of the flag
+     * @param newKey - New key for the flag
+     */
+    static rename(previousKey, newKey) {
+        const flag = this.instance.AllDebugFlags[previousKey];
+        if (!flag)
+            return;
+        delete this.instance.AllDebugFlags[previousKey];
+        this.instance.AllDebugFlags[newKey] = flag;
+    }
+}

package/get-log-style.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CSS style properties for console.log() styling.
+ *
+ * Used with the `%c` format specifier in console.log() to apply CSS styles.
+ */
+export type LogStyle = {
+    'color'?: string;
+    'background-color'?: string;
+    'padding'?: string;
+    'border-radius'?: string;
+};
+/**
+ * Generates a CSS style string for console.log() formatting.
+ *
+ * Combines multiple style objects into a single CSS string compatible with
+ * the `%c` format specifier in console.log().
+ *
+ * **Usage**:
+ * ```typescript
+ * const style = getLogStyle({color: 'red', 'background-color': 'yellow'});
+ * console.log('%cStyled text', style, 'normal text');
+ * ```
+ *
+ * @param styleObj - One or more style objects (merged together)
+ * @returns CSS style string
+ */
+export declare function getLogStyle(...styleObj: LogStyle[]): string;

package/get-log-style.js

@@ -0,0 +1,29 @@
+/*
+ * @nu-art/logger - Flexible logging infrastructure with multiple output targets
+ * Copyright (C) 2024 Adam van der Kruk aka TacB0sS
+ * Licensed under the Apache License, Version 2.0
+ */
+/**
+ * Generates a CSS style string for console.log() formatting.
+ *
+ * Combines multiple style objects into a single CSS string compatible with
+ * the `%c` format specifier in console.log().
+ *
+ * **Usage**:
+ * ```typescript
+ * const style = getLogStyle({color: 'red', 'background-color': 'yellow'});
+ * console.log('%cStyled text', style, 'normal text');
+ * ```
+ *
+ * @param styleObj - One or more style objects (merged together)
+ * @returns CSS style string
+ */
+export function getLogStyle(...styleObj) {
+    let style = '';
+    styleObj.forEach(obj => {
+        const _arr = Object.keys(obj).map((key) => `${key}: ${obj[key]}`);
+        style += _arr.join(';');
+        style += ';';
+    });
+    return style;
+}

package/index.d.ts

@@ -0,0 +1,15 @@
+export * from './Logger.js';
+export * from './BeLogged.js';
+export * from './LogClient.js';
+export * from './types.js';
+export * from './debug-flags.js';
+export * from './LogClient_Terminal.js';
+export * from './LogClient_Browser.js';
+export * from './LogClient_BrowserGroups.js';
+export * from './LogClient_File.js';
+export * from './LogClient_MemBuffer.js';
+export * from './LogClient_Function.js';
+export * from './LogClient_ConsoleProxy.js';
+export * from './LogClient_BaseRotate.js';
+export * from './get-log-style.js';
+export * from './utils.js';

package/index.js

@@ -0,0 +1,20 @@
+/*
+ * @nu-art/logger - Flexible logging infrastructure with multiple output targets
+ * Copyright (C) 2024 Adam van der Kruk aka TacB0sS
+ * Licensed under the Apache License, Version 2.0
+ */
+export * from './Logger.js';
+export * from './BeLogged.js';
+export * from './LogClient.js';
+export * from './types.js';
+export * from './debug-flags.js';
+export * from './LogClient_Terminal.js';
+export * from './LogClient_Browser.js';
+export * from './LogClient_BrowserGroups.js';
+export * from './LogClient_File.js';
+export * from './LogClient_MemBuffer.js';
+export * from './LogClient_Function.js';
+export * from './LogClient_ConsoleProxy.js';
+export * from './LogClient_BaseRotate.js';
+export * from './get-log-style.js';
+export * from './utils.js';

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nu-art/logger",
+  "version": "0.401.1",
+  "description": "Flexible logging infrastructure with multiple output targets, debug flags, and log rotation support",
+  "type": "module",
+  "keywords": [
+    "typescript",
+    "logging",
+    "logger",
+    "log-client",
+    "debug-flags",
+    "log-rotation",
+    "nu-art",
+    "thunderstorm"
+  ],
+  "homepage": "https://github.com/nu-art-js/thunderstorm",
+  "bugs": {
+    "url": "https://github.com/nu-art-js/thunderstorm/issues?q=is%3Aissue+label%3Alogger"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:nu-art-js/thunderstorm.git",
+    "directory": "_thunderstorm/logger"
+  },
+  "publishConfig": {
+    "directory": "dist"
+  },
+  "license": "Apache-2.0",
+  "author": "TacB0sS",
+  "scripts": {
+    "build": "tsc",
+    "typedocs": "typedoc --options typedoc.json",
+    "run-tests": "ts-mocha --timeout 50000 -p src/test/tsconfig.json src/test/run-all-tests.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@nu-art/testalot": "0.401.1"
+  },
+  "unitConfig": {
+    "type": "typescript-lib"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./testing": {
+      "types": "./testing/index.d.ts",
+      "import": "./testing/index.js"
+    }
+  }
+}

package/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Log levels ordered from most verbose (lowest priority) to least verbose (highest priority).
+ *
+ * Used for filtering and controlling log output granularity.
+ */
+export declare enum LogLevel {
+    Verbose = "Verbose",
+    Debug = "Debug",
+    Info = "Info",
+    Warning = "Warning",
+    Error = "Error"
+}
+/**
+ * Array of log levels in ordinal order (least to most severe).
+ *
+ * Used for comparisons and determining if a log level meets a threshold.
+ */
+export declare const LogLevelOrdinal: LogLevel[];
+/**
+ * Function type that composes the prefix string for log messages.
+ *
+ * The prefix typically includes timestamp, log level indicator, and tag.
+ *
+ * @param tag - Logger tag/identifier
+ * @param level - Log level
+ * @returns Formatted prefix string
+ */
+export type LogPrefixComposer = (tag: string, level: LogLevel) => string;
+/**
+ * Type for log message parameters - can be any value that can be logged.
+ */
+export type LogParam = string | boolean | number | object | any[] | Error | undefined | null | symbol | bigint;

package/types.js

@@ -0,0 +1,30 @@
+/*
+ * @nu-art/logger - Flexible logging infrastructure with multiple output targets
+ * Copyright (C) 2024 Adam van der Kruk aka TacB0sS
+ * Licensed under the Apache License, Version 2.0
+ */
+/**
+ * Log levels ordered from most verbose (lowest priority) to least verbose (highest priority).
+ *
+ * Used for filtering and controlling log output granularity.
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["Verbose"] = "Verbose";
+    LogLevel["Debug"] = "Debug";
+    LogLevel["Info"] = "Info";
+    LogLevel["Warning"] = "Warning";
+    LogLevel["Error"] = "Error";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Array of log levels in ordinal order (least to most severe).
+ *
+ * Used for comparisons and determining if a log level meets a threshold.
+ */
+export const LogLevelOrdinal = [
+    LogLevel.Verbose,
+    LogLevel.Debug,
+    LogLevel.Info,
+    LogLevel.Warning,
+    LogLevel.Error,
+];

package/utils.d.ts

@@ -0,0 +1,49 @@
+import { LogParam } from './types.js';
+/**
+ * Converts an object to a formatted string for logging.
+ *
+ * @param instance - Object to stringify
+ * @returns Formatted string representation
+ */
+export declare function _logger_logObject(instance: object): string;
+/**
+ * Converts an array of log parameters to an array of strings.
+ *
+ * Handles different types appropriately:
+ * - undefined → 'undefined'
+ * - null → 'null'
+ * - string → as-is
+ * - number → string conversion
+ * - Error → stack trace extraction
+ * - object → JSON stringification
+ *
+ * @param params - Array of log parameters
+ * @returns Array of string representations
+ */
+export declare function _logger_convertLogParamsToStrings(params: LogParam[]): string[];
+/**
+ * Formats an Error object into a readable string with stack trace and cause chain.
+ *
+ * Processes the error stack trace, removes duplicate stack frames, and handles
+ * CustomException instances specially. Recursively processes error causes to build
+ * a complete error chain.
+ *
+ * **Note**: Mutates and filters the stack trace to remove framework-specific noise
+ * and duplicate frames.
+ *
+ * @param error - Error object to format
+ * @param fullStack - Accumulated stack trace from previous errors in the chain
+ * @returns Formatted error string with stack trace
+ */
+export declare function _logger_logException(error: Error, fullStack?: string): string;
+/**
+ * Indents all newlines in a string with a prefix.
+ *
+ * Useful for formatting multi-line log messages so that continuation lines
+ * are properly aligned with the log prefix.
+ *
+ * @param linePrefix - Prefix to add before each line
+ * @param input - String that may contain newlines
+ * @returns String with all newlines prefixed
+ */
+export declare function _logger_indentNewLineBy(linePrefix: string, input: string): string;

package/utils.js

@@ -0,0 +1,106 @@
+/*
+ * @nu-art/logger - Flexible logging infrastructure with multiple output targets
+ * Copyright (C) 2024 Adam van der Kruk aka TacB0sS
+ * Licensed under the Apache License, Version 2.0
+ */
+/**
+ * Converts an object to a formatted string for logging.
+ *
+ * @param instance - Object to stringify
+ * @returns Formatted string representation
+ */
+export function _logger_logObject(instance) {
+    return JSON.stringify(instance, null, 2);
+}
+/**
+ * Converts an array of log parameters to an array of strings.
+ *
+ * Handles different types appropriately:
+ * - undefined → 'undefined'
+ * - null → 'null'
+ * - string → as-is
+ * - number → string conversion
+ * - Error → stack trace extraction
+ * - object → JSON stringification
+ *
+ * @param params - Array of log parameters
+ * @returns Array of string representations
+ */
+export function _logger_convertLogParamsToStrings(params) {
+    return params.map(toLog => {
+        if (typeof toLog === 'undefined')
+            return 'undefined';
+        if (toLog === null)
+            return 'null';
+        if (typeof toLog === 'string')
+            return toLog;
+        if (typeof toLog === 'number')
+            return `${toLog}`;
+        if (typeof toLog === 'function')
+            return 'function';
+        if (typeof toLog === 'symbol')
+            return 'symbol';
+        if (typeof toLog === 'bigint')
+            return `BigInt(${toLog.toString()})`;
+        // @ts-ignore
+        if (toLog.stack)
+            return _logger_logException(toLog);
+        return JSON.stringify(toLog, null, 2);
+    });
+}
+/**
+ * Formats an Error object into a readable string with stack trace and cause chain.
+ *
+ * Processes the error stack trace, removes duplicate stack frames, and handles
+ * CustomException instances specially. Recursively processes error causes to build
+ * a complete error chain.
+ *
+ * **Note**: Mutates and filters the stack trace to remove framework-specific noise
+ * and duplicate frames.
+ *
+ * @param error - Error object to format
+ * @param fullStack - Accumulated stack trace from previous errors in the chain
+ * @returns Formatted error string with stack trace
+ */
+export function _logger_logException(error, fullStack = '') {
+    let toPrint = '';
+    let errorMessage;
+    let isCustomException = false;
+    if (error.stack) {
+        const stackAsList = error.stack.split('\n');
+        errorMessage = stackAsList[0];
+        const errorMessageIndex = stackAsList.indexOf(errorMessage);
+        if (errorMessageIndex > -1)
+            stackAsList.splice(errorMessageIndex, 1);
+        toPrint = stackAsList.reduce((toRet, stacktrace) => {
+            if (fullStack.indexOf(stacktrace) !== -1)
+                return toRet;
+            return toRet + stacktrace + '\n';
+        }, toPrint);
+        isCustomException = toPrint.indexOf('CustomException') !== -1;
+        toPrint = toPrint.replace(/\s+at.*?CustomException.*?\n/, '\n');
+        toPrint = toPrint.replace(/\s+at.*?new\s+(.*?) \(.*?\n/, `${fullStack.length === 0 ? '' : '\nCaused by '}$1: ${errorMessage.replace('Error: ', '')}\n`);
+        if (!isCustomException && errorMessage)
+            toPrint = errorMessage + '\n' + toPrint;
+    }
+    const cause = error.cause;
+    if (cause) {
+        let causeStack = _logger_logException(cause, toPrint);
+        causeStack = causeStack.replace(`Error: ${cause.message}`, `${cause.message}`);
+        toPrint += `${causeStack}`;
+    }
+    return toPrint;
+}
+/**
+ * Indents all newlines in a string with a prefix.
+ *
+ * Useful for formatting multi-line log messages so that continuation lines
+ * are properly aligned with the log prefix.
+ *
+ * @param linePrefix - Prefix to add before each line
+ * @param input - String that may contain newlines
+ * @returns String with all newlines prefixed
+ */
+export function _logger_indentNewLineBy(linePrefix, input) {
+    return linePrefix + input.replace(/\n/g, `\n${linePrefix}`);
+}