@nu-art/logger 0.401.1

package/LogClient_File.js

@@ -0,0 +1,89 @@
+/*
+ * @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 * as fs from 'fs';
+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 class LogClient_File extends LogClient_BaseRotate {
+    /** Directory path where log files are stored */
+    pathToFolder;
+    /** WriteStream for the current log file */
+    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, pathToFolder, maxEntries = 10, maxSize = 1024 * 1024) {
+        super(name, maxEntries, maxSize);
+        this.pathToFolder = pathToFolder;
+        if (!fs.existsSync(pathToFolder))
+            fs.mkdirSync(pathToFolder, { recursive: true });
+        const defaultLogfile = this.getFileName();
+        if (fs.existsSync(defaultLogfile))
+            this.bufferSize = fs.statSync(`${defaultLogfile}`).size;
+        this.prepare();
+    }
+    /**
+     * 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
+     */
+    getFileName(index = 0) {
+        return `${this.pathToFolder}/${this.name}-${index}.txt`;
+    }
+    /**
+     * Writes a log message to the current log file.
+     *
+     * @param log - Formatted log string (includes newline)
+     */
+    printLogMessage(log) {
+        this.buffer.write(log);
+    }
+    /**
+     * Rotates a log file by renaming it to the next index.
+     *
+     * @param fromIndex - Source index
+     * @param toIndex - Destination index
+     */
+    rotateBuffer(fromIndex, toIndex) {
+        if (fs.existsSync(this.getFileName(fromIndex))) {
+            console.log(`rotating ${fromIndex} => ${toIndex}`);
+            fs.renameSync(this.getFileName(fromIndex), this.getFileName(toIndex));
+        }
+    }
+    /**
+     * 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.
+     */
+    cleanup() {
+        const fileName = this.getFileName(this.maxEntries - 1);
+        if (fs.existsSync(fileName))
+            fs.unlinkSync(fileName);
+        this.buffer.end();
+    }
+    /**
+     * Prepares a new log file by creating a write stream.
+     *
+     * Opens the current log file (index 0) in append mode.
+     */
+    prepare() {
+        this.buffer = fs.createWriteStream(this.getFileName(), { flags: 'a' });
+    }
+}

package/LogClient_Function.d.ts

