@jmlq/logger 0.1.0-alpha.20 → 0.1.0-alpha.21

package/install.md

@@ -1,632 +0,0 @@
-# GUÍA DE CONFIGURACIÓN @jmlq/logger Y SUS PLUGINS
-
-## PASO 1 – BOOTSTRAP DEL LOGGER CORE
-
-### 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;
-  };
-}
-```
-
-- `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 ?? [],
-      },
-    });
-
-    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();
-  }
-}
-```
-
----
-
-## PASO 2 – CONFIGURAR PLUGINS / DATASOURCES
-
-### 2.1. Plugin FileSystem (`@jmlq/logger-plugin-fs`)
-
-Path sugerido: `src/infrastructure/adapters/jmlq/logger/fs/fs.adapter.ts`
-
-`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`.
-
-```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 {
-      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;
-  }
-}
-```
-
----
-
-### 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
-// 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);
-    }
-  }
-
-  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,
-      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,
-      //----
-    },
-  });
-}
-
-// Inicializar promesa Singleton
-export const bootReady: Promise<LoggerBootstrap> =
-  globalThis.__LOGGER_BOOT__ ?? (globalThis.__LOGGER_BOOT__ = init());
-
-// Acceso directo al logger
-export const loggerReady = bootReady.then((b) => b.logger);
-
-// Vaciar buffers antes de terminar el proceso
-export async function flushLogs() {
-  const boot = await bootReady;
-  await boot.flush();
-}
-
-// Cerrar recursos
-export async function disposeLogs() {
-  const boot = await bootReady;
-  await boot.dispose();
-}
-```
-
-**NOTA**: `parseLogLevel` es un helper para convertir un `string` en `LogLevel`:
-
-```ts
-import { LogLevel } from "@jmlq/logger";
-
-export function parseLogLevel(value?: string): LogLevel {
-  if (!value) return LogLevel.DEBUG; // fallback seguro
-
-  const normalized = value.toUpperCase();
-
-  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
-}
-```
-
----
-
-## PASO 3 – INTEGRACIÓN CON EXPRESS
-
-### 3.1. Extender `Request` con logger y requestId
-
-Path sugerido: `src/types/express.d.ts`
-
-```ts
-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;
-  }
-}
-```
-
-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
-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();
-  };
-}
-
-export function createServer(base: ILogger) {
-  const app = express();
-  app.use(express.json());
-  app.use(attachLogger(base));
-
-  // Aquí se montan las rutas que llamarán a tus casos de uso
-  // <-- los handlers pueden usar req.logger
-
-  app.get("/health", (_req, res) => res.json({ ok: true }));
-
-  // IMPORTANTE: Siempre colocar un errorHandler al final
-
-  return app;
-}
-```
-
-En tus controladores, la idea es:
-
-```ts
-// 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)
-});
-
-// aquí llamarías al caso de uso correspondiente (no se implementa en este doc)
-```
-
----
-
-## PASO 4 – BOOTSTRAP DE LA APLICACIÓN (Express + logger)
-
-Path sugerido: `src/app.ts`
-
-Aquí se orquesta todo:
-
-```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 });
-  });
-
-  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);
-  });
-
-  // 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);
-    });
-  };
-
-  process.on("SIGINT", () => shutdown("SIGINT"));
-  process.on("SIGTERM", () => shutdown("SIGTERM"));
-
-  // 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);
-});
-```
-
-Puntos clave:
-
-- `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.
-
----
-
-### Filtros Avanzados
-
-```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
-
-```