@eqxjs/nest-logger 3.1.0-beta.9 → 3.1.1-beta.0

package/dist/helpers/log.helper.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isLevelEnable = isLevelEnable;
+exports.maskMessageReplacer = maskMessageReplacer;
+exports.logStringify = logStringify;
+/**
+ * Checks if a specific log level is enabled based on the LOG_LEVEL environment variable.
+ *
+ * The LOG_LEVEL environment variable should contain a comma-separated list of enabled levels.
+ * Common log levels: 'debug', 'info', 'log', 'warn', 'error', 'verbose'
+ *
+ * @param level - The log level to check (e.g., 'info', 'debug', 'error')
+ * @returns True if the level is enabled, false otherwise
+ *
+ * @example
+ * ```typescript
+ * process.env.LOG_LEVEL = 'info,error,warn';
+ *
+ * if (isLevelEnable('debug')) {
+ *   // Won't execute - debug is not enabled
+ *   console.log('Debug info');
+ * }
+ *
+ * if (isLevelEnable('info')) {
+ *   // Will execute - info is enabled
+ *   console.log('Info message');
+ * }
+ * ```
+ */
+function isLevelEnable(level) {
+    const configLevel = process.env.LOG_LEVEL?.split(',') ?? [];
+    return configLevel.includes(level);
+}
+/**
+ * JSON replacer function that masks sensitive field values.
+ *
+ * Used with JSON.stringify to automatically replace sensitive field values with '*****'.
+ * Sensitive fields are configured via the LOG_MASK_KEYS environment variable.
+ *
+ * @param key - The property key being stringified
+ * @param value - The property value being stringified
+ * @returns The original value if not sensitive, or '*****' if the key is in the mask list
+ *
+ * @example
+ * ```typescript
+ * process.env.LOG_MASK_KEYS = 'password,apiKey,secret';
+ *
+ * const data = {
+ *   username: 'john',
+ *   password: 'secret123',
+ *   apiKey: 'abc-def-ghi'
+ * };
+ *
+ * const masked = JSON.stringify(data, maskMessageReplacer);
+ * // {"username":"john","password":"*****","apiKey":"*****"}
+ * ```
+ *
+ * @see logStringify
+ */
+function maskMessageReplacer(key, value) {
+    const maskConfig = process.env.LOG_MASK_KEYS?.split(',') ?? [];
+    if (maskConfig.includes(key)) {
+        return '*****';
+    }
+    return value;
+}
+/**
+ * Converts any value to a string with automatic masking of sensitive fields.
+ *
+ * Handles various input types:
+ * - Strings: returned as-is
+ * - Objects: JSON stringified with automatic masking via maskMessageReplacer
+ * - Others: converted using String()
+ *
+ * Sensitive fields are masked based on the LOG_MASK_KEYS environment variable.
+ *
+ * @param message - The value to stringify (can be any type)
+ * @returns String representation of the message with sensitive fields masked
+ *
+ * @example
+ * ```typescript
+ * process.env.LOG_MASK_KEYS = 'password,token';
+ *
+ * // String input
+ * logStringify('Hello'); // "Hello"
+ *
+ * // Object with sensitive data
+ * const user = { name: 'John', password: 'secret' };
+ * logStringify(user); // '{"name":"John","password":"*****"}'
+ *
+ * // Nested objects
+ * const data = { user: { token: 'abc123' }, message: 'test' };
+ * logStringify(data); // '{"user":{"token":"*****"},"message":"test"}'
+ * ```
+ *
+ * @see maskMessageReplacer
+ */
+function logStringify(message) {
+    if (typeof message === 'string') {
+        return message;
+    }
+    try {
+        return JSON.stringify(message, maskMessageReplacer);
+    }
+    catch {
+        return String(message);
+    }
+}
+//# sourceMappingURL=log.helper.js.map

package/dist/helpers/log.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.helper.js","sourceRoot":"","sources":["../../src/helpers/log.helper.ts"],"names":[],"mappings":";;AAwBA,sCAGC;AA4BD,kDAMC;AAiCD,oCASC;AAvGD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,aAAa,CAAC,KAAa;IACzC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAC5D,OAAO,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,mBAAmB,CAAC,GAAW,EAAE,KAAU;IACzD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAC/D,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,SAAgB,YAAY,CAAC,OAAY;IACvC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;AACH,CAAC"}

package/dist/helpers/logger-builder.helper.d.ts

