@nu-art/logger 0.401.1

package/BeLogged.d.ts

@@ -0,0 +1,92 @@
+import { LogClient } from './LogClient.js';
+import { LogLevel, LogParam } from './types.js';
+/**
+ * Central logging manager that distributes log messages to all registered log clients.
+ *
+ * BeLogged acts as a dispatcher - when a log message is sent, it forwards it to all
+ * registered LogClient instances. This allows multiple output destinations simultaneously
+ * (e.g., console + file + remote logging).
+ *
+ * Log clients are added via `addClient()` and can be removed via `removeClient()`.
+ * Each client can have its own filter and prefix composer.
+ */
+declare class BeLogged_Class {
+    /** Array of registered log clients */
+    private clients;
+    /** Line count for console rewriting (used by some clients) */
+    private lineCount;
+    /**
+     * Registers a log client to receive all log messages.
+     *
+     * The client's `init()` method is called immediately. If the client is already
+     * registered, this method does nothing (no duplicate registration).
+     *
+     * @param client - LogClient instance to register
+     */
+    addClient<Client extends LogClient>(client: Client): void;
+    /**
+     * Removes a log client (alias for removeClient for backwards compatibility).
+     *
+     * @param client - LogClient instance to remove
+     */
+    removeConsole<Client extends LogClient>(client: Client): void;
+    /**
+     * Removes a log client from the registry.
+     *
+     * The client's `stop()` method is called for cleanup. If the client is not
+     * registered, this method does nothing.
+     *
+     * @param client - LogClient instance to remove
+     */
+    removeClient<Client extends LogClient>(client: Client): void;
+    /**
+     * Logs a message to all registered clients.
+     *
+     * @param tag - Logger tag/identifier
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param toLog - Values to log (spread arguments)
+     */
+    log(tag: string, level: LogLevel, bold: boolean, ...toLog: LogParam[]): void;
+    /**
+     * Internal implementation that distributes the log message to all clients.
+     *
+     * Creates a copy of the toLog array for each client to prevent mutation issues.
+     *
+     * @param tag - Logger tag/identifier
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param toLog - Array of values to log
+     */
+    private logImpl;
+    /**
+     * Clears footer lines from console output.
+     *
+     * Used by console-based log clients to clear previously written footer content.
+     * Writes newlines to stdout to clear the specified number of lines.
+     */
+    clearFooter(): void;
+    /**
+     * Sets the line count for console rewriting operations.
+     *
+     * Used by log clients that rewrite console output (e.g., progress indicators).
+     *
+     * @param lineCount - Number of lines to track for rewriting
+     */
+    rewriteConsole(lineCount: number): void;
+    /**
+     * Removes all registered log clients and stops them.
+     *
+     * Useful for test cleanup to ensure no clients remain active.
+     */
+    removeAllClients(): void;
+}
+/**
+ * Singleton instance of the logging manager.
+ *
+ * This is the central entry point for all logging. Logger instances call
+ * `BeLogged.logImpl()` to output messages, which are then distributed to
+ * all registered log clients.
+ */
+export declare const BeLogged: BeLogged_Class;
+export {};

package/BeLogged.js

