@mrxsys/mrx-core 2.11.0-1-and-269-20251003 → 2.11.1-1-and-275-20251023

package/dist/modules/logger/logger.d.ts

@@ -1,189 +1,171 @@
 import { TypedEventEmitter } from '../../modules/typed-event-emitter/typed-event-emitter';
 import type { LoggerEvent } from './events/logger-events';
-import type { BodiesIntersection } from './types/bodies-intersection';
+import type { LoggerOptions } from './types/logger-options';
 import type { LoggerSink } from './types/logger-sink';
+import type { SinkBodiesIntersection } from './types/sink-bodies-intersection';
 import type { SinkMap } from './types/sink-map';
-/**
- * Logger provides a flexible, type-safe logging system that allows multiple sinks for log output.
- * The logger uses a transform stream to process log entries and execute the logging sinks.
- *
- * Logger extends the TypedEventEmitter class to emit typed events when an error occurs or when the logger ends.
- * The logger can log messages with different levels: error, warn, info, debug, and log.
- *
- * @template TSinks - The map of sink names to LoggerStrategy types.
- */
 export declare class Logger<TSinks extends SinkMap = {}> extends TypedEventEmitter<LoggerEvent> {
     /**
-     * The map of sinks.
+     * Map of registered sinks (logging destinations)
      */
     private readonly _sinks;
     /**
-     * The transform stream for processing log entries.
+     * List of registered sink keys for quick access
      */
-    private readonly _logStream;
+    private readonly _sinkKeys;
     /**
-     * The queue of pending log entries.
+     * Worker instance handling log processing
      */
-    private readonly _pendingLogs;
+    private readonly _worker;
     /**
-     * The maximum number of pending logs.
-     * @defaultValue 10_000
+     * Maximum number of pending log messages allowed in the queue
      */
     private readonly _maxPendingLogs;
     /**
-     * Flag to indicate if the logger is currently writing logs.
+     * Maximum number of messages in flight to the worker
+     */
+    private readonly _maxMessagesInFlight;
+    /**
+     * Number of logs to batch before sending to worker
+     */
+    private readonly _batchSize;
+    /**
+     * Timeout in milliseconds before flushing incomplete batch
+     */
+    private readonly _batchTimeout;
+    /**
+     * Whether to auto flush and close on process exit
+     */
+    private readonly _autoEnd;
+    /**
+     * Whether to flush before process exit
+     */
+    private readonly _flushOnBeforeExit;
+    /**
+     * Queue of pending log messages
+     */
+    private readonly _pendingLogs;
+    /**
+     * Number of log messages currently being processed by the worker
+     */
+    private _messagesInFlight;
+    /**
+     * Timer for batching log messages
+     */
+    private _batchTimer;
+    /**
+     * Whether the logger is currently writing log messages to the worker
      */
     private _isWriting;
     /**
-     * Construct a Logger.
-     *
-     * @template TStrategies - The map of sink names to LoggerStrategy types.
-     *
-     * @param sinks - Initial sinks map.
-     *
-     * @param maxPendingLogs - Maximum number of logs in the queue (default: 10_000)
+     * Resolvers for flush promises
      */
-    constructor(sinks?: TSinks, maxPendingLogs?: number);
+    private readonly _flushResolvers;
     /**
-     * Register a new logging sink.
-     *
-     * @template Key - The name of the sink.
-     * @template Sink - The sink type.
-     *
-     * @param name - The name of the sink.
-     * @param sink - The sink to add. It must implement {@link LoggerSink}.
-     *
-     * @throws ({@link BaseError}) - If the sink is already added.
-     *
-     * @returns A new Logger instance with the added sink.
+     * Resolver for the close promise
      */
-    registerSink<Key extends string, Sink extends LoggerSink>(name: Key, sink: Sink): Logger<TSinks & Record<Key, Sink>>;
+    private _closeResolver;
     /**
-     * Unregister a logging sink.
-     *
-     * @template Key - The name of the sink.
-     *
-     * @param name - The name of the sink to remove.
-     *
-     * @throws ({@link BaseError}) - If the sink is not found.
-     *
-     * @returns A new Logger instance without the removed sink.
+     * Resolver for backpressure when maxMessagesInFlight is reached
      */
-    unregisterSink<Key extends keyof TSinks>(name: Key): Logger<Omit<TSinks, Key>>;
+    private _backpressureResolver;
     /**
-     * Register multiple sinks at once.
-     *
-     * @template TNew - The new sinks to add.
-     *
-     * @param sinks - An array of tuples where each tuple contains the sink name and the sink instance.
-     *
-     * @throws ({@link BaseError}) - If any sink is already added.
-     *
-     * @returns A new Logger instance with the added sinks.
+     * Handle the exit event
      */
-    registerSinks<TNew extends [string, LoggerSink][] = [string, LoggerSink][]>(sinks: TNew): Logger<TSinks & {
-        [K in TNew[number][0]]: Extract<TNew[number], [K, LoggerSink]>[1];
-    }>;
+    private readonly _handleExit;
     /**
-     * Unregister multiple sinks at once.
-     *
-     * @template Keys - The names of the sinks to remove.
-     *
-     * @param names - An array of sink names to remove.
-     *
-     * @throws ({@link BaseError}) - If any sink is not found.
-     *
-     * @returns A new Logger instance without the removed sinks.
+     * Handle the worker close event
      */
-    unregisterSinks<Keys extends Extract<keyof TSinks, string>>(names: Keys[]): Logger<Omit<TSinks, Keys>>;
+    private readonly _handleWorkerClose;
     /**
-     * Remove all sinks.
+     * Creates a new Logger instance with the specified options.
      *
-     * @returns A new Logger instance without any sinks.
+     * @param options - Configuration options for the logger
      */
-    clearSinks(): Logger;
+    constructor(options?: LoggerOptions);
     /**
-     * Log an error message.
-     *
-     * @template SNames - The names of the sinks to use.
+     * Registers a new sink (logging destination) with the logger.
      *
-     * @param object - The object to log.
-     * @param sinksNames - The names of the sinks to use. If not provided, all sinks will be used.
+     * @param sinkName - The name of the sink
+     * @param sinkConstructor - The sink class constructor
+     * @param sinkArgs - The sink constructor arguments
      *
-     * @throws ({@link BaseError}) - If no sink is added.
+     * @returns The logger instance with new type (for chaining)
      */
-    error<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: BodiesIntersection<TSinks, SNames[number]>, sinksNames?: SNames): void;
+    registerSink<TSinkName extends string, TSink extends LoggerSink, TSinkArgs extends unknown[]>(sinkName: TSinkName, sinkConstructor: new (...args: TSinkArgs) => TSink, ...sinkArgs: TSinkArgs): Logger<TSinks & Record<TSinkName, new (...args: TSinkArgs) => TSink>>;
     /**
-     * Log a warning message.
-     *
-     * @template SNames - The names of the sinks to use.
-     *
-     * @param object - The object to log.
-     * @param sinksNames - The names of the sinks to use. If not provided, all sinks will be used.
+     * Logs a message at the ERROR level to the specified sinks.
      *
-     * @throws ({@link BaseError}) - If no sink is added.
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
      */
