@nu-art/logger 0.401.1

package/LogClient_Browser.d.ts

@@ -0,0 +1,38 @@
+import { LogLevel, LogParam } from './types.js';
+import { LogClient } from './LogClient.js';
+/**
+ * Log client implementation for browser console output with CSS styling.
+ *
+ * Uses browser console's `%c` formatting to apply CSS styles to log messages.
+ * Different log levels are styled with different colors for visual distinction.
+ */
+declare class LogClient_Browser_class extends LogClient {
+    /** CSS styles for different log levels */
+    private style;
+    /**
+     * Gets the CSS style string for a log level.
+     *
+     * Returns a CSS style string compatible with browser console's `%c` formatting
+     * for the given log level. Combines base styles with level-specific colors.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting (not currently used)
+     * @returns CSS style string for console.log formatting
+     */
+    getColor(level: LogLevel, bold: boolean): string;
+    /**
+     * Outputs a log message to the browser console with CSS styling.
+     *
+     * Uses `%c` formatting to apply styles. Strings are concatenated with the prefix,
+     * while objects are passed as separate arguments to preserve browser console's
+     * object inspection capabilities.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting (not currently used in browser)
+     * @param prefix - Composed prefix string
+     * @param toLog - Array of values to log
+     */
+    protected logMessage(level: LogLevel, bold: boolean, prefix: string, toLog: LogParam[]): void;
+}
+export declare const LogClient_Browser: LogClient_Browser_class;
+export {};

package/LogClient_Browser.js

@@ -0,0 +1,92 @@
+/*
+ * @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 } from './types.js';
+import { LogClient } from './LogClient.js';
+import { getLogStyle } from './get-log-style.js';
+/**
+ * Log client implementation for browser console output with CSS styling.
+ *
+ * Uses browser console's `%c` formatting to apply CSS styles to log messages.
+ * Different log levels are styled with different colors for visual distinction.
+ */
+class LogClient_Browser_class extends LogClient {
+    /** CSS styles for different log levels */
+    style = {
+        base: {
+            // 'background-color': '#fff',
+            'padding': '2px 0px',
+            'border-radius': '2px',
+        },
+        verbose: {
+            'color': '#808080',
+            'background-color': 'unset'
+        },
+        debug: {
+            'color': '#6564c9',
+        },
+        info: {
+            'color': '#189702',
+        },
+        warning: {
+            'color': '#926E00',
+        },
+        error: {
+            'color': '#B40000',
+        }
+    };
+    /**
+     * Gets the CSS style string for a log level.
+     *
+     * Returns a CSS style string compatible with browser console's `%c` formatting
+     * for the given log level. Combines base styles with level-specific colors.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting (not currently used)
+     * @returns CSS style string for console.log formatting
+     */
+    getColor(level, bold) {
+        switch (level) {
+            case LogLevel.Verbose:
+                return getLogStyle(this.style.base, this.style.verbose);
+            case LogLevel.Debug:
+                return getLogStyle(this.style.base, this.style.debug);
+            case LogLevel.Info:
+                return getLogStyle(this.style.base, this.style.info);
+            case LogLevel.Warning:
+                return getLogStyle(this.style.base, this.style.warning);
+            case LogLevel.Error:
+                return getLogStyle(this.style.base, this.style.error);
+            default:
+                return getLogStyle({ 'color': '#000000' });
+        }
+    }
+    /**
+     * Outputs a log message to the browser console with CSS styling.
+     *
+     * Uses `%c` formatting to apply styles. Strings are concatenated with the prefix,
+     * while objects are passed as separate arguments to preserve browser console's
+     * object inspection capabilities.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting (not currently used in browser)
+     * @param prefix - Composed prefix string
+     * @param toLog - Array of values to log
+     */
+    logMessage(level, bold, prefix, toLog) {
+        for (const param of toLog) {
+            if (typeof param === 'string') {
+                console.log(`%c${prefix}${param}`, this.getColor(level, bold));
+                continue;
+            }
+            if (typeof param === 'object') {
+                console.log(`%c${prefix}`, this.getColor(level, bold), param);
+                continue;
+            }
+            console.log(`%c${prefix}`, this.getColor(level, bold), param);
+        }
+    }
+}
+export const LogClient_Browser = new LogClient_Browser_class();

