@jmlq/logger 0.1.0-alpha.5 → 0.1.0-alpha.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 mlahuasi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -34,75 +34,33 @@ npm i pg@^8.16.3
 
 ---
 
-## 🧱 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`.
-
-### [LEER MAS](./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
+    # @jmlq/logger
+    # Nivel mínimo por entorno (dev: debug, prod: warn)
+    LOGGER_LEVEL=debug
+    # PII (Personally Identifiable Information)
+    LOGGER_PII_ENABLED=true
+    LOGGER_PII_INCLUDE_DEFAULTS=true
+
+    # MONGO DB @jmlq/logger-plugin-mongo
+    MONGO_URL=mongodb://<user>:<password>@localhost:<port>
+    MONGO_DB_NAME=<db-name>
+    MONGO_COLLECTION=<collection-name>
+    LOGGER_MONGO_RETENTION_DAYS=30
+
+    # POSTGRESQL  @jmlq/logger-plugin-postgresql
+    POSTGRES_URL="postgresql://mlahuasi:123456@localhost:5432/NOC"
+    POSTGRES_DB=<db-name>
+    POSTGRES_SCHEMA=public
+    POSTGRES_TABLE=<table-name>
+    LOGGER_PG_RETENTION_DAYS=30
+
+    # FILESYSTEM @jmlq/logger-plugin-fs
+    LOGGER_FS_PATH=./logs
 
 ```
 
@@ -110,77 +68,132 @@ LOGGER_PII_INCLUDE_DEFAULTS=true
 
 ### 🚀 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) Estructura recomendada
 
-#### 1) Configuración de `pii.ts`
+```
+src/
+├─ infrastructure/
+│  ├─ logger/
+│  │  ├─ adapters/
+│  │  │  ├─ fs.adapter.ts
+│  │  │  ├─ mongo.adapter.ts
+│  │  │  └─ postgresql.adapter.ts
+│  │  ├─ settings/
+│  │  │  ├─ pii.settings.ts
+│  │  │  └─ loglevel.settings.ts
+│  │  └─ bootstrap.ts            # LoggerBootstrap (orquesta adapters + PII)
+│  └─ plugins/
+│     ├─ env.plugin.ts
+│     └─ index.ts
+├─ config/
+│  └─ logger/
+│     └─ index.ts                # singleton global: loggerReady / flush / dispose
+└─ presentation/
+   └─ server.ts                  # uso del logger en Express
 
-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
+#### 2) Settings
 
-import type { IPiiPattern } from "@jmlq/logger";
+#### 2.1) pii.settings.ts (patrones PII + merge)
 