-    warn<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: BodiesIntersection<TSinks, SNames[number]>, sinksNames?: SNames): void;
+    error<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
     /**
-     * Log an info message.
+     * Logs a message at the WARN level to the specified sinks.
      *
-     * @template SNames - The names of the sinks to use.
-     *
-     * @param object - The object to log.
-     * @param sinksNames - The names of the sinks to use. If not provided, all sinks will be used.
-     *
-     * @throws ({@link BaseError}) - If no sink is added.
+     * @param object - The log message object
+     * @param sinkNames - Optionnal array of sink names to log to; logs to all sinks if omitted
      */
-    info<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: BodiesIntersection<TSinks, SNames[number]>, sinksNames?: SNames): void;
+    warn<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
     /**
-     * Log a debug message.
-     *
-     * @template SNames - The names of the sinks to use.
-     *
-     * @param object - The object to log.
-     * @param sinksNames - The names of the sinks to use. If not provided, all sinks will be used.
+     * Logs a message at the INFO level to the specified sinks.
      *
-     * @throws ({@link BaseError}) - If no sink is added.
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
      */
-    debug<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: BodiesIntersection<TSinks, SNames[number]>, sinksNames?: SNames): void;
+    info<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
     /**
-     * Log a generic message.
+     * Logs a message at the DEBUG level to the specified sinks.
      *
-     * @template SNames - The names of the sinks to use.
-     *
-     * @param object - The object to log.
-     * @param sinksNames - The names of the sinks to use. If not provided, all sinks will be used.
-     *
-     * @throws ({@link BaseError}) - If no sink is added.
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
      */