package/LogClient_BrowserGroups.d.ts

@@ -0,0 +1,50 @@
+import { LogClient } from './LogClient.js';
+import { LogLevel, LogParam } from './types.js';
+/**
+ * CSS style object for browser console styling.
+ *
+ * Defines CSS properties that can be applied to log messages using browser
+ * console's `%c` formatting. Used by LogClient_BrowserGroups for styled output.
+ */
+export type LoggerStyleObject = {
+    color?: string;
+    'background-color'?: string;
+    'font-weight'?: 'bold' | 'normal';
+    padding?: string;
+    'border-radius'?: string;
+};
+/**
+ * Log client for browser console with grouped output and styled prefixes.
+ *
+ * Uses browser console's grouping feature (console.groupCollapsed) to organize
+ * logs. Applies CSS styling to different parts of the log prefix (level, timestamp, tag)
+ * for visual distinction. If the first log parameter is a primitive, it's combined
+ * with the prefix for cleaner output.
+ */
+declare class LogClient_BrowserGroups_Class extends LogClient {
+    constructor();
+    private newComposer;
+    /**
+     * Outputs log messages with browser console grouping and styling.
+     *
+     * If the first parameter is a primitive (string/number/boolean), it's combined
+     * with the prefix for cleaner single-line output. Otherwise, uses console.groupCollapsed
+     * to create a collapsible group with the prefix as the header and remaining parameters
+     * as grouped content.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param prefix - Composed prefix string (with %c markers for styling)
+     * @param toLog - Array of values to log
+     */
+    protected logMessage(level: LogLevel, bold: boolean, prefix: string, toLog: LogParam[]): void;
+    private logSingle;
+    private logGroup;
+    private getLogLevelColor;
+    private composeStyleString;
+    private getLogLevelStyling;
+    private getTimestampStyling;
+    private getTagStyling;
+}
+export declare const LogClient_BrowserGroups: LogClient_BrowserGroups_Class;
+export {};

package/LogClient_BrowserGroups.js

