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

package/dist/application/factory/create-fs-datasource.factory.d.ts

@@ -0,0 +1,16 @@
+import { IFilesystemDatasourceOptions } from "../../infrastructure/filesystem";
+import { ILogDatasource } from "../../domain/ports";
+/**
+ * createFsDatasource
+ * -----------------------------------------------------------------------------
+ * Composition Root del plugin FS.
+ *
+ * Responsabilidad:
+ * - Construir el grafo de dependencias (VOs, adapters, use-cases)
+ * - Exponer un ILogDatasource compatible con @jmlq/logger
+ *
+ * Clean Architecture:
+ * - Vive en infraestructura porque integra con el core externo (@jmlq/logger)
+ * - Application/domain permanecen sin dependencias externas.
+ */
+export declare function createFsDatasource(options: IFilesystemDatasourceOptions): ILogDatasource;

package/dist/application/factory/create-fs-datasource.factory.js

@@ -0,0 +1,51 @@
+"use strict";
+// import type { ILogDatasource } from "@jmlq/logger";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFsDatasource = createFsDatasource;
+const adapters_1 = require("../../infrastructure/adapters");
+const use_cases_1 = require("../../application/use-cases");
+const value_objects_1 = require("../../domain/value-objects");
+/**
+ * createFsDatasource
+ * -----------------------------------------------------------------------------
+ * Composition Root del plugin FS.
+ *
+ * Responsabilidad:
+ * - Construir el grafo de dependencias (VOs, adapters, use-cases)
+ * - Exponer un ILogDatasource compatible con @jmlq/logger
+ *
+ * Clean Architecture:
+ * - Vive en infraestructura porque integra con el core externo (@jmlq/logger)
+ * - Application/domain permanecen sin dependencias externas.
+ */
+function createFsDatasource(options) {
+    // ---------------------------------------------------------------------------
+    // 1) Value Objects (dominio)
+    // ---------------------------------------------------------------------------
+    const fileNamePattern = new value_objects_1.FileNamePattern(options.fileNamePattern || "app-{yyyy}{MM}{dd}.log");
+    const rotationPolicy = new value_objects_1.FileRotationPolicy(options.rotation?.by || "day", options.rotation?.maxSizeMB, options.rotation?.maxFiles);
+    // ---------------------------------------------------------------------------
+    // 2) Adapters (infraestructura)
+    // ---------------------------------------------------------------------------
+    const clock = new adapters_1.SystemClockAdapter();
+    const filePath = new adapters_1.SystemFilePathAdapter();
+    const fsProvider = new adapters_1.FileSystemProviderAdapter();
+    const writer = new adapters_1.LogStreamWriterAdapter();
+    const fileRotator = new adapters_1.FileRotatorAdapter(fsProvider, filePath, fileNamePattern, options.basePath);
+    // ---------------------------------------------------------------------------
+    // 3) Use-cases (application)
+    //    Nota: no se "exponen" fuera; PersistLog orquesta todo.
+    // ---------------------------------------------------------------------------
+    const ensureDirectoryUseCase = new use_cases_1.EnsureDirectoryUseCase(fsProvider, options.basePath, options.mkdir);
+    const appendLogUseCase = new use_cases_1.AppendLogUseCase(writer);
+    const rotateIfNeededUseCase = new use_cases_1.RotateIfNeededUseCase(fileRotator, writer, options.onRotate);
+    const persistLogUseCase = new use_cases_1.PersistLogUseCase(clock, fileRotator, writer, rotationPolicy, rotateIfNeededUseCase, appendLogUseCase, ensureDirectoryUseCase, options.onError);
+    // 3.x) FindLogs use-case + IO
+    const fileEnumerator = new adapters_1.FileSystemLogFileEnumeratorAdapter(options.basePath);
+    const lineReader = new adapters_1.FileSystemLogFileLineReaderAdapter();
+    const findLogsUseCase = new use_cases_1.FindLogsUseCase({ fileEnumerator, lineReader });
+    // ---------------------------------------------------------------------------
+    // 4) Adapter que expone el contrato del core (@jmlq/logger)
+    // ---------------------------------------------------------------------------
+    return new adapters_1.FsDatasourceAdapter(persistLogUseCase, writer, findLogsUseCase);
+}

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

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

