@mrxsys/mrx-core 2.4.0 → 2.5.1

package/dist/modules/logger/index.js

@@ -0,0 +1,139 @@
+// @bun
+import {
+  TypedEventEmitter
+} from "../../chunk-yvyahr2h.js";
+import {
+  BaseError
+} from "../../chunk-vknq69e0.js";
+
+// source/modules/logger/logger.ts
+import { once } from "events";
+import { Transform } from "stream";
+
+// source/modules/logger/enums/loggerErrorKeys.ts
+var LOGGER_ERROR_KEYS = {
+  STRATEGY_ALREADY_ADDED: "logger.error.strategy_already_added",
+  STRATEGY_NOT_FOUND: "logger.error.strategy_not_found",
+  NO_STRATEGY_ADDED: "logger.error.no_strategy_added",
+  STRATEGY_ERROR: "logger.error.strategy_error"
+};
+
+// source/modules/logger/logger.ts
+class Logger extends TypedEventEmitter {
+  _strategies;
+  _logStream;
+  _pendingLogs = [];
+  _maxPendingLogs;
+  _isWriting = false;
+  constructor(strategies = {}, maxPendingLogs = 1e4) {
+    super();
+    this._strategies = strategies;
+    this._maxPendingLogs = maxPendingLogs;
+    this._logStream = new Transform({
+      objectMode: true,
+      transform: (chunk, _, callback) => {
+        this._executeStrategies(chunk.level, new Date(chunk.date), chunk.object, chunk.strategiesNames).then(() => callback()).catch((error) => {
+          this.emit("error", error);
+          callback();
+        });
+      }
+    });
+  }
+  registerStrategy(name, strategy) {
+    if (this._strategies[name])
+      throw new BaseError({
+        message: LOGGER_ERROR_KEYS.STRATEGY_ALREADY_ADDED,
+        cause: { strategyName: name }
+      });
+    return new Logger({
+      ...this._strategies,
+      [name]: strategy
+    }, this._maxPendingLogs);
+  }
+  unregisterStrategy(name) {
+    if (!(name in this._strategies))
+      throw new BaseError({
+        message: LOGGER_ERROR_KEYS.STRATEGY_NOT_FOUND,
+        cause: { strategyName: name }
+      });
+    const { [name]: _, ...rest } = this._strategies;
+    return new Logger(rest, this._maxPendingLogs);
+  }
+  registerStrategies(strategies) {
+    return strategies.reduce((logger, [name, strategy]) => logger.registerStrategy(name, strategy), this);
+  }
+  unregisterStrategies(names) {
+    let logger = this;
+    for (const name of names)
+      logger = logger.unregisterStrategy(name);
+    return logger;
+  }
+  clearStrategies() {
+    return new Logger({}, this._maxPendingLogs);
+  }
+  error(object, strategiesNames) {
+    this._out("ERROR", object, strategiesNames);
+  }
+  warn(object, strategiesNames) {
+    this._out("WARN", object, strategiesNames);
+  }
+  info(object, strategiesNames) {
+    this._out("INFO", object, strategiesNames);
+  }
+  debug(object, strategiesNames) {
+    this._out("DEBUG", object, strategiesNames);
+  }
+  log(object, strategiesNames) {
+    this._out("LOG", object, strategiesNames);
+  }
+  async _executeStrategies(level, date, object, strategiesNames) {
+    await Promise.all(strategiesNames.map(async (name) => {
+      try {
+        await this._strategies[name]?.log(level, date, object);
+      } catch (error) {
+        throw new BaseError({
+          message: LOGGER_ERROR_KEYS.STRATEGY_ERROR,
+          cause: { strategyName: name, object, error }
+        });
+      }
+    }));
+  }
+  _out(level, object, strategiesNames) {
+    const strategyKeys = Object.keys(this._strategies);
+    if (strategyKeys.length === 0)
+      throw new BaseError({
+        message: LOGGER_ERROR_KEYS.NO_STRATEGY_ADDED,
+        cause: { level, object }
+      });
+    if (this._pendingLogs.length >= this._maxPendingLogs)
+      return;
+    const log = {
+      date: new Date().toISOString(),
+      level,
+      object,
+      strategiesNames: strategiesNames ? strategiesNames : strategyKeys
+    };
+    this._pendingLogs.push(log);
+    if (!this._isWriting) {
+      this._isWriting = true;
+      setImmediate(() => {
+        this._writeLog();
+      });
+    }
+  }
+  async _writeLog() {
+    while (this._pendingLogs.length > 0) {
+      const pendingLog = this._pendingLogs.shift();
+      if (!pendingLog)
+        continue;
+      const canWrite = this._logStream.write(pendingLog);
+      if (!canWrite)
+        await once(this._logStream, "drain");
+    }
+    this._isWriting = false;
+    this.emit("end");
+  }
+}
+export {
+  Logger
+};

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

