@nimbus-cqrs/core 2.0.0-beta.0

package/esm/lib/log/logFormatter.d.ts

@@ -0,0 +1,26 @@
+import type { LogRecord } from './logger.js';
+/**
+ * Type for a function that formats a log record before outputting it.
+ *
+ * @param {LogRecord} logRecord - The log record
+ *
+ * @returns {string} The formatted log record
+ */
+export type LogFormatter = (logRecord: LogRecord) => string | string[];
+/**
+ * A formatter that outputs the log record in JSON format.
+ *
+ * @param {LogRecord} logRecord - The log record
+ *
+ * @returns {string} The formatted log record
+ */
+export declare const jsonLogFormatter: LogFormatter;
+/**
+ * A formatter that outputs the log record in a pretty format.
+ *
+ * @param {LogRecord} logRecord - The log record
+ *
+ * @returns {string} The formatted log record
+ */
+export declare const prettyLogFormatter: LogFormatter;
+//# sourceMappingURL=logFormatter.d.ts.map

package/esm/lib/log/logFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logFormatter.d.ts","sourceRoot":"","sources":["../../../src/lib/log/logFormatter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,SAAS,KAAK,MAAM,GAAG,MAAM,EAAE,CAAC;AAEvE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,YA6B9B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,EAAE,YA6BhC,CAAC"}

package/esm/lib/log/logFormatter.js

@@ -0,0 +1,59 @@
+import { Exception } from '../exception/exception.js';
+/**
+ * A formatter that outputs the log record in JSON format.
+ *
+ * @param {LogRecord} logRecord - The log record
+ *
+ * @returns {string} The formatted log record
+ */
+export const jsonLogFormatter = (logRecord) => {
+    let processedLogRecord = logRecord;
+    if (logRecord.error) {
+        // Special handling for Error objects to preserve stack traces
+        const processedErrorObj = JSON.parse(JSON.stringify(logRecord, (_key, value) => {
+            if (value instanceof Error || value instanceof Exception) {
+                return {
+                    // Include standard error properties
+                    ...value,
+                    message: value.message,
+                    name: value.name,
+                    stack: value.stack,
+                };
+            }
+            return value;
+        }, 2));
+        processedLogRecord = {
+            ...logRecord,
+            error: processedErrorObj,
+        };
+    }
+    return JSON.stringify(processedLogRecord);
+};
+/**
+ * A formatter that outputs the log record in a pretty format.
+ *
+ * @param {LogRecord} logRecord - The log record
+ *
+ * @returns {string} The formatted log record
+ */
+export const prettyLogFormatter = (logRecord) => {
+    let dataString = '';
+    let errorString = '';
+    let correlationId = '';
+    if (logRecord.correlationId) {
+        correlationId = `(${logRecord.correlationId}) `;
+    }
+    if (logRecord.data) {
+        dataString = JSON.stringify(logRecord.data, null, 2);
+    }
+    if (logRecord.error) {
+        errorString = JSON.stringify(logRecord.error, null, 2);
+        return [
+            `[${logRecord.category}] ${logRecord.level.toUpperCase()} ${correlationId}:: ${logRecord.message}`,
+            errorString.length ? `\n${errorString}` : '',
+            logRecord.error.stack ? `\n${logRecord.error.stack}` : '',
+            dataString.length ? `\n${dataString}` : '',
+        ];
+    }
+    return `[${logRecord.category}] ${logRecord.level.toUpperCase()} ${correlationId}:: ${logRecord.message}${dataString.length ? `\n${dataString}` : ''}`;
+};

package/esm/lib/log/logLevel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * There are different log levels or severity levels that can be used to categorize the log messages.
+ *
+ * Debug: Detailed information useful for diagnosing problems.
+ * Information: General information about the application's operation.
+ * Warning: An unexpected event that doesn't prevent the application from functioning.
+ * Error: A more severe problem that prevented a specific operation from being completed.
+ * Critical: A critical error that causes the application to crash.
+ * Silent: No log messages are emitted. This level does not provide a logging function, but it can be used to disable logging.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'critical' | 'silent';
+/**
+ * The numeric representation of the LogLeveL type.
+ */
+export declare const numericLogLevel: Record<LogLevel, number>;
+/**
+ * Parses a log level from a string.
+ *
+ * @param {string} levelString - The log level as a string
+ *
+ * @returns {LogLevel} The log level
+ */
+export declare const parseLogLevel: (levelString?: string) => LogLevel;
+//# sourceMappingURL=logLevel.d.ts.map