package/dist/application/factory/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("./create-fs-datasource.factory"), exports);

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

@@ -0,0 +1,30 @@
+import { SaveLogRequest } from "../../domain/request";
+import { ILogStreamWriterPort } from "../../domain/ports";
+/**
+ * Contrato del caso de uso: permite ejecutar la operación "append log".
+ * Útil si quieres mockearlo en tests o exponerlo vía facade.
+ */
+export interface IAppendLogUseCase {
+    execute(dto: SaveLogRequest): Promise<void>;
+}
+/**
+ * AppendLogUseCase
+ * -----------------------------------------------------------------------------
+ * Caso de uso de Application que:
+ * - toma un log (request model),
+ * - lo serializa (serializer opcional o JSON por defecto),
+ * - asegura salto de línea,
+ * - lo escribe a través de un port (writer por stream).
+ *
+ * Clean Architecture:
+ * - depende de puertos del dominio (ILogStreamWriterPort)
+ * - NO depende de infraestructura directamente.
+ */
+export declare class AppendLogUseCase implements IAppendLogUseCase {
+    private readonly logStreamWriter;
+    constructor(logStreamWriter: ILogStreamWriterPort);
+    /**
+     * Ejecuta el caso de uso "append log".
+     */
+    execute(dto: SaveLogRequest): Promise<void>;
+}

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

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppendLogUseCase = void 0;
+/**
+ * AppendLogUseCase
+ * -----------------------------------------------------------------------------
+ * Caso de uso de Application que:
+ * - toma un log (request model),
+ * - lo serializa (serializer opcional o JSON por defecto),
+ * - asegura salto de línea,
+ * - lo escribe a través de un port (writer por stream).
+ *
+ * Clean Architecture:
+ * - depende de puertos del dominio (ILogStreamWriterPort)
+ * - NO depende de infraestructura directamente.
+ */
+class AppendLogUseCase {
+    constructor(
+    // Outbound port hacia infraestructura (writer de stream)
+    logStreamWriter) {
+        this.logStreamWriter = logStreamWriter;
+    }
+    /**
+     * Ejecuta el caso de uso "append log".
+     */
+    async execute(dto) {
+        const { log } = dto;
+        // 1) Serializar el log
+        let serializedData;
+        serializedData = JSON.stringify(log);
+        // 2) Asegurar salto de línea para escritura line-by-line
+        if (!serializedData.endsWith("\n")) {
+            serializedData += "\n";
+        }
+        // 3) Escribir al stream mediante el port (IO en infraestructura)
+        await this.logStreamWriter.write(serializedData);
+    }
+}
+exports.AppendLogUseCase = AppendLogUseCase;

package/dist/application/use-cases/ensure-directory.use-case.d.ts

@@ -0,0 +1,58 @@
+import { IFileSystemProviderPort } from "../../domain/ports";
+/**
+ * Contrato del caso de uso: asegura la existencia del directorio base.
+ */
+export interface IEnsureDirectoryUseCase {
+    execute(): Promise<void>;
+}
+/**
+ * EnsureDirectoryUseCase
+ * -----------------------------------------------------------------------------
+ * Caso de uso de Application que garantiza que exista un directorio.
+ *
+ * Clean Architecture:
+ * - Depende de un port de dominio (IFileSystemProviderPort) para IO.
+ * - No depende de infraestructura directamente.
+ *
+ * Comportamiento:
+ * - Si createIfNotExists es false, no hace nada (no side-effects).
+ * - Si el directorio no existe, lo crea (recursive).
+ */
+export declare class EnsureDirectoryUseCase implements IEnsureDirectoryUseCase {
+    /**
+     * Port de filesystem
+     */
+    private readonly fileSystemProvider;
+    /**
+     * Ruta del directorio base a asegurar.
+     * Nota: aquí se usa string; idealmente podría ser un VO (FilePath/DirectoryPath)
+     * si tu dominio ya lo maneja.
+     */
+    private readonly basePath;
+    /**
+     * Flag de configuración: si es false, el caso de uso es no-op.
+     */
+    private readonly createIfNotExists;
+    constructor(
+    /**
+     * Port de filesystem
+     */
+    fileSystemProvider: IFileSystemProviderPort, 
+    /**
+     * Ruta del directorio base a asegurar.
+     * Nota: aquí se usa string; idealmente podría ser un VO (FilePath/DirectoryPath)
+     * si tu dominio ya lo maneja.
+     */
+    basePath: string, 
+    /**
+     * Flag de configuración: si es false, el caso de uso es no-op.
+     */
+    createIfNotExists?: boolean);
+    /**
+     * Ejecuta la operación:
+     * - verifica existencia
+     * - crea el directorio si no existe
+     * - encapsula errores en un error de dominio
+     */
+    execute(): Promise<void>;
+}