@@ -0,0 +1,189 @@
+import { TypedEventEmitter } from '../../modules/typedEventEmitter/typedEventEmitter';
+import type { LoggerEvent } from './events/loggerEvents';
+import type { BodiesIntersection } from './types/bodiesIntersection';
+import type { LoggerStrategy } from './types/loggerStrategy';
+import type { StrategyMap } from './types/strategyMap';
+/**
+* Logger provides a flexible, type-safe logging system that allows multiple strategies for log output.
+* The logger uses a transform stream to process log entries and execute the logging strategies.
+*
+* 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 TStrategies - The map of strategy names to LoggerStrategy types.
+*/
+export declare class Logger<TStrategies extends StrategyMap = {}> extends TypedEventEmitter<LoggerEvent> {
+    /**
+    * The map of strategies.
+    */
+    private readonly _strategies;
+    /**
+    * The transform stream for processing log entries.
+    */
+    private readonly _logStream;
+    /**
+    * The queue of pending log entries.
+    */
+    private readonly _pendingLogs;
+    /**
+    * The maximum number of pending logs.
+    * @defaultValue 10_000
+    */
+    private readonly _maxPendingLogs;
+    /**
+    * Flag to indicate if the logger is currently writing logs.
+    */
+    private _isWriting;
+    /**
+    * Construct a Logger.
+    *
+    * @template TStrategies - The map of strategy names to LoggerStrategy types.
+    *
+    * @param strategies - Initial strategies map.
+    *
+    * @param maxPendingLogs - Maximum number of logs in the queue (default: 10_000)
+    */
+    constructor(strategies?: TStrategies, maxPendingLogs?: number);
+    /**
+    * Register a new logging strategy.
+    *
+    * @template Key - The name of the strategy.
+    * @template Strategy - The strategy type.
+    *
+    * @param name - The name of the strategy.
+    * @param strategy - The strategy to add. It must implement {@link LoggerStrategy}.
+    *
+    * @throws ({@link BaseError}) - If the strategy is already added.
+    *
+    * @returns A new Logger instance with the added strategy.
+    */
+    registerStrategy<Key extends string, Strategy extends LoggerStrategy>(name: Key, strategy: Strategy): Logger<TStrategies & Record<Key, Strategy>>;
+    /**
+    * Unregister a logging strategy.
+    *
+    * @template Key - The name of the strategy.
+    *
+    * @param name - The name of the strategy to remove.
+    *
+    * @throws ({@link BaseError}) - If the strategy is not found.
+    *
+    * @returns A new Logger instance without the removed strategy.
+    */
+    unregisterStrategy<Key extends keyof TStrategies>(name: Key): Logger<Omit<TStrategies, Key>>;
+    /**
+    * Register multiple strategies at once.
+    *
+    * @template TNew - The new strategies to add.
+    *
+    * @param strategies - An array of tuples where each tuple contains the strategy name and the strategy instance.
+    *
+    * @throws ({@link BaseError}) - If any strategy is already added.
+    *
+    * @returns A new Logger instance with the added strategies.
+    */
+    registerStrategies<TNew extends [string, LoggerStrategy][] = [string, LoggerStrategy][]>(strategies: TNew): Logger<TStrategies & {
+        [K in TNew[number][0]]: Extract<TNew[number], [K, LoggerStrategy]>[1];
+    }>;
+    /**
+    * Unregister multiple strategies at once.
+    *
+    * @template Keys - The names of the strategies to remove.
+    *
+    * @param names - An array of strategy names to remove.
+    *
+    * @throws ({@link BaseError}) - If any strategy is not found.
+    *
+    * @returns A new Logger instance without the removed strategies.
+    */
+    unregisterStrategies<Keys extends Extract<keyof TStrategies, string>>(names: Keys[]): Logger<Omit<TStrategies, Keys>>;
+    /**
+    * Remove all strategies.
+    *
+    * @returns A new Logger instance without any strategies.
+    */
+    clearStrategies(): Logger;
+    /**
+    * Log an error message.
+    *
+    * @template SNames - The names of the strategies to use.
+    *
+    * @param object - The object to log.
+    * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
+    *
+    * @throws ({@link BaseError}) - If no strategy is added.
+    */
+    error<SNames extends (keyof TStrategies)[] = (keyof TStrategies)[]>(object: BodiesIntersection<TStrategies, SNames[number]>, strategiesNames?: SNames): void;
+    /**
+    * Log a warning message.
+    *
+    * @template SNames - The names of the strategies to use.
+    *
+    * @param object - The object to log.
+    * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
+    *
+    * @throws ({@link BaseError}) - If no strategy is added.
+    */
+    warn<SNames extends (keyof TStrategies)[] = (keyof TStrategies)[]>(object: BodiesIntersection<TStrategies, SNames[number]>, strategiesNames?: SNames): void;
+    /**
+    * Log an info message.
+    *
+    * @template SNames - The names of the strategies to use.
+    *
+    * @param object - The object to log.
+    * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
+    *
+    * @throws ({@link BaseError}) - If no strategy is added.
+    */
+    info<SNames extends (keyof TStrategies)[] = (keyof TStrategies)[]>(object: BodiesIntersection<TStrategies, SNames[number]>, strategiesNames?: SNames): void;
+    /**
+    * Log a debug message.
+    *
+    * @template SNames - The names of the strategies to use.
+    *
+    * @param object - The object to log.
+    * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
+    *
+    * @throws ({@link BaseError}) - If no strategy is added.
+    */
+    debug<SNames extends (keyof TStrategies)[] = (keyof TStrategies)[]>(object: BodiesIntersection<TStrategies, SNames[number]>, strategiesNames?: SNames): void;
+    /**
+    * Log a generic message.
+    *
+    * @template SNames - The names of the strategies to use.
+    *
+    * @param object - The object to log.
+    * @param strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
+    *
+    * @throws ({@link BaseError}) - If no strategy is added.
+    */
+    log<SNames extends (keyof TStrategies)[] = (keyof TStrategies)[]>(object: BodiesIntersection<TStrategies, SNames[number]>, strategiesNames?: SNames): void;
+    /**
+    * Internal: execute all strategies 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 strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
+    *
+    * @throws ({@link BaseError}) - If a strategy throws.
+    */
+    private _executeStrategies;
+    /**
+    * 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 strategiesNames - The names of the strategies to use. If not provided, all strategies will be used.
+    *
+    * @throws ({@link BaseError}) - If no strategy is added.
+    */
+    private _out;
+    /**
+    * Internal: process the log queue and emit 'end' when done.
+    */
+    private _writeLog;
+}

