@seidor-cloud-produtos/orbit-backend-lib 2.0.85 → 2.0.87

package/dist/clean-arch/application/cache/cache.d.ts

@@ -1,31 +1,63 @@
 import { Logger } from '../logger';
 import { CacheClient } from './client';
+/**
+ * Opcoes por metodo (sobrescrevem CacheOptions).
+ */
 export type MethodOptions = {
     throwOnError?: boolean;
 };
+/**
+ * Opcoes globais do cache.
+ * - throwOnError: quando true, propaga erros.
+ * - contingencyClients: lista de clientes alternativos para fallback.
+ */
 export type CacheOptions = {
     throwOnError?: boolean;
     contingencyClients?: CacheClient[];
 };
+/**
+ * Camada de cache padrao da lib.
+ * Responsavel por:
+ * - controlar TTL padrao
+ * - serializacao JSON
+ * - fallback entre clientes
+ */
 export declare abstract class Cache {
     protected logger: Logger;
     protected abstract client: CacheClient;
     protected elegibleClients: CacheClient[];
+    /** TTL padrao (segundos). */
     protected DEFAULT_EXPIRATION_SECONDS: number;
     private options?;
     constructor(options?: CacheOptions, logger?: Logger);
     private setElegibleClients;
     private setOptions;
     private setRunningClient;
+    /** Inicia o cliente de cache. */
     start(options?: MethodOptions): Promise<void>;
+    /** Busca um valor do cache. */
     get(keyCache: string, options?: MethodOptions): Promise<any>;
+    /** Grava um valor no cache com TTL (segundos). */
     set(keyCache: string, data: any, expiration?: number, options?: MethodOptions): Promise<void>;
+    /** Remove uma chave do cache. */
     del(keyCache: string, options?: MethodOptions): Promise<void>;
+    /** Lista chaves; o pattern varia por cliente. */
     getKeys(pattern?: string, options?: MethodOptions): Promise<string[] | null>;
+    /** Remove varias chaves de uma vez. */
     delBatch(patterns: string[], options?: MethodOptions): Promise<void>;
+    /** Limpa o banco/instancia de cache. */
     flush(): Promise<void>;
+    /**
+     * Health-check do cache.
+     * - se falhar, tenta alternar para um cliente elegivel
+     */
     isRunning(options?: MethodOptions, isContingency?: boolean): Promise<boolean>;
+    /** Encerra o cliente de cache. */
     close(options?: MethodOptions): Promise<void>;
+    /** Padroniza o log/propagacao de erros. */
     protected handleException(e: Error): Promise<void>;
+    /**
+     * Busca do cache e, se nao existir, executa a promise e grava o resultado.
+     */
     getOrFetchAndCache<T>(keyCache: string, expiration: number | undefined, promise: () => Promise<T>, options?: MethodOptions): Promise<T | undefined>;
 }

package/dist/clean-arch/application/cache/cache.js

@@ -2,9 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Cache = void 0;
 const env_1 = require("../../infra/environment/env");