@@ -0,0 +1,31 @@
+import { LogLevel, LogParam } from "./types.js";
+import { LogClient } from "./LogClient.js";
+/**
+ * Log client that outputs to console with special handling for different value types.
+ *
+ * Uses a simplified prefix format and handles various JavaScript types appropriately:
+ * - Errors: Extracts stack trace
+ * - Objects: JSON stringification
+ * - Primitives: Direct output
+ * - Functions/Symbols/BigInt: Type name only
+ */
+declare class LogClient_Function_class extends LogClient {
+    constructor();
+    /**
+     * Outputs log messages with type-specific formatting.
+     *
+     * Handles different value types appropriately:
+     * - Errors: Uses stack trace extraction
+     * - Objects: JSON stringification
+     * - Primitives: Direct string conversion
+     * - Functions/Symbols/BigInt: Outputs type name only
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting (not used in this implementation)
+     * @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_Function: LogClient_Function_class;
+export {};

package/LogClient_Function.js

@@ -0,0 +1,63 @@
+/*
+ * @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 { LogClient } from "./LogClient.js";
+import { _logger_logException } from "./utils.js";
+/**
+ * Log client that outputs to console with special handling for different value types.
+ *
+ * Uses a simplified prefix format and handles various JavaScript types appropriately:
+ * - Errors: Extracts stack trace
+ * - Objects: JSON stringification
+ * - Primitives: Direct output
+ * - Functions/Symbols/BigInt: Type name only
+ */
+class LogClient_Function_class extends LogClient {
+    constructor() {
+        super();
+        this.setComposer((tag, level) => `${level} ${tag}: `);
+    }
+    /**
+     * Outputs log messages with type-specific formatting.
+     *
+     * Handles different value types appropriately:
+     * - Errors: Uses stack trace extraction
+     * - Objects: JSON stringification
+     * - Primitives: Direct string conversion
+     * - Functions/Symbols/BigInt: Outputs type name only
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting (not used in this implementation)
+     * @param prefix - Composed prefix string
+     * @param toLog - Array of values to log
+     */
+    logMessage(level, bold, prefix, toLog) {
+        for (const logParam of toLog) {
+            if (logParam)
+                // @ts-ignore
+                if (logParam.stack) {
+                    console.log(`${prefix}${_logger_logException(logParam)}`);
+                    continue;
+                }
+            switch (typeof logParam) {
+                case "undefined":
+                case "function":
+                case "symbol":
+                case "bigint":
+                    console.log(`${prefix}${typeof logParam}`);
+                    continue;
+                case "boolean":
+                case "number":
+                case "string":
+                    console.log(`${prefix}${logParam}`);
+                    continue;
+                case "object":
+                    console.log(`${prefix}${JSON.stringify(logParam)}`);
+                    continue;
+            }
+        }
+    }
+}
+export const LogClient_Function = new LogClient_Function_class();

package/LogClient_MemBuffer.d.ts

@@ -0,0 +1,88 @@
+import { LogClient_BaseRotate } from './LogClient_BaseRotate.js';
+import { LogLevel, LogParam } from './types.js';
+/**
+ * Log client that stores logs in memory buffers with rotation support.
+ *
+ * Maintains an array of string buffers that rotate when the current buffer exceeds maxBufferSize.
+ * Useful for in-memory log aggregation, testing, or when you need programmatic access to logs.
+ *
+ * Supports:
+ * - Log transformation via `setLogTransformer()`
+ * - Callbacks when logs are appended via `setLogAppendedListener()`
+ * - Color code preservation via `keepLogsNaturalColors()`
+ */
+export declare class LogClient_MemBuffer extends LogClient_BaseRotate {
+    /** If true, preserves natural colors in log output (disables ANSI color codes) */
+    private keepNaturalColors;
+    /** Array of log buffers, where index 0 is the current buffer */
+    readonly buffers: string[];
+    /** Optional callback invoked when a log is appended */
+    private onLogAppended?;
+    /** Optional function to transform log strings before storage */
+    private logTransformer?;
+    /**
+     * Creates a new memory buffer log client.
+     *
+     * @param name - Identifier for this log client
+     * @param maxBuffers - Maximum number of rotated buffers to keep (default: 10)
+     * @param maxBufferSize - Maximum buffer size in bytes before rotation (default: 1MB)
+     */
+    constructor(name: string, maxBuffers?: number, maxBufferSize?: number);
+    /**
+     * Sets a function to transform log strings before they are stored.
+     *
+     * The transformer receives the log content (without prefix) and can modify it.
+     * Useful for sanitization, formatting, or filtering sensitive data.
+     *
+     * @param logTransformer - Function that transforms log strings
+     */
+    setLogTransformer(logTransformer: (log: string) => string): void;
+    /**
+     * Sets a callback to be invoked whenever a log is appended to the buffer.
+     *
+     * Useful for real-time log monitoring or triggering actions when logs are written.
+     *
+     * @param onLogAppended - Function to call when a log is appended
+     */
+    setLogAppendedListener(onLogAppended: VoidFunction): void;
+    /**
+     * Processes log message with color codes and optional transformation.
+     *
+     * Applies ANSI color codes, transforms the log if a transformer is set, and
+     * formats with proper indentation.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param prefix - Composed prefix string
+     * @param toLog - Array of values to log
+     * @returns Formatted log string
+     */
+    protected processLogMessage(level: LogLevel, bold: boolean, prefix: string, toLog: LogParam[]): string;
+    /**
+     * Appends a log message to the current buffer and invokes the callback.
+     *
+     * @param log - Formatted log string (includes newline)
+     */
+    protected printLogMessage(log: string): void;
+    /**
+     * No cleanup needed for memory buffers (they're just strings).
+     */
+    protected cleanup(): void;
+    /**
+     * Rotates buffers by copying the source buffer to the destination index.
+     *
+     * @param fromIndex - Source buffer index
+     * @param toIndex - Destination buffer index
+     */
+    protected rotateBuffer(fromIndex: number, toIndex: number): void;
+    /**
+     * Prepares a new buffer by clearing the current one.
+     */
+    protected prepare(): void;
+    /**
+     * Controls whether natural colors in log output are preserved.
+     *
+     * @param keepNaturalColors - If true, disables color codes. Defaults to true.
+     */
+    keepLogsNaturalColors(keepNaturalColors?: boolean): void;
+}

package/LogClient_MemBuffer.js

@@ -0,0 +1,139 @@
+/*
+ * @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 { LogClient_BaseRotate } from './LogClient_BaseRotate.js';
+import { LogLevel } from './types.js';
+import { _logger_convertLogParamsToStrings, _logger_indentNewLineBy } from './utils.js';
+import { NoColor } from './LogClient_Terminal.js';
+function getColor(level, bold = false) {
+    let color;
+    switch (level) {
+        case LogLevel.Verbose:
+            color = '\x1b[90m';
+            break;
+        case LogLevel.Debug:
+            color = '\x1b[34m';
+            break;
+        case LogLevel.Info:
+            color = '\x1b[32m';
+            break;
+        case LogLevel.Warning:
+            color = '\x1b[33m';
+            break;
+        case LogLevel.Error:
+            color = '\x1b[31m';
+            break;
+    }
+    return color + (bold ? '\x1b[1m' : '');
+}
+/**
+ * Log client that stores logs in memory buffers with rotation support.
+ *
+ * Maintains an array of string buffers that rotate when the current buffer exceeds maxBufferSize.
+ * Useful for in-memory log aggregation, testing, or when you need programmatic access to logs.
+ *
+ * Supports:
+ * - Log transformation via `setLogTransformer()`
+ * - Callbacks when logs are appended via `setLogAppendedListener()`
+ * - Color code preservation via `keepLogsNaturalColors()`
+ */
+export class LogClient_MemBuffer extends LogClient_BaseRotate {
+    /** If true, preserves natural colors in log output (disables ANSI color codes) */
+    keepNaturalColors = false;
+    /** Array of log buffers, where index 0 is the current buffer */
+    buffers = [''];
+    /** Optional callback invoked when a log is appended */
+    onLogAppended;
+    /** Optional function to transform log strings before storage */
+    logTransformer;
+    /**
+     * Creates a new memory buffer log client.
+     *
+     * @param name - Identifier for this log client
+     * @param maxBuffers - Maximum number of rotated buffers to keep (default: 10)
+     * @param maxBufferSize - Maximum buffer size in bytes before rotation (default: 1MB)
+     */
+    constructor(name, maxBuffers = 10, maxBufferSize = 1024 * 1024) {
+        super(name, maxBuffers, maxBufferSize);
+    }
+    /**
+     * Sets a function to transform log strings before they are stored.
+     *
+     * The transformer receives the log content (without prefix) and can modify it.
+     * Useful for sanitization, formatting, or filtering sensitive data.
+     *
+     * @param logTransformer - Function that transforms log strings
+     */
+    setLogTransformer(logTransformer) {
+        this.logTransformer = logTransformer;
+    }
+    /**
+     * Sets a callback to be invoked whenever a log is appended to the buffer.
+     *
+     * Useful for real-time log monitoring or triggering actions when logs are written.
+     *
+     * @param onLogAppended - Function to call when a log is appended
+     */
+    setLogAppendedListener(onLogAppended) {
+        this.onLogAppended = onLogAppended;
+    }
+    /**
+     * Processes log message with color codes and optional transformation.
+     *
+     * Applies ANSI color codes, transforms the log if a transformer is set, and
+     * formats with proper indentation.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param prefix - Composed prefix string
+     * @param toLog - Array of values to log
+     * @returns Formatted log string
+     */
+    processLogMessage(level, bold, prefix, toLog) {
+        const color = getColor(level, bold);
+        let log = _logger_convertLogParamsToStrings(toLog).join(' ');
+        const linePrefix = `${color}${prefix}${this.keepNaturalColors ? NoColor : ''}`;
+        if (this.logTransformer)
+            log = this.logTransformer(log);
+        return _logger_indentNewLineBy(linePrefix, log);
+    }
+    /**
+     * Appends a log message to the current buffer and invokes the callback.
+     *
+     * @param log - Formatted log string (includes newline)
+     */
+    printLogMessage(log) {
+        this.buffers[0] += log;
+        this.onLogAppended?.();
+    }
+    /**
+     * No cleanup needed for memory buffers (they're just strings).
+     */
+    cleanup() {
+    }
+    /**
+     * Rotates buffers by copying the source buffer to the destination index.
+     *
+     * @param fromIndex - Source buffer index
+     * @param toIndex - Destination buffer index
+     */
+    rotateBuffer(fromIndex, toIndex) {
+        this.buffers[toIndex] = this.buffers[fromIndex];
+    }
+    /**
+     * Prepares a new buffer by clearing the current one.
+     */
+    prepare() {
+        this.buffers[0] = '';
+    }
+    /**
+     * Controls whether natural colors in log output are preserved.
+     *
+     * @param keepNaturalColors - If true, disables color codes. Defaults to true.
+     */
+    keepLogsNaturalColors(keepNaturalColors = true) {
+        this.keepNaturalColors = keepNaturalColors;
+    }
+}

package/LogClient_Terminal.d.ts

@@ -0,0 +1,49 @@
+import { LogLevel, LogParam } from './types.js';
+import { LogClient } from './LogClient.js';
+/**
+ * ANSI escape code to reset terminal color formatting.
+ *
+ * Used to reset color codes after applying colored log output.
+ */
+export declare const NoColor = "\u001B[0m";
+/**
+ * Log client implementation for terminal/console output with ANSI color codes.
+ *
+ * Outputs colored log messages to the console using ANSI escape sequences.
+ * Different log levels are displayed in different colors for visual distinction.
+ */
+declare class LogClient_Terminal_class extends LogClient {
+    /** If true, preserves natural colors in log output (disables color codes) */
+    private keepNaturalColors;
+    /**
+     * Gets the ANSI color code for a log level.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @returns ANSI escape sequence for the color
+     */
+    getColor(level: LogLevel, bold?: boolean): string;
+    /**
+     * Outputs a log message to the terminal with color formatting.
+     *
+     * Converts all log parameters to strings, applies color codes, and outputs
+     * to console.log. Always resets color at the end of the line.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param prefix - Composed prefix string
+     * @param toLog - Array of values to log
+     */
+    protected logMessage(level: LogLevel, bold: boolean, prefix: string, toLog: LogParam[]): void;
+    /**
+     * Controls whether natural colors in log output are preserved.
+     *
+     * When enabled, disables ANSI color codes to preserve any colors that might
+     * be present in the log content itself.
+     *
+     * @param keepNaturalColors - If true, disables color codes. Defaults to true.
+     */
+    keepLogsNaturalColors(keepNaturalColors?: boolean): void;
+}
+export declare const LogClient_Terminal: LogClient_Terminal_class;
+export {};

package/LogClient_Terminal.js

@@ -0,0 +1,81 @@
+/*
+ * @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 { _logger_convertLogParamsToStrings, _logger_indentNewLineBy } from './utils.js';
+/**
+ * ANSI escape code to reset terminal color formatting.
+ *
+ * Used to reset color codes after applying colored log output.
+ */
+export const NoColor = '\x1b[0m';
+/**
+ * Log client implementation for terminal/console output with ANSI color codes.
+ *
+ * Outputs colored log messages to the console using ANSI escape sequences.
+ * Different log levels are displayed in different colors for visual distinction.
+ */
+class LogClient_Terminal_class extends LogClient {
+    /** If true, preserves natural colors in log output (disables color codes) */
+    keepNaturalColors = false;
+    /**
+     * Gets the ANSI color code for a log level.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @returns ANSI escape sequence for the color
+     */
+    getColor(level, bold = false) {
+        let color;
+        switch (level) {
+            case LogLevel.Verbose:
+                color = '\x1b[90m';
+                break;
+            case LogLevel.Debug:
+                color = '\x1b[34m';
+                break;
+            case LogLevel.Info:
+                color = '\x1b[32m';
+                break;
+            case LogLevel.Warning:
+                color = '\x1b[33m';
+                break;
+            case LogLevel.Error:
+                color = '\x1b[31m';
+                break;
+        }
+        return color + (bold ? '\x1b[1m' : '');
+    }
+    /**
+     * Outputs a log message to the terminal with color formatting.
+     *
+     * Converts all log parameters to strings, applies color codes, and outputs
+     * to console.log. Always resets color at the end of the line.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param prefix - Composed prefix string
+     * @param toLog - Array of values to log
+     */
+    logMessage(level, bold, prefix, toLog) {
+        const color = this.getColor(level, bold);
+        const paramsAsStrings = _logger_convertLogParamsToStrings(toLog);
+        const linePrefix = `${color}${prefix}${this.keepNaturalColors ? NoColor : ''}`;
+        console.log(_logger_indentNewLineBy(linePrefix, paramsAsStrings.join(' ')) + NoColor);
+    }
+    /**
+     * Controls whether natural colors in log output are preserved.
+     *
+     * When enabled, disables ANSI color codes to preserve any colors that might
+     * be present in the log content itself.
+     *
+     * @param keepNaturalColors - If true, disables color codes. Defaults to true.
+     */
+    keepLogsNaturalColors(keepNaturalColors = true) {
+        this.keepNaturalColors = keepNaturalColors;
+    }
+}
+export const LogClient_Terminal = new LogClient_Terminal_class();