@@ -0,0 +1,242 @@
+import { LoggerDto } from '../models/logger.dto';
+/**
+ * LoggerDtoBuilder - Fluent builder for creating LoggerDto instances.
+ *
+ * Provides a chainable API for constructing logger data transfer objects with all necessary fields.
+ * Each setter method returns 'this' to enable method chaining. The builder pattern ensures
+ * consistent and readable construction of complex logger DTOs.
+ *
+ * @example
+ * ```typescript
+ * const dto = new LoggerDtoBuilder()
+ *   .setLevel('info')
+ *   .setTimestamp('2026-01-12T10:00:00.000Z')
+ *   .setAppName('MyApp')
+ *   .setComponentName('UserService')
+ *   .setAction('[USER_CREATE]')
+ *   .setMessage('User created successfully')
+ *   .setSessionId('sess-123')
+ *   .normalizeEmptyFields()
+ *   .build();
+ * ```
+ */
+export declare class LoggerDtoBuilder {
+    private dto;
+    /**
+     * Creates a new LoggerDtoBuilder instance with an empty LoggerDto.
+     */
+    constructor();
+    /**
+     * Sets the log level.
+     *
+     * @param level - Log level (e.g., 'debug', 'info', 'warn', 'error')
+     * @returns This builder instance for method chaining
+     */
+    setLevel(level: string): this;
+    /**
+     * Sets the timestamp for the log entry.
+     *
+     * @param timestamp - ISO 8601 formatted timestamp string
+     * @returns This builder instance for method chaining
+     */
+    setTimestamp(timestamp: string): this;
+    /**
+     * Sets the application name.
+     *
+     * @param appName - Name of the application
+     * @returns This builder instance for method chaining
+     */
+    setAppName(appName: string): this;
+    /**
+     * Sets the component name (optional).
+     * Only sets the value if componentName is provided.
+     *
+     * @param componentName - Name of the component or service
+     * @returns This builder instance for method chaining
+     */
+    setComponentName(componentName?: string): this;
+    /**
+     * Sets the action tag for the log entry.
+     *
+     * @param action - Action identifier (e.g., '[HTTP_REQUEST]', '[DB_QUERY]')
+     * @returns This builder instance for method chaining
+     */
+    setAction(action: string): this;
+    /**
+     * Sets the log message.
+     *
+     * @param message - The log message content
+     * @returns This builder instance for method chaining
+     */
+    setMessage(message: string): this;
+    /**
+     * Sets the instance identifier (typically hostname or container ID).
+     *
+     * @param instance - Instance identifier
+     * @returns This builder instance for method chaining
+     */
+    setInstance(instance: string): this;
+    /**
+     * Sets the originating service name.
+     *
+     * @param originateServiceName - Name of the service that originated the log
+     * @returns This builder instance for method chaining
+     */
+    setOriginateServiceName(originateServiceName: string): this;
+    /**
+     * Sets the record name or identifier.
+     *
+     * @param recordName - Record identifier (e.g., order ID, user ID)
+     * @returns This builder instance for method chaining
+     */
+    setRecordName(recordName: string): this;
+    /**
+     * Sets the record type (e.g., 'detail', 'summary').
+     *
+     * @param recordType - Type of the log record
+     * @returns This builder instance for method chaining
+     */
+    setRecordType(recordType: string): this;
+    /**
+     * Sets the session identifier.
+     *
+     * @param sessionId - Session ID for tracking user sessions
+     * @returns This builder instance for method chaining
+     */
+    setSessionId(sessionId: string): this;
+    /**
+     * Sets the transaction identifier.
+     *
+     * @param transactionId - Transaction ID for tracking distributed transactions
+     * @returns This builder instance for method chaining
+     */
+    setTransactionId(transactionId: string): this;
+    /**
+     * Sets the communication channel.
+     *
+     * @param channel - Channel identifier (e.g., 'web', 'mobile', 'api')
+     * @returns This builder instance for method chaining
+     */
+    setChannel(channel: string): this;
+    /**
+     * Sets the component version.
+     *
+     * @param componentVersion - Version of the component (e.g., '1.0.0')
+     * @returns This builder instance for method chaining
+     */
+    setComponentVersion(componentVersion: string): this;
+    /**
+     * Sets the use case name.
+     *
+     * @param useCase - Name of the use case being executed
+     * @returns This builder instance for method chaining
+     */
+    setUseCase(useCase: string): this;
+    /**
+     * Sets the use case step.
+     *
+     * @param useCaseStep - Specific step within the use case
+     * @returns This builder instance for method chaining
+     */
+    setUseCaseStep(useCaseStep: string): this;
+    /**
+     * Sets the user identifier.
+     *
+     * @param user - User identifier (e.g., email, username, user ID)
+     * @returns This builder instance for method chaining
+     */
+    setUser(user: string): this;
+    /**
+     * Sets the device identifier(s).
+     *
+     * @param device - Single device identifier or array of identifiers
+     * @returns This builder instance for method chaining
+     */
+    setDevice(device: string | string[]): this;
+    /**
+     * Sets the public identifier(s).
+     *
+     * @param public_ - Single public identifier or array of identifiers
+     * @returns This builder instance for method chaining
+     */
+    setPublic(public_: string | string[]): this;
+    /**
+     * Sets the application result description.
+     *
+     * @param appResult - Result description (e.g., 'Success', 'Failed')
+     * @returns This builder instance for method chaining
+     */
+    setAppResult(appResult: string): this;
+    /**
+     * Sets the application result code.
+     *
+     * @param appResultCode - Result code (e.g., '200', '500', 'ERR_001')
+     * @returns This builder instance for method chaining
+     */
+    setAppResultCode(appResultCode: string): this;
+    /**
+     * Sets the service processing time in milliseconds.
+     *
+     * @param serviceTime - Processing duration in milliseconds
+     * @returns This builder instance for method chaining
+     */
+    setServiceTime(serviceTime: number): this;
+    /**
+     * Sets the error stack trace (optional).
+     * Only sets the value if stack is provided and not empty.
+     *
+     * @param stack - Array of stack trace lines
+     * @returns This builder instance for method chaining
+     */
+    setStack(stack?: string[]): this;
+    /**
+     * Normalizes empty string fields by replacing them with DEFAULT_VALUES.NONE ('none').
+     *
+     * Iterates through all DTO properties and replaces any empty string values
+     * with the default 'none' value for consistency in log output.
+     *
+     * @returns This builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const dto = new LoggerDtoBuilder()
+     *   .setLevel('info')
+     *   .setMessage('')  // Empty string
+     *   .normalizeEmptyFields()  // Converts empty string to 'none'
+     *   .build();
+     * ```
+     */
+    normalizeEmptyFields(): this;
+    /**
+     * Merges additional options into the DTO.
+     *
+     * Takes an optional object of additional fields and merges them into the DTO.
+     * Empty string values in the options are normalized to DEFAULT_VALUES.NONE.
+     *
+     * @param opt - Optional record of additional fields to merge
+     * @returns This builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const dto = new LoggerDtoBuilder()
+     *   .setLevel('info')
+     *   .mergeOptions({ broker: 'kafka', customField: 'value' })
+     *   .build();
+     * ```
+     */
+    mergeOptions(opt?: Record<string, unknown>): this;
+    /**
+     * Builds and returns the final LoggerDto instance.
+     *
+     * @returns The constructed LoggerDto object
+     *
+     * @example
+     * ```typescript
+     * const dto = new LoggerDtoBuilder()
+     *   .setLevel('info')
+     *   .setMessage('Test message')
+     *   .build();
+     * ```
+     */
+    build(): LoggerDto;
+}

