sm-utility 2.4.9 → 2.4.12

package/general/command.abstract.d.ts

@@ -0,0 +1,112 @@
+import { MetadataModel } from './metadata.model';
+import { LeveledLogMethod } from 'winston';
+type LogData<T> = {
+    context?: T;
+};
+type EnhancedLogParams<T, E> = {
+    logMethod: LeveledLogMethod;
+    message: string;
+    logData?: LogData<T>;
+    error?: E;
+};
+export declare abstract class Command {
+    protected readonly className: string;
+    protected readonly metadata: MetadataModel;
+    protected readonly logger: import("winston").Logger;
+    private startTime;
+    /**
+     * Creates a new instance of the Command class.
+     *
+     * @param className - The name of the class extending the Command class. Used for logging purposes.
+     * @param metadata - (Optional) A metadata model containing additional information for the command.
+     * If not provided, a new `MetadataModel` will be created with a randomly generated `auditUuid`.
+     */
+    constructor(className: string, metadata?: MetadataModel);
+    /**
+     * Executes the command logic. This method must be implemented by any class extending the Command base class.
+     *
+     * @param params - (Optional) Parameters required to execute the command. The specific structure and type of these
+     * parameters depend on the implementation in the derived class.
+     *
+     * @returns A promise that resolves when the command execution is complete. If the command encounters an error during
+     * execution, the promise should reject with the appropriate error.
+     *
+     * @example
+     * // Example implementation in a derived class
+     * class MyCommand extends Command {
+     *   async execute(params?: { userId: string }): Promise<void> {
+     *     try {
+     *       this.logInitiated({ context: params });
+     *       // Command logic here
+     *       await someAsyncOperation(params?.userId);
+     *       this.logFinished({ context: params });
+     *     } catch (error) {
+     *       this.logUnexpectedFailed(error, { context: params });
+     *       throw error; // Re-throw the error for further handling
+     *     }
+     *   }
+     * }
+     */
+    abstract execute(params?: any): Promise<any>;
+    /**
+     * Logs that the command has been initiated.
+     * @param logData Optional contextual data for the log.
+     */
+    protected logInitiated<T>(logData?: LogData<T>): void;
+    /**
+     * Logs that the command has been successfully finished.
+     * @param logData Optional contextual data for the log.
+     */
+    protected logFinished<T>(logData?: LogData<T>): void;
+    /**
+     * Logs that the command has failed unexpectedly.
+     * @param error The error that occurred.
+     * @param logData Optional contextual data for the log.
+     */
+    protected logUnexpectedFailed<T>(error: Error, logData?: LogData<T>): void;
+    /**
+     * Logs detailed information about the current operation, optionally including execution time and error details.
+     *
+     * @template T - The type of contextual data included in the log.
+     * @template E - The type of the error (if any) included in the log.
+     *
+     * @param params - The parameters for the enhanced log.
+     * @param params.logMethod - The logging method to be used (e.g., `logger.info` or `logger.error`).
+     * @param params.message - The log message to be recorded.
+     * @param params.logData - (Optional) Additional contextual data for the log.
+     * @param params.error - (Optional) An error object to include in the log.
+     *
+     * @remarks
+     * - If the log message does not contain the word "initiated," the method automatically appends the `executionTime` field.
+     * - If an error object is provided, it will be added to the log payload under the `err` property.
+     * - This method builds the log payload dynamically using the provided context and metadata.
+     *
+     * @example
+     * // Log a successful operation
+     * this.enhancedLog({
+     *   logMethod: this.logger.info,
+     *   message: 'Operation finished successfully',
+     *   logData: { userId: '12345' },
+     * });
+     *
+     * @example
+     * // Log a failed operation with an error
+     * this.enhancedLog({
+     *   logMethod: this.logger.error,
+     *   message: 'Operation failed',
+     *   logData: { userId: '12345' },
+     *   error: new Error('Unexpected error'),
+     * });
+     *
+     * @example
+     * // Log an initiated operation
+     * this.enhancedLog({
+     *   logMethod: this.logger.info,
+     *   message: 'Operation initiated',
+     * });
+     */
+    protected enhancedLog<T, E>({ logMethod, message, logData, error, }: EnhancedLogParams<T, E>): void;
+    getExecutionTime(): string;
+    private buildLogData;
+}
+export {};

