@jmlq/logger 0.1.0-alpha.20 → 0.1.0-alpha.21

package/architecture.md

@@ -2,69 +2,95 @@
 
 ## Visión General
 
-El paquete `@jmlq/logger` está diseñado siguiendo los principios de **Arquitectura Limpia**, proporcionando un sistema de logging extensible y desacoplado que permite registrar logs en múltiples destinos mediante plugins y soporta enmascarado de datos sensibles (PII - Personally Identifiable Information).
+El paquete `@jmlq/logger` implementa **Clean Architecture** (Arquitectura Limpia), proporcionando un sistema de logging modular que permite registrar logs en múltiples destinos y enmascarar datos sensibles (PII).
 
-## Principios de Diseño
+### Principios Aplicados
 
-- **Separación de responsabilidades**: Cada capa tiene una responsabilidad específica
-- **Inversión de dependencias**: Las capas internas no dependen de las externas
-- **Extensibilidad**: Sistema de plugins para diferentes adaptadores de persistencia
-- **Testabilidad**: Arquitectura que facilita la creación de pruebas unitarias
-- **Configurabilidad**: Múltiples opciones de configuración mediante variables de entorno
+- **Separación de responsabilidades**: Cada capa tiene una función específica
+- **Inversión de dependencias**: Las capas internas no conocen las externas
+- **Extensibilidad**: Sistema de plugins para diferentes adaptadores
+- **Testabilidad**: Contratos claros facilitan las pruebas
+
+---
 
 ## Estructura de Capas
 
 ### 📁 Domain (Capa de Dominio)
 
-La capa más interna que contiene la lógica de negocio pura, sin dependencias externas.
+_La capa más interna - lógica de negocio pura_
+
+#### **Value Objects**
+
+- [`log-level.vo.ts`](src/domain/value-objects/log-level.vo.ts): Enumeración de niveles de logging (TRACE, DEBUG, INFO, WARN, ERROR, FATAL)
 
-#### **Entities & Value Objects**
+#### **Models**
 
-- [`LogLevelVo`](src/domain/value-objects/log-level.vo.ts): Objeto de valor que representa los niveles de log
+- [`log-entry.model.ts`](src/domain/model/log-entry.model.ts): Estructura de datos de un log
+- [`pii-options.model.ts`](src/domain/model/pii-options.model.ts): Configuración para enmascarado PII
+- [`pii-replacement-rule.ts`](src/domain/model/pii-replacement-rule.ts): Reglas de reemplazo para datos sensibles
 
-#### **Ports (Interfaces)**
+#### **Ports (Contratos)**
 
-- [`ILoggerPort`](src/domain/ports/logger.port.ts): Contrato principal del logger
-- [`ILogDatasourcePort`](src/domain/ports/log-datasource.port.ts): Contrato para fuentes de datos
-- [`ILoggerServicePort`](src/domain/ports/logger-service.port.ts): Contrato para servicios de logging
-- [`IPiiRedactorPort`](src/domain/ports/pii-redactor.port.ts): Contrato para enmascarado PII
-- [`ILoggerFactoryConfigPort`](src/domain/ports/logger-factory-config.port.ts): Contrato de configuración del factory
+- [`logger.port.ts`](src/domain/ports/logger.port.ts): Interfaz principal del logger (`ILogger`)
+- [`log-datasource.port.ts`](src/domain/ports/log-datasource.port.ts): Contrato para persistencia (`ILogDatasource`)
+- [`pii-redactor.port.ts`](src/domain/ports/pii-redactor.port.ts): Contrato para enmascarado (`IPiiRedactor`)
+- [`create-logger-options.port.ts`](src/domain/ports/create-logger-options.port.ts): Configuración del factory
 
 #### **Services (Servicios de Dominio)**
 