@@ -0,0 +1,112 @@
+/*
+ * @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 { _logger_finalDate, _logger_getPrefix, _logger_timezoneOffset, LogClient } from './LogClient.js';
+import { LogLevel } from './types.js';
+/** Array of primitive types that can be combined with prefix */
+const PrimitiveLogParams = ['string', 'number', 'boolean'];
+/**
+ * Log client for browser console with grouped output and styled prefixes.
+ *
+ * Uses browser console's grouping feature (console.groupCollapsed) to organize
+ * logs. Applies CSS styling to different parts of the log prefix (level, timestamp, tag)
+ * for visual distinction. If the first log parameter is a primitive, it's combined
+ * with the prefix for cleaner output.
+ */
+class LogClient_BrowserGroups_Class extends LogClient {
+    constructor() {
+        super();
+        this.setComposer(this.newComposer);
+    }
+    // ################## Class Methods - Logging ##################
+    newComposer(tag, level) {
+        _logger_finalDate.setTime(Date.now() - _logger_timezoneOffset);
+        const date = _logger_finalDate.toISOString().replace(/T/, '_').replace(/Z/, '').substring(0, 23);
+        return `%c${_logger_getPrefix(level)}%c${date}%c${tag}`;
+    }
+    /**
+     * Outputs log messages with browser console grouping and styling.
+     *
+     * If the first parameter is a primitive (string/number/boolean), it's combined
+     * with the prefix for cleaner single-line output. Otherwise, uses console.groupCollapsed
+     * to create a collapsible group with the prefix as the header and remaining parameters
+     * as grouped content.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param prefix - Composed prefix string (with %c markers for styling)
+     * @param toLog - Array of values to log
+     */
+    logMessage(level, bold, prefix, toLog) {
+        if (!prefix.startsWith('%c'))
+            prefix = `%c ${prefix}`;
+        //If the first log param is a primitive combine it with the prefix
+        if (toLog[0] != null && PrimitiveLogParams.includes(typeof toLog[0])) {
+            prefix += ` ${String(toLog[0])}`;
+            toLog.shift();
+        }
+        //If no more items to log
+        if (!toLog.length)
+            return this.logSingle(level, bold, prefix);
+        this.logGroup(level, bold, prefix, toLog);
+    }
+    logSingle = (logLevel, bold, toLog) => {
+        console.log(toLog, this.getLogLevelStyling(logLevel, bold), this.getTimestampStyling(bold, logLevel), this.getTagStyling(logLevel, bold));
+    };
+    logGroup = (logLevel, bold, prefix, toLog) => {
+        // group & groupCollapsed print the same thing, only groupCollapsed is collapsed by default.
+        // console.group(
+        console.groupCollapsed(prefix, this.getLogLevelStyling(logLevel, bold), this.getTimestampStyling(bold, logLevel), this.getTagStyling(logLevel, bold));
+        toLog.forEach(logParam => console.log(logParam));
+        console.groupEnd();
+    };
+    // ################## Class Methods - Styling ##################
+    getLogLevelColor = (logLevel) => {
+        switch (logLevel) {
+            case LogLevel.Verbose:
+                return '#444444';
+            case LogLevel.Debug:
+                return '#3066be';
+            case LogLevel.Info:
+                return '#52a447';
+            case LogLevel.Warning:
+                return '#ed820e';
+            case LogLevel.Error:
+                return '#d14348';
+            default:
+                return 'transparent';
+        }
+    };
+    composeStyleString = (styleObject) => {
+        const styleArr = Object.keys(styleObject).map((key) => `${key}: ${styleObject[key]}`);
+        return styleArr.join(';') + ';';
+    };
+    getLogLevelStyling = (logLevel, bold) => {
+        return this.composeStyleString({
+            color: '#ffffff',
+            'background-color': this.getLogLevelColor(logLevel),
+            'font-weight': bold ? 'bold' : 'normal',
+            padding: '2px 5px',
+            'border-radius': '4px 0 0 4px',
+        });
+    };
+    getTimestampStyling = (bold, logLevel) => {
+        return this.composeStyleString({
+            color: '#ffffff',
+            'background-color': this.getLogLevelColor(logLevel),
+            'font-weight': bold ? 'bold' : 'normal',
+            padding: '2px 5px',
+            'border-radius': '0 4px 4px 0',
+        });
+    };
+    getTagStyling = (logLevel, bold) => {
+        return this.composeStyleString({
+            color: this.getLogLevelColor(logLevel),
+            'font-weight': bold ? 'bold' : 'normal',
+            padding: '2px 5px',
+        });
+    };
+}
+export const LogClient_BrowserGroups = new LogClient_BrowserGroups_Class();

package/LogClient_ConsoleProxy.d.ts