package/general/command.abstract.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Command = void 0;
+const logger_1 = require("../logger");
+const metadata_model_1 = require("./metadata.model");
+const uuid_1 = require("uuid");
+class Command {
+    /**
+     * Creates a new instance of the Command class.
+     *
+     * @param className - The name of the class extending the Command class. Used for logging purposes.
+     * @param metadata - (Optional) A metadata model containing additional information for the command.
+     * If not provided, a new `MetadataModel` will be created with a randomly generated `auditUuid`.
+     */
+    constructor(className, metadata = new metadata_model_1.MetadataModel({
+        auditUuid: (0, uuid_1.v4)(),
+    })) {
+        this.className = className;
+        this.metadata = metadata;
+        this.logger = logger_1.logger;
+        this.startTime = performance.now();
+    }
+    /**
+     * Logs that the command has been initiated.
+     * @param logData Optional contextual data for the log.
+     */
+    logInitiated(logData) {
+        this.enhancedLog({
+            logMethod: this.logger.info,
+            message: `${this.className} initiated`,
+            logData,
+        });
+    }
+    /**
+     * Logs that the command has been successfully finished.
+     * @param logData Optional contextual data for the log.
+     */
+    logFinished(logData) {
+        this.enhancedLog({
+            logMethod: this.logger.info,
+            message: `${this.className} finished`,
+            logData,
+        });
+    }
+    /**
+     * Logs that the command has failed unexpectedly.
+     * @param error The error that occurred.
+     * @param logData Optional contextual data for the log.
+     */
+    logUnexpectedFailed(error, logData) {
+        this.enhancedLog({
+            logMethod: this.logger.error,
+            message: `${this.className} failed`,
+            logData,
+            error,
+        });
+    }
+    /**
+     * Logs detailed information about the current operation, optionally including execution time and error details.
+     *
+     * @template T - The type of contextual data included in the log.
+     * @template E - The type of the error (if any) included in the log.
+     *
+     * @param params - The parameters for the enhanced log.
+     * @param params.logMethod - The logging method to be used (e.g., `logger.info` or `logger.error`).
+     * @param params.message - The log message to be recorded.
+     * @param params.logData - (Optional) Additional contextual data for the log.
+     * @param params.error - (Optional) An error object to include in the log.
+     *
+     * @remarks
+     * - If the log message does not contain the word "initiated," the method automatically appends the `executionTime` field.
+     * - If an error object is provided, it will be added to the log payload under the `err` property.
+     * - This method builds the log payload dynamically using the provided context and metadata.
+     *
+     * @example
+     * // Log a successful operation
+     * this.enhancedLog({
+     *   logMethod: this.logger.info,
+     *   message: 'Operation finished successfully',
+     *   logData: { userId: '12345' },
+     * });
+     *
+     * @example
+     * // Log a failed operation with an error
+     * this.enhancedLog({
+     *   logMethod: this.logger.error,
+     *   message: 'Operation failed',
+     *   logData: { userId: '12345' },
+     *   error: new Error('Unexpected error'),
+     * });
+     *
+     * @example
+     * // Log an initiated operation
+     * this.enhancedLog({
+     *   logMethod: this.logger.info,
+     *   message: 'Operation initiated',
+     * });
+     */
+    enhancedLog({ logMethod, message, logData, error, }) {
+        const logPayload = {
+            ...this.buildLogData(logData),
+        };
+        //* Add `executionTime` if the message is not about initiation
+        if (!message.includes('initiated')) {
+            logPayload.executionTime = this.getExecutionTime();
+        }
+        //* Add error details if present
+        if (error) {
+            logPayload.err = error;
+        }
+        //* Log the message with the appropriate level
+        logMethod(message, logPayload);
+    }
+    getExecutionTime() {
+        const executionTime = performance.now() - this.startTime;
+        if (executionTime >= 1000) {
+            //* Converting to seconds if the execution time is greater than 1000ms
+            return `${(executionTime / 1000).toFixed(2)}s`;
+        }
+        return `${executionTime.toFixed(2)}ms`;
+    }
+    buildLogData(logData) {
+        var _a;
+        return {
+            metadata: (_a = this.metadata) === null || _a === void 0 ? void 0 : _a.getData(),
+            ...logData,
+        };
+    }
+}
+exports.Command = Command;

package/general/decorators/logMethod.decorator.d.ts

@@ -0,0 +1,4 @@
+export declare function LogMethod(options?: {
+    logParams?: boolean;
+    logReturn?: boolean;
+}): (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;

package/general/decorators/logMethod.decorator.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogMethod = void 0;
+const logger_1 = require("src/logger");
+function LogMethod(options) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            var _a, _b;
+            const className = target.constructor.name;
+            const params = (options === null || options === void 0 ? void 0 : options.logParams) ? args : undefined;
+            const metadata = (_a = this.metadata) === null || _a === void 0 ? void 0 : _a.getData();
+            try {
+                logger_1.logger.info(`${className}.${propertyKey} Initiated`, {
+                    metadata,
+                    context: {
+                        params,
+                    },
+                });
+                const result = await originalMethod.apply(this, args);
+                logger_1.logger.info(`${className}.${propertyKey} Finished`, {
+                    metadata,
+                    context: {
+                        params,
+                        result: (options === null || options === void 0 ? void 0 : options.logReturn) ? result : undefined,
+                    },
+                });
+                return result;
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    // Tentativa de deixar o stack trace mais limpo
+                    const cleanStack = (_b = error.stack) === null || _b === void 0 ? void 0 : _b.split('\n').filter((line) => !line.includes('descriptor.value') &&
+                        !line.includes('logMethod.decorator.ts') &&
+                        !line.includes('node:internal/process/task_queues')).join('\n');
+                    logger_1.logger.error(`${className}.${propertyKey} Failed`, {
+                        err: { message: error.message, stack: cleanStack },
+                        metadata,
+                        context: {
+                            params,
+                        },
+                    });
+                }
+                else {
+                    // Caso o erro não seja uma instância de Error, logamos como um objeto desconhecido
+                    logger_1.logger.error(`${className}.${propertyKey} Failed`, {
+                        err: { message: 'Unknown error', details: error },
+                        metadata,
+                        context: {
+                            params,
+                        },
+                    });
+                }
+                throw error;
+            }
+        };
+        return descriptor;
+    };
+}
+exports.LogMethod = LogMethod;

