@jmlq/logger-plugin-fs 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -0,0 +1,292 @@
+# @jmlq/logger-plugin-fs
+
+Plugin de sistema de archivos (FileSystem) para **@jmlq/logger**. Permite persistir logs en archivos locales, ideal para entornos de desarrollo, servidores con volumen montado o como “sink” secundario junto a bases de datos.
+
+---
+
+## 📦 Instalación
+
+```bash
+# Con npm
+npm i @jmlq/logger @jmlq/logger-plugin-fs
+
+# Con pnpm
+pnpm add @jmlq/logger @jmlq/logger-plugin-fs
+
+# Con yarn
+yarn add @jmlq/logger @jmlq/logger-plugin-fs
+
+```
+
+Este plugin **depende** de `@jmlq/logger`. Asegúrate de instalar ambos paquetes.
+
+## 🧱 Estructura del paquete
+
+La estructura puede variar según tu versión; esta es la forma típica en librerías de “Clean Architecture”.
+
+```txt
+@jmlq/logger-plugin-fs/
+├─ src/
+│  ├─ index.ts                    # Implementa ILogDatasource escribiendo a disco y lo Exporta FileSystemDatasource
+├─ package.json
+└─ README.md
+```
+
+### 📝 Resumen rápido
+
+> - **Qué es**: Un `Datasource` para **@jmlq/logger** que escribe logs en un archivo.
+> - **Cuándo usarlo**: Desarrollo, staging, escrituras locales, sidecar para auditoría en disco.
+> - **Cómo se usa**: Instancia `FileSystemDatasource({ filePath })`, crea el logger con `createLogger`, y registra tus eventos.
+
+---
+
+### 🧩 Configuración
+
+Configurar la ruta del archivo y el nivel mínimo de log vía variables de entorno (nombres sugeridos; adáptalos en el proyecto):
+
+### 🔐 Variables de Entorno (.env)
+
+```ini
+# Archivo donde se guardarán los logs (crear carpeta si no existe)
+LOGGER_FS_PATH=./logs/app.log
+
+# Nivel mínimo de log aceptado por el logger global
+# Valores: trace|debug|info|warn|error|fatal
+LOGGER_LEVEL=info
+
+# --- (Opcional) Controles de PII ---
+# Activa redacción de datos sensibles
+LOGGER_PII_ENABLED=true
+# Incluye patrones por defecto del core, si tu build los expone
+LOGGER_PII_INCLUDE_DEFAULTS=true
+
+```
+
+Sugerencia: crea el directorio `./logs` en tu entorno local o asegúrate de que el proceso tenga permisos de escritura en la ruta indicada.
+
+---
+
+### 🚀 Uso del paquete
+
+#### 1) Crea un wrapper: `rotating-fs.datasource.ts`
+
+```tsx
+// src/config/logger/rotating-fs.datasource.ts
+import { dirname, extname, basename } from "node:path";
+import { existsSync, mkdirSync } from "node:fs";
+import { FileSystemDatasource } from "@jmlq/logger-plugin-fs";
+import type { ILog, ILogDatasource } from "@jmlq/logger";
+
+/** YYYYMMDD con hora local del servidor */
+function dateStamp(d = new Date()) {
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, "0");
+  const dd = String(d.getDate()).padStart(2, "0");
+  return `${yyyy}${mm}${dd}`;
+}
+
+/** Crea carpeta si falta */
+function ensureDirFor(filePath: string) {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/** Devuelve ruta diaria: ./logs/app-YYYYMMDD.log a partir de base ./logs/app.log */
+function dailyPath(basePath: string, stamp = dateStamp()) {
+  const ext = extname(basePath) || ".log";
+  const name = basename(basePath, ext);
+  const dir = dirname(basePath);
+  return `${dir}/${name}-${stamp}${ext}`;
+}
+
+/** Milisegundos hasta la próxima medianoche local */
+function msUntilNextMidnight() {
+  const now = new Date();
+  const next = new Date(
+    now.getFullYear(),
+    now.getMonth(),
+    now.getDate() + 1,
+    0,
+    0,
+    0,
+    0
+  );
+  return next.getTime() - now.getTime();
+}
+
+/**
+ * Datasource que rota el archivo a diario sin reiniciar el proceso.
+ * Estrategia:
+ * - Chequea fecha en cada save().
+ * - Agenda un timer para forzar rotación exacto a medianoche.
+ */
+export class RotatingDailyFSDatasource implements ILogDatasource {
+  private readonly basePath: string;
+  private currentStamp: string;
+  private inner: FileSystemDatasource;
+  private midnightTimer: NodeJS.Timeout | null = null;
+
+  constructor(opts: { basePath: string }) {
+    if (!opts.basePath) throw new Error("[logger] basePath requerido");
+    this.basePath = opts.basePath;
+    this.currentStamp = dateStamp();
+    const fp = dailyPath(this.basePath, this.currentStamp);
+    ensureDirFor(fp);
+    this.inner = new FileSystemDatasource({ filePath: fp });
+    this.armMidnightTimer();
+  }
+
+  /** Programa rotación en la próxima medianoche */
+  private armMidnightTimer() {
+    const delay = msUntilNextMidnight();
+    this.midnightTimer = setTimeout(() => {
+      // Forzamos rotación incluso si no llega ningún save()
+      this.rotateIfNeeded(/*force*/ true);
+      // Re-armar para el siguiente día
+      this.armMidnightTimer();
+    }, delay);
+    // Evita que el timer mantenga vivo el proceso si todo lo demás termina:
+    this.midnightTimer.unref?.();
+  }
+
+  /** Cierra el archivo actual y crea uno nuevo si cambió el día o si es forzado */
+  private async rotateIfNeeded(force = false) {
+    const today = dateStamp();
+    if (!force && today === this.currentStamp) return;
+
+    // Cerrar el datasource actual si expone dispose()
+    await this.inner.dispose?.().catch(() => {
+      /* no-op */
+    });
+
+    this.currentStamp = today;
+    const fp = dailyPath(this.basePath, this.currentStamp);
+    ensureDirFor(fp);
+    this.inner = new FileSystemDatasource({ filePath: fp });
+  }
+
+  /** Guarda un log; rota si el día cambió */
+  async save(log: ILog): Promise<void> {
+    // Rota on-demand si cambió la fecha
+    await this.rotateIfNeeded(false);
+    return this.inner.save(log);
+  }
+
+  /** Delegación opcional si el DS base lo implementa */
+  async find?(filter?: any): Promise<ILog[]> {
+    const maybe = (this.inner as any).find;
+    if (typeof maybe === "function") return maybe.call(this.inner, filter);
+    throw new Error("find() no soportado por FileSystemDatasource");
+  }
+
+  /** Intenta vaciar buffers si existe */
+  async flush?(): Promise<void> {
+    await this.inner.flush?.();
+  }
+
+  /** Cierra recursos, cancela timer */
+  async dispose?(): Promise<void> {
+    if (this.midnightTimer) {
+      clearTimeout(this.midnightTimer);
+      this.midnightTimer = null;
+    }
+    await this.inner.dispose?.();
+  }
+}
+```
+
+**Notas clave**
+
+> - Usa **hora local** del servidor. Si necesitas zona específica (p. ej. America/Guayaquil), conviene fijar el TZ del contenedor/host.
+> - `unref()` del timer ayuda a que el proceso pueda salir si no hay nada más pendiente.
+> - Si tu `FileSystemDatasource` no implementa `flush`/`dispose`, las llamadas son seguras con el optional chaining.
+
+#### 2) Configuración (solo FS)
+
+```ts
+// src/config/logger/index.ts
+import { envs } from "../plugins/envs.plugin";
+import { LogLevel, createLogger } from "@jmlq/logger";
+import type { ILogDatasource } from "@jmlq/logger";
+import { clientPiiPatterns, redactKeys, preserveKeys } from "./pii";
+import { RotatingDailyFSDatasource } from "./rotating-fs.datasource";
+
+/** Mapea string (.env) -> LogLevel */
+function toMinLevel(level: string): LogLevel {
+  switch (level?.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;
+  }
+}
+
+async function buildDatasource(): Promise<ILogDatasource> {
+  const basePath = envs.logger.LOGGER_FS_PATH;
+  if (!basePath) throw new Error("[logger] Falta LOGGER_FS_PATH en .env");
+
+  // << Cambio importante: datasource rotatorio >>
+  return new RotatingDailyFSDatasource({ basePath });
+}
+
+async function initLogger() {
+  const datasource = await buildDatasource();
+  return createLogger(datasource, {
+    minLevel: toMinLevel(envs.logger.LOGGER_LEVEL),
+    pii: {
+      enabled: envs.logger.LOGGER_PII_ENABLED,
+      includeDefaultPatterns: envs.logger.LOGGER_PII_INCLUDE_DEFAULTS,
+      patterns: clientPiiPatterns,
+      redactKeys,
+      preserveKeys,
+    },
+  });
+}
+
+export const loggerReady = initLogger();
+
+export async function flushLogs() {
+  const logger = (await loggerReady) as any;
+  if (typeof logger.flush === "function") await logger.flush();
+}
+
+export async function disposeLogs() {
+  const logger = (await loggerReady) as any;
+  if (typeof logger.dispose === "function") await logger.dispose();
+}
+```
+
+#### 3) Comportamiento esperado
+
+Con `.env`
+
+```ini
+LOGGER_FS_PATH=./logs/app.log
+
+```
+
+> - Hoy se escribe en: `./logs/app-YYYYMMDD.log`.
+> - En `pleno funcionamiento`, al llegar a medianoche local:
+>   > - El wrapper cierra el archivo anterior y abre `./logs/app-YYYYMMDD+1.log`.
+>   > - No pierdes logs y no necesitas reiniciar el servicio.
+
+---
+
+#### Consideraciones y opciones
+
+> - **Rotación por tamaño**: si además quieres limitar tamaño, se necesitaría añadir lógica extra (por ejemplo, chequear `fs.stat` y rotar al superar un umbral) o usar un transport que ya lo haga.
+> - **Compresión/retención**: se puede anexar un job (cron/worker) que comprima y borre archivos antiguos.
+
+## 📄 Licencia
+
+MIT © Mauricio Lahuasi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmlq/logger-plugin-fs",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "author": "MLahuasi",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",