-// 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]",
-  },
+```ts
+//Se definine reglas de redacción PII (buscar-y-reemplazar con regex) que el logger aplica antes de persistir/emitir un log.
+
+export type PiiReplacement = {
+  pattern: string;
+  replaceWith: string;
+  flags?: string;
+};
+
+export interface PiiConfig {
+  enabled: boolean;
+  whitelistKeys?: string[];
+  blacklistKeys?: string[];
+  patterns?: PiiReplacement[];
+  deep?: boolean;
+  includeDefaults?: boolean;
+}
+
+// patrones “de fábrica” (del sistema):
+export const DEFAULT_PII_PATTERNS: PiiReplacement[] = [
   {
-    // Ejemplo: token JWT simulado
-    regex: /\beyJ[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\b/g,
-    replacement: "[REDACTED_JWT]",
+    pattern: String.raw`[^@\n\r ]+@[^@\n\r ]+`,
+    replaceWith: "[EMAIL]",
+    flags: "g",
   },
 ];
 
-// 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-postgresql";
-
-// Configuración cargada desde variables de entorno (env-var + dotenv)
-import { envs } from "../plugins/envs.plugin";
+// patrones “del cliente/proyecto”:
+export const clientPiiPatterns: PiiReplacement[] = [
+  { pattern: String.raw`\b\d{10}\b`, flags: "g", replaceWith: "[EC_DNI]" },
+];
 
-// Patrones propios de PII definidos en src/config/logger/pii.ts
-import { clientPiiPatterns, redactKeys, preserveKeys } from "./pii";
+// lista negra de nombres de clave que se siempre se ocultan
+export const redactKeys: string[] = ["password", "secret"];
+// lista blanca de nombres de clave que no se deben ocultar por clave
+export const preserveKeys: string[] = ["city"];
+
+// Helpers
+// 1. Filtra valores no válidos: elimina null, undefined y "" (cadena vacía).
+// 2. Elimina duplicados usando Set.
+// 3. Conserva el primero de cada valor repetido (porque Set guarda la primera aparición).
+export function dedupeStrings(arr: Array<string | undefined | null>): string[] {
+  return [...new Set(arr.filter((x): x is string => !!x && x.length > 0))];
+}
 
-// Utilidades de Node.js para manejo de directorios y archivos
-import { mkdirSync, existsSync } from "node:fs";
-import { dirname } from "node:path";
+// 1. Construye una clave de identidad por patrón: pattern + "__" + replaceWith + "__" + (flags || "").
+// 2. Inserta cada elemento en un `Map` usando esa clave. Si la clave ya existe, sobrescribe el anterior (es decir, gana el último).
+// 3. Devuelve los valores únicos del `Map`.
+export function dedupePatterns(arr: PiiReplacement[]): PiiReplacement[] {
+  const m = new Map<string, PiiReplacement>();
+  for (const p of arr)
+    m.set(`${p.pattern}__${p.replaceWith}__${p.flags ?? ""}`, p);
+  return [...m.values()];
+}
 
-// Cliente oficial de MongoDB
-import { MongoClient } from "mongodb";
+// Builder unificado
+export function buildPiiConfig(
+  opts?: PiiConfig
+): Required<Omit<PiiConfig, "includeDefaults">> {
+  const includeDefaults = opts?.includeDefaults ?? true;
+
+  const patterns = dedupePatterns([
+    ...(includeDefaults ? DEFAULT_PII_PATTERNS : []),
+    ...clientPiiPatterns,
+    ...(opts?.patterns ?? []),
+  ]);
+
+  const whitelistKeys = dedupeStrings([
+    ...(opts?.whitelistKeys ?? []),
+    ...preserveKeys,
+  ]);
+  const blacklistKeys = dedupeStrings([
+    ...(opts?.blacklistKeys ?? []),
+    ...redactKeys,
+  ]);
+
+  return {
+    enabled: !!opts?.enabled,
+    whitelistKeys,
+    blacklistKeys,
+    patterns,
+    deep: opts?.deep ?? true,
+  };
+}
+```
 
-// Se mantiene una referencia global al cliente de MongoDB para cerrarlo en dispose
-let mongoClient: MongoClient | null = null;
+##### 2.2) loglevel.settings.ts (normalización de nivel)
 