@@ -0,0 +1,124 @@
+/*
+ * @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
+ */
+/**
+ * Central logging manager that distributes log messages to all registered log clients.
+ *
+ * BeLogged acts as a dispatcher - when a log message is sent, it forwards it to all
+ * registered LogClient instances. This allows multiple output destinations simultaneously
+ * (e.g., console + file + remote logging).
+ *
+ * Log clients are added via `addClient()` and can be removed via `removeClient()`.
+ * Each client can have its own filter and prefix composer.
+ */
+class BeLogged_Class {
+    /** Array of registered log clients */
+    clients = [];
+    /** Line count for console rewriting (used by some clients) */
+    lineCount = 0;
+    /**
+     * Registers a log client to receive all log messages.
+     *
+     * The client's `init()` method is called immediately. If the client is already
+     * registered, this method does nothing (no duplicate registration).
+     *
+     * @param client - LogClient instance to register
+     */
+    addClient(client) {
+        if (this.clients.indexOf(client) !== -1)
+            return;
+        client.init();
+        this.clients.push(client);
+    }
+    /**
+     * Removes a log client (alias for removeClient for backwards compatibility).
+     *
+     * @param client - LogClient instance to remove
+     */
+    removeConsole(client) {
+        this.removeClient(client);
+    }
+    /**
+     * Removes a log client from the registry.
+     *
+     * The client's `stop()` method is called for cleanup. If the client is not
+     * registered, this method does nothing.
+     *
+     * @param client - LogClient instance to remove
+     */
+    removeClient(client) {
+        const index = this.clients.indexOf(client);
+        if (index === -1)
+            return;
+        this.clients.splice(index, 1);
+        client.stop();
+    }
+    /**
+     * Logs a message to all registered clients.
+     *
+     * @param tag - Logger tag/identifier
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param toLog - Values to log (spread arguments)
+     */
+    log(tag, level, bold, ...toLog) {
+        this.logImpl(tag, level, bold, toLog);
+    }
+    /**
+     * Internal implementation that distributes the log message to all clients.
+     *
+     * Creates a copy of the toLog array for each client to prevent mutation issues.
+     *
+     * @param tag - Logger tag/identifier
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param toLog - Array of values to log
+     */
+    logImpl(tag, level, bold, toLog) {
+        for (const client of this.clients) {
+            client.log(tag, level, bold, [...toLog]);
+        }
+    }
+    /**
+     * Clears footer lines from console output.
+     *
+     * Used by console-based log clients to clear previously written footer content.
+     * Writes newlines to stdout to clear the specified number of lines.
+     */
+    clearFooter() {
+        for (let i = 0; i < this.lineCount + 3; i++) {
+            process.stdout.write(`\n`);
+        }
+    }
+    /**
+     * Sets the line count for console rewriting operations.
+     *
+     * Used by log clients that rewrite console output (e.g., progress indicators).
+     *
+     * @param lineCount - Number of lines to track for rewriting
+     */
+    rewriteConsole(lineCount) {
+        this.lineCount = lineCount;
+    }
+    /**
+     * Removes all registered log clients and stops them.
+     *
+     * Useful for test cleanup to ensure no clients remain active.
+     */
+    removeAllClients() {
+        const clients = [...this.clients];
+        for (const client of clients) {
+            this.removeClient(client);
+        }
+    }
+}
+/**
+ * Singleton instance of the logging manager.
+ *
+ * This is the central entry point for all logging. Logger instances call
+ * `BeLogged.logImpl()` to output messages, which are then distributed to
+ * all registered log clients.
+ */
+export const BeLogged = new BeLogged_Class();

package/LogClient.d.ts

