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

package/README.md

@@ -0,0 +1,551 @@
+# @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
+```
+
+- `@jmlq/logger` >= 0.1.0-alpha.20
+
+---
+
+## Configuración @jmlq/logger-plugin-fs
+
+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):
+
+> - **Adapter de infraestructura**
+
+```ts
+// Path Ejemplo: src/infrastructure/logger/fs/fs.adapter.ts
+
+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;
+  }
+}
+```
+
+---
+
+## Configuración @jmlq/logger
+
+### 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();
+  };
+}
+```
+
+#### 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:
+
+### Opciones principales
+
+| Opción            | Tipo             | Descripción                                            | Por defecto                 |
+| ----------------- | ---------------- | ------------------------------------------------------ | --------------------------- |
+| `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`                      |
+| `serializer`      | `LogSerializer`  | Serializador personalizado para el formato de líneas   | Serializer JSON por defecto |
+
+### Configuración de rotación
+
+```typescript
+interface RotationConfig {
+  by: "none" | "day" | "size";
+  maxSizeMB?: number; // Para rotación por tamaño
+  maxFiles?: number; // Límite de archivos rotados
+}
+```
+
+### Patrones de nombre de archivo
+
+Utiliza tokens que se reemplazan con valores de fecha (UTC):
+
+- `{yyyy}` - Año completo (ej: 2024)
+- `{MM}` - Mes con ceros (ej: 01, 12)
+- `{dd}` - Día con ceros (ej: 01, 31)
+
+**Ejemplos:**
+
+- `"app-{yyyy}{MM}{dd}.log"` → `app-20241201.log`
+- `"service-{yyyy}-{MM}-{dd}.log"` → `service-2024-12-01.log`
+- `"application.log"` → `application.log` (sin rotación por fecha)
+
+## 🔁 Políticas de rotación
+
+### Rotación por fecha
+
+Crea un archivo nuevo cada día basado en fecha UTC:
+
+```typescript
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+
+const datasource = createFsDatasource({
+  basePath: "./logs/",
+  fileNamePattern: "app-{yyyy}{MM}{dd}.log",
+  rotation: { by: "day" },
+  onRotate: (oldPath, newPath) => {
+    console.log(
+      `Log rotado: ${oldPath.absolutePath} → ${newPath.absolutePath}`
+    );
+  },
+});
+```
+
+### Rotación por tamaño
+
+Rota cuando el archivo alcanza el tamaño máximo especificado:
+
+```typescript
+const datasource = createFsDatasource({
+  basePath: "./logs/",
+  fileNamePattern: "app.log",
+  rotation: {
+    by: "size",
+    maxSizeMB: 50, // Rota al alcanzar 50MB
+    maxFiles: 10, // Mantiene máximo 10 archivos rotados
+  },
+  onRotate: (oldPath, newPath) => {
+    console.log(
+      `Archivo rotado por tamaño: ${oldPath.absolutePath} → ${newPath.absolutePath}`
+    );
+  },
+});
+```
+
+### Sin rotación
+
+Mantiene un único archivo que crece indefinidamente:
+
+```typescript
+const datasource = createFsDatasource({
+  basePath: "./logs/",
+  fileNamePattern: "application.log",
+  rotation: { by: "none" },
+});
+```
+
+## 📄 Más Información
+
+- **[Arquitectura Detallada](./architecture.md)** - Documentación técnica completa
+- **[Ejemplos](./examples/)** - Códigos de ejemplo funcionales
+
+## 📄 Licencia
+
+MIT © Mauricio Lahuasi