@jmlq/logger 0.1.0-alpha.2 → 0.1.0-alpha.4

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
+
+```
+
+Si usas Mongo o Postgres en tu app cliente, instala además:
+
+```bash
+npm i mongodb@^6.19.0
+npm i pg@^8.16.3
+
+```
+
+### 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
+
+### 📝 Resumen rápido
+
+> - **`src/domain/`** — Reglas del negocio (sin dependencias de frameworks).
+>   > - **`value-objects/`**
+>   >   > - `log-level.ts` — Define niveles (`TRACE…FATAL`) y `toLogLevel()` para convertir strings a nivel.
+>   > - **`types/`**
+>   >   > - `log.types.ts` — Tipos puros del dominio: `ILog`, `IGetLogsFilter`, `PiiOptions`, etc.
+>   > - **`contracts/`**
+>   >   > - `log.datasource.ts` — Puerto que debe implementar cualquier destino de logs (`save/find/flush/dispose`).
+>   >   > - `logger.ts` — Contrato del logger público (`ILogger`, `ICreateLoggerOptions`).
+>   >   > - `pii.ts` — Contrato del redactor de PII.
+>   > - **`services/`**
+>   >   > - `pii-redactor.ts` — Enmascarado de datos sensibles (whitelist/blacklist, patrones, modo profundo).
+
+> - **`src/application/`** — Orquestación de casos de uso (no depende de infraestructura).
+>   > - **`use-cases/`**
+>   >   > - `save-log.ts` — Aplica `minLevel` + PII y delega a `datasource.save()`.
+>   >   > - `get-logs.ts` — Recupera logs con filtros/paginación si el datasource lo soporta.
+>   >   > - `flush-buffers.ts` — Ejecuta `flush()` en el datasource cuando exista.
+
+> - **`src/infrastructure/`** — Adaptadores concretos (tecnología).
+>   > - **`adapters/`**
+>   >   > - `composite.datasource.ts` — Fan-out: envía el log a varios datasources y no falla el todo si uno cae (avisa con `console.warn`).
+
+> - **`src/presentation/`** — API pública y fábricas (cara del paquete).
+>   > - **`factory/`**
+>   >   > - `create-logger.ts` — Crea el logger listo para usar (`trace…fatal`, `flush`, `dispose`) conectando casos de uso + PII.
+
+> - **`src/index.ts`** — Barrel.
+>   > - Re-exporta lo público: `createLogger`, `LogLevel`, tipos/contratos y `CompositeDatasource`.
+
+### [](./ARQUITECTURA.md)
+
+---
+
+## 🧩 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();
+```
+
+### 🔎 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/application/use-cases/flush-buffers.d.ts

@@ -0,0 +1,6 @@
+import { ILogDatasource } from "../../domain/contracts";
+export declare class FlushBuffers {
+    private readonly ds;
+    constructor(ds: ILogDatasource);
+    execute(): Promise<void>;
+}

package/dist/application/use-cases/flush-buffers.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlushBuffers = void 0;
+class FlushBuffers {
+    constructor(ds) {
+        this.ds = ds;
+    }
+    async execute() {
+        // flush es opcional; si no está implementado, no hace nada
+        await this.ds.flush?.();
+    }
+}
+exports.FlushBuffers = FlushBuffers;

package/dist/application/use-cases/get-logs.d.ts

@@ -0,0 +1,7 @@
+import { ILogDatasource } from "../../domain/contracts";
+import { IGetLogsFilter, ILog } from "../../domain/types";
+export declare class GetLogs {
+    private readonly ds;
+    constructor(ds: ILogDatasource);
+    execute(filter?: IGetLogsFilter): Promise<ILog[]>;
+}

package/dist/application/use-cases/get-logs.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetLogs = void 0;
+class GetLogs {
+    constructor(ds) {
+        this.ds = ds;
+    }
+    async execute(filter) {
+        if (!this.ds.find)
+            return []; // si el datasource no lo soporta, retorna vacío
+        // Sanitiza límites (evita valores negativos o absurdos)
+        const safe = filter
+            ? {
+                ...filter,
+                limit: filter.limit && filter.limit > 0
+                    ? Math.min(filter.limit, 5000)
+                    : undefined,
+                offset: filter.offset && filter.offset >= 0 ? filter.offset : undefined,
+            }
+            : undefined;
+        return this.ds.find(safe);
+    }
+}
+exports.GetLogs = GetLogs;

package/dist/application/use-cases/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./save-log";
+export * from "./get-logs";
+export * from "./flush-buffers";

package/dist/application/use-cases/index.js

@@ -0,0 +1,19 @@
+"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("./save-log"), exports);
+__exportStar(require("./get-logs"), exports);
+__exportStar(require("./flush-buffers"), exports);

package/dist/application/use-cases/save-log.d.ts