package/dist/helpers/logger-builder.helper.js

@@ -0,0 +1,345 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoggerDtoBuilder = void 0;
+const logger_dto_1 = require("../models/logger.dto");
+const logger_constants_1 = require("../constants/logger.constants");
+/**
+ * LoggerDtoBuilder - Fluent builder for creating LoggerDto instances.
+ *
+ * Provides a chainable API for constructing logger data transfer objects with all necessary fields.
+ * Each setter method returns 'this' to enable method chaining. The builder pattern ensures
+ * consistent and readable construction of complex logger DTOs.
+ *
+ * @example
+ * ```typescript
+ * const dto = new LoggerDtoBuilder()
+ *   .setLevel('info')
+ *   .setTimestamp('2026-01-12T10:00:00.000Z')
+ *   .setAppName('MyApp')
+ *   .setComponentName('UserService')
+ *   .setAction('[USER_CREATE]')
+ *   .setMessage('User created successfully')
+ *   .setSessionId('sess-123')
+ *   .normalizeEmptyFields()
+ *   .build();
+ * ```
+ */
+class LoggerDtoBuilder {
+    dto;
+    /**
+     * Creates a new LoggerDtoBuilder instance with an empty LoggerDto.
+     */
+    constructor() {
+        this.dto = new logger_dto_1.LoggerDto();
+    }
+    /**
+     * Sets the log level.
+     *
+     * @param level - Log level (e.g., 'debug', 'info', 'warn', 'error')
+     * @returns This builder instance for method chaining
+     */
+    setLevel(level) {
+        this.dto.level = level;
+        return this;
+    }
+    /**
+     * Sets the timestamp for the log entry.
+     *
+     * @param timestamp - ISO 8601 formatted timestamp string
+     * @returns This builder instance for method chaining
+     */
+    setTimestamp(timestamp) {
+        this.dto.timestamp = timestamp;
+        return this;
+    }
+    /**
+     * Sets the application name.
+     *
+     * @param appName - Name of the application
+     * @returns This builder instance for method chaining
+     */
+    setAppName(appName) {
+        this.dto.appName = appName;
+        return this;
+    }
+    /**
+     * Sets the component name (optional).
+     * Only sets the value if componentName is provided.
+     *
+     * @param componentName - Name of the component or service
+     * @returns This builder instance for method chaining
+     */
+    setComponentName(componentName) {
+        if (componentName) {
+            this.dto.componentName = componentName;
+        }
+        return this;
+    }
+    /**
+     * Sets the action tag for the log entry.
+     *
+     * @param action - Action identifier (e.g., '[HTTP_REQUEST]', '[DB_QUERY]')
+     * @returns This builder instance for method chaining
+     */
+    setAction(action) {
+        this.dto.action = action;
+        return this;
+    }
+    /**
+     * Sets the log message.
+     *
+     * @param message - The log message content
+     * @returns This builder instance for method chaining
+     */
+    setMessage(message) {
+        this.dto.message = message;
+        return this;
+    }
+    /**
+     * Sets the instance identifier (typically hostname or container ID).
+     *
+     * @param instance - Instance identifier
+     * @returns This builder instance for method chaining
+     */
+    setInstance(instance) {
+        this.dto.instance = instance;
+        return this;
+    }
+    /**
+     * Sets the originating service name.
+     *
+     * @param originateServiceName - Name of the service that originated the log
+     * @returns This builder instance for method chaining
+     */
+    setOriginateServiceName(originateServiceName) {
+        this.dto.originateServiceName = originateServiceName;
+        return this;
+    }
+    /**
+     * Sets the record name or identifier.
+     *
+     * @param recordName - Record identifier (e.g., order ID, user ID)
+     * @returns This builder instance for method chaining
+     */
+    setRecordName(recordName) {
+        this.dto.recordName = recordName;
+        return this;
+    }
+    /**
+     * Sets the record type (e.g., 'detail', 'summary').
+     *
+     * @param recordType - Type of the log record
+     * @returns This builder instance for method chaining
+     */
+    setRecordType(recordType) {
+        this.dto.recordType = recordType;
+        return this;
+    }
+    /**
+     * Sets the session identifier.
+     *
+     * @param sessionId - Session ID for tracking user sessions
+     * @returns This builder instance for method chaining
+     */
+    setSessionId(sessionId) {
+        this.dto.sessionId = sessionId;
+        return this;
+    }
+    /**
+     * Sets the transaction identifier.
+     *
+     * @param transactionId - Transaction ID for tracking distributed transactions
+     * @returns This builder instance for method chaining
+     */
+    setTransactionId(transactionId) {
+        this.dto.transactionId = transactionId;
+        return this;
+    }
+    /**
+     * Sets the communication channel.
+     *
+     * @param channel - Channel identifier (e.g., 'web', 'mobile', 'api')
+     * @returns This builder instance for method chaining
+     */
+    setChannel(channel) {
+        this.dto.channel = channel;
+        return this;
+    }
+    /**
+     * Sets the component version.
+     *
+     * @param componentVersion - Version of the component (e.g., '1.0.0')
+     * @returns This builder instance for method chaining
+     */
+    setComponentVersion(componentVersion) {
+        this.dto.componentVersion = componentVersion;
+        return this;
+    }
+    /**
+     * Sets the use case name.
+     *
+     * @param useCase - Name of the use case being executed
+     * @returns This builder instance for method chaining
+     */
+    setUseCase(useCase) {
+        this.dto.useCase = useCase;
+        return this;
+    }
+    /**
+     * Sets the use case step.
+     *
+     * @param useCaseStep - Specific step within the use case
+     * @returns This builder instance for method chaining
+     */
+    setUseCaseStep(useCaseStep) {
+        this.dto.useCaseStep = useCaseStep;
+        return this;
+    }
+    /**
+     * Sets the user identifier.
+     *
+     * @param user - User identifier (e.g., email, username, user ID)
+     * @returns This builder instance for method chaining
+     */
+    setUser(user) {
+        this.dto.user = user;
+        return this;
+    }
+    /**
+     * Sets the device identifier(s).
+     *
+     * @param device - Single device identifier or array of identifiers
+     * @returns This builder instance for method chaining
+     */
+    setDevice(device) {
+        this.dto.device = device;
+        return this;
+    }
+    /**
+     * Sets the public identifier(s).
+     *
+     * @param public_ - Single public identifier or array of identifiers
+     * @returns This builder instance for method chaining
+     */
+    setPublic(public_) {
+        this.dto.public = public_;
+        return this;
+    }
+    /**
+     * Sets the application result description.
+     *
+     * @param appResult - Result description (e.g., 'Success', 'Failed')
+     * @returns This builder instance for method chaining
+     */
+    setAppResult(appResult) {
+        this.dto.appResult = appResult;
+        return this;
+    }
+    /**
+     * Sets the application result code.
+     *
+     * @param appResultCode - Result code (e.g., '200', '500', 'ERR_001')
+     * @returns This builder instance for method chaining
+     */
+    setAppResultCode(appResultCode) {
+        this.dto.appResultCode = appResultCode;
+        return this;
+    }
+    /**
+     * Sets the service processing time in milliseconds.
+     *
+     * @param serviceTime - Processing duration in milliseconds
+     * @returns This builder instance for method chaining
+     */
+    setServiceTime(serviceTime) {
+        this.dto.serviceTime = serviceTime;
+        return this;
+    }
+    /**
+     * Sets the error stack trace (optional).
+     * Only sets the value if stack is provided and not empty.
+     *
+     * @param stack - Array of stack trace lines
+     * @returns This builder instance for method chaining
+     */
+    setStack(stack) {
+        if (stack) {
+            this.dto.stack = stack;
+        }
+        return this;
+    }
+    /**
+     * Normalizes empty string fields by replacing them with DEFAULT_VALUES.NONE ('none').
+     *
+     * Iterates through all DTO properties and replaces any empty string values
+     * with the default 'none' value for consistency in log output.
+     *
+     * @returns This builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const dto = new LoggerDtoBuilder()
+     *   .setLevel('info')
+     *   .setMessage('')  // Empty string
+     *   .normalizeEmptyFields()  // Converts empty string to 'none'
+     *   .build();
+     * ```
+     */
+    normalizeEmptyFields() {
+        Object.keys(this.dto).forEach((key) => {
+            const value = this.dto[key];
+            if (typeof value === 'string' && value === '') {
+                this.dto[key] = logger_constants_1.DEFAULT_VALUES.NONE;
+            }
+        });
+        return this;
+    }
+    /**
+     * Merges additional options into the DTO.
+     *
+     * Takes an optional object of additional fields and merges them into the DTO.
+     * Empty string values in the options are normalized to DEFAULT_VALUES.NONE.
+     *
+     * @param opt - Optional record of additional fields to merge
+     * @returns This builder instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const dto = new LoggerDtoBuilder()
+     *   .setLevel('info')
+     *   .mergeOptions({ broker: 'kafka', customField: 'value' })
+     *   .build();
+     * ```
+     */
+    mergeOptions(opt) {
+        if (opt) {
+            const normalizedOpt = { ...opt };
+            Object.keys(normalizedOpt).forEach((key) => {
+                if (typeof normalizedOpt[key] === 'string' &&
+                    normalizedOpt[key] === '') {
+                    normalizedOpt[key] = logger_constants_1.DEFAULT_VALUES.NONE;
+                }
+            });
+            Object.assign(this.dto, normalizedOpt);
+        }
+        return this;
+    }
+    /**
+     * Builds and returns the final LoggerDto instance.
+     *
+     * @returns The constructed LoggerDto object
+     *
+     * @example
+     * ```typescript
+     * const dto = new LoggerDtoBuilder()
+     *   .setLevel('info')
+     *   .setMessage('Test message')
+     *   .build();
+     * ```
+     */
+    build() {
+        return this.dto;
+    }
+}
+exports.LoggerDtoBuilder = LoggerDtoBuilder;
+//# sourceMappingURL=logger-builder.helper.js.map