@jmlq/logger-plugin-fs 0.1.0-alpha.10 → 0.1.0-alpha.11

package/README.md

@@ -1,49 +1,454 @@
 # @jmlq/logger-plugin-fs
 
+## Introducción técnica
+
 Plugin de **sistema de archivos** para [`@jmlq/logger`](https://www.npmjs.com/package/@jmlq/logger). Permite persistir logs en archivos con soporte para rotación automática, manejo de backpressure y configuración flexible de formato y estructura de archivos.
 
+El plugin se encarga de:
+
+- Persistencia de logs en File System
+- Rotación automática de archivos por fecha o tamaño
+- Búsqueda y filtrado de logs históricos
+- Gestión eficiente de streams de escritura
+
+---
+
+## Componentes principales expuestos
+
+### Factory
+
+- **[`createFsDatasource`](src/application/factory/create-fs-datasource.factory.ts)**  
+  Factory de alto nivel que construye un `ILogDatasource` compatible con `@jmlq/logger`, resolviendo internamente:
+
+  - Cliente File System con adaptadores específicos de Node.js
+  - Casos de uso para persistencia, rotación y búsqueda
+  - Adaptadores de infraestructura para operaciones de archivos
+
+  > Es el **único punto recomendado de entrada** para consumidores del paquete.
+
+---
+
+### Tipos de configuración
+
+- **[`IFilesystemDatasourceOptions`](src/application/types/filesystem-datasource-options.type.ts)**  
+  Define la configuración necesaria para crear el datasource de File System:
+  - `basePath`: Directorio base donde se almacenarán los logs
+  - `fileNamePattern`: Patrón de nombres con tokens de fecha
+  - `rotation`: Configuración de rotación automática
+  - `mkdir`: Creación automática de directorios
+  - `onRotate`: Callback ejecutado al rotar archivos
+  - `onError`: Manejador de errores personalizado
+
+---
+
+## Contratos (Types / Ports)
+
+Estos tipos existen para **desacoplar el dominio y la aplicación del File System**.  
+Son útiles para testing, extensiones avanzadas o integraciones personalizadas.
+
+- **[`IFileSystemRotationConfig`](src/infrastructure/filesystem/types/filesystem-rotation.type.ts)**: Define estrategias de rotación (día, tamaño, ninguna)
+- **[`FsRotationBy`](src/domain/types/fs-rotation-by.type.ts)**: Enum con tipos de rotación disponibles
+- **[`FilePath`](src/domain/value-objects/file-path.vo.ts)**: Value Object para rutas de archivos con validaciones
+- **[`FileSize`](src/domain/value-objects/file-size.vo.ts)**: Value Object para tamaños de archivos con conversiones
+- **[`FileRotationPolicy`](src/domain/value-objects/file-rotation-policy.vo.ts)**: Encapsula la política de rotación configurada
+- **[`FileNamePattern`](src/domain/value-objects/file-name-pattern.vo.ts)**: Maneja patrones de nombres con tokens de fecha
+
+---
+
 ## 📦 Instalación
 
 ```bash
 npm install @jmlq/logger @jmlq/logger-plugin-fs
 ```
 
-### Dependencias
+- `@jmlq/logger` >= 0.1.0-alpha.20
 
-El plugin requiere como peer dependency:
+---
 
-- `@jmlq/logger` >= 0.1.0-alpha.12
+## Configuración @jmlq/logger-plugin-fs
 
-> **Nota:** Este plugin requiere [`@jmlq/logger`](https://www.npmjs.com/package/@jmlq/logger) como dependencia principal.
+Se recomienda implementar en la capa `infrastructure` de la API REST que usa [`@jmlq/logger`](https://www.npmjs.com/package/@jmlq/logger) y [`@jmlq/logger-plugin-fs`](https://www.npmjs.com/package/@jmlq/logger-plugin-fs):
 
-## 🚀 Uso rápido
+> - **Adapter de infraestructura**
 
-```typescript
-import { LoggerFactory } from "@jmlq/logger";
-import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+```ts
+// Path Ejemplo: src/infrastructure/logger/fs/fs.adapter.ts
 
-// Crear datasource de filesystem
-const fsDatasource = createFsDatasource({
-  basePath: "./logs",
-  fileNamePattern: "app-{yyyy}{MM}{dd}.log",
-  rotation: { by: "day" },
-});
+import {
+  createFsDatasource,
+  IFilesystemDatasourceOptions,
+} from "@jmlq/logger-plugin-fs";
+import type { ILogDatasource } from "@jmlq/logger";
+
+export class FsAdapter {
+  private constructor(private readonly ds: ILogDatasource) {}
+  static create(opts: IFilesystemDatasourceOptions): FsAdapter | undefined {
+    try {
+      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);
+    }
+  }
+  get datasource(): ILogDatasource {
+    return this.ds;
+  }
+}
+```
+
+---
 
-// Crear logger usando la factory
-const logger = LoggerFactory.create([fsDatasource]);
+## Configuración @jmlq/logger
 
-// Usar el logger
-logger.info("Aplicación iniciada", { timestamp: new Date(), pid: process.pid });
-logger.error("Error de conexión", { service: "database", retries: 3 });
+### Variables de entorno
+
+El plugin no gestiona variables de entorno internamente, pero puedes implementar tu propia capa de configuración:
+
+```ini
+# Nivel mínimo de logs
+# Valores: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
+LOG_LEVEL=INFO
+# PII Protection
+LOGGER_PII_ENABLED=true
+LOGGER_PII_INCLUDE_DEFAULTS=false
+# FS Plugin Settings
+LOGGER_FS_PATH=./logs/
+```
+
+### Interface de configuración del paquete
+
+```ts
+// Path Ejemplo: src/infrastructure/logger/core/logger.bootstrap.options.ts
+
+import { LogLevel } from "@jmlq/logger";
+import { IFilesystemDatasourceOptions } from "@jmlq/logger-plugin-fs";
+
+export interface LoggerBootstrapOptions {
+  minLevel: LogLevel;
+  pii?: {
+    enabled?: boolean;
+    whitelistKeys?: string[];
+    blacklistKeys?: string[];
+    patterns?: any[];
+    deep?: boolean;
+    includeDefaults?: boolean;
+  };
+  adapters?: {
+    // NOTA: Opcional, depende de las necesidades del cliente
+    fs?: IFilesystemDatasourceOptions;
+  };
+}
+```
+
+### Implementación del Logger
+
+```ts
+// Path Ejemplo: src/infrastructure/logger/core/logger.bootstrap.ts
+
+import { type ILogDatasource, createLogger } from "@jmlq/logger";
+import { FsAdapter } from "../fs/fs.adapter";
+import { LoggerBootstrapOptions } from "./logger.bootstrap.options";
+
+export class LoggerBootstrap {
+  private constructor(
+    private readonly _logger: ReturnType<typeof createLogger>
+  ) {}
+
+  static async create(opts: LoggerBootstrapOptions): Promise<LoggerBootstrap> {
+    const dsList: ILogDatasource[] = [];
+
+    // NOTA: Opcional, depende de las necesidades del cliente
+    if (opts.adapters?.fs) {
+      const fs = FsAdapter.create(opts.adapters.fs);
+      if (fs) dsList.push(fs.datasource);
+    }
+    //----
+
+    if (dsList.length === 0)
+      throw new Error("[logger] No hay datasources válidos.");
+
+    const logger = createLogger({
+      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");
+
+    return new LoggerBootstrap(logger);
+  }
+
+  get logger() {
+    return this._logger;
+  }
+
+  // Limpia buffers pendientes antes del cierre
+  async flush() {
+    const logs = this._logger as any;
+    if (typeof logs.flush === "function") await logs.flush();
+  }
+
+  // Cierra recursos (conexiones, handles, etc.)
+  async dispose() {
+    const logs = this._logger as any;
+    if (typeof logs.dispose === "function") await logs.dispose();
+  }
+}
+```
+
+### Inicializador del Logger
+
+```ts
+// Path Ejemplo: src/infrastructure/logger/index.ts
+
+import { envs } from "../../../../config/plugins";
+// NOTA: envs es un archivo donde se leen variables de entorno .env
+import { LoggerBootstrap } from "./core/logger.bootstrap";
+import { parseLogLevel } from "./helper";
+// NOTA: parseLogLevel hace un match con los valores del objeto LogLevel de @jmlq/logger
+
+declare global {
+  var __LOGGER_BOOT__: Promise<LoggerBootstrap> | undefined;
+}
+
+async function init() {
+  return LoggerBootstrap.create({
+    minLevel: parseLogLevel(envs.logger.LOGGER_LEVEL),
+    pii: {
+      enabled: envs.logger.LOGGER_PII_ENABLED,
+      includeDefaults: envs.logger.LOGGER_PII_INCLUDE_DEFAULTS,
+      deep: true,
+      patterns: [
+        {
+          pattern: "\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b",
+          replaceWith: "****-****-****-****",
+        },
+        {
+          pattern: "[\\w.-]+@[\\w.-]+",
+          replaceWith: "***@***",
+        },
+      ],
+    },
+    adapters: {
+      // NOTA: Opcional, depende de las necesidades del cliente
+      fs: envs.logger.LOGGER_FS_PATH
+        ? {
+            basePath: envs.logger.LOGGER_FS_PATH,
+            fileNamePattern: "app-{yyyy}{MM}{dd}.log",
+            rotation: { by: "day" },
+            mkdir: true,
+            onRotate: (oldPath, newPath) => {
+              console.log(
+                `   [Rotate] Rotación completada: ${oldPath.absolutePath} → ${newPath.absolutePath}`
+              );
+            },
+            onError: (err) => {
+              console.error("   [Error Handler]", err.message);
+            },
+          }
+        : undefined,
+    },
+  });
+}
+
+// 1. Es una promesa singleton de LoggerBootstrap
+// 2. Usa el operador nullish-coalescing (??) para: Reutilizar 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 MongoDB/Postgres, file handles, etc.)
+export async function disposeLogs() {
+  const boot = await bootReady;
+  await boot.dispose();
+}
+```
+
+---
+
+## Configuración en Frameworks
+
+**NOTA**: Se sugiere realizarlo en la capa `presentation` de la API que implementa `@jmlq/logger` y/o sus plugins.
+
+### Express
+
+#### Crear middleware (opcional):
+
+Se puede realizar de la forma que el usuario considere conveniente
+
+```ts
+// Path Ejemplo: src/presentation/middlewares/attach-logger.middleware.ts
+
+import { ILogger } from "@jmlq/logger";
+import { randomUUID } from "crypto";
+import { Request, Response, NextFunction } from "express";
+
+/**
+ * Middleware factory que adjunta contexto de logging al request.
+ *
+ * Responsabilidades:
+ * 1. Inyectar un logger base accesible desde cualquier controller/middleware.
+ * 2. Garantizar un requestId único para trazabilidad y correlación de logs.
+ *
+ * No configura el logger ni emite logs:
+ * solo prepara el contexto por request.
+ */
+export function attachLogger(base: ILogger) {
+  /**
+   * Middleware de Express ejecutado en cada request HTTP.
+   */
+  return async (req: Request, _res: Response, next: NextFunction) => {
+    /**
+     * Se adjunta el logger al objeto Request para evitar:
+     * - imports globales
+     * - singletons
+     * - acoplamiento directo en controllers
+     */
+    req.logger = base;
+
+    /**
+     * Se asigna un identificador único por request.
+     *
+     * - Si el cliente ya envía "x-request-id" (ej. API Gateway, Load Balancer),
+     *   se reutiliza para mantener trazabilidad entre servicios.
+     * - Si no existe, se genera un UUID local.
+     */
+    req.requestId = (req.headers["x-request-id"] as string) ?? randomUUID();
+
+    /**
+     * Continúa el pipeline normal de Express.
+     */
+    next();
+  };
+}
+```
 
-// Cierre elegante
-process.on("SIGTERM", async () => {
-  await logger.flush();
-  await logger.dispose();
-  process.exit(0);
+#### Adjuntar middleware en el servidor
+
+```ts
+// Path Ejemplo: src/presentation/server.ts
+
+import { ILogger } from "@jmlq/logger";
+import express from "express";
+import { attachLogger } from "./middlewares";
+
+export function createServer(base: ILogger) {
+  const app = express();
+  app.use(express.json()); // <-- necesario para POST JSON
+  app.use(attachLogger(base));
+
+  app.get("/health", (_req, res) => res.json({ ok: true }));
+
+  return app;
+}
+```
+
+#### Iniciar servidor
+
+**NOTA**: Esto se realiza en la raíz de la API
+
+```ts
+// Path Ejemplo: src/app.ts
+
+import { envs } from "./config/plugins";
+import { disposeLogs, flushLogs, loggerReady } from "./infrastructure/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);
+  });
+
+  // 3) 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,
+    });
+    await shutdown("unhandledRejection", 1);
+  });
+
+  process.on("uncaughtException", async (err) => {
+    logger.error("uncaught.exception", {
+      message: err.message,
+      stack: err.stack,
+    });
+    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);
 });
 ```
 
+---
+
 ## ⚙️ Configuración del datasource
 
 El datasource de filesystem acepta las siguientes opciones de configuración:
@@ -52,7 +457,7 @@ El datasource de filesystem acepta las siguientes opciones de configuración:
 
 | Opción            | Tipo             | Descripción                                            | Por defecto                 |
 | ----------------- | ---------------- | ------------------------------------------------------ | --------------------------- |
-| `basePath`        | `string`         | Directorio base donde se guardarán los archivos de log | `"./logs"`                  |
+| `basePath`        | `string`         | Directorio base donde se guardarán los archivos de log | `"./logs/"`                 |
 | `fileNamePattern` | `string`         | Patrón para nombrar archivos con tokens de fecha       | `"app-{yyyy}{MM}{dd}.log"`  |
 | `rotation`        | `RotationConfig` | Configuración de política de rotación                  | `{ by: "day" }`             |
 | `mkdir`           | `boolean`        | Crear directorio base si no existe                     | `true`                      |
@@ -92,7 +497,7 @@ Crea un archivo nuevo cada día basado en fecha UTC:
 import { createFsDatasource } from "@jmlq/logger-plugin-fs";
 
 const datasource = createFsDatasource({
-  basePath: "./logs",
+  basePath: "./logs/",
   fileNamePattern: "app-{yyyy}{MM}{dd}.log",
   rotation: { by: "day" },
   onRotate: (oldPath, newPath) => {
@@ -109,7 +514,7 @@ Rota cuando el archivo alcanza el tamaño máximo especificado:
 
 ```typescript
 const datasource = createFsDatasource({
-  basePath: "./logs",
+  basePath: "./logs/",
   fileNamePattern: "app.log",
   rotation: {
     by: "size",
@@ -130,98 +535,15 @@ Mantiene un único archivo que crece indefinidamente:
 
 ```typescript
 const datasource = createFsDatasource({
-  basePath: "./logs",
+  basePath: "./logs/",
   fileNamePattern: "application.log",
   rotation: { by: "none" },
 });
 ```
 
-## 🧩 Ejemplo completo
-
-```typescript
-import { createFsDatasource } from "@jmlq/logger-plugin-fs";
-import { LogLevel } from "@jmlq/logger";
-
-const datasource = createFsDatasource({
-  basePath: "./logs",
-  fileNamePattern: "app-{yyyy}-{MM}-{dd}.log",
-  rotation: { by: "day" },
-  mkdir: true,
-  serializer: {
-    serialize(log: any) {
-      return JSON.stringify(log, null, 2);
-    },
-  },
-  onRotate: (oldPath, newPath) => {
-    console.log(`Rotación: ${oldPath.absolutePath} → ${newPath.absolutePath}`);
-  },
-  onError: (err) => {
-    console.error("Error en datasource:", err.message);
-  },
-});
-
-// Guardar logs
-await datasource.save({
-  level: LogLevel.INFO,
-  message: "Servidor iniciado correctamente",
-  timestamp: Date.now(),
-});
-
-await datasource.save({
-  level: LogLevel.DEBUG,
-  message: "Conectando a base de datos...",
-  timestamp: Date.now(),
-});
-
-// Cierre
-await datasource.flush();
-await datasource.dispose();
-```
-
-## 🧪 Testing
-
-```typescript
-import { createFsDatasource } from "@jmlq/logger-plugin-fs";
-import * as fs from "fs";
-import * as path from "path";
-
-describe("FileSystem Datasource", () => {
-  const testLogsPath = "./test-logs";
-
-  beforeEach(() => {
-    if (fs.existsSync(testLogsPath)) {
-      fs.rmSync(testLogsPath, { recursive: true });
-    }
-  });
-
-  test("debe crear archivo de log", async () => {
-    const datasource = createFsDatasource({
-      basePath: testLogsPath,
-      fileNamePattern: "test.log",
-      rotation: { by: "none" },
-    });
-
-    await datasource.save({
-      level: "info",
-      message: "Test message",
-      timestamp: new Date(),
-    });
-
-    await datasource.flush();
-
-    const logFile = path.join(testLogsPath, "test.log");
-    expect(fs.existsSync(logFile)).toBe(true);
-
-    const content = fs.readFileSync(logFile, "utf8");
-    expect(content).toContain("Test message");
-  });
-});
-```
-
 ## 📄 Más Información
 
 - **[Arquitectura Detallada](./architecture.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