@@ -0,0 +1,108 @@
+import { LogClient } from './LogClient.js';
+import { LogLevel, LogParam } from './types.js';
+/**
+ * Structure for log entries sent to remote endpoints.
+ *
+ * Used by LogClient_ConsoleProxy and its subclasses to format log messages
+ * before sending them to remote logging services.
+ */
+export type LogToStream = {
+    /** Log severity level */
+    severity: LogLevel;
+    /** Formatted log content */
+    logContent: string;
+    /** Logger tag/reporter name */
+    reporter: string;
+    /** Timestamp string */
+    timestamp: string;
+};
+/**
+ * Abstract base class for log clients that proxy logs to remote endpoints.
+ *
+ * Buffers log messages and sends them in batches to reduce network overhead.
+ * Automatically intercepts `console.error` calls and includes them in the log stream.
+ *
+ * Features:
+ * - Batched sending (flushes when buffer reaches maxBuffers or after timeout)
+ * - Automatic retry logic with exponential backoff
+ * - Immediate flush on error-level logs
+ * - Periodic flushing via setInterval (every 2 minutes)
+ *
+ * Subclasses must implement `sendLogsToEndpoint()` to define the actual sending mechanism.
+ */
+export declare abstract class LogClient_ConsoleProxy extends LogClient {
+    /** Buffer of log entries waiting to be sent */
+    private buffers;
+    /** Maximum number of logs to buffer before forcing a flush */
+    private readonly maxBuffers;
+    /** Interval handle for periodic log flushing */
+    private flushInterval?;
+    /** Original console.error function (saved before interception) */
+    private readonly originalConsoleError;
+    /** Flag indicating if a send request is currently in progress */
+    private activeRequest;
+    /** Timeout handle for error log flushing */
+    private errorLogTimeout?;
+    /**
+     * Application name - must be set by subclasses.
+     * Used to identify the source of logs in the remote system.
+     */
+    protected abstract appName: string;
+    /**
+     * Creates a new console proxy log client.
+     *
+     * Sets up console.error interception and debounced flushing.
+     */
+    constructor();
+    /**
+     * Initializes the log client by intercepting console.error and setting up flushing.
+     *
+     * Intercepts all `console.error` calls and routes them through this log client.
+     * Sets up periodic flushing via setInterval (every 2 minutes).
+     */
+    init(): void;
+    /**
+     * Buffers log messages and triggers flushing when thresholds are met.
+     *
+     * Logs are converted to LogToStream format and added to the buffer. Flushing occurs:
+     * - Immediately if buffer reaches maxBuffers
+     * - After a short delay (500ms) for error-level logs
+     * - Periodically via setInterval (every 2 minutes)
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting (not used)
+     * @param prefix - Composed prefix string (parsed to extract timestamp and reporter)
+     * @param toLog - Array of values to log
+     */
+    protected logMessage(level: LogLevel, bold: boolean, prefix: string, toLog: LogParam[]): void;
+    /**
+     * Flushes buffered logs to the remote endpoint.
+     *
+     * Removes up to maxBuffers logs from the buffer and sends them. Uses retry logic
+     * to handle transient network failures.
+     */
+    private flushLogs;
+    /**
+     * Sends logs with retry logic.
+     *
+     * Attempts to send logs up to 10 times with 1 second delay between retries.
+     * Logs errors to console if all retries fail.
+     *
+     * @param logs - Log entries to send
+     * @param retries - Maximum number of retry attempts (default: 10)
+     */
+    private retrySendLogs;
+    /**
+     * Abstract method that subclasses must implement to send logs to the remote endpoint.
+     *
+     * @param logs - Array of log entries to send
+     */
+    protected abstract sendLogsToEndpoint: (logs: LogToStream[]) => Promise<void>;
+    /**
+     * Stops the log client and performs cleanup.
+     *
+     * Clears any pending error log timeouts and flush intervals, restores the original
+     * console.error function, and calls the parent stop() method.
+     */
+    stop(): void;
+}

package/LogClient_ConsoleProxy.js

