@eqxjs/nest-logger 3.1.0-beta.12 → 3.1.0-beta.14

package/dist/helpers/log.helper.d.ts

@@ -1,3 +1,84 @@
+/**
+ * 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');
+ * }
+ * ```
+ */
 export declare function isLevelEnable(level: string): boolean;
+/**
+ * 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
+ */
 export declare function maskMessageReplacer(key: string, value: any): any;
+/**
+ * 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
+ */
 export declare function logStringify(message: any): string;

package/dist/helpers/log.helper.js

@@ -3,10 +3,60 @@ 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)) {
@@ -14,6 +64,37 @@ function maskMessageReplacer(key, value) {
     }
     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;

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

@@ -1 +1 @@
-{"version":3,"file":"log.helper.js","sourceRoot":"","sources":["../../src/helpers/log.helper.ts"],"names":[],"mappings":";;AAAA,sCAGC;AAED,kDAMC;AAED,oCASC;AAtBD,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,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,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"}
+{"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

@@ -1,37 +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;
     /**
-     * Replace empty strings with 'none'
+     * 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;
     /**
-     * Merge additional options into the DTO
+     * 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;
 }