@jmlq/logger 0.1.0-alpha.1 → 0.1.0-alpha.11

package/README.md

@@ -0,0 +1,307 @@
+# @jmlq/logger
+
+Sistema de logging modular y extensible con **Arquitectura Limpia**. Soporta múltiples destinos (archivos, MongoDB, PostgreSQL) y enmascarado automático de datos sensibles (PII).
+
+## 📦 Instalación
+
+```bash
+# Core del logger
+npm install @jmlq/logger
+
+# Plugins opcionales (instala según necesites)
+npm install @jmlq/logger-plugin-fs        # Para archivos
+npm install @jmlq/logger-plugin-mongo     # Para MongoDB
+npm install @jmlq/logger-plugin-postgresql # Para PostgreSQL
+```
+
+## 🚀 Uso Básico
+
+### Configuración Simple
+
+```typescript
+import { LoggerFactory, LogLevel } from "@jmlq/logger";
+
+// Crear un datasource en memoria (para testing/desarrollo)
+const memoryDatasource = {
+  name: "memory",
+  async save(log) {
+    console.log("LOG:", log);
+  },
+  async find(filter) {
+    return [];
+  },
+  async flush() {},
+  async dispose() {},
+};
+
+// Crear el logger
+const logger = LoggerFactory.create({
+  datasources: memoryDatasource,
+  minLevel: LogLevel.INFO,
+  redactorOptions: {
+    enabled: true,
+    deep: true,
+    includeDefaults: true,
+  },
+});
+
+// Usar el logger
+await logger.info("Usuario conectado", {
+  userId: "123",
+  email: "user@example.com",
+});
+await logger.error("Error en el sistema", {
+  error: "Database connection failed",
+});
+```
+
+### Con Múltiples Datasources
+
+```typescript
+import { LoggerFactory } from "@jmlq/logger";
+import { FileSystemDatasource } from "@jmlq/logger-plugin-fs";
+import { MongoDatasource } from "@jmlq/logger-plugin-mongo";
+
+const logger = LoggerFactory.create({
+  datasources: [
+    new FileSystemDatasource({ basePath: "./logs" }),
+    new MongoDatasource({ url: "mongodb://localhost:27017", dbName: "logs" }),
+  ],
+  minLevel: LogLevel.INFO,
+});
+
+await logger.warn("Latencia alta", { endpoint: "/api/users", duration: 850 });
+```
+
+## 🎯 Características Principales
+
+### Niveles de Log
+
+- `TRACE` (0) - Información muy detallada
+- `DEBUG` (1) - Información de depuración
+- `INFO` (2) - Información general
+- `WARN` (3) - Advertencias
+- `ERROR` (4) - Errores
+- `FATAL` (5) - Errores críticos
+
+### Enmascarado PII Automático
+
+El logger detecta y enmascara automáticamente datos sensibles:
+
+```typescript
+await logger.info("Pago procesado", {
+  email: "user@example.com", // → user@[EMAIL]
+  card: "4111-1111-1111-1111", // → ****-****-****-****
+  password: "secret123", // → [REDACTED]
+});
+```
+
+### Filtros y Consultas
+
+```typescript
+// Obtener logs de errores de las últimas 24 horas
+const errors = await logger.getLogs({
+  levelMin: LogLevel.ERROR,
+  since: Date.now() - 24 * 60 * 60 * 1000,
+  limit: 50,
+});
+
+// Buscar logs que contengan "usuario"
+const userLogs = await logger.getLogs({
+  query: "usuario",
+  limit: 100,
+});
+```
+
+## 🔧 Configuración con Variables de Entorno
+
+```env
+# Nivel mínimo de logs
+LOG_LEVEL=info
+
+# Filesystem
+LOGGER_FS_PATH=./logs
+
+# MongoDB
+MONGO_URL=mongodb://localhost:27017
+MONGO_DB_NAME=logs
+
+# PostgreSQL
+POSTGRES_URL=postgresql://user:pass@localhost:5432/logs
+
+# PII Protection
+LOGGER_PII_ENABLED=true
+```
+
+## 📁 Ejemplos Prácticos
+
+El proyecto incluye ejemplos completos en el directorio [`examples/`](examples/):
+
+```bash
+# Ver todos los ejemplos disponibles
+npm run example:help
+
+# Ejecutar ejemplos específicos
+npm run example:factories      # LoggerFactory
+npm run example:use-cases     # SaveLog, GetLogs, FlushBuffers
+npm run example:domain-services # PII, normalización
+npm run example:all           # Todos los ejemplos
+```
+
+### Ejemplo Express
+
+```typescript
+import express from "express";
+import { LoggerFactory, LogLevel } from "@jmlq/logger";
+
+const app = express();
+const logger = LoggerFactory.create({
+  datasources: /* tu datasource */,
+  minLevel: LogLevel.INFO
+});
+
+app.use(async (req, res, next) => {
+  await logger.info("Request iniciado", {
+    method: req.method,
+    url: req.url,
+    ip: req.ip
+  });
+  next();
+});
+
+app.get("/users/:id", async (req, res) => {
+  try {
+    await logger.info("Obteniendo usuario", { userId: req.params.id });
+    // ... tu lógica
+    res.json({ user: data });
+  } catch (error) {
+    await logger.error("Error al obtener usuario", {
+      userId: req.params.id,
+      error: error.message
+    });
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+```
+
+### Ejemplo NestJS
+
+```typescript
+@Injectable()
+export class AppService {
+  constructor(@Inject("LOGGER") private readonly logger: ILoggerService) {}
+
+  async createUser(userData: any) {
+    await this.logger.info("Creando usuario", { userData });
+    try {
+      // ... lógica
+      await this.logger.info("Usuario creado", { userId: result.id });
+      return result;
+    } catch (error) {
+      await this.logger.error("Error creando usuario", {
+        error: error.message,
+      });
+      throw error;
+    }
+  }
+}
+```
+
+## 🏗️ Arquitectura
+
+El paquete sigue **Arquitectura Limpia**:
+
+```
+src/
+├─ domain/           # Reglas de negocio puras
+│  ├─ entities/
+│  ├─ value-objects/ # LogLevel
+│  ├─ services/      # PiiRedactor, MessageNormalizer
+│  ├─ ports/         # Interfaces/contratos
+│  └─ types/
+├─ application/      # Casos de uso
+│  ├─ use-cases/     # SaveLog, GetLogs, FlushBuffers
+│  └─ factory/       # LoggerFactory
+└─ infrastructure/   # Implementaciones concretas
+   └─ services/      # DataSourceService (composite)
+```
+
+### Casos de Uso Principales
+
+- **[`SaveLogUseCase`](src/application/use-cases/save-log.use-case.ts)** - Guarda logs aplicando filtros de nivel y PII
+- **[`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 datasources
+
+### Servicios de Dominio
+
+- **[`PiiRedactor`](src/domain/services/pii-redactor.service.ts)** - Enmascara datos sensibles
+- **[`MessageNormalizer`](src/domain/services/message-normalizer.service.ts)** - Normaliza mensajes de log
+- **[`LogLevelService`](src/domain/services/log-level.service.ts)** - Maneja niveles de log
+
+## 🔌 Plugins Disponibles
+
+| Plugin                           | Descripción                | NPM                                                             |
+| -------------------------------- | -------------------------- | --------------------------------------------------------------- |
+| `@jmlq/logger-plugin-fs`         | Persistencia en archivos   | [npm](https://npmjs.com/package/@jmlq/logger-plugin-fs)         |
+| `@jmlq/logger-plugin-mongo`      | Persistencia en MongoDB    | [npm](https://npmjs.com/package/@jmlq/logger-plugin-mongo)      |
+| `@jmlq/logger-plugin-postgresql` | Persistencia en PostgreSQL | [npm](https://npmjs.com/package/@jmlq/logger-plugin-postgresql) |
+
+## 🧪 Testing
+
+```typescript
+import { LoggerFactory, LogLevel } from "@jmlq/logger";
+
+describe("Logger Tests", () => {
+  it("debe enmascarar PII correctamente", async () => {
+    const logs: any[] = [];
+    const mockDatasource = {
+      name: "mock",
+      async save(log: any) {
+        logs.push(log);
+      },
+      async find() {
+        return [];
+      },
+      async flush() {},
+      async dispose() {},
+    };
+
+    const logger = LoggerFactory.create({
+      datasources: mockDatasource,
+      redactorOptions: { enabled: true },
+    });
+
+    await logger.info("Usuario: user@example.com");
+
+    expect(logs[0].message).not.toContain("user@example.com");
+    expect(logs[0].message).toContain("[EMAIL]");
+  });
+});
+```
+
+## 🚨 Troubleshooting
+
+**Error: No datasources válidos**
+
+- Asegúrate de configurar al menos un datasource
+- Verifica las variables de entorno
+
+**MongoDB no conecta**
+
+- Verifica la URL de conexión
+- Incluye `authSource=admin` si usas usuarios root
+
+**Alto uso de memoria**
+
+- Implementa límites en las consultas
+- Usa `flush()` periódicamente para vaciar buffers
+
+## 📄 Más Información
+
+- **[Arquitectura Detallada](./architecture.md)** - Documentación técnica completa
+- **[Guía de Instalación](./install.md)** - Configuración paso a paso
+- **[Ejemplos](./examples/)** - Códigos de ejemplo funcionales
+
+## 📝 Licencia
+
+MIT © Mauricio Lahuasi

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/dist/examples/data-source-service.example.d.ts

@@ -0,0 +1,3 @@
+export declare class DataSourceServiceExample {
+    static Main(): Promise<void>;
+}

package/dist/examples/data-source-service.example.js

@@ -0,0 +1,174 @@
+"use strict";
+// ============================================================================
+// 🧩 Ejemplo realista de cómo un cliente podría integrar DataSourceService
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataSourceServiceExample = void 0;
+const src_1 = require("src");
+const infrastructure_1 = require("src/infrastructure");
+/**
+ * InMemoryLogDatasource
+ *
+ * Implementación simple de ILogDatasource que almacena los logs en memoria.
+ * Útil para:
+ *  - Tests
+ *  - Ejemplos / demos
+ *  - Entornos de desarrollo
+ */
+class InMemoryLogDatasource {
+    constructor() {
+        this.name = "in-memory";
+        this.logs = [];
+    }
+    /**
+     * Guarda un log en memoria.
+     * No aplica lógica especial, solo hace push al arreglo interno.
+     */
+    async save(log) {
+        // Suponemos que ILogResponse es compatible con ILogProps.
+        // Si en tu dominio ILogResponse tiene campos extra (ej: id),
+        // aquí podrías generarlos.
+        this.logs.push(log);
+    }
+    /**
+     * Devuelve los logs almacenados en memoria.
+     * Por simplicidad, se ignora el filtro. Puedes adaptar esta parte cuando
+     * tengas definido el shape completo de IGetLogsFilterProps.
+     */
+    async find(_filter) {
+        // Retornamos una copia para evitar mutación externa.
+        return [...this.logs];
+    }
+    /**
+     * Limpia todos los logs almacenados.
+     */
+    async flush() {
+        this.logs.length = 0;
+    }
+    /**
+     * Libera recursos.
+     * En este caso es equivalente a flush(), pero queda listo
+     * por si en el futuro necesitas lógica adicional.
+     */
+    async dispose() {
+        await this.flush();
+    }
+}
+/**
+ * AppLoggerService
+ *
+ * Servicio de logging de la aplicación que:
+ * - Usa DataSourceService (composite) debajo.
+ * - Configura múltiples datasources.
+ * - Centraliza el manejo de errores del logger vía errorHandler.
+ */
+class AppLoggerService {
+    constructor() {
+        // 1️⃣ Definimos los datasources que usará la app
+        const datasources = [
+            new InMemoryLogDatasource(), // para debugging / tests / fallback
+            new HttpLogDatasource(// datasource custom del cliente
+            process.env.LOG_API_URL ?? "https://logs.my-api.com/events"),
+        ];
+        // 2️⃣ Definimos un error handler centralizado para errores del logger
+        const errorHandler = (info) => {
+            // Aquí el cliente podría usar su propio logger de infra (pino, winston, etc).
+            // En este ejemplo usamos console.error por simplicidad.
+            // IMPORTANTE: este logger NO debe depender de @jmlq/logger para evitar ciclos.
+            console.error("[AppLoggerService] Error en datasource de logger", {
+                op: info.operation,
+                datasource: info.datasourceName,
+                error: info.reason,
+            });
+        };
+        // 3️⃣ Creamos el DataSourceService composite con los datasources y el handler
+        this.dataSourceService = new infrastructure_1.DataSourceService(datasources, errorHandler);
+    }
+    // ----------------------------------------------------------------------------
+    // API pública del logger de la app (lo que realmente usa el cliente)
+    // ----------------------------------------------------------------------------
+    async info(message, meta) {
+        await this.log(src_1.LogLevel.INFO, message, meta);
+    }
+    async warn(message, meta) {
+        await this.log(src_1.LogLevel.WARN, message, meta);
+    }
+    async error(message, meta) {
+        await this.log(src_1.LogLevel.ERROR, message, meta);
+    }
+    async debug(message, meta) {
+        await this.log(src_1.LogLevel.DEBUG, message, meta);
+    }
+    async log(level, message, meta) {
+        const log = {
+            level,
+            message,
+            timestamp: Date.now(),
+            meta,
+        };
+        await this.dataSourceService.save(log);
+    }
+    /**
+     * Métodos opcionales para flush/dispose (por ejemplo, en shutdown de la app).
+     */
+    async flush() {
+        await this.dataSourceService.flush();
+    }
+    async dispose() {
+        await this.dataSourceService.dispose();
+    }
+}
+// ============================================================================
+// 🌐 Ejemplo de datasource HTTP implementado por el cliente
+//    (no forma parte del core, lo crea el consumidor usando ILogDatasource)
+// ============================================================================
+class HttpLogDatasource {
+    constructor(endpoint) {
+        this.endpoint = endpoint;
+        this.name = "http";
+    }
+    async save(log) {
+        // Aquí el cliente puede usar fetch, axios, got, etc.
+        // Lo dejamos como pseudo-código para no acoplar dependencias reales.
+        const body = JSON.stringify(log);
+        await fetch(this.endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+        });
+    }
+}
+// ============================================================================
+// 🚀 Example runner: cómo el cliente lo usaría en su app
+// ============================================================================
+class DataSourceServiceExample {
+    static async Main() {
+        console.log("=== 🧩 Ejemplo REAL de uso: AppLoggerService sobre DataSourceService ===\n");
+        // 1️⃣ Crear instancia de logger de aplicación
+        const logger = new AppLoggerService();
+        // 2️⃣ Loguear eventos típicos de una app
+        console.log("📝 Enviando logs de ejemplo...\n");
+        await logger.info("Servidor iniciado", {
+            port: 3000,
+            env: process.env.NODE_ENV ?? "development",
+        });
+        await logger.info("Usuario autenticado", {
+            userId: "12345",
+            method: "password",
+        });
+        await logger.error("Error al procesar pedido", {
+            orderId: "ORD-999",
+            reason: "Stock insuficiente",
+        });
+        await logger.warn("Latencia alta detectada en /payments", {
+            p95_ms: 850,
+        });
+        console.log("✅ Logs enviados. Si algún datasource falla, el error handler los captura.\n");
+        // 3️⃣ Ejemplo de uso en shutdown de la app
+        console.log("🧹 Realizando flush() y dispose() del logger...\n");
+        await logger.flush();
+        await logger.dispose();
+        console.log("🏁 Ejemplo real completado.\n");
+    }
+}
+exports.DataSourceServiceExample = DataSourceServiceExample;

package/dist/examples/flush-buffers-use-case.example.d.ts

@@ -0,0 +1,3 @@
+export declare class FlushBuffersUseCaseExample {
+    static Main(): Promise<void>;
+}