@@ -0,0 +1,13 @@
+import { ILogDatasource, IPiiRedactor } from "../../domain/contracts";
+import { LogMessage } from "../../domain/types";
+import { LogLevel } from "../../domain/value-objects";
+export interface SaveLogDeps {
+    ds: ILogDatasource;
+    minLevel: LogLevel;
+    redactor: IPiiRedactor;
+}
+export declare class SaveLog {
+    private readonly deps;
+    constructor(deps: SaveLogDeps);
+    execute(level: LogLevel, message: LogMessage, meta?: unknown): Promise<void>;
+}

package/dist/application/use-cases/save-log.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SaveLog = void 0;
+// Normaliza el mensaje: si es función, la evalúa; si es objeto, se redacta; si es string, se redacta
+function normalizeMessage(message, redactor) {
+    const resolved = typeof message === "function" ? message() : message; // eval laziness
+    return redactor.redact(resolved);
+}
+class SaveLog {
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(level, message, meta) {
+        // 1) Filtro por nivel (evita hacer trabajo innecesario)
+        if (level < this.deps.minLevel)
+            return; // no se loggea
+        // 2) Normalización + PII
+        const normalized = normalizeMessage(message, this.deps.redactor);
+        // 3) Construcción del evento
+        const log = {
+            level,
+            message: normalized,
+            meta: meta === undefined ? undefined : this.deps.redactor.redact(meta),
+            timestamp: Date.now(),
+        };
+        // 4) Persistencia (fan-out lo maneja el ds si es composite)
+        await this.deps.ds.save(log);
+    }
+}
+exports.SaveLog = SaveLog;

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

@@ -0,0 +1,3 @@
+export * from "./log.datasource";
+export * from "./logger";
+export * from "./pii";

package/dist/domain/contracts/index.js

@@ -0,0 +1,19 @@
+"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("./log.datasource"), exports);
+__exportStar(require("./logger"), exports);
+__exportStar(require("./pii"), exports);

package/dist/domain/contracts/log.datasource.d.ts

@@ -0,0 +1,8 @@
+import { IGetLogsFilter, ILog } from "../types";
+export interface ILogDatasource {
+    save(log: ILog): Promise<void>;
+    find?(filter?: IGetLogsFilter): Promise<ILog[]>;
+    flush?(): Promise<void>;
+    dispose?(): Promise<void>;
+    readonly name?: string;
+}

package/dist/{config/interfaces/index.js → domain/contracts/log.datasource.js}

@@ -1,3 +1,2 @@
 "use strict";
-// ---- Contratos ----
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/contracts/logger.d.ts

@@ -0,0 +1,19 @@
+import { ILogDatasource } from ".";
+import { PiiOptions } from "../types";
+import { LogLevel } from "../value-objects";
+export interface ICreateLoggerOptions {
+    minLevel?: LogLevel;
+    redactPII?: boolean;
+    pii?: PiiOptions;
+}
+export interface ILogger {
+    trace: (message: unknown, meta?: unknown) => void | Promise<void>;
+    debug: (message: unknown, meta?: unknown) => void | Promise<void>;
+    info: (message: unknown, meta?: unknown) => void | Promise<void>;
+    warn: (message: unknown, meta?: unknown) => void | Promise<void>;
+    error: (message: unknown, meta?: unknown) => void | Promise<void>;
+    fatal: (message: unknown, meta?: unknown) => void | Promise<void>;
+    flush?: () => Promise<void>;
+    dispose?: () => Promise<void>;
+}
+export type { ILogDatasource as LogDatasourcePort };

package/dist/domain/contracts/logger.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/contracts/pii.d.ts

@@ -0,0 +1,5 @@
+import { PiiOptions } from "../types";
+export interface IPiiRedactor {
+    redact<T = unknown>(value: T): T;
+    updateOptions?(opts: PiiOptions): void;
+}

package/dist/domain/contracts/pii.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/services/pii-redactor.d.ts

@@ -1,27 +1,10 @@
-/**
- * Domain Service: PiiRedactor
- *
- * Propósito:
- * - Redactar/anonimizar PII en strings, objetos y arrays (deep).
- * - Permitir que el cliente pase patrones adicionales/propios.
- * - Controlar redacción por nombre de clave (whitelist/blacklist).
- */
-import { IPiiPattern, IPiiRedactorOptions } from "../../config";
-export declare class PiiRedactor {
-    private readonly enabled;
-    private readonly patterns;
-    private readonly redactKeys;
-    private readonly preserveKeys;
-    constructor(opts?: IPiiRedactorOptions);
-    /** Patrones por defecto (seguros y genéricos). Ajusta según tu dominio/región si lo deseas. */
-    static defaultPatterns(): IPiiPattern[];
-    /** Punto de entrada público: redacción deep de cualquier estructura */
+import { IPiiRedactor } from "../contracts";
+import { PiiOptions } from "../types";
+export declare class PiiRedactor implements IPiiRedactor {
+    private options;
+    constructor(options?: PiiOptions);
+    updateOptions(opts: PiiOptions): void;
     redact<T = unknown>(value: T): T;
-    /** === Internos === */
-    private redactValue;
     private applyPatterns;
-    private isRedactedKey;
-    private isPreservedKey;
-    private keyRedactionReplacement;
-    private clone;
+    private redactDeep;
 }