package/esm/lib/log/logLevel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logLevel.d.ts","sourceRoot":"","sources":["../../../src/lib/log/logLevel.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,MAAM,QAAQ,GACd,OAAO,GACP,MAAM,GACN,MAAM,GACN,OAAO,GACP,UAAU,GACV,QAAQ,CAAC;AAEf;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAOpD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,cAAc,MAAM,KAAG,QAYpD,CAAC"}

package/esm/lib/log/logLevel.js

@@ -0,0 +1,27 @@
+import { defaultLogOptions } from './options.js';
+/**
+ * The numeric representation of the LogLeveL type.
+ */
+export const numericLogLevel = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    critical: 50,
+    silent: 100,
+};
+/**
+ * Parses a log level from a string.
+ *
+ * @param {string} levelString - The log level as a string
+ *
+ * @returns {LogLevel} The log level
+ */
+export const parseLogLevel = (levelString) => {
+    let logLevel = levelString?.toLowerCase();
+    if (!logLevel || !Object.keys(numericLogLevel).includes(logLevel)) {
+        console.warn(`Invalid log level: ${levelString}, using default log level: ${defaultLogOptions.logLevel}`);
+        logLevel = defaultLogOptions.logLevel;
+    }
+    return logLevel;
+};

package/esm/lib/log/logger.d.ts

