@jmlq/logger 0.1.0-alpha.13 → 0.1.0-alpha.16

package/install.md

@@ -1,367 +1,632 @@
-# Guía de Instalación y Configuración para @jmlq/logger
+# GUÍA DE CONFIGURACIÓN @jmlq/logger Y SUS PLUGINS
 
-## Instalación
+## PASO 1 – BOOTSTRAP DEL LOGGER CORE
 
-```bash
-npm install @jmlq/logger
+### 1.1. OPCIONES DE BOOTSTRAP
+
+Path sugerido: `src/infrastructure/adapters/jmlq/logger/core/logger.bootstrap.options.ts`
+
+`LoggerBootstrapOptions` es un **contrato de configuración** usado al momento de inicializar el logger. Define:
+
+- El **nivel mínimo de log** permitido.
+- Configuración de **redacción de PII** (datos sensibles).
+- Los **datasources** del logger que se deben habilitar (FS, Mongo, PostgreSQL).
+
+Describe cómo debe construirse el logger, qué debe censurar, y a dónde deben enviarse los logs.
+
+```ts
+import { LogLevel } from "@jmlq/logger";
+import { IFilesystemDatasourceOptions } from "@jmlq/logger-plugin-fs";
+import { MongoPluginConfig } from "@jmlq/logger-plugin-mongo";
+import { PostgresPluginConfig } from "@jmlq/logger-plugin-postgresql";
+
+export interface LoggerBootstrapOptions {
+  minLevel: LogLevel;
+  pii?: {
+    enabled?: boolean;
+    whitelistKeys?: string[];
+    blacklistKeys?: string[];
+    patterns?: any[];
+    deep?: boolean;
+    includeDefaults?: boolean;
+  };
+  adapters?: {
+    // NOTA: Opcionales depende de las necesidades del cliente
+    fs?: IFilesystemDatasourceOptions;
+    mongo?: MongoPluginConfig;
+    pg?: PostgresPluginConfig;
+  };
+}
 ```
 
-## Configuración Básica
-
-### NestJS
-
-1. Crear el módulo de Logger
-
-```typescript
-// src/logger/logger.module.ts
-import { Module, Global } from "@nestjs/common";
-import { ConfigModule, ConfigService } from "@nestjs/config";
-import { LoggerFactory } from "@jmlq/logger";
-
-@Global()
-@Module({
-  imports: [ConfigModule],
-  providers: [
-    {
-      provide: "LOGGER",
-      useFactory: async (configService: ConfigService) => {
-        // Configurar datasources según necesidades
-        const datasources = [];
-
-        // Ejemplo: Plugin de filesystem (requiere @jmlq/logger-plugin-fs)
-        if (configService.get("LOG_FS_ENABLED") === "true") {
-          const { FileSystemDatasource } = await import(
-            "@jmlq/logger-plugin-fs"
-          );
-          datasources.push(
-            new FileSystemDatasource({
-              basePath: configService.get("LOG_FS_PATH", "./logs"),
-            })
-          );
-        }
-
-        return LoggerFactory.create({
-          datasources,
-          minLevel: configService.get("LOG_LEVEL", "info"),
-          redactorOptions: {
-            enabled: true,
-            deep: true,
-            includeDefaults: true,
-          },
-        });
+- `minLevel`: nivel mínimo de log (ss de tipo `LogLevel` de `@jmlq/logger`).
+- `pii`: configuración de redacción (redaction) de datos sensibles.
+- `adapters`: configuración específica para cada plugin (**todos opcionales**).
+
+---
+
+### 1.2. IMPLEMENTACIÓN DEL BOOTSTRAP
+
+Path sugerido: `src/infrastructure/adapters/jmlq/logger/core/logger.bootstrap.ts`
+
+La clase `LoggerBootstrap` es un componente de infraestructura cuyo objetivo es:
+
+- Crear e inicializar el **logger principal** de la aplicación.
+- Construir la lista de **datasources** (FS, Mongo, PostgreSQL) según la configuración del usuario.
+- Exponer funciones para **flush** y **dispose**, importantes para apagado limpio.
+- Encapsular la instancia del logger para no exponer detalles internos.
+
+La clase completa se encarga de arrancar correctamente el sistema de logging.
+
+```ts
+import { type ILogDatasource, LoggerFactory } from "@jmlq/logger";
+import { FsAdapter } from "../fs/fs.adapter";
+import { MongoAdapter } from "../mongo/mongo.adapter";
+import { PgAdapter } from "../pg/pg.adapter";
+import { LoggerBootstrapOptions } from "./logger.bootstrap.options";
+
+export class LoggerBootstrap {
+  private constructor(
+    private readonly _logger: ReturnType<typeof LoggerFactory.create>
+  ) {}
+
+  /**
+   * Este es el punto de entrada para construir el logger.
+   */
+  static async create(opts: LoggerBootstrapOptions): Promise<LoggerBootstrap> {
+    // Almacena los plugins inicializados.
+    const dsList: ILogDatasource[] = [];
+
+    // Inyectar datasources
+    // NOTA: Opcionales depende de las necesidades del cliente
+    // FS si está configurado
+    if (opts.adapters?.fs) {
+      const fs = FsAdapter.create(opts.adapters.fs);
+      if (fs) dsList.push(fs.datasource);
+    }
+    // MongoDB si está configurado
+    if (opts.adapters?.mongo) {
+      const mongo = await MongoAdapter.create(opts.adapters.mongo);
+      if (mongo) dsList.push(mongo.datasource);
+    }
+    // Postgresql si está configurado
+    if (opts.adapters?.pg) {
+      const pg = await PgAdapter.create(opts.adapters.pg);
+      if (pg) dsList.push(pg.datasource);
+    }
+
+    if (dsList.length === 0)
+      throw new Error("[logger] No hay datasources válidos.");
+
+    // Crear el logger central
+    const logger = LoggerFactory.create({
+      datasources: dsList,
+      minLevel: opts.minLevel,
+      redactorOptions: {
+        enabled: opts.pii?.enabled ?? false,
+        deep: opts.pii?.deep ?? true,
+        patterns: opts.pii?.patterns ?? [],
       },
-      inject: [ConfigService],
-    },
-  ],
-  exports: ["LOGGER"],
-})
-export class LoggerModule {}
+    });
+
+    console.log("✅ Logger creado correctamente.\n");
+
+    // Retornar la instancia final
+    return new LoggerBootstrap(logger);
+  }
+
+  // Permite acceder al logger real pero manteniendo encapsulación.
+  get logger() {
+    return this._logger;
+  }
+
+  // Fuerza a que todos los logs pendientes se escriban en los datasources.
+  // Lo usa el ciclo de vida del servidor (shutdown, errores críticos, etc.).
+  async flush() {
+    const logs = this._logger as any;
+    if (typeof logs.flush === "function") await logs.flush();
+  }
+
+  // Cierra conexiones y limpia recursos (como conexiones a BD).
+  // Asegura un apagado ordenado.
+  async dispose() {
+    const logs = this._logger as any;
+    if (typeof logs.dispose === "function") await logs.dispose();
+  }
+}
 ```
 
-2. Usar en servicios
+---
 
-```typescript
-// src/users/users.service.ts
-import { Injectable, Inject } from "@nestjs/common";
-import { ILogger } from "@jmlq/logger";
+## PASO 2 – CONFIGURAR PLUGINS / DATASOURCES
+
+### 2.1. Plugin FileSystem (`@jmlq/logger-plugin-fs`)
+
+Path sugerido: `src/infrastructure/adapters/jmlq/logger/fs/fs.adapter.ts`
 
-@Injectable()
-export class UsersService {
-  constructor(@Inject("LOGGER") private readonly logger: ILogger) {}
+`FsAdapter` es un **adaptador de infraestructura** cuyo propósito es `crear`, `inicializar` y `exponer` un `datasource` de logs basado en archivos (FileSystem) usando el plugin `@jmlq/logger-plugin-fs`.
 
-  async createUser(userData: any) {
+```ts
+import {
+  // Función del plugin que crea realmente el datasource de FileSystem.
+  createFsDatasource,
+  // Tipo de configuración que el plugin requiere
+  IFilesystemDatasourceOptions,
+} from "@jmlq/logger-plugin-fs";
+// Interfaz estándar que todos los datasources deben implementar para funcionar dentro de @jmlq/logger
+import type { ILogDatasource } from "@jmlq/logger";
+
+export class FsAdapter {
+  private constructor(private readonly ds: ILogDatasource) {}
+
+  // Este es el punto central del adaptador.
+  static create(opts: IFilesystemDatasourceOptions): FsAdapter | undefined {
+    try {
+      // Se inicializa el plugin.
+      // Se configuran rutas, políticas de rotación, serializer, etc.
+      // El datasource queda listo para recibir logs.
+      const ds = createFsDatasource(opts);
+      console.log("[logger] Conectado a FS para logs");
+      return new FsAdapter(ds);
+    } catch (e: any) {
+      console.warn("[logger] FS deshabilitado:", e?.message ?? e);
+    }
+  }
+  // Permite a otras capas (especialmente LoggerBootstrap) obtener el datasource real que necesita LoggerFactory.create
+  get datasource(): ILogDatasource {
+    return this.ds;
+  }
+}
+```
+
+---
+
+### 2.2. Plugin MongoDB (`@jmlq/logger-plugin-mongo`)
+
+Path sugerido: `src/infrastructure/adapters/jmlq/logger/mongo/mongo.adapter.ts`
+
+`MongoAdapter` es un **adaptador de infraestructura** cuyo propósito es `crear`, `inicializar` y `exponer` un `datasource` de los logs almacenados en `MongoDB` usando el plugin `@jmlq/logger-plugin-mongo`.
+
+```ts
+// Interfaz estándar que todos los datasources deben implementar para funcionar dentro de @jmlq/logger
+import type { ILogDatasource } from "@jmlq/logger";
+import {
+  // Función del plugin que crea realmente el datasource de MongoDb.
+  createMongoDatasource,
+  // Tipo de configuración que el plugin requiere
+  MongoPluginConfig,
+} from "@jmlq/logger-plugin-mongo";
+
+export class MongoAdapter {
+  private constructor(private readonly ds: ILogDatasource) {}
+
+  // Este es el punto central del adaptador.
+  static async create(
+    opts: MongoPluginConfig
+  ): Promise<MongoAdapter | undefined> {
     try {
-      await this.logger.info("Creando usuario", { userData });
-      // ... lógica del servicio
-      await this.logger.info("Usuario creado exitosamente", {
-        userId: result.id,
-      });
-      return result;
-    } catch (error) {
-      await this.logger.error("Error al crear usuario", {
-        error: error.message,
-        userData,
-      });
-      throw error;
+      const ds = await createMongoDatasource(opts);
+      console.log("[logger] Conectado a MongoDB para logs");
+      return new MongoAdapter(ds);
+    } catch (e: any) {
+      console.warn("[logger] MongoDB deshabilitado:", e?.message ?? e);
     }
   }
+  get datasource(): ILogDatasource {
+    return this.ds;
+  }
 }
 ```
 
-### Express
+---
 
-1. Configurar logger en app.js
+### 2.3. Plugin PostgreSQL (`@jmlq/logger-plugin-postgresql`)
+
+Path sugerido: `src/infrastructure/adapters/jmlq/logger/pg/pg.adapter.ts`
+
+`PgAdapter` es un **adaptador de infraestructura** cuyo propósito es `crear`, `inicializar` y `exponer` un `datasource` de los logs almacenados en `Postgresal` usando el plugin `@jmlq/logger-plugin-postgresql`.
 
 ```ts
-// src/logger.ts
-import { LoggerFactory, LogLevel } from "@jmlq/logger";
-
-export const createLogger = async () => {
-  const datasources = [];
-
-  // Configurar datasources según variables de entorno
-  if (process.env.LOG_FS_ENABLED === "true") {
-    const { FileSystemDatasource } = await import("@jmlq/logger-plugin-fs");
-    datasources.push(
-      new FileSystemDatasource({
-        basePath: process.env.LOG_FS_PATH || "./logs",
-      })
-    );
+// Interfaz estándar que todos los datasources deben implementar para funcionar dentro de @jmlq/logger
+import type { ILogDatasource } from "@jmlq/logger";
+import {
+  // Función del plugin que crea realmente el datasource de Postgresql.
+  createPostgresDatasource,
+  // Tipo de configuración que el plugin requiere
+  PostgresPluginConfig,
+} from "@jmlq/logger-plugin-postgresql";
+
+export class PgAdapter {
+  private constructor(private readonly ds: ILogDatasource) {}
+
+  // Este es el punto central del adaptador.
+  static async create(
+    opts: PostgresPluginConfig
+  ): Promise<PgAdapter | undefined> {
+    try {
+      const ds = await createPostgresDatasource(opts);
+      console.log("[logger] Conectado a PostgreSQL para logs");
+      return new PgAdapter(ds);
+    } catch (e: any) {
+      console.warn("[logger] PostgreSQL deshabilitado:", e?.message ?? e);
+    }
   }
 
-  return LoggerFactory.create({
-    datasources,
-    minLevel: process.env.LOG_LEVEL || LogLevel.INFO,
-    redactorOptions: {
-      enabled: true,
+  get datasource(): ILogDatasource {
+    return this.ds;
+  }
+}
+```
+
+### 2.4. Configuración Global @jmlq/Logger
+
+Path sugerido: `src/infrastructure/adapters/jmlq/logger/index.ts`
+
+Este archivo implementa el **bootstrap global** y singleton del sistema de logging de tu proyecto.
+En términos simples: garantiza que **el logger, sus adapters y sus reglas de PII se inicialicen una sola vez**, sin importar cuántas veces se importe este archivo en distintos módulos.
+
+```ts
+import { envs } from "../../../../config/plugins";
+import { LoggerBootstrap } from "./core/logger.bootstrap";
+import { parseLogLevel } from "./helper";
+
+// Promesa Singleton
+declare global {
+  var __LOGGER_BOOT__: Promise<LoggerBootstrap> | undefined;
+}
+
+// Construye toda la infraestructura del logger
+async function init() {
+  // Envía la configuración del logger en envs (se puede usar .env)
+  return LoggerBootstrap.create({
+    // Nivel mínimo de log
+    minLevel: parseLogLevel(envs.logger.LOGGER_LEVEL),
+    // Configuración de PII (ocultamiento de datos sensibles)
+    pii: {
+      // Activación global
+      enabled: envs.logger.LOGGER_PII_ENABLED,
+      // Incluir reglas de validación declaradas en @jmlq/logger
+      includeDefaults: envs.logger.LOGGER_PII_INCLUDE_DEFAULTS,
+      // Incluye recursión profunda
       deep: true,
-      includeDefaults: true,
       patterns: [
+        // Patrón para ocultar tarjetas
         {
           pattern: "\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b",
           replaceWith: "****-****-****-****",
         },
+        // Patrón para ocultar correos
+        {
+          pattern: "[\\w.-]+@[\\w.-]+",
+          replaceWith: "***@***",
+        },
+        // NOTA: Se pueden agregar mas reglas
       ],
     },
+    adapters: {
+      // NOTA: Opcionales depende de las necesidades del cliente
+      // Adapter FS
+      fs: envs.logger.LOGGER_FS_PATH
+        ? {
+            // Path donde se guarda el log
+            basePath: envs.logger.LOGGER_FS_PATH,
+            // Patrón de archivo por fecha
+            fileNamePattern: "app-{yyyy}{MM}{dd}.log",
+            // Tipo de Rotacion (Generación de un nuevo archivo puede ser por día, peso, etc)
+            rotation: { by: "day" },
+            // Crear directorio nuevo
+            mkdir: true,
+            // Darle formato a la trama
+            serializer: {
+              serialize(log: any) {
+                // Serializer personalizado
+                return JSON.stringify(log, null, 2);
+              },
+            },
+            // Se ejecuta acción cuando se genera un nuevo archivo (Se podría enviar un email por ejempo)
+            onRotate: (oldPath, newPath) => {
+              console.log(
+                `   [Rotate] Rotación completada: ${oldPath.absolutePath} → ${newPath.absolutePath}`
+              );
+            },
+            // Se ejecuta acción cuando se presenta un error
+            onError: (err) => {
+              console.error("   [Error Handler]", err.message);
+            },
+          }
+        : undefined,
+      // Adapter MongoDB
+      mongo: envs.logger.LOGGER_MONGO_DB_URL
+        ? {
+            url: envs.logger.LOGGER_MONGO_DB_URL,
+            dbName: envs.logger.LOGGER_MONGO_DB_NAME ?? "logs",
+            collectionName:
+              envs.logger.LOGGER_MONGO_COLLECTION_NAME ?? "app_logs",
+            ensureIndexes: true,
+            // Tiempo de retención del log
+            retentionDays: 7,
+            // Crear Index extra (opcional)
+            extraIndexes: [{ key: { level: 1 } }],
+            //   writeOrdered: true,
+            createIfMissing: true,
+          }
+        : undefined,
+      // Adapter Postgresql
+      pg: envs.logger.LOGGER_PG_CONNECTION_STRING
+        ? {
+            connectionString: envs.logger.LOGGER_PG_CONNECTION_STRING,
+            table: envs.logger.LOGGER_PG_TABLE_NAME ?? "app_logs",
+            schema: envs.logger.LOGGER_PG_SCHEMA ?? "public",
+            createIfMissing: true,
+            // Tiempo de retención del log
+            retentionDays: 7,
+          }
+        : undefined,
+      //----
+    },
   });
-};
-```
+}
 
-2. Middleware de logging
+// Inicializar promesa Singleton
+export const bootReady: Promise<LoggerBootstrap> =
+  globalThis.__LOGGER_BOOT__ ?? (globalThis.__LOGGER_BOOT__ = init());
 
-```ts
-// src/middleware/logger.middleware.ts
-import { Request, Response, NextFunction } from "express";
-import { ILogger } from "@jmlq/logger";
+// Acceso directo al logger
+export const loggerReady = bootReady.then((b) => b.logger);
 
-export const createLoggerMiddleware = (logger: ILogger) => {
-  return async (req: Request, res: Response, next: NextFunction) => {
-    const startTime = Date.now();
+// Vaciar buffers antes de terminar el proceso
+export async function flushLogs() {
+  const boot = await bootReady;
+  await boot.flush();
+}
 
-    await logger.info("Request iniciado", {
-      method: req.method,
-      url: req.url,
-      ip: req.ip,
-      userAgent: req.get("User-Agent"),
-    });
+// Cerrar recursos
+export async function disposeLogs() {
+  const boot = await bootReady;
+  await boot.dispose();
+}
+```
 
-    res.on("finish", async () => {
-      const duration = Date.now() - startTime;
-      const level = res.statusCode >= 400 ? "error" : "info";
+**NOTA**: `parseLogLevel` es un helper para convertir un `string` en `LogLevel`:
 
-      await logger[level]("Request completado", {
-        method: req.method,
-        url: req.url,
-        statusCode: res.statusCode,
-        duration,
-      });
-    });
+```ts
+import { LogLevel } from "@jmlq/logger";
 
-    next();
-  };
-};
-```
+export function parseLogLevel(value?: string): LogLevel {
+  if (!value) return LogLevel.DEBUG; // fallback seguro
 
-3. Usar en la aplicación
+  const normalized = value.toUpperCase();
 
-```ts
-// src/app.ts
-import express from "express";
-import { createLogger } from "./logger";
-import { createLoggerMiddleware } from "./middleware/logger.middleware";
-
-const app = express();
-const logger = await createLogger();
-
-app.use(createLoggerMiddleware(logger));
-
-app.get("/users/:id", async (req, res) => {
-  try {
-    await logger.info("Obteniendo usuario", { userId: req.params.id });
-    // ... lógica
-    res.json(user);
-  } catch (error) {
-    await logger.error("Error al obtener usuario", {
-      userId: req.params.id,
-      error: error.message,
-    });
-    res.status(500).json({ error: "Internal server error" });
-  }
-});
+  const map: Record<string, LogLevel> = {
+    TRACE: LogLevel.TRACE,
+    DEBUG: LogLevel.DEBUG,
+    INFO: LogLevel.INFO,
+    WARN: LogLevel.WARN,
+    ERROR: LogLevel.ERROR,
+    FATAL: LogLevel.FATAL,
+  };
+
+  return map[normalized] ?? LogLevel.DEBUG; // fallback en caso de valor inválido
+}
 ```
 
-## Configuración de PII (Datos Sensibles)
+---
 
-### Patrones Predefinidos
+## PASO 3 – INTEGRACIÓN CON EXPRESS
 
-El logger incluye patrones comunes para enmascarar datos sensibles:
+### 3.1. Extender `Request` con logger y requestId
+
+Path sugerido: `src/types/express.d.ts`
 
 ```ts
-const logger = LoggerFactory.create({
-  datasources,
-  redactorOptions: {
-    enabled: true,
-    deep: true, // Busca en objetos anidados
-    includeDefaults: true, // Incluye patrones predefinidos (email, teléfono, etc.)
-  },
-});
+import "express";
+import type { ILogger } from "@jmlq/logger";
+
+// Cada req trae un logger y un requestId.
+declare module "express-serve-static-core" {
+  interface Request {
+    logger?: ILogger;
+    requestId?: string;
+  }
+}
 ```
 
-Patrones Personalizados
+Esto permite escribir `req.logger` y `req.requestId` con type safety.
+
+### 3.2. Crear el servidor y adjuntar el logger
+
+Path sugerido: `src/presentation/server.ts`
 
 ```ts
-const logger = LoggerFactory.create({
-  datasources,
-  redactorOptions: {
-    enabled: true,
-    deep: true,
-    includeDefaults: true,
-    patterns: [
-      // Tarjetas de crédito
-      {
-        pattern: "\\b\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}\\b",
-        replaceWith: "****-****-****-****",
-      },
-      // CURP (México)
-      {
-        pattern: "[A-Z]{4}\\d{6}[HM][A-Z]{5}[A-Z0-9]\\d",
-        replaceWith: "****CURP****",
-      },
-      // Números de cuenta bancaria
-      {
-        pattern: "\\b\\d{10,20}\\b",
-        replaceWith: "****ACCOUNT****",
-      },
-      // Tokens JWT
-      {
-        pattern: "eyJ[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*",
-        replaceWith: "****JWT****",
-      },
-    ],
-  },
-});
-```
+import { ILogger } from "@jmlq/logger";
+import express, { Request, Response, NextFunction } from "express";
+import router from "./routes";
+import { randomUUID } from "crypto";
+
+// Middleware para adjuntar logger por request
+function attachLogger(base: ILogger) {
+  return async (req: Request, _res: Response, next: NextFunction) => {
+    req.logger = base;
+    req.requestId = (req.headers["x-request-id"] as string) ?? randomUUID();
+    next();
+  };
+}
 
-## Filtrado de Registros
+export function createServer(base: ILogger) {
+  const app = express();
+  app.use(express.json());
+  app.use(attachLogger(base));
 
-### Filtros Básicos
+  // Aquí se montan las rutas que llamarán a tus casos de uso
+  // <-- los handlers pueden usar req.logger
 
-```ts
-// Obtener todos los logs de nivel ERROR o superior
-const errors = await logger.getLogs({
-  levelMin: LogLevel.ERROR,
-});
+  app.get("/health", (_req, res) => res.json({ ok: true }));
 
-// Filtrar por rango de fechas
-const yesterday = Date.now() - 24 * 60 * 60 * 1000;
-const recentLogs = await logger.getLogs({
-  since: yesterday,
-  until: Date.now(),
-});
+  // IMPORTANTE: Siempre colocar un errorHandler al final
 
-// Búsqueda por texto
-const userLogs = await logger.getLogs({
-  query: "usuario",
-  limit: 50,
-});
+  return app;
+}
 ```
 
-### Filtros Avanzados
+En tus controladores, la idea es:
 
 ```ts
-// Combinación de filtros
-const criticalRecentErrors = await logger.getLogs({
-  levelMin: LogLevel.ERROR,
-  since: Date.now() - 2 * 60 * 60 * 1000, // Últimas 2 horas
-  query: "database connection",
-  limit: 20,
-  offset: 0,
+// controlador de ejemplo (no incluido en este archivo)
+req.logger?.info("user.create.request", {
+  requestId: req.requestId,
+  // aquí podrías pasar info de la request (sin PII sensible)
 });
 
-// Paginación
-const page1 = await logger.getLogs({ limit: 10, offset: 0 });
-const page2 = await logger.getLogs({ limit: 10, offset: 10 });
+// aquí llamarías al caso de uso correspondiente (no se implementa en este doc)
 ```
 
-## Variables de Entorno
+---
 
-```bash
-# Nivel mínimo de logs
-LOG_LEVEL=info
+## PASO 4 – BOOTSTRAP DE LA APLICACIÓN (Express + logger)
 
-# Filesystem
-LOG_FS_ENABLED=true
-LOG_FS_PATH=./logs
+Path sugerido: `src/app.ts`
 
-# MongoDB (si usas @jmlq/logger-plugin-mongo)
-LOG_MONGO_ENABLED=true
-LOG_MONGO_URL=mongodb://localhost:27017
-LOG_MONGO_DB=logs
+Aquí se orquesta todo:
 
-# PostgreSQL (si usas @jmlq/logger-plugin-postgresql)
-LOG_PG_ENABLED=true
-LOG_PG_HOST=localhost
-LOG_PG_PORT=5432
-LOG_PG_DATABASE=logs
-LOG_PG_USERNAME=logger
-LOG_PG_PASSWORD=secret
-```
+```ts
+import { envs } from "./config/plugins";
+import {
+  disposeLogs,
+  flushLogs,
+  loggerReady,
+} from "./infrastructure/adapters/jmlq/logger";
+import { createServer } from "./presentation/server";
+
+async function bootstrap() {
+  const logger = await loggerReady;
+
+  const app = createServer(logger);
+  const server = app.listen(envs.PORT, envs.HOST, () => {
+    console.log(`🚀 Server running at http://${envs.HOST}:${envs.PORT}`);
+    logger.info("http.start", { host: envs.HOST, port: envs.PORT });
+  });
 
-## Ejemplo Completo
+  server.on("error", async (err: any) => {
+    logger.error("http.listen.error", {
+      message: err?.message,
+      stack: err?.stack,
+    });
+    await flushLogs().catch(() => {});
+    await disposeLogs().catch(() => {});
+    process.exit(1);
+  });
 
-```ts
-import { LoggerFactory, LogLevel } from "@jmlq/logger";
-
-// Configuración completa
-const logger = await LoggerFactory.create({
-  datasources: [
-    // Múltiples datasources
-    new FileSystemDatasource({ basePath: "./logs" }),
-    new MongoDatasource({ url: "mongodb://localhost:27017", dbName: "logs" }),
-  ],
-  minLevel: LogLevel.DEBUG,
-  redactorOptions: {
-    enabled: true,
-    deep: true,
-    includeDefaults: true,
-    patterns: [
-      {
-        pattern: "\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b",
-        replaceWith: "****-****-****-****",
-      },
-    ],
-  },
-});
+  // Señales de apagado limpio
+  const shutdown = async (reason: string, code = 0) => {
+    logger.info("app.shutdown.begin", { reason });
+    server.close(async () => {
+      try {
+        await flushLogs();
+      } catch {}
+      try {
+        await disposeLogs();
+      } catch {}
+      logger.info("app.shutdown.end", { code });
+      process.exit(code);
+    });
+  };
 
-// Uso con diferentes niveles
-await logger.debug("Debug info", { userId: 123 });
-await logger.info("User login", { email: "user@example.com" });
-await logger.warn("High latency", { endpoint: "/api/users", duration: 950 });
-await logger.error("Database error", { error: "Connection timeout" });
-await logger.fatal("System crash", { stack: error.stack });
-
-// Filtrar y consultar logs
-const recentErrors = await logger.getLogs({
-  levelMin: LogLevel.ERROR,
-  since: Date.now() - 24 * 60 * 60 * 1000,
-  limit: 100,
-});
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
 
-// Limpiar buffers (útil antes de cerrar la aplicación)
-await logger.flush();
+  // Fallos no controlados
+  process.on("unhandledRejection", async (err) => {
+    const e = err as any;
+    logger.error("unhandled.rejection", {
+      message: e?.message,
+      stack: e?.stack,
+    });
+    // Aquí se podría enviar una notificación (email, etc.)
+    await shutdown("unhandledRejection", 1);
+  });
+
+  process.on("uncaughtException", async (err) => {
+    logger.error("uncaught.exception", {
+      message: err.message,
+      stack: err.stack,
+    });
+    // Aquí se podría enviar una notificación (email, etc.)
+    await shutdown("uncaughtException", 1);
+  });
+}
+
+bootstrap().catch(async (err) => {
+  // Falla durante el bootstrap
+  const logger = await loggerReady.catch(() => null);
+  if (logger) {
+    logger.error("bootstrap.fatal", {
+      message: (err as Error)?.message,
+      stack: (err as Error)?.stack,
+    });
+    await flushLogs().catch(() => {});
+    await disposeLogs().catch(() => {});
+  } else {
+    // Último recurso si el logger no llegó a inicializar
+    console.error("Fatal error (no logger):", err);
+  }
+  process.exit(1);
+});
 ```
 
-## Plugins Disponibles
+Puntos clave:
 
-> - `@jmlq/logger-plugin-fs`: Persistencia en archivos
-> - `@jmlq/logger-plugin-mongo`: Persistencia en MongoDB
-> - `@jmlq/logger-plugin-postgresql`: Persistencia en PostgreSQL
+- `loggerReady` asegura que el logger está inicializado antes de levantar HTTP.
+- `flushLogs` y `disposeLogs` se usan:
+  - En errores de `server.listen`.
+  - En apagado por señales.
+  - En fallos no controlados.
 
-Cada plugin se instala por separado según las necesidades de tu aplicación.
+---
 
-## Consideraciones de Rendimiento
+### Filtros Avanzados
 
-Los logs se procesan de forma asíncrona
-Múltiples datasources escriben en paralelo
-Usa [flush()](./examples/logger-factory.example.ts) antes de cerrar la aplicación para asegurar que todos los logs se persistan
-Configura límites apropiados en las consultas para evitar sobrecarga de memoria
+```ts
+// Paginación
+const page1 = await logger.getLogs({ limit: 10, offset: 0 });
+const page2 = await logger.getLogs({ limit: 10, offset: 10 });
+```
+
+## 🔧 Configuración con Variables de Entorno
+
+```env
+###############################################
+# @jmlq/logger – Dummy Environment Variables
+###############################################
+
+# ---------------------------------------------
+# Nivel mínimo del logger
+# Valores: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
+# ---------------------------------------------
+LOG_LEVEL=INFO
+
+# ---------------------------------------------
+# Protección de PII (datos sensibles)
+# ---------------------------------------------
+LOGGER_PII_ENABLED=true
+LOGGER_PII_INCLUDE_DEFAULTS=false
+
+# ---------------------------------------------
+# FileSystem Plugin
+# ---------------------------------------------
+LOGGER_FS_PATH=./logs
+
+# ---------------------------------------------
+# MongoDB Plugin
+# ---------------------------------------------
+LOGGER_MONGO_DB_URL=mongodb://demo_user:demo_pass@localhost:27018/?authSource=admin
+LOGGER_MONGO_DB_NAME=logger_demo_db
+LOGGER_MONGO_COLLECTION_NAME=logger_demo_logs
+
+# ---------------------------------------------
+# PostgreSQL Plugin
+# ---------------------------------------------
+LOGGER_PG_CONNECTION_STRING=postgres://demo_user:demo_pass@localhost:5436/logger_demo_db
+LOGGER_PG_TABLE_NAME=logger_demo_table
+LOGGER_PG_SCHEMA=public
+
+```