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

package/README.md

@@ -1,6 +1,7 @@
 # @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.
+Datasource de `sistema de archivos` para [`@jmlq/logger`](https://www.npmjs.com/package/@jmlq/logger).
+Escribe cada evento de log como **línea** (JSONL por defecto) y soporta `rotación por día` o por `tamaño`, manejo de `backpressure/drain`, `flush()` y `dispose()`.
 
 ---
 
@@ -10,282 +11,198 @@ Plugin de sistema de archivos (FileSystem) para **@jmlq/logger**. Permite persis
 # 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.
+Este plugin **depende** de [`@jmlq/logger`](https://www.npmjs.com/package/@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”.
+### 📝 Resumen rápido
 
-```txt
-@jmlq/logger-plugin-fs/
-├─ src/
-│  ├─ index.ts                    # Implementa ILogDatasource escribiendo a disco y lo Exporta FileSystemDatasource
-├─ package.json
-└─ README.md
-```
+> - **`src/domain/`** — Reglas del negocio del plugin (sin dependencias de Node).
+>   > - **`contracts/`**
+>   >   > - `clock.contract.ts` — Puerto que abstrae el tiempo actual (`now()`), permite testear rotación sin depender de `Date.now()`.
+>   >   > - `file-rotator.port.ts` — Puerto para rotación: calcula path esperado, tamaño, índice, etc.
+>   >   > - `stream-writer.port.ts` — Puerto para escritura secuencial: `write`, `once("drain")`, `end`.
+>   > - **`value-objects/`**
+>   >   > - `file-name-pattern.vo.ts` — VO que encapsula el patrón de nombres (`{yyyy}{MM}{dd}`) con validación.
+>   >   > - `rotation-policy.vo.ts` — VO que define estrategia de rotación (`none | day | size`) con invariantes (`maxSizeMB > 0`).
+>   > - **`types/`**
+>   >   > - `options.type.ts` — Define `FsDatasourceOptions` y `IFsSerializer` (contrato de serialización de líneas).
+
+> - **`src/application/`** — Casos de uso (orquestan, no dependen de Node).
+>   > - **`dto/`**
+>   >   > - `save-log.dto.ts` — DTO de entrada: `{ log: ILog }`.
+>   > - **`use-cases/`**
+>   >   > - `rotate-if-needed.usecase.ts` — Decide si se rota: compara fecha/tamaño contra `RotationPolicy`.
+>   >   > - `append-log.usecase.ts` — Serializa y escribe línea; maneja backpressure (`write=false` → espera `drain`).
+>   >   > - `persist-log.usecase.ts` — Orquesta: asegura writer, rota si corresponde, escribe, dispara hooks.
+>   > - **`services/`**
+>   >   > - `fs-datasource.service.ts` — Implementa `ILogDatasource` del core usando los UC anteriores.
+
+> - **`src/infrastructure/`** — Adaptadores técnicos (Node.js).
+>   > - **`fs/`**
+>   >   > - `fs-provider.ts` — Wrapper de `fs`/`fs.promises` (mockeable en tests).
+>   >   > - `path-utils.ts` — Utilidades para `join`, `splitBaseExt`, `formatPattern` (UTC).
+>   >   > - `file-rotator.adapter.ts` — Implementa `IFileRotatorPort` usando `fs-provider` y `path-utils`.
+>   >   > - `fs-writer.adapter.ts` — Implementa `IStreamWriterPort` con `fs.createWriteStream`.
+>   >   > - `node-clock.adapter.ts` — Implementa `IClock` devolviendo `new Date()`.
+
+> - **`src/presentation/`** — API pública (cara del paquete).
+>   > - **`factory/`**
+>   >   > - `create-fs-datasource.ts` — Ensambla VO + adaptadores + casos de uso y devuelve un `ILogDatasource`.
+>   > - `index.ts` — Barrel: reexporta la factory y VO/contratos públicos (`RotationPolicy`, `FileNamePattern`).
+
+#### [VER MAS](./ARQUITECTURA.md)
+
+## 🧩 Configuración
 
-### 📝 Resumen rápido
+### 🔐 Variables de Entorno (.env)
 
-> - **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.
+```ini
+# Ruta base (carpeta) para los archivos de log
+LOGGER_FS_PATH=./logs
 
----
+# Patrón (opcional). Si omites, usa "app-{yyyy}{MM}{dd}.log"
+LOGGER_FS_PATTERN=app-{yyyy}{MM}{dd}.log
 
-### 🧩 Configuración
+# Rotación: "day" | "size" | "none"
+LOGGER_FS_ROTATION=day
+LOGGER_FS_MAX_SIZE_MB=50
 
-Configurar la ruta del archivo y el nivel mínimo de log vía variables de entorno (nombres sugeridos; adáptalos en el proyecto):
+# Logger core
+LOGGER_LEVEL=info  # trace|debug|info|warn|error|fatal
 
-### 🔐 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
+### 🚀 Uso del paquete
 
-# --- (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
+```tsx
+import { createLogger, LogLevel } from "@jmlq/logger";
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+
+const ds = createFsDatasource({
+  basePath: "./logs", // Carpeta destino
+  mkdir: true, // Crea carpeta si no existe
+  fileNamePattern: "app-{yyyy}{MM}{dd}.log", // Rotación diaria por fecha (UTC)
+  // Alternativa por tamaño:
+  // rotation: { by: "size", maxSizeMB: 50 }
+  rotation: { by: "day" },
+  // Serializador opcional (por defecto JSON.stringify)
+  // serializer: { serialize: (log) => formatMyLine(log) },
+  onRotate: (oldP, newP) => console.log("[fs] rotated:", oldP, "->", newP),
+  onError: (e) => console.error("[fs] error:", e),
+});
+
+const logger = createLogger(ds, { minLevel: LogLevel.INFO });
+
+logger.info("Servidor iniciado", { pid: process.pid });
+
+// Cierre elegante
+process.on("SIGTERM", async () => {
+  await logger.flush?.();
+  await logger.dispose?.();
+  process.exit(0);
+});
+```
+
+También:
 
+```ts
+import { createLogger, LogLevel } from "@jmlq/logger";
+import {
+  createFsDatasource,
+  RotationPolicy,
+  FileNamePattern,
+} from "@jmlq/logger-plugin-fs";
+
+// Validación/invariantes tempranas con VO (throws si es inválido)
+const pt = new FileNamePattern("app-{yyyy}{MM}{dd}.log");
+const rt = new RotationPolicy("size", 50 /* maxSizeMB */);
+
+const ds = createFsDatasource({
+  basePath: "./logs",
+  mkdir: true,
+  // La factory acepta primitives; usamos los VO arriba solo para validar/centrar la decisión
+  fileNamePattern: pt.pattern,
+  rotation: { by: rt.by, maxSizeMB: rotation.maxSizeMB },
+});
+
+const logger = createLogger(ds, { minLevel: LogLevel.INFO });
 ```
 
-Sugerencia: crea el directorio `./logs` en tu entorno local o asegúrate de que el proceso tenga permisos de escritura en la ruta indicada.
+#### ⚙️ Opciones soportadas
+
+> - `basePath: string` – carpeta donde se guardan los logs.
+> - `mkdir?: boolean` – crea la carpeta si no existe.
+> - `fileNamePattern?: string` – tokens {yyyy}{MM}{dd} (formateados en UTC).
+>   > - Ejemplos: `"app-{yyyy}{MM}{dd}.log"`, `"service.log"`.
+> - `rotation?: { by: "none" | "day" | "size"; maxSizeMB?: number; maxFiles?: number }`
+>   > - `day` → rota al cambiar la fecha (UTC).
+>   > - `size` → rota al alcanzar `maxSizeMB` (genera app.1.log, app.2.log, …).
+> - `serializer?: { serialize(entry: unknown): string }` – una línea sin `\n`.
+> - `onRotate?: (oldPath, newPath) => void | Promise<void>`
+> - `onError?: (err) => void | Promise<void>`
 
 ---
 
-### 🚀 Uso del paquete
+### 🗂️ Formato de archivo
 
-#### 1) Crea un wrapper: `rotating-fs.datasource.ts`
+> - **Una línea por evento** (JSONL por defecto).
+> - El `serializer` determina el formato de cada línea (sin salto).
+> - El plugin agrega `"\n"` y maneja `backpressure`/`drain` del stream.
 
-```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**
+### 🔁 Rotación
 
-> - 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.
+**Por día **(`rotation: { by: "day" }`)
 
-#### 2) Configuración (solo FS)
+> - El archivo activo se calcula con `fileNamePattern` usando la `fecha UTC actual`.
+> - Si al persistir cambia el día → `cierra` el stream anterior, abre uno nuevo y dispara `onRotate(old, new)`.
 
-```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();
-}
-```
+**Por tamaño** (`rotation: { by: "size", maxSizeMB }`)
 
-#### 3) Comportamiento esperado
+> - Comprueba el tamaño del archivo activo. Si `>= maxSizeMB` → rota a `app.1.log`, `app.2.log`, … (buscando el siguiente índice libre).
 
-Con `.env`
+---
 
-```ini
-LOGGER_FS_PATH=./logs/app.log
+### 🧯 Backpressure & drain (cómo evita perder logs)
 
-```
+Node.js devuelve `false` en `stream.write()` cuando el **buffer interno está lleno** (backpressure).
+El plugin:
 
-> - 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.
+1. Serializa el log + `"\n"`.
+2. Llama `write(...)`.
+3. Si devuelve `false`, **espera el evento** `drain` antes de continuar.
+4. `flush()` espera a que se libere el buffer si `writableNeedDrain` es `true`.
+5. `dispose()` cierra el stream actual drenando el buffer pendiente.
 
 ---
 
-#### Consideraciones y opciones
+### 🌐 Zona horaria
 
-> - **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.
+> - El formateo `{yyyy}{MM}{dd}` del patrón se realiza en **UTC** para evitar desfases por huso horario (máquinas/CI distintas).
+> - Si necesitas otro criterio (p.ej., “día de Guayaquil”), puedes:
+>   > - Ajustar el **IClock** para proveer el “ahora” en otro huso y/o
+>   > - Reemplazar el util de formateo si deseas `{…}` en local time.
+
+---
+
+## ❓ FAQ
+
+**¿Puedo usar mi propio serializador?**
+Sí. Pasa serializer: { serialize: (log) => "mi-línea" }. Debe devolver una sola línea sin `\n`.
+
+**¿Qué pasa si el proceso se detiene en medio de un write?**
+Usamos los mecanismos de `Writable` (buffer + `drain`) y exponemos `flush()`/`dispose()` para el cierre. Llama a ambos en shutdown.
+
+**¿Puedo rotar por hora?**
+No out-of-the-box. Puedes implementar un **FileNamePattern** por hora (ej. `app-{yyyy}{MM}{dd}-{HH}.log`) + un `RotateIfNeededUseCase` extendido.
+
+---
 
 ## 📄 Licencia
 

package/dist/application/dto/index.d.ts

@@ -0,0 +1 @@
+export * from "./save-log.dto";

package/dist/application/dto/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./save-log.dto"), exports);

package/dist/application/dto/save-log.dto.d.ts

@@ -0,0 +1,4 @@
+import type { ILog } from "@jmlq/logger";
+export interface SaveLogDTO {
+    log: ILog;
+}

package/dist/application/dto/save-log.dto.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/application/services/fs-datasource.service.d.ts

@@ -0,0 +1,9 @@
+import type { ILogDatasource, ILog } from "@jmlq/logger";
+import { PersistLogUseCase } from "../use-cases";
+export declare class FsDatasourceService implements ILogDatasource {
+    private readonly persistUC;
+    constructor(persistUC: PersistLogUseCase);
+    save(log: ILog): Promise<void>;
+    flush(): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/application/services/fs-datasource.service.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsDatasourceService = void 0;
+class FsDatasourceService {
+    constructor(persistUC) {
+        this.persistUC = persistUC;
+    }
+    // Guarda un log (core llama esto). Orquesta vía PersistLogUseCase.
+    async save(log) {
+        const dto = { log };
+        await this.persistUC.execute(dto);
+    }
+    // Espera drenaje del buffer (útil para shutdown)
+    async flush() {
+        await this.persistUC.flush();
+    }
+    // Cierra recursos (stream)
+    async dispose() {
+        await this.persistUC.dispose();
+    }
+}
+exports.FsDatasourceService = FsDatasourceService;

package/dist/application/services/index.d.ts

@@ -0,0 +1 @@
+export * from "./fs-datasource.service";

package/dist/application/services/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./fs-datasource.service"), exports);

package/dist/application/use-cases/append-log.usecase.d.ts

@@ -0,0 +1,7 @@
+import { IFsSerializer, IStreamWriterPort } from "../../domain/contracts";
+import { SaveLogDTO } from "../dto";
+export declare class AppendLogUseCase {
+    private readonly serializer;
+    constructor(serializer: IFsSerializer);
+    execute(input: SaveLogDTO, writer: IStreamWriterPort): Promise<void>;
+}

package/dist/application/use-cases/append-log.usecase.js

@@ -0,0 +1,19 @@
+"use strict";
+// Serializa (línea + '\n') y escribe en el stream con manejo de backpressure.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppendLogUseCase = void 0;
+class AppendLogUseCase {
+    constructor(serializer) {
+        this.serializer = serializer;
+    }
+    async execute(input, writer) {
+        // 1) Serializa el log a texto + salto de línea
+        const line = this.serializer.serialize(input.log) + "\n";
+        // 2) Intenta escribir; si devuelve false, espera 'drain'
+        const ok = writer.write(line);
+        if (!ok) {
+            await new Promise((resolve) => writer.once("drain", resolve));
+        }
+    }
+}
+exports.AppendLogUseCase = AppendLogUseCase;

package/dist/application/use-cases/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./rotate-if-needed.usecase";
+export * from "./append-log.usecase";
+export * from "./persist-log.usecase";

package/dist/application/use-cases/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./rotate-if-needed.usecase"), exports);
+__exportStar(require("./append-log.usecase"), exports);
+__exportStar(require("./persist-log.usecase"), exports);

package/dist/application/use-cases/persist-log.usecase.d.ts

@@ -0,0 +1,23 @@
+import { AppendLogUseCase, RotateIfNeededUseCase } from ".";
+import { IFileRotatorPort, IStreamWriterPort } from "../../domain/contracts";
+import { SaveLogDTO } from "../dto";
+export declare class PersistLogUseCase {
+    private readonly rotateUC;
+    private readonly appendUC;
+    private readonly rotator;
+    private readonly openWriter;
+    private readonly onRotate?;
+    private readonly onError?;
+    constructor(rotateUC: RotateIfNeededUseCase, // caso de uso de rotación
+    appendUC: AppendLogUseCase, // caso de uso de escritura
+    rotator: IFileRotatorPort, // puerto para actualizar activePath
+    openWriter: (path: string) => IStreamWriterPort, // factory: abre stream
+    onRotate?: ((oldPath: string, newPath: string) => void | Promise<void>) | undefined, onError?: ((err: unknown) => void | Promise<void>) | undefined);
+    private writer;
+    private path;
+    private ensureWriter;
+    private disposeWriter;
+    execute(input: SaveLogDTO): Promise<void>;
+    flush(): Promise<void>;
+    dispose(): Promise<void>;
+}