-- [`LogLevelService`](src/domain/services/log-level.service.ts): Lógica para manejo de niveles de log
-- [`MessageNormalizerService`](src/domain/services/message-normalizer.service.ts): Normalización de mensajes
-- [`PiiPatternService`](src/domain/services/pii-pattern.service.ts): Gestión de patrones PII
-- [`PiiRedactorService`](src/domain/services/pii-redactor.service.ts): Enmascarado de datos sensibles
+- [`pii-redactor.service.ts`](src/domain/services/pii-redactor.service.ts): Implementación del enmascarado de datos sensibles
+
+#### **Request/Response**
+
+- [`log-filter.request.ts`](src/domain/request/log-filter.request.ts): Filtros para consultas (`LogFilterRequest`)
+- [`log.response.ts`](src/domain/response/log.response.ts): Formato de respuesta (`ILogResponse`)
 
-#### **Types & DTOs**
+#### **Types & Utils**
 
-- **Request**: [`SaveLogProps`](src/domain/request/save-log.props.ts), [`GetLogsFilterProps`](src/domain/request/get-logs-filter.props.ts), [`PiiOptionsProps`](src/domain/request/pii-options.props.ts)
-- **Response**: [`LogResponse`](src/domain/response/log.response.ts)
-- **Types**: [`LogMessageType`](src/domain/types/log-message.type.ts)
+- [`log-message.type.ts`](src/domain/types/log-message.type.ts): Tipo para mensajes de log
+- [`normalize-message.util.ts`](src/domain/utils/normalize-message.util.ts): Normalización de mensajes
+- [`parse-log-level.util.ts`](src/domain/utils/parse-log-level.util.ts): Conversión de strings a LogLevel
+- [`pii-regex.util.ts`](src/domain/utils/pii-regex.util.ts): Generación de expresiones regulares para PII
+
+---
 
 ### 📁 Application (Capa de Aplicación)
 
-Orquesta la lógica de negocio y coordina los casos de uso.
+_Orquesta casos de uso y coordina la lógica de negocio_
+
+#### **Factory**
+
+- [`logger.factory.ts`](src/application/factory/logger.factory.ts): **Punto de entrada principal** - crea instancias del logger con configuración completa
 
 #### **Use Cases**
 
-- [`SaveLogUseCase`](src/application/use-cases/save-log.use-case.ts): Guarda logs en los datasources configurados
-- [`GetLogsUseCase`](src/application/use-cases/get-logs.use-case.ts): Recupera logs con filtros
-- [`FlushBuffersUseCase`](src/application/use-cases/flush-buffers.use-case.ts): Vacía buffers de los datasources
+- [`save-log.use-case.ts`](src/application/use-cases/save-log.use-case.ts): Guarda logs aplicando filtros y PII
+- [`get-logs.use-case.ts`](src/application/use-cases/get-logs.use-case.ts): Recupera logs con filtros avanzados
+- [`flush-buffers.use-case.ts`](src/application/use-cases/flush-buffers.use-case.ts): Vacía buffers de los datasources
 
-#### **Factory**
+#### **Dependencies**
 
-- [`LoggerFactory`](src/application/factory/logger.factory.ts): Factory para crear instancias del logger
+- [`save-log.props.ts`](src/application/use-cases/save-log/save-log.props.ts): Dependencias para SaveLogUseCase
+
+#### **Types**
+
+- [`logger-factory-config.type.ts`](src/application/types/logger-factory-config.type.ts): Configuración del factory (`ILoggerFactoryConfig`)
+
+---
 
 ### 📁 Infrastructure (Capa de Infraestructura)
 
-Implementaciones concretas de los contratos definidos en el dominio.
+_Implementaciones concretas y adaptadores externos_
 
 #### **Services**
 
-- [`DatasourceService`](src/infrastructure/services/datasource.service.ts): Implementación del servicio de datasource
-- [`DataSourceErrorHandlerType`](src/infrastructure/services/data-source-error-handler.type.ts): Manejo de errores de datasources
+- [`datasource.service.ts`](src/infrastructure/services/datasource.service.ts): Implementación del patrón Composite para múltiples datasources
+
+#### **Types**
+
+- [`on-data-source-error.type.ts`](src/infrastructure/types/on-data-source-error.type.ts): Manejo de errores de datasources
+
+---
 
 ## Flujo de Dependencias
 
