@jmlq/logger 0.1.0-alpha.8 → 0.1.0-alpha.9

package/architecture.md

@@ -0,0 +1,171 @@
+# Arquitectura del Paquete @jmlq/logger
+
+## 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).
+
+## Principios de Diseño
+
+- **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
+
+## Estructura de Capas
+
+### 📁 Domain (Capa de Dominio)
+
+La capa más interna que contiene la lógica de negocio pura, sin dependencias externas.
+
+#### **Entities & Value Objects**
+
+- [`LogLevelVo`](src/domain/value-objects/log-level.vo.ts): Objeto de valor que representa los niveles de log
+
+#### **Ports (Interfaces)**
+
+- [`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
+
+#### **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
+
+#### **Types & DTOs**
+
+- **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)
+
+### 📁 Application (Capa de Aplicación)
+
+Orquesta la lógica de negocio y coordina los casos de uso.
+
+#### **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
+
+#### **Factory**
+
+- [`LoggerFactory`](src/application/factory/logger.factory.ts): Factory para crear instancias del logger
+
+### 📁 Infrastructure (Capa de Infraestructura)
+
+Implementaciones concretas de los contratos definidos en el dominio.
+
+#### **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
+
+## Flujo de Dependencias
+
+```txt
+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
+
+## Patrones Implementados
+
+### **Factory Pattern**
+
+El [`LoggerFactory`](src/application/factory/logger.factory.ts) centraliza la creación de instancias del logger con las configuraciones apropiadas.
+
+### **Port-Adapter Pattern**
+
+Los ports en el domain definen contratos que son implementados por adaptadores en infrastructure.
+
+### **Use Case Pattern**
+
+Cada operación principal está encapsulada en un caso de uso específico con un método `execute()`.
+
+### **Dependency Injection**
+
+Las dependencias se inyectan a través de constructores, facilitando el testing y la flexibilidad.
+
+## 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
+- Configuración de nivel mínimo por entorno
+
+### **Múltiples Datasources**
+
+- Soporte simultáneo para múltiples backends
+- Configuración opcional de cada adaptador
+
+### **Configuración Flexible**
+
+- Variables de entorno
+- Configuración programática
+- Políticas de retención de datos
+
+## Ejemplo de Uso
+
+```typescript
+import { LoggerBootstrap } from "@jmlq/logger";
+
+const logger = await LoggerBootstrap.create({
+  minLevel: "debug",
+  pii: {
+    enabled: true,
+    includeDefaults: true,
+    deep: true,
+  },
+  adapters: {
+    fs: { basePath: "./logs" },
+    mongo: { url: "mongodb://localhost:27017", dbName: "logs" },
+  },
+});
+
+await logger.info("User logged in", {
+  userId: "12345",
+  email: "user@example.com",
+});
+```
+
+## Testing
+
+La arquitectura facilita el testing mediante:
+
+> - Interfaces claramente definidas
+> - Servicios desacoplados
+> - Casos de uso aislados
+> - Mocks sencillos de implementar
+
+## Consideraciones de Rendimiento
+
+> - Buffers para escritura asíncrona
+> - Políticas de rotación de archivos
+> - Retención configurable de datos
+> - Procesamiento asíncrono de logs
+
+Esta arquitectura asegura mantenibilidad, extensibilidad y testabilidad del sistema de logging, siguiendo las mejores prácticas de clean architecture.

package/install.md

@@ -0,0 +1,367 @@
+# Guía de Instalación y Configuración para @jmlq/logger
+
+## Instalación
+
+```bash
+npm install @jmlq/logger
+```
+
+## Configuración Básica
+
+### NestJS
+
+1. Crear el módulo de Logger
+
+```typescript
+// src/logger/logger.module.ts
+import { Module, Global } from "@nestjs/common";
+import { ConfigModule, ConfigService } from "@nestjs/config";
+import { LoggerFactory } from "@jmlq/logger";
+
+@Global()
+@Module({
+  imports: [ConfigModule],
+  providers: [
+    {
+      provide: "LOGGER",
+      useFactory: async (configService: ConfigService) => {
+        // Configurar datasources según necesidades
+        const datasources = [];
+
+        // Ejemplo: Plugin de filesystem (requiere @jmlq/logger-plugin-fs)
+        if (configService.get("LOG_FS_ENABLED") === "true") {
+          const { FileSystemDatasource } = await import(
+            "@jmlq/logger-plugin-fs"
+          );
+          datasources.push(
+            new FileSystemDatasource({
+              basePath: configService.get("LOG_FS_PATH", "./logs"),
+            })
+          );
+        }
+
+        return LoggerFactory.create({
+          datasources,
+          minLevel: configService.get("LOG_LEVEL", "info"),
+          redactorOptions: {
+            enabled: true,
+            deep: true,
+            includeDefaults: true,
+          },
+        });
+      },
+      inject: [ConfigService],
+    },
+  ],
+  exports: ["LOGGER"],
+})
+export class LoggerModule {}
+```
+
+2. Usar en servicios
+
+```typescript
+// src/users/users.service.ts
+import { Injectable, Inject } from "@nestjs/common";
+import { ILogger } from "@jmlq/logger";
+
+@Injectable()
+export class UsersService {
+  constructor(@Inject("LOGGER") private readonly logger: ILogger) {}
+
+  async createUser(userData: any) {
+    try {
+      await this.logger.info("Creando usuario", { userData });
+      // ... lógica del servicio
+      await this.logger.info("Usuario creado exitosamente", {
+        userId: result.id,
+      });
+      return result;
+    } catch (error) {
+      await this.logger.error("Error al crear usuario", {
+        error: error.message,
+        userData,
+      });
+      throw error;
+    }
+  }
+}
+```
+
+### Express
+
+1. Configurar logger en app.js
+
+```ts
+// src/logger.ts
+import { LoggerFactory, LogLevel } from "@jmlq/logger";
+
+export const createLogger = async () => {
+  const datasources = [];
+
+  // Configurar datasources según variables de entorno
+  if (process.env.LOG_FS_ENABLED === "true") {
+    const { FileSystemDatasource } = await import("@jmlq/logger-plugin-fs");
+    datasources.push(
+      new FileSystemDatasource({
+        basePath: process.env.LOG_FS_PATH || "./logs",
+      })
+    );
+  }
+
+  return LoggerFactory.create({
+    datasources,
+    minLevel: process.env.LOG_LEVEL || LogLevel.INFO,
+    redactorOptions: {
+      enabled: true,
+      deep: true,
+      includeDefaults: true,
+      patterns: [
+        {
+          pattern: "\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b",
+          replaceWith: "****-****-****-****",
+        },
+      ],
+    },
+  });
+};
+```
+
+2. Middleware de logging
+
+```ts
+// src/middleware/logger.middleware.ts
+import { Request, Response, NextFunction } from "express";
+import { ILogger } from "@jmlq/logger";
+
+export const createLoggerMiddleware = (logger: ILogger) => {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const startTime = Date.now();
+
+    await logger.info("Request iniciado", {
+      method: req.method,
+      url: req.url,
+      ip: req.ip,
+      userAgent: req.get("User-Agent"),
+    });
+
+    res.on("finish", async () => {
+      const duration = Date.now() - startTime;
+      const level = res.statusCode >= 400 ? "error" : "info";
+
+      await logger[level]("Request completado", {
+        method: req.method,
+        url: req.url,
+        statusCode: res.statusCode,
+        duration,
+      });
+    });
+
+    next();
+  };
+};
+```
+
+3. Usar en la aplicación
+
+```ts
+// src/app.ts
+import express from "express";
+import { createLogger } from "./logger";
+import { createLoggerMiddleware } from "./middleware/logger.middleware";
+
+const app = express();
+const logger = await createLogger();
+
+app.use(createLoggerMiddleware(logger));
+
+app.get("/users/:id", async (req, res) => {
+  try {
+    await logger.info("Obteniendo usuario", { userId: req.params.id });
+    // ... lógica
+    res.json(user);
+  } catch (error) {
+    await logger.error("Error al obtener usuario", {
+      userId: req.params.id,
+      error: error.message,
+    });
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+```
+
+## Configuración de PII (Datos Sensibles)
+
+### Patrones Predefinidos
+
+El logger incluye patrones comunes para enmascarar datos sensibles:
+
+```ts
+const logger = LoggerFactory.create({
+  datasources,
+  redactorOptions: {
+    enabled: true,
+    deep: true, // Busca en objetos anidados
+    includeDefaults: true, // Incluye patrones predefinidos (email, teléfono, etc.)
+  },
+});
+```
+
+Patrones Personalizados
+
+```ts
+const logger = LoggerFactory.create({
+  datasources,
+  redactorOptions: {
+    enabled: true,
+    deep: true,
+    includeDefaults: true,
+    patterns: [
+      // Tarjetas de crédito
+      {
+        pattern: "\\b\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}\\b",
+        replaceWith: "****-****-****-****",
+      },
+      // CURP (México)
+      {
+        pattern: "[A-Z]{4}\\d{6}[HM][A-Z]{5}[A-Z0-9]\\d",
+        replaceWith: "****CURP****",
+      },
+      // Números de cuenta bancaria
+      {
+        pattern: "\\b\\d{10,20}\\b",
+        replaceWith: "****ACCOUNT****",
+      },
+      // Tokens JWT
+      {
+        pattern: "eyJ[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*",
+        replaceWith: "****JWT****",
+      },
+    ],
+  },
+});
+```
+
+## Filtrado de Registros
+
+### Filtros Básicos
+
+```ts
+// Obtener todos los logs de nivel ERROR o superior
+const errors = await logger.getLogs({
+  levelMin: LogLevel.ERROR,
+});
+
+// Filtrar por rango de fechas
+const yesterday = Date.now() - 24 * 60 * 60 * 1000;
+const recentLogs = await logger.getLogs({
+  since: yesterday,
+  until: Date.now(),
+});
+
+// Búsqueda por texto
+const userLogs = await logger.getLogs({
+  query: "usuario",
+  limit: 50,
+});
+```
+
+### Filtros Avanzados
+
+```ts
+// Combinación de filtros
+const criticalRecentErrors = await logger.getLogs({
+  levelMin: LogLevel.ERROR,
+  since: Date.now() - 2 * 60 * 60 * 1000, // Últimas 2 horas
+  query: "database connection",
+  limit: 20,
+  offset: 0,
+});
+
+// Paginación
+const page1 = await logger.getLogs({ limit: 10, offset: 0 });
+const page2 = await logger.getLogs({ limit: 10, offset: 10 });
+```
+
+## Variables de Entorno
+
+```bash
+# Nivel mínimo de logs
+LOG_LEVEL=info
+
+# Filesystem
+LOG_FS_ENABLED=true
+LOG_FS_PATH=./logs
+
+# MongoDB (si usas @jmlq/logger-plugin-mongo)
+LOG_MONGO_ENABLED=true
+LOG_MONGO_URL=mongodb://localhost:27017
+LOG_MONGO_DB=logs
+
+# PostgreSQL (si usas @jmlq/logger-plugin-postgresql)
+LOG_PG_ENABLED=true
+LOG_PG_HOST=localhost
+LOG_PG_PORT=5432
+LOG_PG_DATABASE=logs
+LOG_PG_USERNAME=logger
+LOG_PG_PASSWORD=secret
+```
+
+## Ejemplo Completo
+
+```ts
+import { LoggerFactory, LogLevel } from "@jmlq/logger";
+
+// Configuración completa
+const logger = await LoggerFactory.create({
+  datasources: [
+    // Múltiples datasources
+    new FileSystemDatasource({ basePath: "./logs" }),
+    new MongoDatasource({ url: "mongodb://localhost:27017", dbName: "logs" }),
+  ],
+  minLevel: LogLevel.DEBUG,
+  redactorOptions: {
+    enabled: true,
+    deep: true,
+    includeDefaults: true,
+    patterns: [
+      {
+        pattern: "\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b",
+        replaceWith: "****-****-****-****",
+      },
+    ],
+  },
+});
+
+// Uso con diferentes niveles
+await logger.debug("Debug info", { userId: 123 });
+await logger.info("User login", { email: "user@example.com" });
+await logger.warn("High latency", { endpoint: "/api/users", duration: 950 });
+await logger.error("Database error", { error: "Connection timeout" });
+await logger.fatal("System crash", { stack: error.stack });
+
+// Filtrar y consultar logs
+const recentErrors = await logger.getLogs({
+  levelMin: LogLevel.ERROR,
+  since: Date.now() - 24 * 60 * 60 * 1000,
+  limit: 100,
+});
+
+// Limpiar buffers (útil antes de cerrar la aplicación)
+await logger.flush();
+```
+
+## Plugins Disponibles
+
+> - `@jmlq/logger-plugin-fs`: Persistencia en archivos
+> - `@jmlq/logger-plugin-mongo`: Persistencia en MongoDB
+> - `@jmlq/logger-plugin-postgresql`: Persistencia en PostgreSQL
+
+Cada plugin se instala por separado según las necesidades de tu aplicación.
+
+## Consideraciones de Rendimiento
+
+Los logs se procesan de forma asíncrona
+Múltiples datasources escriben en paralelo
+Usa [flush()](./examples/logger-factory.example.ts) antes de cerrar la aplicación para asegurar que todos los logs se persistan
+Configura límites apropiados en las consultas para evitar sobrecarga de memoria

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jmlq/logger",
   "description": "logger package with clean architecture",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0-alpha.9",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -35,6 +35,8 @@
     "typescript": "^5.2.2"
   },
   "files": [
-    "dist"
+    "dist",
+    "architecture.md",
+    "install.md"
   ]
 }