package/dist/application/use-cases/ensure-directory.use-case.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnsureDirectoryUseCase = void 0;
+const errors_1 = require("../../infrastructure/errors");
+/**
+ * EnsureDirectoryUseCase
+ * -----------------------------------------------------------------------------
+ * Caso de uso de Application que garantiza que exista un directorio.
+ *
+ * Clean Architecture:
+ * - Depende de un port de dominio (IFileSystemProviderPort) para IO.
+ * - No depende de infraestructura directamente.
+ *
+ * Comportamiento:
+ * - Si createIfNotExists es false, no hace nada (no side-effects).
+ * - Si el directorio no existe, lo crea (recursive).
+ */
+class EnsureDirectoryUseCase {
+    constructor(
+    /**
+     * Port de filesystem
+     */
+    fileSystemProvider, 
+    /**
+     * Ruta del directorio base a asegurar.
+     * Nota: aquí se usa string; idealmente podría ser un VO (FilePath/DirectoryPath)
+     * si tu dominio ya lo maneja.
+     */
+    basePath, 
+    /**
+     * Flag de configuración: si es false, el caso de uso es no-op.
+     */
+    createIfNotExists = true) {
+        this.fileSystemProvider = fileSystemProvider;
+        this.basePath = basePath;
+        this.createIfNotExists = createIfNotExists;
+    }
+    /**
+     * Ejecuta la operación:
+     * - verifica existencia
+     * - crea el directorio si no existe
+     * - encapsula errores en un error de dominio
+     */
+    async execute() {
+        // Si la config indica no crear, salimos sin hacer nada.
+        if (!this.createIfNotExists) {
+            return;
+        }
+        try {
+            // El basePath ES el directorio que queremos asegurar.
+            const exists = await this.fileSystemProvider.exists(this.basePath);
+            if (!exists) {
+                await this.fileSystemProvider.mkdir(this.basePath, {
+                    recursive: true,
+                });
+            }
+        }
+        catch (error) {
+            // Error de dominio (no infraestructura) para mantener la dirección de dependencias.
+            throw errors_1.FileOperationError.create("mkdir", this.basePath, error);
+        }
+    }
+}
+exports.EnsureDirectoryUseCase = EnsureDirectoryUseCase;

package/dist/application/use-cases/find-logs-use-case.d.ts

@@ -0,0 +1,17 @@
+import { LogFilterRequest } from "../../domain/request";
+import { ILogFileEnumeratorPort, ILogFileLineReaderPort } from "../../domain/ports";
+import { ILogResponse } from "../../domain/response";
+export interface IFindLogsUseCase {
+    execute(filter?: LogFilterRequest): Promise<ILogResponse[]>;
+}
+export declare class FindLogsUseCase implements IFindLogsUseCase {
+    private readonly deps;
+    constructor(deps: {
+        fileEnumerator: ILogFileEnumeratorPort;
+        lineReader: ILogFileLineReaderPort;
+    });
+    execute(filter?: LogFilterRequest): Promise<ILogResponse[]>;
+    private matchesFilter;
+    private applyPagination;
+    private messageToText;
+}