@@ -72,100 +98,96 @@ Implementaciones concretas de los contratos definidos en el dominio.
 Infrastructure → Application → Domain
 ```
 
-- **Domain**: No depende de nada, contiene la lógica de negocio pura
-- **Application**: Depende solo del Domain, orquesta los casos de uso
-- **Infrastructure**: Depende del Domain y Application, implementa los contratos
+- **Domain**: Contiene la lógica pura, sin dependencias externas
+- **Application**: Usa el Domain, coordina casos de uso
+- **Infrastructure**: Implementa contratos del Domain
+
+---
 
 ## Patrones Implementados
 
 ### **Factory Pattern**
 
-El [`LoggerFactory`](src/application/factory/logger.factory.ts) centraliza la creación de instancias del logger con las configuraciones apropiadas.
+[`logger.factory.ts`](src/application/factory/logger.factory.ts) centraliza la creación del logger y sus dependencias.
 
 ### **Port-Adapter Pattern**
 
-Los ports en el domain definen contratos que son implementados por adaptadores en infrastructure.
+Los ports en Domain definen contratos implementados por adaptadores externos (plugins).
 
 ### **Use Case Pattern**
 
-Cada operación principal está encapsulada en un caso de uso específico con un método `execute()`.
+Cada operación principal tiene un caso de uso con método `execute()`.
 
-### **Dependency Injection**
+### **Composite Pattern**
 
-Las dependencias se inyectan a través de constructores, facilitando el testing y la flexibilidad.
+[`datasource.service.ts`](src/infrastructure/services/datasource.service.ts) maneja múltiples datasources como uno solo.
 
-## Sistema de Plugins
-
-El logger soporta múltiples adaptadores de persistencia:
-
-- **Filesystem**: `@jmlq/logger-plugin-fs`
-- **MongoDB**: `@jmlq/logger-plugin-mongo`
-- **PostgreSQL**: `@jmlq/logger-plugin-postgresql`
-
-Cada plugin implementa los ports definidos en el domain.
+---
 
 ## Características Principales
 
-### **PII (Personally Identifiable Information)**
-
-- Enmascarado automático de datos sensibles
-- Patrones configurables y extensibles
-- Soporte para patrones por defecto y personalizados
-
 ### **Niveles de Log**
 
-- debug, info, warn, error, fatal
+- `TRACE` (10), `DEBUG` (20), `INFO` (30), `WARN` (40), `ERROR` (50), `FATAL` (60)
 - Configuración de nivel mínimo por entorno
 
+### **Enmascarado PII**
+
+- Patrones configurables para emails, tarjetas, teléfonos, etc.
+- Procesamiento profundo en objetos anidados
+- Whitelist/blacklist de campos
+
 ### **Múltiples Datasources**
 
-- Soporte simultáneo para múltiples backends
-- Configuración opcional de cada adaptador
+- Soporte simultáneo para archivos, MongoDB, PostgreSQL
+- Fan-out automático a todos los datasources configurados
+
+### **Sistema de Plugins**
 
-### **Configuración Flexible**
+- **Filesystem**: `@jmlq/logger-plugin-fs`
+- **MongoDB**: `@jmlq/logger-plugin-mongo`
+- **PostgreSQL**: `@jmlq/logger-plugin-postgresql`
 
-- Variables de entorno
-- Configuración programática
-- Políticas de retención de datos
+---
 
-## Ejemplo de Uso
+## Punto de Entrada
 
 ```typescript
-import { LoggerBootstrap } from "@jmlq/logger";
+import { createLogger } from "@jmlq/logger";
 