@@ -0,0 +1,377 @@
+import type { Exception } from '../exception/exception.js';
+import { type LogLevel } from './logLevel.js';
+import { type LogOptions } from './options.js';
+/**
+ * The input for a log message.
+ *
+ * Use this type when calling any of the Logger's log methods (debug, info, warn, error, critical).
+ */
+export type LogInput = {
+    /**
+     * The log message to output. This should be a human-readable description of what occurred.
+     */
+    message: string;
+    /**
+     * An optional category to group related log messages.
+     * Useful for filtering logs by component or domain (e.g., 'Database', 'API', 'Auth').
+     * Defaults to 'Default' if not provided.
+     */
+    category?: string;
+    /**
+     * Optional structured data to include with the log message.
+     * This data will be serialized according to the configured formatter.
+     */
+    data?: Record<string, unknown>;
+    /**
+     * Optional error or exception to include with the log message.
+     * The error's message and stack trace will be captured in the log output.
+     */
+    error?: Error;
+    /**
+     * Optional correlation ID to trace related log messages across operations.
+     * Useful for tracking a request through multiple services or handlers.
+     */
+    correlationId?: string;
+};
+/**
+ * A full log record with the log input and additional metadata attached.
+ *
+ * This type is passed to the LogFormatter function to produce the final log output.
+ */
+export type LogRecord = {
+    /**
+     * The timestamp when the log message was created.
+     */
+    timestamp: Date;
+    /**
+     * The severity level of the log message (debug, info, warn, error, critical).
+     */
+    level: LogLevel;
+    /**
+     * The category for grouping related log messages.
+     */
+    category: string;
+    /**
+     * The log message describing what occurred.
+     */
+    message: string;
+    /**
+     * Optional structured data included with the log message.
+     */
+    data?: Record<string, unknown>;
+    /**
+     * Optional error or exception included with the log message.
+     */
+    error?: Error | Exception;
+    /**
+     * Optional correlation ID for tracing related log messages.
+     */
+    correlationId?: string;
+};
+/**
+ * The Logger provides structured logging with configurable log levels, formatters, and console colors.
+ *
+ * The Logger is a singleton that should be configured once at application startup using
+ * {@link setupLogger}, then accessed throughout the application using {@link getLogger}.
+ *
+ * Log levels in order of severity: debug < info < warn < error < critical.
+ * Messages below the configured log level are silently ignored.
+ *
+ * @example
+ * ```ts
+ * import {
+ *     getLogger,
+ *     jsonLogFormatter,
+ *     parseLogLevel,
+ *     prettyLogFormatter,
+ *     setupLogger,
+ * } from '@nimbus/core';
+ *
+ * // Configure the logger at application startup
+ * setupLogger({
+ *     logLevel: parseLogLevel(process.env.LOG_LEVEL),
+ *     formatter: process.env.NODE_ENV === 'production'
+ *         ? jsonLogFormatter
+ *         : prettyLogFormatter,
+ *     useConsoleColors: process.env.NODE_ENV !== 'production',
+ * });
+ *
+ * // Use the logger throughout your application
+ * const logger = getLogger();
+ *
+ * logger.info({
+ *     message: 'Application started',
+ *     category: 'App',
+ *     data: { port: 3000, environment: 'production' },
+ * });
+ *
+ * logger.error({
+ *     message: 'Failed to connect to database',
+ *     category: 'Database',
+ *     error: new Error('Connection timeout'),
+ *     correlationId: '550e8400-e29b-41d4-a716-446655440000',
+ * });
+ * ```
+ */
+export declare class Logger {
+    private static _instance;
+    private readonly _logLevel;
+    private readonly _formatter;
+    private readonly _useConsoleColors;
+    constructor(options: LogOptions);
+    /**
+     * Configure the Logger.
+     *
+     * @param {LogOptions} options - The options for the Logger
+     * @param {LogLevel} options.logLevel - The log level to use for the Logger
+     * @param {LogFormatter} options.formatter - The formatter to use for the Logger
+     */
+    static configure(options: LogOptions): void;
+    /**
+     * Get the Logger instance.
+     *
+     * @returns {Logger} The Logger instance
+     */
+    static getInstance(): Logger;
+    /**
+     * Log a message at the debug level.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {string} logInput.message - The message
+     * @param {string} logInput.category - An optional category
+     * @param {string} logInput.correlationId - An optional correlation ID
+     * @param {Record<string, unknown>} logInput.data - An optional data object
+     * @param {Error | Exception} logInput.error - An optional error
+     *
+     * @example
+     * ```ts
+     * import { getLogger } from "@nimbus/core";
+     *
+     * getLogger().debug({
+     *     message: 'Hello World!',
+     *     category: 'MyCategory',
+     *     correlationId: '1234567890',
+     *     data: {
+     *         foo: 'bar',
+     *     },
+     *     error: new Error('Something went wrong!'),
+     * });
+     * ```
+     */
+    debug(logInput: LogInput): void;
+    /**
+     * Log a message at the info level.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {string} logInput.message - The message
+     * @param {string} logInput.category - An optional category
+     * @param {string} logInput.correlationId - An optional correlation ID
+     * @param {Record<string, unknown>} logInput.data - An optional data object
+     * @param {Error | Exception} logInput.error - An optional error
+     *
+     * @example
+     * ```ts
+     * import { getLogger } from "@nimbus/core";
+     *
+     * getLogger().info({
+     *     message: 'Hello World!',
+     *     category: 'MyCategory',
+     *     correlationId: '1234567890',
+     *     data: {
+     *         foo: 'bar',
+     *     },
+     *     error: new Error('Something went wrong!'),
+     * });
+     * ```
+     */
+    info(logInput: LogInput): void;
+    /**
+     * Log a message at the warn level.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {string} logInput.message - The message
+     * @param {string} logInput.category - An optional category
+     * @param {string} logInput.correlationId - An optional correlation ID
+     * @param {Record<string, unknown>} logInput.data - An optional data object
+     * @param {Error | Exception} logInput.error - An optional error
+     *
+     * @example
+     * ```ts
+     * import { getLogger } from "@nimbus/core";
+     *
+     * getLogger().warn({
+     *     message: 'Hello World!',
+     *     category: 'MyCategory',
+     *     correlationId: '1234567890',
+     *     data: {
+     *         foo: 'bar',
+     *     },
+     *     error: new Error('Something went wrong!'),
+     * });
+     * ```
+     */
+    warn(logInput: LogInput): void;
+    /**
+     * Log a message at the error level.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {string} logInput.message - The message
+     * @param {string} logInput.category - An optional category
+     * @param {string} logInput.correlationId - An optional correlation ID
+     * @param {Record<string, unknown>} logInput.data - An optional data object
+     * @param {Error | Exception} logInput.error - An optional error
+     *
+     * @example
+     * ```ts
+     * import { getLogger } from "@nimbus/core";
+     *
+     * getLogger().error({
+     *     message: 'Hello World!',
+     *     category: 'MyCategory',
+     *     correlationId: '1234567890',
+     *     data: {
+     *         foo: 'bar',
+     *     },
+     *     error: new Error('Something went wrong!'),
+     * });
+     * ```
+     */
+    error(logInput: LogInput): void;
+    /**
+     * Log a message at the critical level.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {string} logInput.message - The message
+     * @param {string} logInput.category - An optional category
+     * @param {string} logInput.correlationId - An optional correlation ID
+     * @param {Record<string, unknown>} logInput.data - An optional data object
+     * @param {Error | Exception} logInput.error - An optional error
+     *
+     * @example
+     * ```ts
+     * import { getLogger } from "@nimbus/core";
+     *
+     * getLogger().critical({
+     *     message: 'Hello World!',
+     *     category: 'MyCategory',
+     *     correlationId: '1234567890',
+     *     data: {
+     *         foo: 'bar',
+     *     },
+     *     error: new Error('Something went wrong!'),
+     * });
+     * ```
+     */
+    critical(logInput: LogInput): void;
+    /**
+     * Produce a log record.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {LogLevel} level - The log level
+     *
+     * @returns {LogRecord} The log record
+     */
+    private _produceLogRecord;
+    /**
+     * Format a log record.
+     *
+     * @param {LogRecord} logRecord - The log record
+     *
+     * @returns {string} The formatted log record
+     */
+    private _formatLogRecord;
+    /**
+     * Colorize a string.
+     *
+     * @param {string} string - The string to colorize
+     * @param {LogLevel} logLevel - The log level to determine the color
+     *
+     * @returns {string} The colorized string
+     */
+    private _colorizeString;
+    /**
+     * Log a message.
+     *
+     * @param {LogInput} logInput - The log input
+     * @param {LogLevel} logLevel - The log level
+     * @param {Function} logFunction - The log function
+     */
+    private _log;
+}
+/**
+ * Configure the Logger.
+ *
+ * @param {LogOptions} options - The options for the Logger
+ *
+ * @example
+ * ```ts
+ * import {
+ *     jsonLogFormatter,
+ *     parseLogLevel,
+ *     prettyLogFormatter,
+ *     setupLogger,
+ * } from "@nimbus/core";
+ *
+ * setupLogger({
+ *     logLevel: parseLogLevel(process.env.LOG_LEVEL),
+ *     formatter:
+ *         process.env.NODE_ENV === "development"
+ *             ? prettyLogFormatter
+ *             : jsonLogFormatter,
+ *     useConsoleColors: process.env.NODE_ENV === "development",
+ * });
+ * ```
+ */
+export declare const setupLogger: (options: LogOptions) => void;
+/**
+ * Get the Logger instance.
+ *
+ * Returns the singleton Logger instance. If the logger has not been configured
+ * via {@link setupLogger}, a default logger with silent log level is returned.
+ *
+ * @returns The Logger instance.
+ *
+ * @example
+ * ```ts
+ * import { getLogger } from '@nimbus/core';
+ *
+ * const logger = getLogger();
+ *
+ * // Log at different levels with all available options
+ * logger.debug({
+ *     message: 'Processing request',
+ *     category: 'API',
+ *     data: { method: 'POST', path: '/orders' },
+ *     correlationId: '550e8400-e29b-41d4-a716-446655440000',
+ * });
+ *
+ * logger.info({
+ *     message: 'Order created successfully',
+ *     category: 'Orders',
+ *     data: { orderId: '12345', customerId: '67890' },
+ *     correlationId: '550e8400-e29b-41d4-a716-446655440000',
+ * });
+ *
+ * logger.warn({
+ *     message: 'Rate limit approaching',
+ *     category: 'API',
+ *     data: { currentRate: 95, maxRate: 100 },
+ * });
+ *
+ * logger.error({
+ *     message: 'Failed to process payment',
+ *     category: 'Payments',
+ *     data: { orderId: '12345' },
+ *     error: new Error('Payment gateway timeout'),
+ *     correlationId: '550e8400-e29b-41d4-a716-446655440000',
+ * });
+ *
+ * logger.critical({
+ *     message: 'Database connection lost',
+ *     category: 'Database',
+ *     error: new Error('Connection refused'),
+ * });
+ * ```
+ */
+export declare const getLogger: () => Logger;
+//# sourceMappingURL=logger.d.ts.map

package/esm/lib/log/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/lib/log/logger.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EAAE,KAAK,QAAQ,EAAmB,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAElE;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG;IACnB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACpB;;OAEG;IACH,SAAS,EAAE,IAAI,CAAC;IAChB;;OAEG;IACH,KAAK,EAAE,QAAQ,CAAC;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,MAAM;IACf,OAAO,CAAC,MAAM,CAAC,SAAS,CAAS;IAEjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;gBAEhC,OAAO,EAAE,UAAU;IAO/B;;;;;;OAMG;WACW,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAIlD;;;;OAIG;WACW,WAAW,IAAI,MAAM;IAQnC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMtC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMtC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAMzC;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAwBvB;;;;;;OAMG;IACH,OAAO,CAAC,IAAI;CAwBf;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,UAAU,KAAG,IAEjD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,SAAS,QAAO,MAE5B,CAAC"}