+/**
+ * Camada de cache padrao da lib.
+ * Responsavel por:
+ * - controlar TTL padrao
+ * - serializacao JSON
+ * - fallback entre clientes
+ */
 class Cache {
     logger;
     elegibleClients;
+    /** TTL padrao (segundos). */
     DEFAULT_EXPIRATION_SECONDS = env_1.env?.DEFAULT_CACHE_EXPIRATION || 360;
     options;
     constructor(options, logger = console) {
@@ -51,6 +59,7 @@ class Cache {
         this.logger.warn(`Changed cache client to ${this.client.constructor.name}`);
         return this;
     }
+    /** Inicia o cliente de cache. */
     async start(options) {
         try {
             await this.client.start();
@@ -66,6 +75,7 @@ class Cache {
         }
         this.logger.info('💾 Cache Connected');
     }
+    /** Busca um valor do cache. */
     async get(keyCache, options) {
         try {
             const dataFromCache = await this.client.get(keyCache);
@@ -78,6 +88,7 @@ class Cache {
             return null;
         }
     }
+    /** Grava um valor no cache com TTL (segundos). */
     async set(keyCache, data, expiration = this.DEFAULT_EXPIRATION_SECONDS, options) {
         try {
             return await this.client.set(keyCache, JSON.stringify(data), expiration);
@@ -89,6 +100,7 @@ class Cache {
             return;
         }
     }
+    /** Remove uma chave do cache. */
     async del(keyCache, options) {
         try {
             return await this.client.del(keyCache);
@@ -100,6 +112,7 @@ class Cache {
             return;
         }
     }
+    /** Lista chaves; o pattern varia por cliente. */
     async getKeys(pattern, options) {
         try {
             return await this.client.getKeys(pattern);
@@ -111,6 +124,7 @@ class Cache {
             return null;
         }
     }
+    /** Remove varias chaves de uma vez. */
     async delBatch(patterns, options) {
         try {
             return await this.client.delBatch(patterns);
@@ -122,6 +136,7 @@ class Cache {
             return;
         }
     }
+    /** Limpa o banco/instancia de cache. */
     async flush() {
         try {
             return await this.client.flush();
@@ -130,6 +145,10 @@ class Cache {
             await this.handleException(e);
         }
     }
+    /**
+     * Health-check do cache.
+     * - se falhar, tenta alternar para um cliente elegivel
+     */
     async isRunning(options, isContingency = false) {
         let isRunning = false;
         try {
@@ -146,6 +165,7 @@ class Cache {
         }
         return isRunning;
     }
+    /** Encerra o cliente de cache. */
     async close(options) {
         this.logger.info('💾 Cache closed');
         try {
@@ -158,10 +178,14 @@ class Cache {
             return;
         }
     }
+    /** Padroniza o log/propagacao de erros. */
     async handleException(e) {
         this.logger.error(JSON.stringify(e));
         throw e;
     }
+    /**
+     * Busca do cache e, se nao existir, executa a promise e grava o resultado.
+     */
     async getOrFetchAndCache(keyCache, expiration = this.DEFAULT_EXPIRATION_SECONDS, promise, options) {
         let data = await this.get(keyCache, options);
         if (!data) {

package/dist/clean-arch/application/cache/client.d.ts

@@ -1,16 +1,39 @@
+/**
+ * Opcoes basicas para clientes de cache.
+ * - timeout: segundos usados como timeout de operacoes e ping.
+ */
 export interface CacheClientOptions {
     timeout?: number;
 }
+/**
+ * Contrato minimo de um cliente de cache.
+ * Cada implementacao deve cuidar de:
+ * - conexao (start/close)
+ * - operacoes basicas (get/set/del/getKeys/flush)
+ */
 export declare abstract class CacheClient {
     protected connection?: CacheClientOptions | undefined;
     constructor(connection?: CacheClientOptions | undefined);
+    /** Inicializa o cliente/conexao. */
     abstract start(): Promise<void>;
+    /** Encerra o cliente/conexao. */
     abstract close(): Promise<void>;
+    /** Recupera um valor pelo nome da chave. */
     abstract get(keyCache: string): Promise<any>;
+    /** Grava um valor com TTL opcional (segundos). */
     abstract set(keyCache: string, data: any, expiration?: number): Promise<void>;
+    /** Remove uma chave. */
     abstract del(keyCache: string): Promise<void>;
+    /** Remove varias chaves. */
     abstract delBatch(keyCache: string[]): Promise<void>;
+    /** Lista chaves; o pattern depende do cliente. */
     abstract getKeys(pattern?: string): Promise<string[] | null>;
+    /** Limpa o banco/instancia. */
     abstract flush(): Promise<void>;
+    /**
+     * Health-check simples:
+     * - grava um ping
+     * - le de volta e valida
+     */
     isRunning(): Promise<any>;
 }

package/dist/clean-arch/application/cache/client.js

@@ -2,11 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacheClient = void 0;
 const unique_entity_id_1 = require("../../domain/entities/unique-entity-id");
+/**
+ * Contrato minimo de um cliente de cache.
+ * Cada implementacao deve cuidar de:
+ * - conexao (start/close)
+ * - operacoes basicas (get/set/del/getKeys/flush)
+ */
 class CacheClient {
     connection;
     constructor(connection) {
         this.connection = connection;
     }
+    /**
+     * Health-check simples:
+     * - grava um ping
+     * - le de volta e valida
+     */
     async isRunning() {
         const key = new unique_entity_id_1.UniqueEntityId().toValue();
         await this.set(key, JSON.stringify({ ping: true }), this.connection?.timeout || 60);

package/dist/clean-arch/application/logger/index.d.ts

@@ -1,53 +1,130 @@
 import { LOG_LEVEL } from '../../infra/environment/types';
 import { Cache } from '../cache/cache';
+/**
+ * Identifica o tipo de ator que originou o log.
+ */
 export declare enum ActorEnum {
     SYSTEM = "system",
     USER = "user"
 }
+/**
+ * Categoriza o log em negócio ou técnico.
+ */
 export declare enum CategoryEnum {
     BUSINESS = "business",
     TECHNICAL = "technical"
 }
+/**
+ * Propriedades obrigatórias após a construção do log.
+ */
 export interface LogProperties {
     level: LOG_LEVEL;
     actor: string;
     type: string;
     dateTime: Date;
 }
+/**
+ * Propriedades mínimas de entrada para logar.
+ */
 export interface LogPropertiesInput {
     level: LOG_LEVEL;
 }
+/**
+ * Parâmetros padrão usados para construir propriedades de log.
+ */
 export interface LogParams {
     actor: string;
     type: string;
 }
-export interface LogParamsInput extends Partial<LogParams> {
-}
+export type LogParamsInput = Partial<LogParams>;
+/**
+ * Opções de comportamento do logger.
+ */
 export interface LogOptions {
+    /**
+     * Quando `true`, assume que o último argumento do log é `params` adicionais.
+     */
     lastArgIsParams?: boolean;
 }
+/**
+ * Interface mínima de um logger.
+ */
 export interface Logger {
     info: (...input: any[]) => Promise<void> | void;
     warn: (...input: any[]) => Promise<void> | void;
     error: (...input: any[]) => Promise<void> | void;
     debug: (...input: any[]) => Promise<void> | void;
 }
+/**
+ * Classe base para loggers.
+ *
+ * Responsável por:
+ * - Montar propriedades padrão (`actor`, `type`, `level`, `dateTime`).
+ * - Aplicar filtros por nível com apoio opcional de cache.
+ * - Delegar o envio para a implementação concreta (`register`).
+ */
 export default abstract class LoggerGateway implements Logger {
     protected cache?: Cache | undefined;
     protected options?: LogOptions | undefined;
-    protected params?: LogParamsInput | undefined;
-    constructor(cache?: Cache | undefined, options?: LogOptions | undefined, params?: LogParamsInput | undefined);
+    protected params?: Partial<LogParams> | undefined;
+    constructor(cache?: Cache | undefined, options?: LogOptions | undefined, params?: Partial<LogParams> | undefined);
     private static cacheKey;
+    /**
+     * Loga com nível `info`.
+     */
     info(...input: any[]): Promise<void>;
+    /**
+     * Loga com nível `warn`.
+     */
     warn(...input: any[]): Promise<void>;
+    /**
+     * Loga com nível `error`.
+     */
     error(...input: any[]): Promise<void>;
+    /**
+     * Loga com nível `debug`.
+     */
     debug(...input: any[]): Promise<void>;
+    /**
+     * Fluxo principal de logging.
+     *
+     * - Extrai params extras quando `lastArgIsParams` estiver habilitado.
+     * - Monta propriedades finais.
+     * - Checa se deve logar (nível/cache).
+     * - Delegada envio para `register`.
+     */
     log(props: LogPropertiesInput, dataToLog: any): Promise<void>;
+    /**
+     * Implementação concreta deve persistir/enviar o log.
+     */
     protected abstract register(props: LogProperties, dataToLog: any, params?: LogParams): Promise<void> | void;
+    /**
+     * Constrói a lista de níveis aceitos com base no nível configurado.
+     */
     private static buildAcceptLogLevelValues;
+    /**
+     * Decide se o log deve ser emitido.
+     *
+     * - `error` sempre é emitido.
+     * - Sem cache, sempre emite.
+     * - Com cache, consulta o nível permitido por tipo/actor.
+     */
     protected isToLog(props: LogProperties, dataToLog: any): Promise<boolean>;
+    /**
+     * Monta as propriedades finais do log.
+     */
     protected buildProps(props?: LogPropertiesInput, params?: LogParamsInput): LogProperties;
+    /**
+     * Monta propriedades padrão.
+     */
     protected buildDefaultProps(params?: LogParamsInput): LogProperties;
+    /**
+     * Define o nível de log no cache para um filtro (type/actor).
+     *
+     * @param level Nível mínimo a ser aceito.
+     * @param filter Filtro de log por tipo e ator.
+     * @param ttl Tempo em segundos (default 4 dias).
+     */
     setLevel(level: LOG_LEVEL, filter: {
         logType: string;
         logActor: string;

package/dist/clean-arch/application/logger/index.js

@@ -2,16 +2,30 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CategoryEnum = exports.ActorEnum = void 0;
 const types_1 = require("../../infra/environment/types");
+/**
+ * Identifica o tipo de ator que originou o log.
+ */
 var ActorEnum;
 (function (ActorEnum) {
     ActorEnum["SYSTEM"] = "system";
     ActorEnum["USER"] = "user";
 })(ActorEnum || (exports.ActorEnum = ActorEnum = {}));
+/**
+ * Categoriza o log em negócio ou técnico.
+ */
 var CategoryEnum;
 (function (CategoryEnum) {
     CategoryEnum["BUSINESS"] = "business";
     CategoryEnum["TECHNICAL"] = "technical";
 })(CategoryEnum || (exports.CategoryEnum = CategoryEnum = {}));
+/**
+ * Classe base para loggers.
+ *
+ * Responsável por:
+ * - Montar propriedades padrão (`actor`, `type`, `level`, `dateTime`).
+ * - Aplicar filtros por nível com apoio opcional de cache.
+ * - Delegar o envio para a implementação concreta (`register`).
+ */
 class LoggerGateway {
     cache;
     options;
@@ -22,18 +36,38 @@ class LoggerGateway {
         this.params = params;
     }
     static cacheKey = 'LOG_LEVEL';
+    /**
+     * Loga com nível `info`.
+     */
     async info(...input) {
         return await this.log({ level: types_1.LOG_LEVEL.info }, input);
     }
+    /**
+     * Loga com nível `warn`.
+     */
     async warn(...input) {
         return await this.log({ level: types_1.LOG_LEVEL.warn }, input);
     }
+    /**
+     * Loga com nível `error`.
+     */
     async error(...input) {
         return await this.log({ level: types_1.LOG_LEVEL.error }, input);
     }
+    /**
+     * Loga com nível `debug`.
+     */
     async debug(...input) {
         return await this.log({ level: types_1.LOG_LEVEL.debug }, input);
     }
+    /**
+     * Fluxo principal de logging.
+     *
+     * - Extrai params extras quando `lastArgIsParams` estiver habilitado.
+     * - Monta propriedades finais.
+     * - Checa se deve logar (nível/cache).
+     * - Delegada envio para `register`.
+     */
     async log(props, dataToLog) {
         try {
             let params = this.params;
@@ -43,6 +77,7 @@ class LoggerGateway {
                     ...dataToLog[dataToLog.length - 1],
                 };
                 dataToLog = dataToLog.slice(0, dataToLog.length - 1);
+                dataToLog = dataToLog.length === 1 ? dataToLog[0] : dataToLog;
             }
             const buildedProperties = this.buildProps(props, params);
             const isToLog = await this.isToLog(buildedProperties, dataToLog);
@@ -56,6 +91,9 @@ class LoggerGateway {
             console.log('Input', props, dataToLog);
         }
     }
+    /**
+     * Constrói a lista de níveis aceitos com base no nível configurado.
+     */
     static buildAcceptLogLevelValues(level) {
         const acceptValues = [types_1.LOG_LEVEL.error];
         if (level === types_1.LOG_LEVEL.warn) {
@@ -69,6 +107,13 @@ class LoggerGateway {
         }
         return acceptValues;
     }
+    /**
+     * Decide se o log deve ser emitido.
+     *
+     * - `error` sempre é emitido.
+     * - Sem cache, sempre emite.
+     * - Com cache, consulta o nível permitido por tipo/actor.
+     */
     async isToLog(props, dataToLog) {
         if (props.level === types_1.LOG_LEVEL.error || !this.cache) {
             return true;
@@ -97,6 +142,9 @@ class LoggerGateway {
         const acceptValues = LoggerGateway.buildAcceptLogLevelValues(cachedValue);
         return acceptValues.includes(props.level);
     }
+    /**
+     * Monta as propriedades finais do log.
+     */
     buildProps(props, params) {
         const defaultProps = this.buildDefaultProps(params);
         if (props) {
@@ -107,6 +155,9 @@ class LoggerGateway {
         }
         return defaultProps;
     }
+    /**
+     * Monta propriedades padrão.
+     */
     buildDefaultProps(params) {
         return {
             level: types_1.LOG_LEVEL.info,
@@ -116,6 +167,13 @@ class LoggerGateway {
             ...(params || {}),
         };
     }
+    /**
+     * Define o nível de log no cache para um filtro (type/actor).
+     *
+     * @param level Nível mínimo a ser aceito.
+     * @param filter Filtro de log por tipo e ator.
+     * @param ttl Tempo em segundos (default 4 dias).
+     */
     async setLevel(level, filter, ttl) {
         if (!this.cache) {
             return;

package/dist/clean-arch/application/queue/handler.d.ts

@@ -1,7 +1,35 @@
+/**
+ * Classe base para consumidores de fila.
+ *
+ * A ideia é estender esta classe e implementar o método `handle`.
+ * A lib usa os metadados abaixo para controlar concorrência e timeout.
+ */
 export default abstract class Handler {
+    /**
+     * Quantas mensagens podem ser processadas em paralelo.
+     *
+     * No RabbitMQ (`AmqpQueue.on`), este valor é aplicado como `prefetch`.
+     * Nos runners de ScaledJob, ele é usado como limite por execução.
+     */
     protected simultaneity: number;
+    /**
+     * Timeout por mensagem, em segundos.
+     *
+     * Quando definido, alguns runners competem o `handle` contra um timeout.
+     */
     protected timeoutPerMessageSeconds: number | undefined;
+    /**
+     * Retorna o nível de concorrência configurado para o handler.
+     */
     getSimultaneity(): number;
+    /**
+     * Retorna o timeout por mensagem, em segundos, se definido.
+     */
     getTimeoutPerMessageSeconds(): number | undefined;
+    /**
+     * Processa uma única mensagem.
+     *
+     * @param message Mensagem já desserializada (normalmente um objeto JSON).
+     */
     abstract handle(message: any): Promise<void>;
 }

package/dist/clean-arch/application/queue/handler.js

@@ -1,11 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Classe base para consumidores de fila.
+ *
+ * A ideia é estender esta classe e implementar o método `handle`.
+ * A lib usa os metadados abaixo para controlar concorrência e timeout.
+ */
 class Handler {
+    /**
+     * Quantas mensagens podem ser processadas em paralelo.
+     *
+     * No RabbitMQ (`AmqpQueue.on`), este valor é aplicado como `prefetch`.
+     * Nos runners de ScaledJob, ele é usado como limite por execução.
+     */
     simultaneity = 1;
+    /**
+     * Timeout por mensagem, em segundos.
+     *
+     * Quando definido, alguns runners competem o `handle` contra um timeout.
+     */
     timeoutPerMessageSeconds = undefined;
+    /**
+     * Retorna o nível de concorrência configurado para o handler.
+     */
     getSimultaneity() {
         return this.simultaneity;
     }
+    /**
+     * Retorna o timeout por mensagem, em segundos, se definido.
+     */
     getTimeoutPerMessageSeconds() {
         return this.timeoutPerMessageSeconds;
     }

package/dist/clean-arch/application/queue/messages-in-memory.d.ts

@@ -1,4 +1,10 @@
 import DomainEvent from '../../domain/events/domain-event';
+/**
+ * Representa uma publicação que falhou e foi guardada em memória.
+ *
+ * A implementação AMQP usa esta estrutura para re-publicar mensagens
+ * após reconexões.
+ */
 export type MessagesInMemory = {
     exchangeName: string;
     domainEvent: DomainEvent;

package/dist/clean-arch/application/queue/queue-connection.d.ts

@@ -1,9 +1,26 @@
 import Queue from './queue';
+/**
+ * Contrato de conexão com a infraestrutura de filas.
+ *
+ * Estende o contrato de `Queue` com ciclo de vida (`connect`/`close`)
+ * e com a capacidade opcional de declarar topologia (`createConsumers`).
+ */
 export default interface QueueConnection extends Queue {
+    /**
+     * Abre a conexão com o provedor de fila.
+     *
+     * @param props Parâmetros de conexão (ex.: vHost no RabbitMQ).
+     */
     connect(props: unknown): Promise<any>;
+    /**
+     * Encerra a conexão atual.
+     */
     close(): Promise<void>;
     /**
+     * Declara a topologia necessária para um consumidor.
      *
+     * Este método é opcional porque algumas implementações não precisam
+     * (ou não conseguem) declarar topologia programaticamente.
      * @deprecated Use createQueues() instead.
      */
     createConsumers?<T>(queueName: string, configs: T | any): Promise<void>;

package/dist/clean-arch/application/queue/queue.d.ts

@@ -1,7 +1,38 @@
 import DomainEvent from '../../domain/events/domain-event';
 import Handler from './handler';
+/**
+ * Contrato mínimo de uma implementação de fila.
+ *
+ * A interface foi pensada para suportar tanto consumo contínuo (`on`)
+ * quanto publicação baseada em eventos de domínio (`publish`).
+ */
 export default interface Queue {
+    /**
+     * Inicia o consumo contínuo de uma fila.
+     *
+     * @param queueName Nome da fila (e, por convenção, também o routing key).
+     * @param callback Handler responsável por processar cada mensagem.
+     */
     on(queueName: string, callback: Handler): Promise<void>;
+    /**
+     * Publica um evento de domínio em um exchange.
+     *
+     * Em implementações AMQP, o `domainEvent.name` costuma ser usado como
+     * routing key e como nome da fila por convenção.
+     *
+     * @param exchangeName Nome do exchange de destino.
+     * @param domainEvent Evento a ser publicado.
+     * @param configs Configurações específicas da implementação (ex.: TTL).
+     */
     publish(exchangeName: string, domainEvent: DomainEvent, configs?: Record<string, any>): Promise<void>;
+    /**
+     * Faz polling (pull) de uma mensagem.
+     *
+     * Este método é opcional porque nem toda implementação precisa suportar
+     * o modelo de consumo por polling.
+     *
+     * @param queueName Nome da fila.
+     * @param options Opções específicas da implementação (ex.: `noAck` no AMQP).
+     */
     get?(queueName: string, options?: any): Promise<unknown>;
 }

package/dist/clean-arch/domain/events/domain-event.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Contrato mínimo de um evento de domínio publicado em filas.
+ *
+ * O campo `name` é usado como routing key no AMQP por convenção.
+ */
 export default interface DomainEvent {
     name: string;
     eventDate: Date;

package/dist/clean-arch/infra/cache/cache-in-memory.d.ts

@@ -1,7 +1,12 @@
 import { Cache } from '../../application/cache/cache';
 import { CacheClient } from '../../application/cache/client';
+/**
+ * Cache em memoria pronto para uso na lib.
+ * Usa NodeCache como cliente.
+ */
 declare class LibCache extends Cache {
     protected client: CacheClient;
 }
+/** Singleton do cache em memoria. */
 declare const libCacheInstance: LibCache;
 export default libCacheInstance;

package/dist/clean-arch/infra/cache/cache-in-memory.js

@@ -2,9 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const cache_1 = require("../../application/cache/cache");
 const node_cache_1 = require("./clients/node-cache");
+/**
+ * Cache em memoria pronto para uso na lib.
+ * Usa NodeCache como cliente.
+ */
 class LibCache extends cache_1.Cache {
     client = new node_cache_1.NodeCache();
 }
+/** Singleton do cache em memoria. */
 const libCacheInstance = new LibCache();
+/** Inicializa no import. */
 libCacheInstance.start();
 exports.default = libCacheInstance;