@@ -0,0 +1,126 @@
+import { LogLevel, LogParam, LogPrefixComposer } from './types.js';
+/**
+ * Filter function type for controlling which log messages are output.
+ *
+ * Returns true if the message should be logged, false to suppress it.
+ */
+export type LogFilter = (level: LogLevel, tag: string) => boolean;
+/**
+ * Abstract base class for all log client implementations.
+ *
+ * LogClient defines the interface for outputting log messages. Each implementation
+ * handles the actual output mechanism (console, file, browser, etc.). The base class
+ * provides:
+ * - Prefix composition (timestamp, level, tag formatting)
+ * - Filtering (optional per-client filtering)
+ * - Lifecycle management (init/stop)
+ *
+ * Concrete implementations must override `logMessage()` to perform the actual output.
+ *
+ * @example
+ * ```typescript
+ * class CustomLogClient extends LogClient {
+ *   protected logMessage(level: LogLevel, bold: boolean, prefix: string, ...toLog: LogParam[]) {
+ *     // Custom output logic
+ *     console.log(prefix, ...toLog);
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class LogClient {
+    /** Function that composes the log prefix (timestamp, level, tag) */
+    private prefixComposer;
+    /** Optional filter function to suppress certain log messages */
+    private filter;
+    /**
+     * Abstract method that concrete implementations must override.
+     *
+     * Performs the actual output of the log message. The prefix is already composed,
+     * and filtering has already been applied.
+     *
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param prefix - Composed prefix string (timestamp, level indicator, tag)
+     * @param toLog - Array of values to log
+     */
+    protected abstract logMessage(level: LogLevel, bold: boolean, prefix: string, toLog: LogParam[]): void;
+    /**
+     * Sets a custom prefix composer for this log client.
+     *
+     * The composer function generates the prefix string that appears before each log message.
+     *
+     * @param logComposer - Function that generates the prefix from tag and level
+     */
+    setComposer(logComposer: LogPrefixComposer): void;
+    /**
+     * Lifecycle hook called when the log client is added to BeLogged.
+     *
+     * Override to perform initialization (e.g., open files, set up connections).
+     */
+    init(): void;
+    /**
+     * Lifecycle hook called when the log client is removed from BeLogged.
+     *
+     * Override to perform cleanup (e.g., close files, clean up resources).
+     */
+    stop(): void;
+    /**
+     * Sets a filter function for this log client.
+     *
+     * The filter is applied before `logMessage()` is called. If the filter returns
+     * false, the message is not output by this client.
+     *
+     * @param filter - Function that returns true to log, false to suppress
+     * @returns This instance for method chaining
+     */
+    setFilter(filter: LogFilter): this;
+    /**
+     * Logs a message through this client.
+     *
+     * Applies the filter, composes the prefix, and calls `logMessage()` if the
+     * message passes the filter.
+     *
+     * @param tag - Logger tag/identifier
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param toLog - Array of values to log
+     */
+    log(tag: string, level: LogLevel, bold: boolean, toLog: LogParam[]): void;
+}
+/**
+ * Timezone offset in milliseconds, calculated once at module load.
+ *
+ * Used to adjust timestamps to local timezone in log prefixes.
+ */
+export declare const _logger_timezoneOffset: number;
+/**
+ * Reusable Date object for timestamp formatting (mutated, not recreated for performance).
+ *
+ * **Performance Note**: This Date object is mutated on every log call to avoid creating
+ * new Date instances. This is safe in Node.js's single-threaded execution model but
+ * would not be thread-safe in a multi-threaded environment.
+ */
+export declare const _logger_finalDate: Date;
+/**
+ * Array of log level prefix indicators.
+ *
+ * Maps log levels to their string representations: '---' (unknown), '-V-' (Verbose),
+ * '-D-' (Debug), '-I-' (Info), '-W-' (Warning), '-E-' (Error).
+ */
+export declare const _logger_logPrefixes: readonly ["---", "-V-", "-D-", "-I-", "-W-", "-E-"];
+/**
+ * Gets the prefix indicator for a log level.
+ *
+ * @param level - Log level
+ * @returns Prefix string ('-V-' for Verbose, '-D-' for Debug, etc.)
+ */
+export declare function _logger_getPrefix(level: LogLevel): typeof _logger_logPrefixes[number];
+/**
+ * Default prefix composer that generates timestamps and level indicators.
+ *
+ * Format: `  YYYY-MM-DD_HH:mm:ss.SSS -X- Tag:  `
+ *
+ * **Note**: Mutates the shared `_logger_finalDate` object for performance.
+ * Uses timezone offset to adjust timestamps.
+ */
+export declare const DefaultLogPrefixComposer: LogPrefixComposer;

package/LogClient.js