package/dist/{logger → modules/logger}/strategies/consoleLogger.d.ts

@@ -1,7 +1,7 @@
-import type { LoggerStrategy } from '../../logger/types/loggerStrategy';
-import type { LogLevels } from '../../logger/types/logLevels';
+import type { LoggerStrategy } from '../../../modules/logger/types/loggerStrategy';
+import type { LogLevels } from '../../../modules/logger/types/logLevels';
 /**
- * ConsoleLoggerStrategy implements LoggerStrategy to provide logging functionality to the console. ({@link LoggerStrategy})
+ * ConsoleLoggerStrategy implements {@link LoggerStrategy} to provide logging functionality to the console.
  */
 export declare class ConsoleLoggerStrategy implements LoggerStrategy {
     private readonly _colorize;
@@ -14,7 +14,7 @@ export declare class ConsoleLoggerStrategy implements LoggerStrategy {
     /**
      * Logs a message to the console with the specified log level.
      *
-     * @param level - The log level at which the message should be logged. ({@link LogLevels})
+     * @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.
      */

package/dist/{logger → modules/logger}/strategies/fileLogger.d.ts

@@ -1,7 +1,7 @@
-import type { LoggerStrategy } from '../../logger/types/loggerStrategy';
-import type { LogLevels } from '../../logger/types/logLevels';
+import type { LoggerStrategy } from '../../../modules/logger/types/loggerStrategy';
+import type { LogLevels } from '../../../modules/logger/types/logLevels';
 /**
- * FileLoggerStrategy implements LoggerStrategy to provide logging functionality to the file system. ({@link LoggerStrategy})
+ * FileLoggerStrategy implements {@link LoggerStrategy} to provide logging functionality to the file system.
  */
 export declare class FileLoggerStrategy implements LoggerStrategy {
     /**
@@ -17,7 +17,7 @@ export declare class FileLoggerStrategy implements LoggerStrategy {
     /**
      * Logs a message to the file system with the specified log level.
      *
-     * @param level - The log level at which the message should be logged. {@link LogLevels}
+     * @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.
      */

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

@@ -0,0 +1,2 @@
+export { ConsoleLoggerStrategy } from './consoleLogger.ts';
+export { FileLoggerStrategy } from './fileLogger.ts';

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

@@ -0,0 +1,44 @@
+// @bun
+// source/modules/logger/strategies/consoleLogger.ts
+class ConsoleLoggerStrategy {
+  _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);
+  }
+}
+// source/modules/logger/strategies/fileLogger.ts
+import { appendFile } from "fs/promises";
+
+class FileLoggerStrategy {
+  _path;
+  constructor(path) {
+    this._path = path;
+  }
+  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}
+`);
+  }
+}
+export {
+  FileLoggerStrategy,
+  ConsoleLoggerStrategy
+};

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

@@ -0,0 +1,6 @@
+export type { BodiesIntersection } from './bodiesIntersection.ts';
+export type { LoggerStrategy } from './loggerStrategy.ts';
+export type { LogLevels } from './logLevels.ts';
+export type { LogStreamChunk } from './logStreamChunk.ts';
+export type { StrategyBody } from './strategyBody.ts';
+export type { StrategyMap } from './strategyMap.ts';

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

@@ -0,0 +1 @@
+// @bun

package/dist/{logger → modules/logger}/types/logStreamChunk.d.ts

@@ -5,11 +5,11 @@ import type { StrategyMap } from './strategyMap';
  */
 export interface LogStreamChunk<TLogObject, TStrategies extends StrategyMap> {
     /** ISO date string of the log event. */
-    date: string;
+    readonly date: string;
     /** Log level. */
-    level: LogLevels;
+    readonly level: LogLevels;
     /** The object to log. */
-    object: TLogObject;
+    readonly object: TLogObject;
     /** Names of strategies to use. */
-    strategiesNames: (keyof TStrategies)[];
+    readonly strategiesNames: (keyof TStrategies)[];
 }

package/dist/{logger → modules/logger}/types/loggerStrategy.d.ts

@@ -3,7 +3,7 @@ export interface LoggerStrategy<TLogObject = unknown> {
     /**
      * Logs a message with the strategy's implementation.
      *
-     * @param level - The log level at which the message should be logged. ({@link LogLevels})
+     * @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.
      */

package/dist/modules/mailer/enums/mailerErrorKeys.d.ts

@@ -0,0 +1,5 @@
+export declare const MAILER_ERROR_KEYS: {
+    readonly SMTP_CONNECTION_ERROR: "mailer.error.smtp.connection_error";
+    readonly SMTP_NOT_CONNECTED: "mailer.error.smtp.not_connected";
+    readonly SMTP_ALREADY_CONNECTED: "mailer.error.smtp.already_connected";
+};

package/dist/modules/mailer/index.d.ts

@@ -0,0 +1 @@
+export { SMTP } from './smtp';

package/dist/modules/mailer/index.js

@@ -0,0 +1,64 @@
+// @bun
+import {
+  BaseError
+} from "../../chunk-vknq69e0.js";
+
+// source/modules/mailer/smtp.ts
+import { createTransport } from "nodemailer";
+
+// source/modules/mailer/enums/mailerErrorKeys.ts
+var MAILER_ERROR_KEYS = {
+  SMTP_CONNECTION_ERROR: "mailer.error.smtp.connection_error",
+  SMTP_NOT_CONNECTED: "mailer.error.smtp.not_connected",
+  SMTP_ALREADY_CONNECTED: "mailer.error.smtp.already_connected"
+};
+
+// source/modules/mailer/smtp.ts
+class SMTP {
+  _config;
+  _transporter = null;
+  constructor(config) {
+    this._config = {
+      port: 587,
+      secure: false,
+      ...config
+    };
+  }
+  async connect() {
+    if (this._transporter)
+      throw new BaseError({ message: MAILER_ERROR_KEYS.SMTP_ALREADY_CONNECTED });
+    this._transporter = createTransport({
+      host: this._config.host,
+      port: this._config.port,
+      secure: this._config.secure,
+      auth: {
+        user: this._config.credentials.user,
+        pass: this._config.credentials.pass
+      },
+      pool: true,
+      maxConnections: this._config.pool?.maxConnections ?? 5
+    });
+    try {
+      await this._transporter.verify();
+    } catch (error) {
+      throw new BaseError({
+        message: MAILER_ERROR_KEYS.SMTP_CONNECTION_ERROR,
+        cause: error
+      });
+    }
+  }
+  disconnect() {
+    if (this._transporter) {
+      this._transporter.close();
+      this._transporter = null;
+    }
+  }
+  async sendMail(options) {
+    if (!this._transporter)
+      throw new BaseError({ message: MAILER_ERROR_KEYS.SMTP_NOT_CONNECTED });
+    return this._transporter.sendMail(options);
+  }
+}
+export {
+  SMTP
+};

package/dist/{mailer → modules/mailer}/smtp.d.ts

@@ -4,10 +4,10 @@ import type { SMTPOptions } from './types/smtpOptions';
  * The `SMTP` class manages the connection and operations with an SMTP server.
  *
  * This class provides methods to connect, disconnect, and send emails using
- * the Nodemailer library. It supports connection pooling and error handling ({@link CoreError}).
+ * the Nodemailer library. It supports connection pooling and error handling ({@link BaseError}).
  *
  * @example
- * ```typescript
+ * ```ts
  * const smtp = new SMTP({
  *   host: 'smtp.example.com',
  *   credentials: { user: 'user', pass: 'pass' }
@@ -29,7 +29,7 @@ export declare class SMTP {
     /**
      * Creates an instance of the SMTP class.
      *
-     * @param config - The configuration options for the SMTP connection. (see {@link SMTPOptions}).
+     * @param config - The configuration options for the SMTP connection.
      */
     constructor(config: SMTPOptions);
     /**
@@ -39,8 +39,8 @@ export declare class SMTP {
      * It enables connection pooling for efficient resource usage and sets the maximum number of
      * concurrent connections as specified in the configuration (default: 5).
      *
-     * @throws ({@link CoreError}): If the transporter is already connected. ({@link mailerErrorKeys.smtpAlreadyConnected})
-     * @throws ({@link CoreError}): If the connection or verification fails. ({@link mailerErrorKeys.smtpConnectionError})
+     * @throws ({@link BaseError}) - If the transporter is already connected.
+     * @throws ({@link BaseError}) - If the connection or verification fails.
      */
     connect(): Promise<void>;
     /**
@@ -54,7 +54,7 @@ export declare class SMTP {
      *
      * @param options - The mail options, such as recipient, subject, and content.
      *
-     * @throws ({@link CoreError}) - If the transporter is not connected. ({@link mailerErrorKeys.smtpNotConnected})
+     * @throws ({@link BaseError}) - If the transporter is not connected.
      *
      * @returns A promise resolving to the result of the send operation.
      */

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

@@ -0,0 +1,3 @@
+export type { SMTPCredentials } from './smtpCredentials';
+export type { SMTPOptions } from './smtpOptions';
+export type { SMTPPoolOptions } from './smtpPoolOptions';

package/dist/modules/mailer/types/index.js

@@ -0,0 +1 @@
+// @bun

package/dist/{mailer → modules/mailer}/types/smtpCredentials.d.ts

@@ -2,9 +2,9 @@ export interface SMTPCredentials {
     /**
      * The username for SMTP authentication.
      */
-    user: string;
+    readonly user: string;
     /**
      * The password for SMTP authentication.
      */
-    pass: string;
+    readonly pass: string;
 }

package/dist/{mailer → modules/mailer}/types/smtpOptions.d.ts

@@ -4,23 +4,23 @@ export interface SMTPOptions {
     /**
      * The hostname or IP address of the SMTP server.
      */
-    host: string;
+    readonly host: string;
     /**
      * The port number to connect to.
      * @defaultValue 587
      */
-    port?: number;
+    readonly port?: number;
     /**
      * Whether to use a secure (TLS) connection.
      * @defaultValue false
      */
-    secure?: boolean;
+    readonly secure?: boolean;
     /**
      * The credentials for SMTP authentication.
      */
-    credentials: SMTPCredentials;
+    readonly credentials: SMTPCredentials;
     /**
      * Optional pool configuration.
      */
-    pool?: SMTPPoolOptions;
+    readonly pool?: SMTPPoolOptions;
 }

package/dist/{mailer → modules/mailer}/types/smtpPoolOptions.d.ts

@@ -3,5 +3,5 @@ export interface SMTPPoolOptions {
      * The maximum number of concurrent SMTP connections.
      * @defaultValue 5
      */
-    maxConnections?: number;
+    readonly maxConnections?: number;
 }

package/dist/modules/repository/index.d.ts

@@ -0,0 +1 @@
+export { Repository } from './repository';

package/dist/modules/repository/index.js

@@ -0,0 +1,10 @@
+// @bun
+import {
+  Repository
+} from "../../chunk-1a3wj3m1.js";
+import"../../chunk-5qtpggzv.js";
+import"../../chunk-84mqvfsk.js";
+import"../../chunk-vknq69e0.js";
+export {
+  Repository
+};