package/general/index.d.ts

@@ -38,3 +38,4 @@ export declare function shortUniqueId(): string;
  */
 export declare function copy<T>(obj: T): T;
 export { MetadataModel, IMetadata } from './metadata.model';
+export { Command } from './command.abstract';

package/general/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MetadataModel = exports.copy = exports.shortUniqueId = exports.mergeDeep = exports.timeout = exports.randomSixDigitNumber = exports.pipe = void 0;
+exports.Command = exports.MetadataModel = exports.copy = exports.shortUniqueId = exports.mergeDeep = exports.timeout = exports.randomSixDigitNumber = exports.pipe = void 0;
 const nanoid_1 = require("nanoid");
 function pipe(...fns) {
     return (x) => fns.reduce((v, f) => f(v), x);
@@ -104,3 +104,5 @@ function copy(obj) {
 exports.copy = copy;
 var metadata_model_1 = require("./metadata.model");
 Object.defineProperty(exports, "MetadataModel", { enumerable: true, get: function () { return metadata_model_1.MetadataModel; } });
+var command_abstract_1 = require("./command.abstract");
+Object.defineProperty(exports, "Command", { enumerable: true, get: function () { return command_abstract_1.Command; } });

package/general/metadata.model.d.ts

@@ -1,9 +1,45 @@
-export interface IMetadata {
+/**
+ * Represents metadata for tracking execution flow within commands.
+ *
+ * @param auditUuid - The UUID used to track the full execution flow.
+ *   Example: The `auditUuid` from `OrderTravelCommand` will be passed to all items processed by `ProcessOrderItemCommand`.
+ * @param actionUuid - (Optional) The UUID used for tracking sub-flows.
+ *   Example: `ProcessOrderItemCommand` generates its own `actionUuid` and passes it along for tracking each item.
+ * @param extraInfo - (Optional) Additional information related to the command.
+ */
+export interface IMetadata<T = any> {
     auditUuid: string;
+    actionUuid?: string;
+    extraInfo?: T;
 }
+/**
+ * @param metadata - The metadata object containing execution tracking details.
+ */
 export declare class MetadataModel {
     private metadata;
     constructor(metadata: IMetadata);
+    /**
+    * Retrieves the complete metadata object.
+    *
+    * @returns The metadata object.
+    */
     getData(): IMetadata;
+    /**
+     * Retrieves the UUID used to track the full execution flow.
+     *
+     * @returns The audit UUID.
+     */
     getAuditUuid(): string;
+    /**
+     * Retrieves the UUID used for tracking sub-flows.
+     *
+     * @returns The action UUID, or undefined if not set.
+     */
+    getActionUuid(): string | undefined;
+    /**
+    * Retrieves additional information related to the execution flow.
+    *
+    * @returns The extra information, or undefined if not available.
+    */
+    getExtraInfo<T = any>(): T | undefined;
 }

package/general/metadata.model.js

@@ -1,15 +1,44 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MetadataModel = void 0;
+/**
+ * @param metadata - The metadata object containing execution tracking details.
+ */
 class MetadataModel {
     constructor(metadata) {
         this.metadata = metadata;
     }
+    /**
+    * Retrieves the complete metadata object.
+    *
+    * @returns The metadata object.
+    */
     getData() {
         return this.metadata;
     }
+    /**
+     * Retrieves the UUID used to track the full execution flow.
+     *
+     * @returns The audit UUID.
+     */
     getAuditUuid() {
         return this.metadata.auditUuid;
     }
+    /**
+     * Retrieves the UUID used for tracking sub-flows.
+     *
+     * @returns The action UUID, or undefined if not set.
+     */
+    getActionUuid() {
+        return this.metadata.actionUuid;
+    }
+    /**
+    * Retrieves additional information related to the execution flow.
+    *
+    * @returns The extra information, or undefined if not available.
+    */
+    getExtraInfo() {
+        return this.metadata.extraInfo;
+    }
 }
 exports.MetadataModel = MetadataModel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sm-utility",
-  "version": "2.4.9",
+  "version": "2.4.12",
   "description": "reusable utility codes for sm projects",
   "main": "index.js",
   "types": "./index.d.ts",