package/dist/application/use-cases/find-logs-use-case.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FindLogsUseCase = void 0;
+class FindLogsUseCase {
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(filter) {
+        // if (!this.ds.find) return [];
+        const files = await this.deps.fileEnumerator.listLogFiles();
+        const records = [];
+        for (const file of files) {
+            for await (const line of this.deps.lineReader.readLines(file)) {
+                if (!line.trim())
+                    continue;
+                let record;
+                try {
+                    record = JSON.parse(line);
+                }
+                catch {
+                    continue; // línea corrupta → la ignoras
+                }
+                if (!this.matchesFilter(record, filter))
+                    continue;
+                records.push(record);
+            }
+        }
+        return this.applyPagination(records, filter);
+    }
+    matchesFilter(r, f) {
+        if (f?.levelMin != null && r.level < f.levelMin)
+            return false;
+        if (f?.since != null && r.timestamp < f.since)
+            return false;
+        if (f?.until != null && r.timestamp > f.until)
+            return false;
+        if (f?.query?.trim()) {
+            const q = f.query.trim().toLowerCase();
+            const msgText = this.messageToText(r.message).toLowerCase();
+            if (!msgText.includes(q))
+                return false;
+        }
+        return true;
+    }
+    applyPagination(records, f) {
+        const ordered = records.slice().sort((a, b) => a.timestamp - b.timestamp);
+        const limit = typeof f?.limit === "number" ? f.limit : ordered.length;
+        const page = typeof f?.offset === "number" ? f.offset : 0;
+        const slice = ordered.slice(page * limit, page * limit + limit);
+        return slice.reverse();
+    }
+    messageToText(message) {
+        if (typeof message === "string")
+            return message;
+        // message es objeto: lo convertimos a string para búsqueda simple
+        try {
+            return JSON.stringify(message);
+        }
+        catch {
+            return "";
+        }
+    }
+}
+exports.FindLogsUseCase = FindLogsUseCase;

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

@@ -0,0 +1,5 @@
+export * from "./append-log.use-case";
+export * from "./ensure-directory.use-case";
+export * from "./persist-log.use-case";
+export * from "./rotate-if-needed.use-case";
+export * from "./find-logs-use-case";

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

@@ -0,0 +1,21 @@
+"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("./append-log.use-case"), exports);
+__exportStar(require("./ensure-directory.use-case"), exports);
+__exportStar(require("./persist-log.use-case"), exports);
+__exportStar(require("./rotate-if-needed.use-case"), exports);
+__exportStar(require("./find-logs-use-case"), exports);

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

@@ -0,0 +1,96 @@
+import { ISystemClockPort, ILogStreamWriterPort, IFileRotatorPort } from "../../domain/ports";
+import { SaveLogRequest } from "../../domain/request";
+import { IAppendLogUseCase, IEnsureDirectoryUseCase, IRotateIfNeededUseCase } from ".";
+import { FileRotationPolicy } from "../../domain/value-objects";
+/**
+ * Contrato del caso de uso principal para persistir logs.
+ */
+export interface IPersistLogUseCase {
+    execute(dto: SaveLogRequest): Promise<void>;
+}
+/**
+ * PersistLogUseCase
+ * -----------------------------------------------------------------------------
+ * Caso de uso de Application que orquesta el flujo completo:
+ * - asegura el directorio base
+ * - decide si rota según política y fecha actual
+ * - garantiza que el stream está abierto en el archivo correcto
+ * - escribe el log (append)
+ *
+ * Nota (Clean Architecture):
+ * - No hace IO directamente: todo IO va por ports/use-cases delegados.
+ * - Centraliza la secuencia y manejo de errores del flujo.
+ */
+export declare class PersistLogUseCase implements IPersistLogUseCase {
+    /**
+     * Port para obtener la hora actual
+     */
+    private readonly systemClock;
+    /**
+     * Port relacionado con rotación/naming (según diseño actual).
+     * Idealmente: la parte de naming debería estar separada en un "namer".
+     */
+    private readonly fileRotator;
+    /**
+     * Writer por stream
+     */
+    private readonly streamWriter;
+    /**
+     * Política de rotación (VO de dominio).
+     */
+    private readonly rotationPolicy;
+    /**
+     * Use-case que ejecuta rotación si corresponde
+     */
+    private readonly rotateIfNeededUseCase;
+    /**
+     * Use-case que serializa y escribe el log al stream.
+     */
+    private readonly appendLogUseCase;
+    /**
+     * Use-case que asegura que el directorio base exista.
+     */
+    private readonly ensureDirectoryUseCase;
+    /**
+     * Hook opcional para reportar/registrar errores antes de relanzarlos.
+     */
+    private readonly onError?;
+    constructor(
+    /**
+     * Port para obtener la hora actual
+     */
+    systemClock: ISystemClockPort, 
+    /**
+     * Port relacionado con rotación/naming (según diseño actual).
+     * Idealmente: la parte de naming debería estar separada en un "namer".
+     */
+    fileRotator: IFileRotatorPort, 
+    /**
+     * Writer por stream
+     */
+    streamWriter: ILogStreamWriterPort, 
+    /**
+     * Política de rotación (VO de dominio).
+     */
+    rotationPolicy: FileRotationPolicy, 
+    /**
+     * Use-case que ejecuta rotación si corresponde
+     */
+    rotateIfNeededUseCase: IRotateIfNeededUseCase, 
+    /**
+     * Use-case que serializa y escribe el log al stream.
+     */
+    appendLogUseCase: IAppendLogUseCase, 
+    /**
+     * Use-case que asegura que el directorio base exista.
+     */
+    ensureDirectoryUseCase: IEnsureDirectoryUseCase, 
+    /**
+     * Hook opcional para reportar/registrar errores antes de relanzarlos.
+     */
+    onError?: ((error: Error) => void | Promise<void>) | undefined);
+    /**
+     * Ejecuta el flujo principal de persistencia del log.
+     */
+    execute(dto: SaveLogRequest): Promise<void>;
+}

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

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PersistLogUseCase = void 0;
+/**
+ * PersistLogUseCase
+ * -----------------------------------------------------------------------------
+ * Caso de uso de Application que orquesta el flujo completo:
+ * - asegura el directorio base
+ * - decide si rota según política y fecha actual
+ * - garantiza que el stream está abierto en el archivo correcto
+ * - escribe el log (append)
+ *
+ * Nota (Clean Architecture):
+ * - No hace IO directamente: todo IO va por ports/use-cases delegados.
+ * - Centraliza la secuencia y manejo de errores del flujo.
+ */
+class PersistLogUseCase {
+    constructor(
+    /**
+     * Port para obtener la hora actual
+     */
+    systemClock, 
+    /**
+     * Port relacionado con rotación/naming (según diseño actual).
+     * Idealmente: la parte de naming debería estar separada en un "namer".
+     */
+    fileRotator, 
+    /**
+     * Writer por stream
+     */
+    streamWriter, 
+    /**
+     * Política de rotación (VO de dominio).
+     */
+    rotationPolicy, 
+    /**
+     * Use-case que ejecuta rotación si corresponde
+     */
+    rotateIfNeededUseCase, 
+    /**
+     * Use-case que serializa y escribe el log al stream.
+     */
+    appendLogUseCase, 
+    /**
+     * Use-case que asegura que el directorio base exista.
+     */
+    ensureDirectoryUseCase, 
+    /**
+     * Hook opcional para reportar/registrar errores antes de relanzarlos.
+     */
+    onError) {
+        this.systemClock = systemClock;
+        this.fileRotator = fileRotator;
+        this.streamWriter = streamWriter;
+        this.rotationPolicy = rotationPolicy;
+        this.rotateIfNeededUseCase = rotateIfNeededUseCase;
+        this.appendLogUseCase = appendLogUseCase;
+        this.ensureDirectoryUseCase = ensureDirectoryUseCase;
+        this.onError = onError;
+    }
+    /**
+     * Ejecuta el flujo principal de persistencia del log.
+     */
+    async execute(dto) {
+        try {
+            // 1) Asegurar que el directorio base existe (si está habilitado)
+            await this.ensureDirectoryUseCase.execute();
+            // 2) Obtener "ahora" desde un port (testable)
+            const currentDate = this.systemClock.now();
+            // 3) Verificar si corresponde rotar según política/fecha
+            await this.rotateIfNeededUseCase.execute({
+                currentDate,
+                rotationPolicy: this.rotationPolicy,
+            });
+            // 4) Asegurar que el stream esté abierto en la ruta esperada
+            const expectedPath = this.fileRotator.getExpectedPathForDate(currentDate);
+            const currentPath = this.streamWriter.getCurrentPath();
+            // Reabrir si:
+            // - no está abierto
+            // - no hay path actual
+            // - el path actual no coincide con el esperado (por fecha/patrón)
+            if (
+            // Cerrar si estaba abierto (evita handles colgando)
+            !this.streamWriter.isOpen() ||
+                !currentPath ||
+                !currentPath.equals(expectedPath)) {
+                if (this.streamWriter.isOpen()) {
+                    await this.streamWriter.close();
+                }
+                // Abrir stream al archivo esperado
+                await this.streamWriter.open(expectedPath);
+            }
+            // 5) Escribir el log (serialización + newline + write)
+            await this.appendLogUseCase.execute(dto);
+        }
+        catch (error) {
+            // Hook opcional (log/metrics), pero se relanza el error para no ocultarlo
+            if (this.onError) {
+                await this.onError(error);
+            }
+            throw error;
+        }
+    }
+}
+exports.PersistLogUseCase = PersistLogUseCase;

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

@@ -0,0 +1,55 @@
+import { ILogStreamWriterPort, IFileRotatorPort } from "../../domain/ports";
+import { FilePath } from "../../domain/value-objects";
+import { RotateIfNeededRequest } from "../dto";
+/**
+ * Contrato del caso de uso: retorna el nuevo path si rotó, o null si no rotó.
+ */
+export interface IRotateIfNeededUseCase {
+    execute(dto: RotateIfNeededRequest): Promise<FilePath | null>;
+}
+/**
+ * RotateIfNeededUseCase
+ * -----------------------------------------------------------------------------
+ * Caso de uso de Application que:
+ * - determina si se debe rotar (según policy + fecha)
+ * - si aplica, cambia el writer al nuevo archivo (close/open)
+ * - ejecuta un hook opcional onRotate(oldPath, newPath)
+ *
+ * Nota:
+ * - Depende de ports (IO indirecto).
+ * - Existe potencial de duplicidad si otro use-case también asegura open/close.
+ */
+export declare class RotateIfNeededUseCase implements IRotateIfNeededUseCase {
+    /**
+     * Componente de rotación/naming (según diseño actual).
+     */
+    private readonly fileRotator;
+    /**
+     * Writer por stream usado para cerrar/abrir el archivo activo.
+     */
+    private readonly fileSystemWriter;
+    /**
+     * Hook opcional ejecutado cuando efectivamente se rota.
+     */
+    private readonly onRotate?;
+    constructor(
+    /**
+     * Componente de rotación/naming (según diseño actual).
+     */
+    fileRotator: IFileRotatorPort, 
+    /**
+     * Writer por stream usado para cerrar/abrir el archivo activo.
+     */
+    fileSystemWriter: ILogStreamWriterPort, 
+    /**
+     * Hook opcional ejecutado cuando efectivamente se rota.
+     */
+    onRotate?: ((oldPath: FilePath, newPath: FilePath) => void | Promise<void>) | undefined);
+    /**
+     * Ejecuta el flujo "rotar si hace falta".
+     * Retorna:
+     * - null si no corresponde rotar
+     * - newPath si rotó (o si el expected path es el nuevo destino)
+     */
+    execute(dto: RotateIfNeededRequest): Promise<FilePath | null>;
+}