@@ -0,0 +1,179 @@
+/*
+ * @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 { _logger_getPrefix, LogClient } from './LogClient.js';
+import { LogLevel } from './types.js';
+/**
+ * Abstract base class for log clients that proxy logs to remote endpoints.
+ *
+ * Buffers log messages and sends them in batches to reduce network overhead.
+ * Automatically intercepts `console.error` calls and includes them in the log stream.
+ *
+ * Features:
+ * - Batched sending (flushes when buffer reaches maxBuffers or after timeout)
+ * - Automatic retry logic with exponential backoff
+ * - Immediate flush on error-level logs
+ * - Periodic flushing via setInterval (every 2 minutes)
+ *
+ * Subclasses must implement `sendLogsToEndpoint()` to define the actual sending mechanism.
+ */
+export class LogClient_ConsoleProxy extends LogClient {
+    /** Buffer of log entries waiting to be sent */
+    buffers;
+    /** Maximum number of logs to buffer before forcing a flush */
+    maxBuffers = 50;
+    /** Interval handle for periodic log flushing */
+    flushInterval;
+    /** Original console.error function (saved before interception) */
+    originalConsoleError;
+    /** Flag indicating if a send request is currently in progress */
+    activeRequest;
+    /** Timeout handle for error log flushing */
+    errorLogTimeout;
+    /**
+     * Creates a new console proxy log client.
+     *
+     * Sets up console.error interception and debounced flushing.
+     */
+    constructor() {
+        super();
+        this.buffers = [];
+        this.activeRequest = false;
+        // pipe console.error to this log client
+    }
+    /**
+     * Initializes the log client by intercepting console.error and setting up flushing.
+     *
+     * Intercepts all `console.error` calls and routes them through this log client.
+     * Sets up periodic flushing via setInterval (every 2 minutes).
+     */
+    init() {
+        super.init();
+        // Guard against multiple initializations - only save original if not already saved
+        if (!this.originalConsoleError) {
+            // @ts-ignore
+            this['originalConsoleError'] = console.error;
+        }
+        console.error = (...args) => {
+            this.originalConsoleError(...args);
+            this.logMessage.bind(this)(LogLevel.Error, false, `${new Date().toISOString()} ${_logger_getPrefix(LogLevel.Error)} unhandled error`, args);
+        };
+        // Only set up interval if not already set
+        if (!this.flushInterval) {
+            // Flush logs every 60 seconds (not 2 minutes as comment says)
+            this.flushInterval = setInterval(async () => {
+                if (!this.activeRequest && this.buffers.length > 0)
+                    await this.flushLogs();
+            }, 60 * 1000);
+        }
+    }
+    /**
+     * Buffers log messages and triggers flushing when thresholds are met.
+     *
+     * Logs are converted to LogToStream format and added to the buffer. Flushing occurs:
+     * - Immediately if buffer reaches maxBuffers
+     * - After a short delay (500ms) for error-level logs
+     * - Periodically via setInterval (every 2 minutes)
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting (not used)
+     * @param prefix - Composed prefix string (parsed to extract timestamp and reporter)
+     * @param toLog - Array of values to log
+     */
+    logMessage(level, bold, prefix, toLog) {
+        const levelPrefix = _logger_getPrefix(level);
+        const logs = toLog
+            .map(param => {
+            if (!param)
+                return null;
+            let logContent = '';
+            if (typeof param === 'object')
+                logContent = JSON.stringify(param);
+            else
+                logContent = param.toString();
+            const [timestamp, reporter] = prefix.split(levelPrefix);
+            return {
+                severity: level,
+                logContent: logContent.trim(),
+                reporter: reporter.trim(),
+                timestamp: timestamp.trim()
+            };
+        })
+            .filter((log) => log != null);
+        this.buffers.push(...logs);
+        if (this.buffers.length >= this.maxBuffers && !this.activeRequest) {
+            setTimeout(async () => {
+                await this.flushLogs();
+            }, 0); // 2 minutes
+        }
+        else {
+            // trigger flush on error
+            if (level === LogLevel.Error && !this.errorLogTimeout)
+                this.errorLogTimeout = setTimeout(async () => {
+                    this.errorLogTimeout = undefined;
+                    if (!this.activeRequest)
+                        await this.flushLogs();
+                }, 500);
+        }
+    }
+    /**
+     * Flushes buffered logs to the remote endpoint.
+     *
+     * Removes up to maxBuffers logs from the buffer and sends them. Uses retry logic
+     * to handle transient network failures.
+     */
+    async flushLogs() {
+        this.activeRequest = true;
+        const logsToSend = this.buffers.splice(0, this.maxBuffers);
+        await this.retrySendLogs(logsToSend);
+        this.activeRequest = false;
+    }
+    /**
+     * Sends logs with retry logic.
+     *
+     * Attempts to send logs up to 10 times with 1 second delay between retries.
+     * Logs errors to console if all retries fail.
+     *
+     * @param logs - Log entries to send
+     * @param retries - Maximum number of retry attempts (default: 10)
+     */
+    async retrySendLogs(logs, retries = 10) {
+        for (let attempt = 1; attempt <= retries; attempt++) {
+            try {
+                await this.sendLogsToEndpoint(logs);
+                return;
+            }
+            catch (error) {
+                if (attempt === retries) {
+                    this.originalConsoleError('Failed to send logs after multiple attempts', error);
+                }
+                else {
+                    console.warn(`Retrying to send logs, attempt ${attempt} failed`, error);
+                    await new Promise(resolve => setTimeout(resolve, 1000)); // add a bit of delay between retries
+                }
+            }
+        }
+    }
+    /**
+     * Stops the log client and performs cleanup.
+     *
+     * Clears any pending error log timeouts and flush intervals, restores the original
+     * console.error function, and calls the parent stop() method.
+     */
+    stop() {
+        if (this.errorLogTimeout) {
+            clearTimeout(this.errorLogTimeout);
+            this.errorLogTimeout = undefined;
+        }
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+            this.flushInterval = undefined;
+        }
+        if (this.originalConsoleError) {
+            console.error = this.originalConsoleError;
+        }
+        super.stop();
+    }
+}