-// Convierte un string (ej. "debug") al enum LogLevel
-function toMinLevel(level: string): LogLevel {
-  switch (level.toLowerCase()) {
+```ts
+// src/infrastructure/logger/settings/loglevel.settings.ts
+import { LogLevel } from "@jmlq/logger";
+
+export function toMinLevel(
+  level: LogLevel | keyof typeof LogLevel | string
+): LogLevel {
+  if (typeof level === "number") return level as LogLevel;
+  switch (String(level || "debug").toLowerCase()) {
     case "trace":
       return LogLevel.TRACE;
     case "debug":
@@ -194,103 +207,365 @@ function toMinLevel(level: string): LogLevel {
     case "fatal":
       return LogLevel.FATAL;
     default:
-      return LogLevel.INFO; // Valor por defecto
+      return LogLevel.DEBUG;
   }
 }
+```
 
-// 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 });
+#### 3) Adapters (capa infrastructure)
+
+Todos `devuelven`/`encapsulan` un `ILogDatasource` para evitar acoplar la app a clases concretas.
+
+**NOTA**: Solo se implementan los que se necesiten, por ejemplo:
+
+> - Si se necesita generar logs en archivos se crea adapter para `FS`.
+> - Si se necesita guardar logs en una base de datos no relacional se crea adapter para `mongo`.
+> - Si se necesita guardar logs en una base de datos relacional se crea adapter para `postgresql`.
+> - También se pueden combinar.
+> - Se debe implementar al menos un adapter.
+
+##### 3.1) FS (`fs.adapter.ts`)
+
+```ts
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+import type { ILogDatasource } from "@jmlq/logger";
+
+export interface IFsProps {
+  basePath: string;
+  fileNamePattern: string;
+  rotationPolicy: { by: "none" | "day" | "size"; maxSizeMB?: number };
 }
 
-// Inicializa el logger ensamblando los datasources configurados en .env
-async function initLogger() {
-  const datasources = [];
+export class FsAdapter {
+  private constructor(private readonly ds: ILogDatasource) {}
+  static create(opts: IFsProps): FsAdapter | undefined {
+    try {
+      const ds = createFsDatasource({
+        basePath: opts.basePath,
+        mkdir: true,
+        fileNamePattern: opts.fileNamePattern,
+        rotation: opts.rotationPolicy,
+        onRotate: (oldP, newP) =>
+          console.log("[fs] rotated:", oldP, "->", newP),
+        onError: (e) => console.error("[fs] error:", e),
+      });
+      console.log("[logger] Conectado a FS para logs");
+      return new FsAdapter(ds);
+    } catch (e: any) {
+      console.warn("[logger] FS deshabilitado:", e?.message ?? e);
+    }
+  }
+  get datasource(): ILogDatasource {
+    return this.ds;
+  }
+}
+```
 
-  // --- 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 })
-    );
+##### 3.2) Mongo (`mongo.adapter.ts`)
+
+```ts
+import type { ILogDatasource } from "@jmlq/logger";
+import { createMongoInfra, MongoDatasource } from "@jmlq/logger-plugin-mongo";
+
+export interface IMongoProps {
+  url: string;
+  dbName: string;
+  collectionName?: string;
+  retentionDays?: number | null;
+}
+
+export class MongoAdapter {
+  private constructor(private readonly ds: ILogDatasource) {}
+  static async create(opts: IMongoProps): Promise<MongoAdapter | undefined> {
+    try {
+      const infra = await createMongoInfra({
+        url: opts.url,
+        dbName: opts.dbName,
+        collectionName: opts.collectionName ?? "logs",
+        createIfMissing: true,
+        ensureIndexes: true,
+        retentionDays: opts.retentionDays ?? 0,
+        extraIndexes: [{ key: { "meta.userId": 1 } }],
+      });
+      return new MongoAdapter(new MongoDatasource(infra.collection));
+    } catch (e: any) {
+      console.warn("[logger] Mongo deshabilitado:", e?.message ?? e);
+    }
+  }
+  get datasource(): ILogDatasource {
+    return this.ds;
+  }
+}
+```
+
+##### 3.2) Postgresql (`postgresql.adapter.ts`)
+
+```ts
+import type { ILogDatasource } from "@jmlq/logger";
+import { createPostgresDatasource } from "@jmlq/logger-plugin-postgresql";
+
+export interface IPostgresqlProps {
+  url: string;
+  schema: string;
+  table?: string;
+  retentionDays?: number | null;
+}
+
+export class PostgresqlAdapter {
+  private constructor(private readonly ds: ILogDatasource) {}
+  static async create(
+    opts: IPostgresqlProps
+  ): Promise<PostgresqlAdapter | undefined> {
+    try {
+      const ps = await createPostgresDatasource({
+        connectionString: opts.url,
+        schema: opts.schema,
+        table: opts.table ?? "logs",
+        createIfMissing: true,
+        retentionDays: opts.retentionDays ?? 0,
+      });
+      console.log("[logger] Conectado a PostgreSQL para logs");
+      return new PostgresqlAdapter(ps);
+    } catch (e: any) {
+      console.warn("[logger] Postgres deshabilitado:", e?.message ?? e);
+    }
+  }
+  get datasource(): ILogDatasource {
+    return this.ds;
   }
+}
+```
+
+#### 4) `LoggerBootstrap` (orquestador de adapters + PII)
+
+```ts
+// src/infrastructure/logger/bootstrap.ts
+import {
+  createLogger,
+  CompositeDatasource,
+  type ILogDatasource,
+} from "@jmlq/logger";
+import { buildPiiConfig } from "./settings/pii.settings";
+import { toMinLevel } from "./settings/loglevel.settings";
+// NOTA: Opcionales depende de las necesidades del cliente
+import { FsAdapter, type IFsProps } from "./adapters/fs.adapter";
+import { MongoAdapter, type IMongoProps } from "./adapters/mongo.adapter";
+import {
+  PostgresqlAdapter,
+  type IPostgresqlProps,
+} from "./adapters/postgresql.adapter";
+
+export interface LoggerBootstrapOptions {
+  minLevel: string | number;
+  pii?: {
+    enabled?: boolean;
+    whitelistKeys?: string[];
+    blacklistKeys?: string[];
+    patterns?: any[];
+    deep?: boolean;
+    includeDefaults?: boolean;
+  };
+  adapters?: {
+    // NOTA: Opcionales depende de las necesidades del cliente
+    fs?: IFsProps;
+    mongo?: IMongoProps;
+    postgres?: IPostgresqlProps;
+  };
+}
 
-  // --- 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));
+export class LoggerBootstrap {
+  private constructor(
+    private readonly _logger: ReturnType<typeof createLogger>,
+    private readonly _ds: ILogDatasource
+  ) {}
+
+  static async create(opts: LoggerBootstrapOptions): Promise<LoggerBootstrap> {
+    const dsList: ILogDatasource[] = [];
+
+    // NOTA: Opcionales depende de las necesidades del cliente
+    if (opts.adapters?.fs) {
+      const fs = FsAdapter.create(opts.adapters.fs);
+      if (fs) dsList.push(fs.datasource);
+    }
+    if (opts.adapters?.mongo) {
+      const mg = await MongoAdapter.create(opts.adapters.mongo);
+      if (mg) dsList.push(mg.datasource);
+    }
+    if (opts.adapters?.postgres) {
+      const pg = await PostgresqlAdapter.create(opts.adapters.postgres);
+      if (pg) dsList.push(pg.datasource);
+    }
+    //----
+
+    if (dsList.length === 0)
+      throw new Error("[logger] No hay datasources válidos.");
+    const datasource =
+      dsList.length === 1 ? dsList[0] : new CompositeDatasource(dsList);
+
+    const pii = buildPiiConfig({
+      enabled: opts.pii?.enabled ?? false,
+      includeDefaults: opts.pii?.includeDefaults ?? true,
+      whitelistKeys: opts.pii?.whitelistKeys,
+      blacklistKeys: opts.pii?.blacklistKeys,
+      patterns: opts.pii?.patterns,
+      deep: opts.pii?.deep ?? true,
+    });
+
+    const logger = createLogger(datasource, {
+      minLevel: toMinLevel(opts.minLevel),
+      pii,
+    });
+    return new LoggerBootstrap(logger, datasource);
   }
 
-  // --- 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"));
+  get logger() {
+    return this._logger;
+  }
+  async flush() {
+    const any = this._logger as any;
+    if (typeof any.flush === "function") await any.flush();
+  }
+  async dispose() {
+    const any = this._logger as any;
+    if (typeof any.dispose === "function") await any.dispose();
   }
+}
+```
+
+#### 5) Configuración global del logger (singleton)
+
+```ts
+// src/config/logger/index.ts
+import { LoggerBootstrap } from "../../infrastructure/logger/bootstrap";
+import { envs } from "../../infrastructure/plugins";
 
-  // Si hay más de un datasource, se compone con CompositeDatasource (fan-out)
-  const datasource =
-    datasources.length === 1
-      ? datasources[0]
-      : new CompositeDatasource(datasources);
+declare global {
+  var __LOGGER_BOOT__: Promise<LoggerBootstrap> | undefined;
+}
 
-  // Crea y retorna el logger con nivel mínimo y configuración de PII
-  return createLogger(datasource, {
-    minLevel: toMinLevel(envs.logger.LOGGER_LEVEL),
+async function init() {
+  return LoggerBootstrap.create({
+    minLevel: envs.logger.LOGGER_LEVEL ?? "debug",
     pii: {
       enabled: envs.logger.LOGGER_PII_ENABLED,
-      includeDefaultPatterns: envs.logger.LOGGER_PII_INCLUDE_DEFAULTS,
-      patterns: clientPiiPatterns,
-      redactKeys,
-      preserveKeys,
+      includeDefaults: envs.logger.LOGGER_PII_INCLUDE_DEFAULTS,
+      deep: true,
+    },
+    adapters: {
+      // NOTA: Opcionales depende de las necesidades del cliente
+      fs: envs.logger.LOGGER_FS_PATH
+        ? {
+            basePath: envs.logger.LOGGER_FS_PATH,
+            fileNamePattern: "app-{yyyy}{MM}{dd}.log",
+            rotationPolicy: { by: "day" },
+          }
+        : undefined,
+      mongo: envs.logger.MONGO_URL
+        ? {
+            url: envs.logger.MONGO_URL!,
+            dbName: envs.logger.MONGO_DB_NAME!,
+            collectionName: envs.logger.MONGO_COLLECTION ?? "logs",
+            retentionDays: Number(envs.logger.LOGGER_MONGO_RETENTION_DAYS) || 0,
+          }
+        : undefined,
+      postgres: envs.logger.POSTGRES_URL
+        ? {
+            url: envs.logger.POSTGRES_URL!,
+            schema: envs.logger.POSTGRES_SCHEMA ?? "public",
+            table: envs.logger.POSTGRES_TABLE ?? "logs",
+            retentionDays: Number(envs.logger.LOGGER_PG_RETENTION_DAYS) || 0,
+          }
+        : undefined,
+      // ---
     },
   });
 }
 
-// Exporta el logger como una Promise porque la inicialización es async
-export const loggerReady = initLogger();
+// 1. Es una promesa singleton de LoggerBootstrap
+// 2. usa el operador nullish-coalescing (??) para: Reusar globalThis.__LOGGER_BOOT__ si ya existe. En caso contrario crea y memoriza (= init()) la promesa si no existe aún.
+// 3. Garantiza una sola inicialización global del sistema de logging (adapters, datasources, PII, etc.) aunque el módulo se importe múltiples veces
+export const bootReady: Promise<LoggerBootstrap> =
+  globalThis.__LOGGER_BOOT__ ?? (globalThis.__LOGGER_BOOT__ = init());
 
-// --- Funciones de utilidad ---
+// 1. Es una promesa que resuelve directamente al logger
+// 2. Hace un map de la promesa anterior: bootReady.then(b => b.logger).
+export const loggerReady = bootReady.then((b) => b.logger);
 
-// Fuerza un flush() de todos los datasources, útil para apagar servicios con logs pendientes
+// 1. Espera a bootReady y llama boot.flush(), que a su vez pide al logger/datasources que vacíen buffers pendientes (útil antes de apagar el proceso o en tests).
 export async function flushLogs() {
-  const logger: any = await loggerReady;
-  if (typeof logger.flush === "function") await logger.flush();
+  const boot = await bootReady;
+  await boot.flush();
 }
 
-// Cierra conexiones abiertas (ej. MongoClient) y libera recursos
+// 1. Espera a bootReady y llama boot.dispose(), que cierra recursos (conexiones a Mongo/Postgres, file handles, etc.)
 export async function disposeLogs() {
-  const logger: any = await loggerReady;
-  if (typeof logger.dispose === "function") await logger.dispose();
-  if (mongoClient) await mongoClient.close();
+  const boot = await bootReady;
+  await boot.dispose();
 }
 ```
 
-#### 3) Uso desde cualquier aplicación Node.js
-
-En cualquier parte de la app se puede usar el logger así:
+#### 6) Uso en la aplicación (Express)
 
 ```ts
-import { loggerReady } from "./config/logger";
-
-async function main() {
-  const logger = await loggerReady;
-
-  await logger.info("Aplicación iniciada", { pid: process.pid });
+// src/presentation/server.ts
+import express, { Request, Response, NextFunction } from "express";
+import { loggerReady } from "../config/logger";
+
+function attachLogger() {
+  const boot = loggerReady;
+  return async (req: Request, _res: Response, next: NextFunction) => {
+    // @ts-expect-error: extensión ad-hoc
+    req.logger = await boot;
+    // @ts-expect-error: idem
+    req.requestId = (req.headers["x-request-id"] as string) ?? randomUUID();
+    next();
+  };
+}
 
-  await logger.error("Error en proceso", {
-    password: "123456", // será redactado
-    city: "Quito", // se preserva
+export function createServer() {
+  const app = express();
+  app.use(express.json());
+  app.use(attachLogger());
+
+  app.get("/health", (_req, res) =>
+    res
+      .status(200)
+      .json({ ok: true, service: "ml-dev-test", timestamp: Date.now() })
+  );
+
+  app.get("/debug/log-demo", async (req, res) => {
+    // @ts-expect-error: logger agregado por attachLogger
+    const logger = req.logger;
+    await logger.info(
+      "Pago con tarjeta 4111 1111 1111 1111 del email demo@correo.com",
+      {
+        password: "abc123",
+        phone: "0987654321",
+        city: "Quito",
+      }
+    );
+    res.json({ ok: true });
   });
-}
 
-main();
+  // Error handler con logging
+  app.use(
+    async (err: any, req: Request, res: Response, _next: NextFunction) => {
+      const status = err?.statusCode ?? 500;
+      // @ts-expect-error
+      const logger = req.logger ?? (await loggerReady);
+      await logger.error("http_error", {
+        message: err?.message,
+        stack: err?.stack,
+        status,
+      });
+      res
+        .status(status)
+        .json({ error: err?.message ?? "Internal Server Error" });
+    }
+  );
+
+  return app;
+}
 ```
 
 ### 🔎 Notas importantes
@@ -342,6 +617,10 @@ test("logger redacta PII en FS", async () => {
 
 ---
 
+### [LEER MAS...](./ARQUITECTURA.md)
+
+---
+
 ## 📄 Licencia
 
 MIT © Mauricio Lahuasi

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@jmlq/logger",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
   "author": "MLahuasi",
+  "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [