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

package/README.md

@@ -0,0 +1,188 @@
+# @jmlq/logger-plugin-fs
+
+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()`.
+
+---
+
+## 📦 Instalación
+
+```bash
+# Con npm
+npm i @jmlq/logger @jmlq/logger-plugin-fs
+
+```
+
+Este plugin **depende** de [`@jmlq/logger`](https://www.npmjs.com/package/@jmlq/logger). Asegúrate de instalar ambos paquetes.
+
+## 🧱 Estructura del paquete
+
+### 📝 Resumen rápido
+
+> - **`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`).
+
+---
+
+### 🧩 Configuración
+
+### 🔐 Variables de Entorno (.env)
+
+```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
+
+# Rotación: "day" | "size" | "none"
+LOGGER_FS_ROTATION=day
+LOGGER_FS_MAX_SIZE_MB=50
+
+# Logger core
+LOGGER_LEVEL=info  # trace|debug|info|warn|error|fatal
+
+```
+
+---
+
+### 🚀 Uso del paquete
+
+```tsx
+import { createLogger, LogLevel } from "@jmlq/logger";
+import {
+  createFsDatasource,
+  RotationPolicy,
+  FileNamePattern,
+} 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);
+});
+```
+
+#### 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>`
+
+---
+
+### 🗂️ Formato de archivo
+
+> - **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.
+
+---
+
+### 🔁 Rotación
+
+**Por día **(`rotation: { by: "day" }`)
+
+> - 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)`.
+
+**Por tamaño** (`rotation: { by: "size", maxSizeMB }`)
+
+> - Comprueba el tamaño del archivo activo. Si `>= maxSizeMB` → rota a `app.1.log`, `app.2.log`, … (buscando el siguiente índice libre).
+
+---
+
+### 🧯 Backpressure & drain (cómo evita perder logs)
+
+Node.js devuelve `false` en `stream.write()` cuando el **buffer interno está lleno** (backpressure).
+El plugin:
+
+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.
+
+---
+
+### 🌐 Zona horaria
+
+> - 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
+
+MIT © Mauricio Lahuasi

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>;
+}

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

@@ -0,0 +1,74 @@
+"use strict";
+// Orquesta: (1) rotar si hace falta, (2) escribir línea, (3) hooks de rotación/errores.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersistLogUseCase = void 0;
+class PersistLogUseCase {
+    constructor(rotateUC, // caso de uso de rotación
+    appendUC, // caso de uso de escritura
+    rotator, // puerto para actualizar activePath
+    openWriter, // factory: abre stream
+    onRotate, onError) {
+        this.rotateUC = rotateUC;
+        this.appendUC = appendUC;
+        this.rotator = rotator;
+        this.openWriter = openWriter;
+        this.onRotate = onRotate;
+        this.onError = onError;
+        this.writer = null; // writer activo
+        this.path = null; // path activo
+    }
+    // Inicializa el writer si no existe (idempotente)
+    ensureWriter(currentPath) {
+        if (!this.writer) {
+            this.writer = this.openWriter(currentPath);
+            this.path = currentPath;
+        }
+    }
+    // Cierra writer activo de forma segura
+    async disposeWriter() {
+        if (!this.writer)
+            return;
+        await new Promise((resolve) => this.writer.end(resolve));
+        this.writer = null;
+    }
+    // Persistir un log con rotación condicional
+    async execute(input) {
+        try {
+            // 1) Asegurar writer inicial para el path actual del rotator
+            const currentPath = this.rotator.getActiveFilePath();
+            this.ensureWriter(currentPath);
+            // 2) Consultar si debemos rotar → abrir nuevo writer si hace falta
+            const nextPath = await this.rotateUC.execute();
+            if (nextPath) {
+                const old = this.path;
+                await this.disposeWriter();
+                this.rotator.setActivePath(nextPath);
+                this.writer = this.openWriter(nextPath);
+                this.path = nextPath;
+                // Notificar rotación (no bloqueante)
+                Promise.resolve(this.onRotate?.(old, nextPath)).catch((e) => this.onError?.(e));
+            }
+            // 3) Escribir línea manejando backpressure
+            await this.appendUC.execute(input, this.writer);
+        }
+        catch (err) {
+            // Notificar error sin tumbar el proceso (política del plugin)
+            await Promise.resolve(this.onError?.(err));
+            // Si quieres propagar al core, descomenta:
+            // throw err;
+        }
+    }
+    // Esperar drenaje del buffer
+    async flush() {
+        if (!this.writer)
+            return;
+        if (this.writer.writableNeedDrain) {
+            await new Promise((resolve) => this.writer.once("drain", resolve));
+        }
+    }
+    // Cerrar el writer activo
+    async dispose() {
+        await this.disposeWriter();
+    }
+}
+exports.PersistLogUseCase = PersistLogUseCase;

package/dist/application/use-cases/rotate-if-needed.usecase.d.ts

@@ -0,0 +1,10 @@
+import { IClock, IFileRotatorPort } from "../../domain/contracts";
+import { RotationPolicy } from "../../domain/value-objects";
+export declare class RotateIfNeededUseCase {
+    private readonly policy;
+    private readonly rotator;
+    private readonly clock;
+    private readonly maxSizeBytes?;
+    constructor(policy: RotationPolicy, rotator: IFileRotatorPort, clock: IClock, maxSizeBytes?: number | undefined);
+    execute(): Promise<string | null>;
+}

package/dist/application/use-cases/rotate-if-needed.usecase.js

@@ -0,0 +1,39 @@
+"use strict";
+// Caso de uso: evaluar si corresponde rotar el archivo y, si corresponde, devolver el nuevo path.
+// NO toca node:fs directamente; delega a servicios de infraestructura (rotator).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RotateIfNeededUseCase = void 0;
+class RotateIfNeededUseCase {
+    // Dependencias: política (VO), puerto de rotación y reloj.
+    constructor(policy, rotator, clock, maxSizeBytes // cache de bytes (derivado de policy.maxSizeMB)
+    ) {
+        this.policy = policy;
+        this.rotator = rotator;
+        this.clock = clock;
+        this.maxSizeBytes = maxSizeBytes;
+    }
+    // Devuelve null si no se requiere rotar; o el "nextPath" a usar si hay rotación.
+    async execute() {
+        // Selecciona estrategia según la política
+        if (this.policy.by === "none")
+            return null;
+        if (this.policy.by === "day") {
+            // Compara path actual vs path esperado para "hoy"
+            const now = this.clock.now();
+            const expected = this.rotator.expectedPathForToday(now);
+            return expected !== this.rotator.getActiveFilePath() ? expected : null;
+        }
+        if (this.policy.by === "size") {
+            // Si el archivo supera el umbral, pedimos un nuevo path indexado
+            const current = this.rotator.getActiveFilePath();
+            const size = await this.rotator.sizeOf(current);
+            const limit = this.maxSizeBytes ?? this.policy.maxSizeMB * 1024 * 1024;
+            if ((size ?? 0) >= limit) {
+                return await this.rotator.nextIndexedPath();
+            }
+            return null;
+        }
+        return null;
+    }
+}
+exports.RotateIfNeededUseCase = RotateIfNeededUseCase;

package/dist/domain/contracts/clock.contract.d.ts

@@ -0,0 +1,3 @@
+export interface IClock {
+    now(): Date;
+}

package/dist/domain/contracts/clock.contract.js

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

package/dist/domain/contracts/file-rotator.contract.d.ts

@@ -0,0 +1,7 @@
+export interface IFileRotatorPort {
+    getActiveFilePath(): string;
+    expectedPathForToday(now: Date): string;
+    sizeOf(path: string): Promise<number | null>;
+    nextIndexedPath(): Promise<string>;
+    setActivePath(next: string): void;
+}

package/dist/domain/contracts/file-rotator.contract.js

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

package/dist/domain/contracts/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./clock.contract";
+export * from "./serializer.contract";
+export * from "./file-rotator.contract";
+export * from "./stream-writer.port";

package/dist/domain/contracts/index.js

@@ -0,0 +1,20 @@
+"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("./clock.contract"), exports);
+__exportStar(require("./serializer.contract"), exports);
+__exportStar(require("./file-rotator.contract"), exports);
+__exportStar(require("./stream-writer.port"), exports);

package/dist/domain/contracts/serializer.contract.d.ts

@@ -0,0 +1,3 @@
+export interface IFsSerializer {
+    serialize(entry: unknown): string;
+}

package/dist/domain/contracts/serializer.contract.js

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

package/dist/domain/contracts/stream-writer.port.d.ts

@@ -0,0 +1,6 @@
+export interface IStreamWriterPort {
+    write(line: string): boolean;
+    once(event: "drain" | "error", cb: (...a: any[]) => void): void;
+    end(cb: () => void): void;
+    readonly writableNeedDrain?: boolean;
+}

package/dist/domain/contracts/stream-writer.port.js

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

package/dist/domain/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./options.type";

package/dist/domain/types/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("./options.type"), exports);

package/dist/domain/types/options.type.d.ts

@@ -0,0 +1,11 @@
+import { IFsSerializer } from "../contracts";
+import { FileNamePattern, RotationPolicy } from "../value-objects";
+export interface FsDatasourceOptions {
+    basePath: string;
+    mkdir?: boolean;
+    pattern?: FileNamePattern;
+    rotation?: RotationPolicy;
+    serializer?: IFsSerializer;
+    onRotate?: (oldPath: string, newPath: string) => void | Promise<void>;
+    onError?: (err: unknown) => void | Promise<void>;
+}

package/dist/domain/types/options.type.js

@@ -0,0 +1,5 @@
+"use strict";
+// Tipo de opciones de alto nivel del plugin, expuesto a la "presentación" (factory).
+// Reúne los contratos/VOs de dominio, pero sin detalles de node:fs.
+// Esto mantiene la API pública limpia y testeable.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/domain/value-objects/file-name-pattern.vo.d.ts

@@ -0,0 +1,4 @@
+export declare class FileNamePattern {
+    readonly pattern: string;
+    constructor(pattern: string);
+}

package/dist/domain/value-objects/file-name-pattern.vo.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileNamePattern = void 0;
+// Value Object para el patrón de nombre del archivo.
+// Soporta tokens {yyyy}, {MM}, {dd}; el formateo real ocurre en infraestructura.
+class FileNamePattern {
+    constructor(pattern) {
+        this.pattern = pattern;
+        if (!pattern || typeof pattern !== "string") {
+            throw new Error("[FileNamePattern] pattern inválido");
+        }
+    }
+}
+exports.FileNamePattern = FileNamePattern;

package/dist/domain/value-objects/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./file-name-pattern.vo";
+export * from "./rotation-policy.vo";

package/dist/domain/value-objects/index.js

@@ -0,0 +1,18 @@
+"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("./file-name-pattern.vo"), exports);
+__exportStar(require("./rotation-policy.vo"), exports);

package/dist/domain/value-objects/rotation-policy.vo.d.ts

@@ -0,0 +1,7 @@
+export type RotationBy = "none" | "day" | "size";
+export declare class RotationPolicy {
+    readonly by: RotationBy;
+    readonly maxSizeMB?: number | undefined;
+    readonly maxFiles?: number | undefined;
+    constructor(by: RotationBy, maxSizeMB?: number | undefined, maxFiles?: number | undefined);
+}