package/LogClient_File.d.ts

@@ -0,0 +1,58 @@
+import { LogClient_BaseRotate } from './LogClient_BaseRotate.js';
+/**
+ * Log client that writes logs to rotating files on disk.
+ *
+ * Creates log files in the format `{name}-{index}.txt` where index 0 is the current log.
+ * When the current log exceeds maxSize, it rotates: log-0.txt → log-1.txt, log-1.txt → log-2.txt, etc.
+ * The oldest log (log-{maxEntries-1}.txt) is deleted during rotation.
+ *
+ * The log folder is created automatically if it doesn't exist. If a log file already
+ * exists, its size is used to initialize the bufferSize counter.
+ */
+export declare class LogClient_File extends LogClient_BaseRotate {
+    /** Directory path where log files are stored */
+    private pathToFolder;
+    /** WriteStream for the current log file */
+    private buffer;
+    /**
+     * Creates a new file-based log client.
+     *
+     * @param name - Log file name prefix (e.g., "app" creates "app-0.txt", "app-1.txt", etc.)
+     * @param pathToFolder - Directory path for log files (created if it doesn't exist)
+     * @param maxEntries - Maximum number of rotated log files to keep (default: 10)
+     * @param maxSize - Maximum file size in bytes before rotation (default: 1MB)
+     */
+    constructor(name: string, pathToFolder: string, maxEntries?: number, maxSize?: number);
+    /**
+     * Gets the filename for a log file at the given index.
+     *
+     * @param index - Log file index (0 = current, 1+ = rotated)
+     * @returns Full path to the log file
+     */
+    private getFileName;
+    /**
+     * Writes a log message to the current log file.
+     *
+     * @param log - Formatted log string (includes newline)
+     */
+    protected printLogMessage(log: string): void;
+    /**
+     * Rotates a log file by renaming it to the next index.
+     *
+     * @param fromIndex - Source index
+     * @param toIndex - Destination index
+     */
+    protected rotateBuffer(fromIndex: number, toIndex: number): void;
+    /**
+     * Cleans up the oldest log file and closes the current write stream.
+     *
+     * Called during rotation to delete the oldest log and prepare for a new current log.
+     */
+    protected cleanup(): void;
+    /**
+     * Prepares a new log file by creating a write stream.
+     *
+     * Opens the current log file (index 0) in append mode.
+     */
+    protected prepare(): void;
+}