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

package/README.md

@@ -1,626 +1,307 @@
 # @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).
-
----
+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
-# 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-postgresql
-
-```
-
-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
+# 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
 ```
 
-### DOCUMENTACION
+## 🚀 Uso Básico
 
-> - [`@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-postgresql`](https://www.npmjs.com/package/@jmlq/logger-plugin-postgresql)
+### Configuración Simple
 
----
+```typescript
+import { LoggerFactory, LogLevel } from "@jmlq/logger";
 
-## 🧩 Configuración
-
-### 🔐 Variables de Entorno (.env)
-
-```ini
-    # @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
+// 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() {},
+};
 
-    # FILESYSTEM @jmlq/logger-plugin-fs
-    LOGGER_FS_PATH=./logs
+// 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
 
-### 🚀 Uso del paquete
-
-#### 1) Estructura recomendada
+```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 });
 ```
-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
 
-```
+## 🎯 Características Principales
 
-#### 2) Settings
+### Niveles de Log
 
-#### 2.1) pii.settings.ts (patrones PII + merge)
+- `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
 
-```ts
-//Se definine reglas de redacción PII (buscar-y-reemplazar con regex) que el logger aplica antes de persistir/emitir un log.
+### Enmascarado PII Automático
 
-export type PiiReplacement = {
-  pattern: string;
-  replaceWith: string;
-  flags?: string;
-};
+El logger detecta y enmascara automáticamente datos sensibles:
 
-export interface PiiConfig {
-  enabled: boolean;
-  whitelistKeys?: string[];
-  blacklistKeys?: string[];
-  patterns?: PiiReplacement[];
-  deep?: boolean;
-  includeDefaults?: boolean;
-}
+```typescript
+await logger.info("Pago procesado", {
+  email: "user@example.com", // → user@[EMAIL]
+  card: "4111-1111-1111-1111", // → ****-****-****-****
+  password: "secret123", // → [REDACTED]
+});
+```
 
-// patrones “de fábrica” (del sistema):
-export const DEFAULT_PII_PATTERNS: PiiReplacement[] = [
-  {
-    pattern: String.raw`[^@\n\r ]+@[^@\n\r ]+`,
-    replaceWith: "[EMAIL]",
-    flags: "g",
-  },
-];
-
-// patrones “del cliente/proyecto”:
-export const clientPiiPatterns: PiiReplacement[] = [
-  { pattern: String.raw`\b\d{10}\b`, flags: "g", replaceWith: "[EC_DNI]" },
-];
-
-// 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))];
-}
+### Filtros y Consultas
 
-// 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()];
-}
+```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,
+});
 
-// 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,
-  };
-}
+// Buscar logs que contengan "usuario"
+const userLogs = await logger.getLogs({
+  query: "usuario",
+  limit: 100,
+});
 ```
 
-##### 2.2) loglevel.settings.ts (normalización de nivel)
-
-```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":
-      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.DEBUG;
-  }
-}
-```
+## 🔧 Configuración con Variables de Entorno
 
-#### 3) Adapters (capa infrastructure)
+```env
+# Nivel mínimo de logs
+LOG_LEVEL=info
 
-Todos `devuelven`/`encapsulan` un `ILogDatasource` para evitar acoplar la app a clases concretas.
+# Filesystem
+LOGGER_FS_PATH=./logs
 
-**NOTA**: Solo se implementan los que se necesiten, por ejemplo:
+# MongoDB
+MONGO_URL=mongodb://localhost:27017
+MONGO_DB_NAME=logs
 
-> - 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.
+# PostgreSQL
+POSTGRES_URL=postgresql://user:pass@localhost:5432/logs
 
-##### 3.1) FS (`fs.adapter.ts`)
+# PII Protection
+LOGGER_PII_ENABLED=true
+```
 
-```ts
-import { createFsDatasource } from "@jmlq/logger-plugin-fs";
-import type { ILogDatasource } from "@jmlq/logger";
+## 📁 Ejemplos Prácticos
 
-export interface IFsProps {
-  basePath: string;
-  fileNamePattern: string;
-  rotationPolicy: { by: "none" | "day" | "size"; maxSizeMB?: number };
-}
+El proyecto incluye ejemplos completos en el directorio [`examples/`](examples/):
 
-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;
-  }
-}
+```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
 ```
 
-##### 3.2) Mongo (`mongo.adapter.ts`)
+### Ejemplo Express
 