-    log<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: BodiesIntersection<TSinks, SNames[number]>, sinksNames?: SNames): void;
+    debug<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
     /**
-     * Internal: execute all sinks for a log event.
-     *
-     * @template TLogObject - The type of the log object.
-     *
-     * @param level - The log level.
-     * @param date - The date of the log event.
-     * @param object - The object to log.
-     * @param sinksNames - The names of the sinks to use. If not provided, all sinks will be used.
+     * Logs a message at the TRACE level to the specified sinks.
      *
-     * @throws ({@link BaseError}) - If a sink throws.
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
      */
-    private _executeStrategies;
+    log<SNames extends (keyof TSinks)[] = (keyof TSinks)[]>(object: SinkBodiesIntersection<TSinks, SNames[number]>, sinkNames?: SNames): void;
     /**
-     * Internal: queue a log event and start writing if not already.
-     *
-     * @template TLogObject - The type of the log object.
-     *
-     * @param level - The log level.
-     * @param object - The object to log.
-     * @param sinksNames - The names of the sinks to use. If not provided, all sinks will be used.
+     * Flushes all pending logs and waits for them to be processed.
+     */
+    flush(): Promise<void>;
+    /**
+     * Closes the logger, flushes pending logs, and releases resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Enqueues a log message to be processed by the worker.
      *
-     * @throws ({@link BaseError}) - If no sink is added.
+     * @param level - The log level
+     * @param object - The log message object
+     * @param sinkNames - Optional array of sink names to log to; logs to all sinks if omitted
+     */
+    private _enqueue;
+    /**
+     * Triggers processing of pending logs.
+     */
+    private _triggerProcessing;
+    /**
+     * Processes pending log messages by sending them to the worker in batches.
+     */
+    private _processPendingLogs;
+    /**
+     * Releases a batch by decrementing the in-flight counter and resolving backpressure if needed.
+     */
+    private _releaseBatch;
+    /**
+     * Sets up message handling for the worker.
+     */
+    private _setupWorkerMessages;
+    /**
+     * Sets up automatic flushing and closing of the logger on process exit.
      */
-    private _out;
+    private _setupAutoEnd;
     /**
-     * Internal: process the log queue and emit 'end' when done.
+     * Handles the beforeExit event.
      */
-    private _writeLog;
+    private readonly _handleBeforeExit;
 }

package/dist/modules/logger/sinks/console-logger.d.ts

@@ -3,20 +3,6 @@ import type { LoggerSink } from '../../../modules/logger/types/logger-sink';
 /**
 * ConsoleLoggerSink implements LoggerSink to provide logging functionality to the console.
 */
-export declare class ConsoleLoggerSink implements LoggerSink {
-    private readonly _colorize;
-    /**
-    * Initializes the ConsoleLoggerSink.
-    *
-    * @param colorize - Indicates if the output should be colorized. (Default is false.)
-    */
-    constructor(colorize?: boolean);
-    /**
-    * Logs a message to the console with the specified log level.
-    *
-    * @param level - The log level at which the message should be logged.
-    * @param date - The date at which the message was logged.
-    * @param object - The object to log.
-    */
-    log(level: LogLevels, date: Date, object: unknown): void;
+export declare class ConsoleLoggerSink<TLogObject = unknown> implements LoggerSink<TLogObject> {
+    log(level: LogLevels, timestamp: number, object: TLogObject): Promise<void>;
 }

package/dist/modules/logger/sinks/devnull-logger.d.ts

@@ -0,0 +1,8 @@
+import type { LoggerSink } from '../../../modules/logger/types/logger-sink';
+/**
+ * DevNullLoggerSink implements LoggerSink to discard all logs (like /dev/null).
+ * Useful for benchmarking the logger overhead without I/O.
+ */
+export declare class DevNullLoggerSink<TLogObject = unknown> implements LoggerSink<TLogObject> {
+    log(): void;
+}

package/dist/modules/logger/sinks/file-logger/enums/file-logger-error-keys.d.ts

@@ -0,0 +1,3 @@
+export declare const FILE_LOGGER_ERROR_KEYS: {
+    readonly FAILED_TO_CLOSE_STREAM: "mrx-core.file_logger.error.failed_to_close_stream";
+};

package/dist/modules/logger/sinks/file-logger/file-logger.d.ts

@@ -0,0 +1,25 @@
+import type { LogLevels } from '../../../../modules/logger/types/log-levels';
+import type { LoggerSink } from '../../../../modules/logger/types/logger-sink';
+export interface FileLoggerConfig {
+    /**
+     * Path to the file to log to.
+     */
+    path: string;
+    /**
+     * Buffer size before flushing to disk (default: 16KB)
+     * Higher = better throughput, lower = less memory
+     */
+    bufferSize?: number;
+}
+/**
+* FileLoggerSink implements LoggerSink to provide logging functionality to the file system.
+* Uses a WriteStream for efficient buffered writes (like Pino's sonic-boom).
+*/
+export declare class FileLoggerSink<TLogObject = unknown> implements LoggerSink<TLogObject> {
+    readonly config: FileLoggerConfig;
+    private readonly _stream;
+    private _isClosed;
+    constructor(config: FileLoggerConfig);
+    log(level: LogLevels, timestamp: number, object: TLogObject): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/modules/logger/sinks/index.d.ts

@@ -1,2 +1,4 @@
-export { ConsoleLoggerSink } from './console-logger.ts';
-export { FileLoggerSink } from './file-logger.ts';
+export { ConsoleLoggerSink } from './console-logger';
+export { DevNullLoggerSink } from './devnull-logger';
+export { FILE_LOGGER_ERROR_KEYS } from './file-logger/enums/file-logger-error-keys';
+export { FileLoggerSink, type FileLoggerConfig } from './file-logger/file-logger';

package/dist/modules/logger/sinks/index.js

@@ -1,44 +1,67 @@
 // @bun
+import {
+  BaseError
+} from "../../../chunk-9cgzhc50.js";
+
 // source/modules/logger/sinks/console-logger.ts
 class ConsoleLoggerSink {
-  _colorize;
-  constructor(colorize = false) {
-    this._colorize = colorize;
-  }
-  log(level, date, object) {
-    const colors = {
-      ERROR: "\x1B[31m",
-      WARN: "\x1B[33m",
-      INFO: "\x1B[36m",
-      DEBUG: "\x1B[34m",
-      LOG: "\x1B[35m"
-    };
-    const dateColor = this._colorize ? "\x1B[33m" : "";
-    const colorReset = this._colorize ? "\x1B[0m" : "";
-    const logLevelColor = this._colorize ? colors[level] : "";
-    const sanitizedObject = typeof object === "string" ? object : JSON.stringify(object);
-    const prefixDate = `[${dateColor}${date.toISOString().replace(/T/, " ").replace(/\..+/, "")}${colorReset}]`;
-    const message = `${prefixDate} ${logLevelColor}${level}${colorReset} : ${sanitizedObject}`;
-    console[level.toLowerCase()](message);
+  async log(level, timestamp, object) {
+    const sanitizedContent = typeof object === "string" ? object : JSON.stringify(object);
+    await Bun.write(Bun.stdout, `{"timestamp":${timestamp},"level":"${level}","content":${sanitizedContent}}
+`);
   }
 }
-// source/modules/logger/sinks/file-logger.ts
-import { appendFile } from "fs/promises";
-
+// source/modules/logger/sinks/devnull-logger.ts
+class DevNullLoggerSink {
+  log() {}
+}
+// source/modules/logger/sinks/file-logger/enums/file-logger-error-keys.ts
+var FILE_LOGGER_ERROR_KEYS = {
+  FAILED_TO_CLOSE_STREAM: "mrx-core.file_logger.error.failed_to_close_stream"
+};
+// source/modules/logger/sinks/file-logger/file-logger.ts
+import { createWriteStream } from "fs";
 class FileLoggerSink {
-  _path;
-  constructor(path) {
-    this._path = path;
+  config;
+  _stream;
+  _isClosed = false;
+  constructor(config) {
+    this.config = config;
+    this._stream = createWriteStream(config.path, {
+      flags: "a",
+      encoding: "utf8",
+      highWaterMark: config.bufferSize ?? 16 * 1024
+    });
   }
-  async log(level, date, object) {
-    const prefixDate = `[${date.toISOString().replace(/T/, " ").replace(/\..+/, "")}]`;
-    const sanitizedObject = typeof object === "string" ? object : JSON.stringify(object);
-    const message = `${prefixDate} ${level} : ${sanitizedObject}`;
-    await appendFile(this._path, `${message}
-`);
+  async log(level, timestamp, object) {
+    if (this._isClosed)
+      return;
+    const sanitizedContent = typeof object === "string" ? object : JSON.stringify(object);
+    const message = `{"timestamp":${timestamp},"level":"${level}","content":${sanitizedContent}}
+`;
+    const canContinue = this._stream.write(message);
+    if (!canContinue)
+      await new Promise((resolve) => {
+        this._stream.once("drain", resolve);
+      });
+  }
+  async close() {
+    if (this._isClosed)
+      return;
+    this._isClosed = true;
+    return new Promise((resolve, reject) => {
+      this._stream.end((err) => {
+        if (err)
+          reject(new BaseError(FILE_LOGGER_ERROR_KEYS.FAILED_TO_CLOSE_STREAM, err.message));
+        else
+          resolve();
+      });
+    });
   }
 }
 export {
   FileLoggerSink,
+  FILE_LOGGER_ERROR_KEYS,
+  DevNullLoggerSink,
   ConsoleLoggerSink
 };

package/dist/modules/logger/types/index.d.ts

@@ -1,6 +1,6 @@
-export type { BodiesIntersection } from './bodies-intersection.ts';
-export type { LogLevels } from './log-levels.ts';
-export type { LogStreamChunk } from './log-stream-chunk.ts';
-export type { LoggerSink } from './logger-sink.ts';
-export type { SinkBody } from './sink-body.ts';
-export type { SinkMap } from './sink-map.ts';
+export type { LogLevels } from './log-levels';
+export type { LoggerOptions } from './logger-options';
+export type { LoggerSink } from './logger-sink';
+export type { SinkBodiesIntersection } from './sink-bodies-intersection';
+export type { SinkBody } from './sink-body';
+export type { SinkMap } from './sink-map';

package/dist/modules/logger/types/log-levels.d.ts

@@ -1,4 +1 @@
-/**
- * The log levels.
- */
-export type LogLevels = 'ERROR' | 'WARN' | 'INFO' | 'DEBUG' | 'LOG';
+export type LogLevels = 'ERROR' | 'WARN' | 'INFO' | 'DEBUG' | 'LOG' | 'TRACE';

package/dist/modules/logger/types/logger-options.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Configuration options for the Logger instance.
+ */
+export interface LoggerOptions {
+    /**
+     * Maximum number of log messages that can be queued in memory before dropping new logs.
+     * @default 10_000
+     */
+    maxPendingLogs?: number;
+    /**
+     * Maximum number of messages that can be sent to the worker without acknowledgment.
+     * Controls backpressure to prevent overwhelming the worker thread.
+     * @default 100
+     */
+    maxMessagesInFlight?: number;
+    /**
+     * Maximum number of logs to batch together before sending to the worker.
+     * Higher values = better throughput but higher latency.
+     * @default 100
+     */
+    batchSize?: number;
+    /**
+     * Maximum time in milliseconds to wait before flushing a partial batch.
+     * Prevents logs from being delayed indefinitely when batch size is not reached.
+     * Set to 0 to disable time-based flushing.
+     * @default 0.1 (100 microseconds)
+     */
+    batchTimeout?: number;
+    /**
+     * Whether to automatically flush and close the logger when the process exits.
+     * When enabled, hooks are installed on `process.on('beforeExit')` and `process.on('exit')`.
+     * @default true
+     */
+    autoEnd?: boolean;
+    /**
+     * Whether to flush pending logs before the process exits.
+     * Only applies when `autoEnd` is true.
+     * @default true
+     */
+    flushOnBeforeExit?: boolean;
+}

package/dist/modules/logger/types/logger-sink.d.ts

@@ -1,11 +1,20 @@
 import type { LogLevels } from './log-levels';
-export interface LoggerSink<TLogObject = unknown> {
+export interface LoggerSink<TLogObject = unknown, TConfig = unknown> {
+    /** Optional configuration for the sink */
+    readonly config?: TConfig;
     /**
      * Logs a message with the sink's implementation.
+     * si vous voulez créer votre propre sink vous devrez implémenter cette méthode et tout ce qui est importation doit etre sous forme d'importation dynamique
      *
      * @param level - The log level at which the message should be logged.
-     * @param date - The date at which the message was logged.
+     * @param timestamp - The date at which the message was logged.
      * @param object - The object to log.
      */
-    log(level: LogLevels, date: Date, object: TLogObject): Promise<void> | void;
+    log(level: LogLevels, timestamp: number, object: TLogObject): Promise<void> | void;
+    /**
+     * Closes the sink and flushes any pending logs.
+     * This method is called when the logger is closing to ensure all resources are properly released.
+     * Optional - implement this if your sink needs cleanup (e.g., closing file handles, database connections).
+     */
+    close?(): Promise<void> | void;
 }

package/dist/modules/logger/types/sink-bodies-intersection.d.ts

@@ -0,0 +1,2 @@
+import type { SinkBody } from './sink-body';
+export type SinkBodiesIntersection<TSinks, K extends keyof TSinks> = (K extends unknown ? (object: SinkBody<TSinks, K>) => void : never) extends (object: infer I) => void ? I : never;

package/dist/modules/logger/types/sink-body.d.ts

@@ -1,2 +1,2 @@
 import type { LoggerSink } from './logger-sink';
-export type SinkBody<TSink, Key extends keyof TSink> = TSink[Key] extends LoggerSink<infer TBody> ? TBody : never;
+export type SinkBody<TSink, Key extends keyof TSink> = TSink[Key] extends new (...args: any[]) => LoggerSink<infer TBody> ? TBody : TSink[Key] extends LoggerSink<infer TBody> ? TBody : never;

package/dist/modules/logger/types/sink-map.d.ts

@@ -1,2 +1,2 @@
 import type { LoggerSink } from './logger-sink';
-export type SinkMap = Record<string, LoggerSink>;
+export type SinkMap = Record<string, new (...args: any[]) => LoggerSink>;