-const logger = await LoggerBootstrap.create({
-  minLevel: "debug",
-  pii: {
+const logger = createLogger({
+  datasources: [fsAdapter, mongoAdapter],
+  minLevel: LogLevel.INFO,
+  redactorOptions: {
     enabled: true,
-    includeDefaults: true,
-    deep: true,
-  },
-  adapters: {
-    fs: { basePath: "./logs" },
-    mongo: { url: "mongodb://localhost:27017", dbName: "logs" },
+    patterns: [
+      /* reglas PII */
+    ],
   },
 });
 
-await logger.info("User logged in", {
-  userId: "12345",
-  email: "user@example.com",
-});
+await logger.info("User logged in", { userId: "123" });
 ```
 
-## Testing
+---
+
+## Flujo de Datos
 
-La arquitectura facilita el testing mediante:
+1. **Cliente** → llama método del logger (`info`, `error`, etc.)
+2. **Factory** → crea logger con casos de uso configurados
+3. **SaveLogUseCase** → aplica filtros de nivel y PII
+4. **DataSourceService** → distribuye a múltiples datasources
+5. **Plugins** → persisten en destino final (archivo, BD, etc.)
 
-> - Interfaces claramente definidas
-> - Servicios desacoplados
-> - Casos de uso aislados
-> - Mocks sencillos de implementar
+---
+
+## Testing
 
-## Consideraciones de Rendimiento
+La arquitectura facilita testing mediante:
 
-> - Buffers para escritura asíncrona
-> - Políticas de rotación de archivos
-> - Retención configurable de datos
-> - Procesamiento asíncrono de logs
+- Interfaces bien definidas para mocking
+- Casos de uso aislados
+- Servicios desacoplados
+- Inyección de dependencias explícita
 
-Esta arquitectura asegura mantenibilidad, extensibilidad y testabilidad del sistema de logging, siguiendo las mejores prácticas de clean architecture.
+Esta arquitectura asegura **mantenibilidad**, **extensibilidad** y **testabilidad** siguiendo principios SOLID y Clean Architecture.

package/dist/application/factory/logger.factory.d.ts

@@ -1,4 +1,5 @@
-import { ILoggerFactoryConfig, ILogger } from "../../domain/ports";
+import { ILogger } from "../../domain/ports";
+import { ILoggerFactoryConfig } from "../types";
 /**
  * Factory principal de @jmlq/logger.
  * Se encarga de:

package/dist/application/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./logger-factory-config.type";

package/dist/application/types/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./logger-factory-config.type"), exports);

package/dist/{domain/ports/logger-factory-config.port.d.ts → application/types/logger-factory-config.type.d.ts}

@@ -1,6 +1,6 @@
-import { ILogDatasource, IPiiRedactor } from ".";
-import { PiiOptions } from "../model";
-import { LogLevel } from "../value-objects";
+import { ILogDatasource, IPiiRedactor } from "../../domain/ports";
+import { PiiOptions } from "../../domain/model";
+import { LogLevel } from "../../domain/value-objects";
 /**
  * Configuración de alto nivel para construir el logger.
  * Es lo que recibe el usuario del paquete npm.

package/dist/domain/ports/index.d.ts

@@ -2,4 +2,3 @@ export * from "./log-datasource.port";
 export * from "./logger.port";
 export * from "./pii-redactor.port";
 export * from "./create-logger-options.port";
-export * from "./logger-factory-config.port";

package/dist/domain/ports/index.js

@@ -18,5 +18,3 @@ __exportStar(require("./log-datasource.port"), exports);
 __exportStar(require("./logger.port"), exports);
 __exportStar(require("./pii-redactor.port"), exports);
 __exportStar(require("./create-logger-options.port"), exports);
-__exportStar(require("./logger-factory-config.port"), exports);
-// export * from "./logger-service.port";

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { createLogger } from "./application/factory";
-export type { ILogger, ILoggerFactoryConfig, ILogDatasource, } from "./domain/ports";
+export type { ILoggerFactoryConfig } from "./application/types";
+export type { ILogger, ILogDatasource } from "./domain/ports";
 export { LogLevel } from "./domain/value-objects";
 export type { LogFilterRequest as LogSearchRequest } from "./domain/request";
 export type { ILogResponse as LogRecord } from "./domain/response";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jmlq/logger",
   "description": "logger package with clean architecture",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.21",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -40,6 +40,6 @@
     "dist",
     "README.md",
     "architecture.md",
-    "install.md"
+    "assets"
   ]
 }