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

package/README.md

@@ -0,0 +1,347 @@
+# @jmlq/logger
+
+Paquete de `logging` extensible y desacoplado, diseñado con principios de Arquitectura Limpia.
+Permite registrar logs en múltiples destinos (`archivos`, `MongoDB`, `PostgreSQL`) mediante **plugins** y soporta enmascarado de datos sensibles (PII).
+
+---
+
+## 📦 Instalación
+
+```bash
+# Instalar el core
+npm i @jmlq/logger
+
+# Instalar plugins opcionales según el backend de persistencia
+npm i @jmlq/logger-plugin-fs
+npm i @jmlq/logger-plugin-mongo
+npm i @jmlq/logger-plugin-postgres
+
+```
+
+### DOCUMENTACION
+
+> - [`@jmlq/logger-plugin-fs`](https://www.npmjs.com/package/@jmlq/logger-plugin-fs)
+> - [`@jmlq/logger-plugin-mongo`](https://www.npmjs.com/package/@jmlq/logger-plugin-mongo)
+> - [`@jmlq/logger-plugin-postgres`](https://www.npmjs.com/package/@jmlq/logger-plugin-postgres)
+
+---
+
+## 🧱 Estructura del paquete
+
+```txt
+src/
+  composite/
+    index.ts        # Implementa CompositeDatasource para fan-out de logs a múltiples destinos
+  config/
+    interfaces/
+      index.ts      # Define contratos/puertos (ILogDatasource, ILogRepository)
+    types/
+      index.ts      # Tipos y utilidades comunes (filtros de logs, opciones de logger, etc.)
+  domain/
+    services/
+      index.ts      # Servicio PiiRedactor: enmascara datos sensibles
+  presentation/
+    factory/
+      index.ts      # Factory createLogger: construye la API final del logger
+  index.ts          # Punto de entrada que re-exporta contratos, utilidades y createLogger
+
+```
+
+## 📝 Resumen rápido
+
+> - **composite** → Combinación de múltiples datasources para persistir en paralelo.
+> - **config/interfaces** → Contratos base (ILogDatasource) que los plugins deben implementar.
+> - **config/types** → Tipos auxiliares (`LogLevel`, `GetLogsFilter`, etc.).
+> - **domain/services** → Lógica de dominio (PII redaction).
+> - **presentation/factory** → `createLogger`, expone la API (`trace`, `debug`, `info`, `warn`, `error`, `fatal`).
+> - **index.ts** → Punto de entrada limpio para el consumidor.
+
+---
+
+## 🧩 Configuración
+
+### 🔐 Variables de Entorno (.env)
+
+```ini
+# --- MongoDB ---
+MONGO_URL=mongodb://<usuario>:<password>@localhost:27017
+# Dirección de conexión a MongoDB (usuario/contraseña opcionales)
+MONGO_DB_NAME=my_database
+# Nombre de la base de datos donde se guardarán los logs
+
+
+# --- PostgreSQL ---
+POSTGRES_URL=postgresql://<usuario>:<password>@localhost:5432/my_database
+# URL de conexión a la base de datos principal
+POSTGRES_DB=my_database
+# Credenciales y nombre de la base de datos
+
+# --- FileSystem ---
+LOGGER_FS_PATH=./logs/app.log
+# Ruta local donde se almacenarán los logs en formato JSONL
+
+# --- Nivel de logging ---
+LOGGER_LEVEL=debug
+# Nivel mínimo de logs por entorno (dev: debug, prod: warn)
+
+# --- PII (enmascarado de datos sensibles) ---
+LOGGER_PII_ENABLED=true
+# Activa/desactiva el redactor de datos sensibles
+
+LOGGER_PII_INCLUDE_DEFAULTS=true
+# Incluye los patrones de PII por defecto además de los definidos por el cliente
+
+```
+
+---
+
+### 🚀 Uso del paquete
+
+El cliente (la aplicación que usa `@jmlq/logger`) es responsable de inicializar el logger, ensamblar los **datasources** (`FS`, `Mongo`, `Postgres`) y configurar el **redactor de PII**.
+
+#### 1) Configuración de `pii.ts`
+
+Se definen los patrones propios de la aplicación para enmascarar datos sensibles.
+Estos se combinan con los patrones por defecto del core (`LOGGER_PII_INCLUDE_DEFAULTS=true`).
+
+```ts
+// src/config/logger/pii.ts
+
+import type { IPiiPattern } from "@jmlq/logger";
+
+// Patrones PII propios del cliente
+export const clientPiiPatterns: IPiiPattern[] = [
+  {
+    // Ejemplo: cédula ecuatoriana (10 dígitos con validaciones)
+    regex: /\b\d{10}\b/g,
+    replacement: "[REDACTED_CEDULA]",
+  },
+  {
+    // Ejemplo: token JWT simulado
+    regex: /\beyJ[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\b/g,
+    replacement: "[REDACTED_JWT]",
+  },
+];
+
+// Claves a redactar siempre (aunque no hagan match con regex)
+export const redactKeys = ["password", "secret", "token"];
+
+// Claves a preservar (no se enmascaran aunque coincidan con regex)
+export const preserveKeys = ["city"];
+```
+
+#### 2) Inicialización de `logger/index.ts`
+
+El logger se ensambla en un archivo central, cargando variables de entorno y adaptadores según disponibilidad:
+
+```tsx
+// src/config/logger/index.ts
+
+// Importa las funciones y tipos principales del core del logger
+import { createLogger, LogLevel, CompositeDatasource } from "@jmlq/logger";
+
+// Importa los plugins disponibles para persistencia de logs
+import { FileSystemDatasource } from "@jmlq/logger-plugin-fs";
+import { MongoDatasource } from "@jmlq/logger-plugin-mongo";
+import {
+  connectPostgres,
+  ensurePostgresSchema,
+  PostgresDatasource,
+} from "@jmlq/logger-plugin-postgres";
+
+// Configuración cargada desde variables de entorno (env-var + dotenv)
+import { envs } from "../plugins/envs.plugin";
+
+// Patrones propios de PII definidos en src/config/logger/pii.ts
+import { clientPiiPatterns, redactKeys, preserveKeys } from "./pii";
+
+// Utilidades de Node.js para manejo de directorios y archivos
+import { mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+
+// Cliente oficial de MongoDB
+import { MongoClient } from "mongodb";
+
+// Se mantiene una referencia global al cliente de MongoDB para cerrarlo en dispose
+let mongoClient: MongoClient | null = null;
+
+// Convierte un string (ej. "debug") al enum LogLevel
+function toMinLevel(level: string): LogLevel {
+  switch (level.toLowerCase()) {
+    case "trace":
+      return LogLevel.TRACE;
+    case "debug":
+      return LogLevel.DEBUG;
+    case "info":
+      return LogLevel.INFO;
+    case "warn":
+      return LogLevel.WARN;
+    case "error":
+      return LogLevel.ERROR;
+    case "fatal":
+      return LogLevel.FATAL;
+    default:
+      return LogLevel.INFO; // Valor por defecto
+  }
+}
+
+// Asegura que exista el directorio de logs para el datasource de FileSystem
+function ensureDirFor(filePath: string) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+// Inicializa el logger ensamblando los datasources configurados en .env
+async function initLogger() {
+  const datasources = [];
+
+  // --- FileSystem ---
+  // Si está definido LOGGER_FS_PATH, se usa un datasource local de archivos
+  if (envs.logger.LOGGER_FS_PATH) {
+    ensureDirFor(envs.logger.LOGGER_FS_PATH);
+    datasources.push(
+      new FileSystemDatasource({ filePath: envs.logger.LOGGER_FS_PATH })
+    );
+  }
+
+  // --- MongoDB ---
+  // Si están configurados MONGO_URL y MONGO_DB_NAME, se conecta y usa la colección logs
+  if (envs.logger.MONGO_URL && envs.logger.MONGO_DB_NAME) {
+    mongoClient = new MongoClient(envs.logger.MONGO_URL);
+    await mongoClient.connect();
+    const coll = mongoClient.db(envs.logger.MONGO_DB_NAME).collection("logs");
+    datasources.push(new MongoDatasource(coll));
+  }
+
+  // --- PostgreSQL ---
+  // Si está configurado POSTGRES_URL, se conecta, asegura la tabla y crea el datasource
+  if (envs.logger.POSTGRES_URL) {
+    await connectPostgres(envs.logger.POSTGRES_URL);
+    await ensurePostgresSchema();
+    datasources.push(new PostgresDatasource("logs"));
+  }
+
+  // Si hay más de un datasource, se compone con CompositeDatasource (fan-out)
+  const datasource =
+    datasources.length === 1
+      ? datasources[0]
+      : new CompositeDatasource(datasources);
+
+  // Crea y retorna el logger con nivel mínimo y configuración de PII
+  return createLogger(datasource, {
+    minLevel: toMinLevel(envs.logger.LOGGER_LEVEL),
+    pii: {
+      enabled: envs.logger.LOGGER_PII_ENABLED,
+      includeDefaultPatterns: envs.logger.LOGGER_PII_INCLUDE_DEFAULTS,
+      patterns: clientPiiPatterns,
+      redactKeys,
+      preserveKeys,
+    },
+  });
+}
+
+// Exporta el logger como una Promise porque la inicialización es async
+export const loggerReady = initLogger();
+
+// --- Funciones de utilidad ---
+
+// Fuerza un flush() de todos los datasources, útil para apagar servicios con logs pendientes
+export async function flushLogs() {
+  const logger: any = await loggerReady;
+  if (typeof logger.flush === "function") await logger.flush();
+}
+
+// Cierra conexiones abiertas (ej. MongoClient) y libera recursos
+export async function disposeLogs() {
+  const logger: any = await loggerReady;
+  if (typeof logger.dispose === "function") await logger.dispose();
+  if (mongoClient) await mongoClient.close();
+}
+```
+
+#### 3) Uso desde cualquier aplicación Node.js
+
+En cualquier parte de la app se puede usar el logger así:
+
+```ts
+import { loggerReady } from "./config/logger";
+
+async function main() {
+  const logger = await loggerReady;
+
+  await logger.info("Aplicación iniciada", { pid: process.pid });
+
+  await logger.error("Error en proceso", {
+    password: "123456", // será redactado
+    city: "Quito", // se preserva
+  });
+}
+
+main();
+```
+
+### 📦 Dependencias adicionales en el cliente
+
+```bash
+# Si se va a usar MongoDB
+npm i mongodb@^6.19.0
+
+# Si se va a usar PostgreSQL
+npm i pg@^8.16.3
+
+```
+
+`mongodb` y `pg` son **peerDependencies**: `@jmlq/logger` no las instala por sí mismo para mantener el core desacoplado.
+
+### 🔎 Notas importantes
+
+> - `loggerReady` es una Promise → debe resolverse con `await`.
+> - `flushLogs()` y `disposeLogs()` deben usarse en procesos que cierran conexiones (ej. `SIGINT`, `SIGTERM`).
+> - Los patrones definidos en `pii.ts` se combinan con los patrones por defecto cuando `LOGGER_PII_INCLUDE_DEFAULTS=true`.
+> - El logger puede trabajar con **un único datasource** o con **CompositeDatasource** para múltiples.
+
+---
+
+### 🧪 Escenarios
+
+> - **Solo FS** → logs locales en `./logs/app.log`.
+> - **Solo MongoDB** → logs en colección `logs`.
+> - **Solo PostgreSQL** → logs en tabla `logs`.
+> - **Combinado** → fan-out a varios destinos simultáneamente.
+> - **Extensión** → implementar `ILogDatasource`.
+
+---
+
+## 🧯 Troubleshooting
+
+> - **No se inicializa ningún datasource** → definir al menos una variable (`LOGGER_FS_PATH`, `MONGO_URL`, `POSTGRES_URL`).
+> - **MongoDB Auth** → incluir `authSource=admin` en la URL si se usan usuarios root.
+> - **Postgres** → ejecutar `ensurePostgresSchema()` para crear tabla logs si no existe.
+> - **Alto volumen de logs** → implementar `flush()` o batching en el datasource.
+
+---
+
+## 🧪 Tests
+
+```ts
+import { createLogger, LogLevel } from "@jmlq/logger";
+import { FileSystemDatasource } from "@jmlq/logger-plugin-fs";
+
+test("logger redacta PII en FS", async () => {
+  const fsDs = new FileSystemDatasource({ filePath: "./logs/test.log" });
+  const logger = createLogger(fsDs, {
+    minLevel: LogLevel.DEBUG,
+    pii: { enabled: true },
+  });
+
+  await logger.info("Inicio de sesión", { user: "demo", password: "123456" });
+
+  // Luego verificar que el archivo test.log no contiene la contraseña en claro
+});
+```
+
+---
+
+## 📄 Licencia
+
+MIT © Mauricio Lahuasi

package/dist/Composite/index.js

@@ -7,17 +7,48 @@ class CompositeDatasource {
         this.datasources = datasources;
     }
     async save(log) {
-        await Promise.allSettled(this.datasources.map((ds) => ds.save(log)));
+        const results = await Promise.allSettled(this.datasources.map((ds) => ds.save(log)));
+        for (const r of results) {
+            if (r.status === "rejected") {
+                // Evita romper el flujo si un destino falla.
+                // Aquí podrías enrutar a "dead-letter", métricas, etc.
+                // eslint-disable-next-line no-console
+                console.warn("[CompositeDatasource] save failed:", r.reason);
+            }
+        }
     }
     async find(filter = {}) {
-        const primary = this.datasources[0];
-        return (await primary?.find?.(filter)) ?? [];
+        for (const ds of this.datasources) {
+            if (typeof ds.find === "function") {
+                try {
+                    return await ds.find(filter);
+                }
+                catch (e) {
+                    // eslint-disable-next-line no-console
+                    console.warn("[CompositeDatasource] find failed on a datasource:", e);
+                    // probar siguiente datasource
+                }
+            }
+        }
+        return [];
     }
     async flush() {
-        await Promise.all(this.datasources.map((ds) => ds.flush?.() ?? Promise.resolve()));
+        const results = await Promise.allSettled(this.datasources.map((ds) => ds.flush?.() ?? Promise.resolve()));
+        for (const r of results) {
+            if (r.status === "rejected") {
+                // eslint-disable-next-line no-console
+                console.warn("[CompositeDatasource] flush failed:", r.reason);
+            }
+        }
     }
     async dispose() {
-        await Promise.all(this.datasources.map((ds) => ds.dispose?.() ?? Promise.resolve()));
+        const results = await Promise.allSettled(this.datasources.map((ds) => ds.dispose?.() ?? Promise.resolve()));
+        for (const r of results) {
+            if (r.status === "rejected") {
+                // eslint-disable-next-line no-console
+                console.warn("[CompositeDatasource] dispose failed:", r.reason);
+            }
+        }
     }
 }
 exports.CompositeDatasource = CompositeDatasource;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmlq/logger",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "author": "MLahuasi",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",