-```ts
-import type { ILogDatasource } from "@jmlq/logger";
-import { createMongoInfra, MongoDatasource } from "@jmlq/logger-plugin-mongo";
+```typescript
+import express from "express";
+import { LoggerFactory, LogLevel } from "@jmlq/logger";
 
-export interface IMongoProps {
-  url: string;
-  dbName: string;
-  collectionName?: string;
-  retentionDays?: number | null;
-}
+const app = express();
+const logger = LoggerFactory.create({
+  datasources: /* tu datasource */,
+  minLevel: LogLevel.INFO
+});
 
-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;
+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" });
   }
-}
+});
 ```
 
-##### 3.2) Postgresql (`postgresql.adapter.ts`)
+### Ejemplo NestJS
 
-```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;
-}
+```typescript
+@Injectable()
+export class AppService {
+  constructor(@Inject("LOGGER") private readonly logger: ILoggerService) {}
 
-export class PostgresqlAdapter {
-  private constructor(private readonly ds: ILogDatasource) {}
-  static async create(
-    opts: IPostgresqlProps
-  ): Promise<PostgresqlAdapter | undefined> {
+  async createUser(userData: any) {
+    await this.logger.info("Creando usuario", { userData });
     try {
-      const ps = await createPostgresDatasource({
-        connectionString: opts.url,
-        schema: opts.schema,
-        table: opts.table ?? "logs",
-        createIfMissing: true,
-        retentionDays: opts.retentionDays ?? 0,
+      // ... 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,
       });
-      console.log("[logger] Conectado a PostgreSQL para logs");
-      return new PostgresqlAdapter(ps);
-    } catch (e: any) {
-      console.warn("[logger] Postgres deshabilitado:", e?.message ?? e);
+      throw error;
     }
   }
-  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;
-  };
-}
-
-export class LoggerBootstrap {
-  private constructor(
-    private readonly _logger: ReturnType<typeof createLogger>,
-    private readonly _ds: ILogDatasource
-  ) {}
+## 🏗️ Arquitectura
 
-  static async create(opts: LoggerBootstrapOptions): Promise<LoggerBootstrap> {
-    const dsList: ILogDatasource[] = [];
+El paquete sigue **Arquitectura Limpia**:
 
-    // 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);
-  }
-
-  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";
-
-declare global {
-  var __LOGGER_BOOT__: Promise<LoggerBootstrap> | undefined;
-}
-
-async function init() {
-  return LoggerBootstrap.create({
-    minLevel: envs.logger.LOGGER_LEVEL ?? "debug",
-    pii: {
-      enabled: envs.logger.LOGGER_PII_ENABLED,
-      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,
-      // ---
-    },
-  });
-}
-
-// 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());
-
-// 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);
-
-// 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 boot = await bootReady;
-  await boot.flush();
-}
-
-// 1. Espera a bootReady y llama boot.dispose(), que cierra recursos (conexiones a Mongo/Postgres, file handles, etc.)
-export async function disposeLogs() {
-  const boot = await bootReady;
-  await boot.dispose();
-}
+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)
 ```
 
-#### 6) Uso en la aplicación (Express)
-
-```ts
-// 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();
-  };
-}
-
-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 });
-  });
+### 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 },
+    });
 
-  // 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" });
-    }
-  );
+    await logger.info("Usuario: user@example.com");
 
-  return app;
-}
+    expect(logs[0].message).not.toContain("user@example.com");
+    expect(logs[0].message).toContain("[EMAIL]");
+  });
+});
 ```
 
-### 🔎 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
+## 🚨 Troubleshooting
 
-> - **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`.
+**Error: No datasources válidos**
 
----
+- Asegúrate de configurar al menos un datasource
+- Verifica las variables de entorno
 
-## 🧯 Troubleshooting
+**MongoDB no conecta**
 
-> - **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.
+- Verifica la URL de conexión
+- Incluye `authSource=admin` si usas usuarios root
 
----
-
-## 🧪 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
-});
-```
+**Alto uso de memoria**
 
----
+- Implementa límites en las consultas
+- Usa `flush()` periódicamente para vaciar buffers
 
-### [LEER MAS...](./ARQUITECTURA.md)
+## 📄 Más Información
 
----
+- **[Arquitectura Detallada](./ARQUITECTURA.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
+## 📝 Licencia
 
 MIT © Mauricio Lahuasi