@@ -0,0 +1,143 @@
+/*
+ * @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';
+/**
+ * Abstract base class for all log client implementations.
+ *
+ * LogClient defines the interface for outputting log messages. Each implementation
+ * handles the actual output mechanism (console, file, browser, etc.). The base class
+ * provides:
+ * - Prefix composition (timestamp, level, tag formatting)
+ * - Filtering (optional per-client filtering)
+ * - Lifecycle management (init/stop)
+ *
+ * Concrete implementations must override `logMessage()` to perform the actual output.
+ *
+ * @example
+ * ```typescript
+ * class CustomLogClient extends LogClient {
+ *   protected logMessage(level: LogLevel, bold: boolean, prefix: string, ...toLog: LogParam[]) {
+ *     // Custom output logic
+ *     console.log(prefix, ...toLog);
+ *   }
+ * }
+ * ```
+ */
+export class LogClient {
+    /** Function that composes the log prefix (timestamp, level, tag) */
+    prefixComposer = DefaultLogPrefixComposer;
+    /** Optional filter function to suppress certain log messages */
+    filter = () => true;
+    /**
+     * Sets a custom prefix composer for this log client.
+     *
+     * The composer function generates the prefix string that appears before each log message.
+     *
+     * @param logComposer - Function that generates the prefix from tag and level
+     */
+    setComposer(logComposer) {
+        this.prefixComposer = logComposer;
+    }
+    /**
+     * Lifecycle hook called when the log client is added to BeLogged.
+     *
+     * Override to perform initialization (e.g., open files, set up connections).
+     */
+    init() {
+    }
+    /**
+     * Lifecycle hook called when the log client is removed from BeLogged.
+     *
+     * Override to perform cleanup (e.g., close files, clean up resources).
+     */
+    stop() {
+    }
+    /**
+     * Sets a filter function for this log client.
+     *
+     * The filter is applied before `logMessage()` is called. If the filter returns
+     * false, the message is not output by this client.
+     *
+     * @param filter - Function that returns true to log, false to suppress
+     * @returns This instance for method chaining
+     */
+    setFilter(filter) {
+        this.filter = filter;
+        return this;
+    }
+    /**
+     * Logs a message through this client.
+     *
+     * Applies the filter, composes the prefix, and calls `logMessage()` if the
+     * message passes the filter.
+     *
+     * @param tag - Logger tag/identifier
+     * @param level - Log level
+     * @param bold - Whether to apply bold formatting
+     * @param toLog - Array of values to log
+     */
+    log(tag, level, bold, toLog) {
+        if (!this.filter(level, tag))
+            return;
+        this.logMessage(level, bold, this.prefixComposer(tag, level), toLog);
+    }
+}
+/**
+ * Timezone offset in milliseconds, calculated once at module load.
+ *
+ * Used to adjust timestamps to local timezone in log prefixes.
+ */
+export const _logger_timezoneOffset = new Date().getTimezoneOffset() * 60000; //offset in milliseconds
+/**
+ * Reusable Date object for timestamp formatting (mutated, not recreated for performance).
+ *
+ * **Performance Note**: This Date object is mutated on every log call to avoid creating
+ * new Date instances. This is safe in Node.js's single-threaded execution model but
+ * would not be thread-safe in a multi-threaded environment.
+ */
+export const _logger_finalDate = new Date();
+/**
+ * Array of log level prefix indicators.
+ *
+ * Maps log levels to their string representations: '---' (unknown), '-V-' (Verbose),
+ * '-D-' (Debug), '-I-' (Info), '-W-' (Warning), '-E-' (Error).
+ */
+export const _logger_logPrefixes = ['---', '-V-', '-D-', '-I-', '-W-', '-E-'];
+/**
+ * Gets the prefix indicator for a log level.
+ *
+ * @param level - Log level
+ * @returns Prefix string ('-V-' for Verbose, '-D-' for Debug, etc.)
+ */
+export function _logger_getPrefix(level) {
+    switch (level) {
+        case LogLevel.Verbose:
+            return '-V-';
+        case LogLevel.Debug:
+            return '-D-';
+        case LogLevel.Info:
+            return '-I-';
+        case LogLevel.Warning:
+            return '-W-';
+        case LogLevel.Error:
+            return '-E-';
+        default:
+            return '---';
+    }
+}
+/**
+ * Default prefix composer that generates timestamps and level indicators.
+ *
+ * Format: `  YYYY-MM-DD_HH:mm:ss.SSS -X- Tag:  `
+ *
+ * **Note**: Mutates the shared `_logger_finalDate` object for performance.
+ * Uses timezone offset to adjust timestamps.
+ */
+export const DefaultLogPrefixComposer = (tag, level) => {
+    _logger_finalDate.setTime(Date.now() - _logger_timezoneOffset);
+    const date = _logger_finalDate.toISOString().replace(/T/, '_').replace(/Z/, '').substring(0, 23);
+    return `  ${date} ${_logger_getPrefix(level)} ${tag}:  `;
+};

package/LogClient_BaseRotate.d.ts

@@ -0,0 +1,91 @@
+import { LogClient } from './LogClient.js';
+import { LogLevel, LogParam } from './types.js';
+/** Callback function type for log rotation events */
+type LogRotateListener = () => void;
+/**
+ * Base class for log clients that support log rotation.
+ *
+ * Automatically rotates logs when the buffer size exceeds `maxSize`. Rotation works
+ * by shifting existing log files/buffers (e.g., log-0.txt → log-1.txt, log-1.txt → log-2.txt)
+ * and creating a new current log file/buffer. Oldest logs beyond `maxEntries` are deleted.
+ *
+ * Subclasses must implement:
+ * - `printLogMessage()` - How to output the log
+ * - `prepare()` - Initialize the buffer/file
+ * - `cleanup()` - Clean up old logs
+ * - `rotateBuffer()` - Move log from one index to another
+ */
+export declare abstract class LogClient_BaseRotate extends LogClient {
+    /** Name identifier for this log client (used in filenames) */
+    readonly name: string;
+    /** Maximum number of rotated log files/buffers to keep */
+    readonly maxEntries: number;
+    /** Maximum size in bytes before rotation is triggered */
+    readonly maxSize: number;
+    /** Current size of the buffer in bytes */
+    protected bufferSize: number;
+    /** Optional callback invoked when rotation occurs */
+    private rotationListener?;
+    /**
+     * Creates a new rotating log client.
+     *
+     * @param name - Identifier for this log client (used in filenames)
+     * @param maxEntries - Maximum number of rotated logs to keep (default: 10)
+     * @param maxSize - Maximum buffer size in bytes before rotation (default: 1MB)
+     */
+    protected constructor(name: string, maxEntries?: number, maxSize?: number);
+    /**
+     * Processes and outputs a log message, checking for rotation.
+     *
+     * Checks if rotation is needed before writing. Tracks buffer size and triggers
+     * rotation when the threshold is exceeded.
+     *
+     * @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;
+    /**
+     * Processes log parameters into a formatted string.
+     *
+     * Can be overridden by subclasses to customize formatting.
+     *
+     * @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;
+    /**
+     * Sets a callback to be invoked when log rotation occurs.
+     *
+     * @param rotationListener - Function to call on rotation
+     * @returns This instance for method chaining
+     */
+    setRotationListener(rotationListener: LogRotateListener): this;
+    /**
+     * Outputs the formatted log message.
+     *
+     * Must be implemented by subclasses to define the actual output mechanism.
+     *
+     * @param log - Formatted log string (includes newline)
+     */
+    protected abstract printLogMessage(log: string): void;
+    /**
+     * Checks if rotation is needed and performs it if the buffer size exceeds maxSize.
+     *
+     * Rotation process:
+     * 1. Deletes the oldest log (cleanup)
+     * 2. Shifts all logs one position (rotateBuffer)
+     * 3. Creates a new current log (prepare)
+     * 4. Resets buffer size counter
+     * 5. Invokes rotation listener if set
+     */
+    private rotate;
+    protected abstract cleanup(): void;
+    protected abstract prepare(): void;
+    protected abstract rotateBuffer(fromIndex: number, toIndex: number): void;
+}
+export {};

package/LogClient_BaseRotate.js

@@ -0,0 +1,109 @@
+/*
+ * @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_convertLogParamsToStrings, _logger_indentNewLineBy } from './utils.js';
+/**
+ * Base class for log clients that support log rotation.
+ *
+ * Automatically rotates logs when the buffer size exceeds `maxSize`. Rotation works
+ * by shifting existing log files/buffers (e.g., log-0.txt → log-1.txt, log-1.txt → log-2.txt)
+ * and creating a new current log file/buffer. Oldest logs beyond `maxEntries` are deleted.
+ *
+ * Subclasses must implement:
+ * - `printLogMessage()` - How to output the log
+ * - `prepare()` - Initialize the buffer/file
+ * - `cleanup()` - Clean up old logs
+ * - `rotateBuffer()` - Move log from one index to another
+ */
+export class LogClient_BaseRotate extends LogClient {
+    /** Name identifier for this log client (used in filenames) */
+    name;
+    /** Maximum number of rotated log files/buffers to keep */
+    maxEntries;
+    /** Maximum size in bytes before rotation is triggered */
+    maxSize;
+    /** Current size of the buffer in bytes */
+    bufferSize = 0;
+    /** Optional callback invoked when rotation occurs */
+    rotationListener;
+    /**
+     * Creates a new rotating log client.
+     *
+     * @param name - Identifier for this log client (used in filenames)
+     * @param maxEntries - Maximum number of rotated logs to keep (default: 10)
+     * @param maxSize - Maximum buffer size in bytes before rotation (default: 1MB)
+     */
+    constructor(name, maxEntries = 10, maxSize = 1024 * 1024) {
+        super();
+        this.name = name;
+        this.maxSize = maxSize;
+        this.maxEntries = maxEntries;
+    }
+    /**
+     * Processes and outputs a log message, checking for rotation.
+     *
+     * Checks if rotation is needed before writing. Tracks buffer size and triggers
+     * rotation when the threshold is exceeded.
+     *
+     * @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 log = this.processLogMessage(level, bold, prefix, toLog);
+        this.rotate();
+        const finalLog = log + '\n';
+        this.printLogMessage(finalLog);
+        this.bufferSize += finalLog.length;
+    }
+    /**
+     * Processes log parameters into a formatted string.
+     *
+     * Can be overridden by subclasses to customize formatting.
+     *
+     * @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 paramsAsStrings = _logger_convertLogParamsToStrings(toLog);
+        return _logger_indentNewLineBy(prefix, paramsAsStrings.join(' '));
+    }
+    /**
+     * Sets a callback to be invoked when log rotation occurs.
+     *
+     * @param rotationListener - Function to call on rotation
+     * @returns This instance for method chaining
+     */
+    setRotationListener(rotationListener) {
+        this.rotationListener = rotationListener;
+        return this;
+    }
+    /**
+     * Checks if rotation is needed and performs it if the buffer size exceeds maxSize.
+     *
+     * Rotation process:
+     * 1. Deletes the oldest log (cleanup)
+     * 2. Shifts all logs one position (rotateBuffer)
+     * 3. Creates a new current log (prepare)
+     * 4. Resets buffer size counter
+     * 5. Invokes rotation listener if set
+     */
+    rotate() {
+        if (this.bufferSize < this.maxSize)
+            return;
+        this.cleanup();
+        for (let i = this.maxEntries - 1; i > 0; i--) {
+            this.rotateBuffer(i - 1, i);
+        }
+        this.rotationListener?.();
+        this.bufferSize = 0;
+        this.prepare();
+    }
+}