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

package/dist/infrastructure/adapters/file-rotator.adapter.d.ts

@@ -0,0 +1,79 @@
+import { IFileSystemProviderPort, IFilePathPort, IFileRotatorPort } from "../../domain/ports";
+import { FileSize, FilePath, FileRotationPolicy, FileNamePattern } from "../../domain/value-objects";
+/**
+ * Adapter de infraestructura que implementa IFileRotatorPort.
+ *
+ * Responsabilidad:
+ * - Calcular el path esperado del archivo de log en base a una fecha y un FileNamePattern.
+ * - Leer metadata real del filesystem (tamaño / listado de archivos).
+ * - Decidir si debe rotar (por día o por tamaño) apoyándose en la política del dominio.
+ *
+ * Nota:
+ * - Este adapter mantiene estado mínimo (`currentFilePath`) porque el Port lo requiere.
+ *   Aun así, evitamos mutaciones ocultas: solo se actualiza desde getExpectedPathForDate().
+ */
+export declare class FileRotatorAdapter implements IFileRotatorPort {
+    private readonly fsProvider;
+    private readonly filePathAdapter;
+    private readonly fileNamePattern;
+    private readonly basePath;
+    private currentFilePath;
+    private readonly baseDir;
+    private static readonly TOKEN_REGEX;
+    constructor(fsProvider: IFileSystemProviderPort, filePathAdapter: IFilePathPort, fileNamePattern: FileNamePattern, basePath: string);
+    /**
+     * Devuelve el último archivo considerado “actual” por el rotator.
+     * Puede ser null si aún no se ha calculado/solicitado un path.
+     */
+    getCurrentPath(): FilePath | null;
+    /**
+     * Calcula el path esperado para una fecha y lo “marca” como archivo actual.
+     * OJO: este es el único método que muta currentFilePath a propósito.
+     */
+    getExpectedPathForDate(date: Date): FilePath;
+    /**
+     * Calcula el FilePath esperado para una fecha usando el patrón.
+     * Método “puro”: NO muta estado.
+     */
+    private computePathForDate;
+    /**
+     * Reemplaza tokens de fecha dentro del patrón (ej. {yyyy}{MM}{dd}) por valores reales.
+     */
+    private applyDateTokens;
+    /**
+     * Obtiene el tamaño del archivo (stat) y lo devuelve como FileSize (VO).
+     *
+     * Decisión de diseño:
+     * - Si stat falla (archivo no existe, permisos, etc.), devolvemos tamaño 0.
+     * - Esto evita que el flujo de rotación “reviente” por un fallo de I/O puntual.
+     * - Si quieres hacer esto más estricto, aquí podrías lanzar un FileOperationError("read"/"stat", ...).
+     */
+    getFileSize(filePath: FilePath): Promise<FileSize>;
+    /**
+     * Decide si debe rotar basándose en la política del dominio y el estado actual.
+     *
+     * Nota:
+     * - Para rotación por día: comparamos el path actual vs el esperado para la fecha actual.
+     * - Para rotación por tamaño: consultamos el tamaño real y delegamos la regla al VO.
+     */
+    shouldRotate(policy: FileRotationPolicy, currentDate: Date): Promise<boolean>;
+    /**
+     * Rotación por día:
+     * - Si no hay currentFilePath, se considera que “debe rotar/crear” para inicializar.
+     * - Si el nombre esperado para la fecha actual difiere del actual, debe rotar.
+     *
+     * Importante:
+     * - Este método NO muta currentFilePath (solo calcula).
+     */
+    private shouldRotateByDay;
+    /**
+     * Rotación por tamaño:
+     * - Si no hay currentFilePath, no rotamos (no hay “archivo actual” que evaluar).
+     * - Si no hay maxSize en la policy, no rotamos.
+     * - Si se puede medir tamaño, delegamos al VO para la regla (>= maxSize).
+     */
+    private shouldRotateBySize;
+}
+/**
+ * Escapa caracteres especiales para construir RegExp seguro desde strings (basename/ext).
+ */

package/dist/infrastructure/adapters/file-rotator.adapter.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileRotatorAdapter = void 0;
+const value_objects_1 = require("../../domain/value-objects");
+/**
+ * Adapter de infraestructura que implementa IFileRotatorPort.
+ *
+ * Responsabilidad:
+ * - Calcular el path esperado del archivo de log en base a una fecha y un FileNamePattern.
+ * - Leer metadata real del filesystem (tamaño / listado de archivos).
+ * - Decidir si debe rotar (por día o por tamaño) apoyándose en la política del dominio.
+ *
+ * Nota:
+ * - Este adapter mantiene estado mínimo (`currentFilePath`) porque el Port lo requiere.
+ *   Aun así, evitamos mutaciones ocultas: solo se actualiza desde getExpectedPathForDate().
+ */
+class FileRotatorAdapter {
+    constructor(
+    // Port de FS (stat, readdir, etc.)
+    fsProvider, 
+    // Port de paths (normalización, join, resolve, etc.)
+    filePathAdapter, 
+    // VO de dominio: patrón de nombre
+    fileNamePattern, 
+    // Config cruda (normalmente string proveniente de env/config)
+    basePath) {
+        this.fsProvider = fsProvider;
+        this.filePathAdapter = filePathAdapter;
+        this.fileNamePattern = fileNamePattern;
+        this.basePath = basePath;
+        // Estado mínimo: “archivo actual” según el último cálculo/uso.
+        this.currentFilePath = null;
+        // Resolver y normalizar basePath una sola vez.
+        this.baseDir = this.filePathAdapter.fromRaw(this.basePath);
+    }
+    /**
+     * Devuelve el último archivo considerado “actual” por el rotator.
+     * Puede ser null si aún no se ha calculado/solicitado un path.
+     */
+    getCurrentPath() {
+        return this.currentFilePath;
+    }
+    /**
+     * Calcula el path esperado para una fecha y lo “marca” como archivo actual.
+     * OJO: este es el único método que muta currentFilePath a propósito.
+     */
+    getExpectedPathForDate(date) {
+        const expected = this.computePathForDate(date);
+        this.currentFilePath = expected;
+        return expected;
+    }
+    /**
+     * Calcula el FilePath esperado para una fecha usando el patrón.
+     * Método “puro”: NO muta estado.
+     */
+    computePathForDate(date) {
+        // 1) Aplicar reemplazo de tokens al patrón -> obtenemos el nombre del archivo.
+        const fileName = this.applyDateTokens(this.fileNamePattern.pattern, date);
+        // 2) Unir baseDir + fileName (sin re-resolver basePath en cada llamada).
+        return this.filePathAdapter.join(this.baseDir, fileName);
+    }
+    /**
+     * Reemplaza tokens de fecha dentro del patrón (ej. {yyyy}{MM}{dd}) por valores reales.
+     */
+    applyDateTokens(pattern, date) {
+        // Normalizamos valores una sola vez.
+        const yyyy = date.getFullYear().toString();
+        const MM = String(date.getMonth() + 1).padStart(2, "0");
+        const dd = String(date.getDate()).padStart(2, "0");
+        const HH = String(date.getHours()).padStart(2, "0");
+        const mm = String(date.getMinutes()).padStart(2, "0");
+        const ss = String(date.getSeconds()).padStart(2, "0");
+        // Reemplazamos usando regex global; más simple y eficiente que loop + new RegExp por token.
+        return pattern.replace(FileRotatorAdapter.TOKEN_REGEX, (_m, token) => {
+            switch (token) {
+                case "yyyy":
+                    return yyyy;
+                case "MM":
+                    return MM;
+                case "dd":
+                    return dd;
+                case "HH":
+                    return HH;
+                case "mm":
+                    return mm;
+                case "ss":
+                    return ss;
+                default:
+                    // Defensive: no debería ocurrir por la regex.
+                    return _m;
+            }
+        });
+    }
+    /**
+     * Obtiene el tamaño del archivo (stat) y lo devuelve como FileSize (VO).
+     *
+     * Decisión de diseño:
+     * - Si stat falla (archivo no existe, permisos, etc.), devolvemos tamaño 0.
+     * - Esto evita que el flujo de rotación “reviente” por un fallo de I/O puntual.
+     * - Si quieres hacer esto más estricto, aquí podrías lanzar un FileOperationError("read"/"stat", ...).
+     */
+    async getFileSize(filePath) {
+        try {
+            const stats = await this.fsProvider.stat(filePath.absolutePath);
+            return new value_objects_1.FileSize(stats.size);
+        }
+        catch {
+            return new value_objects_1.FileSize(0);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Decisión de rotación
+    // ---------------------------------------------------------------------------
+    /**
+     * Decide si debe rotar basándose en la política del dominio y el estado actual.
+     *
+     * Nota:
+     * - Para rotación por día: comparamos el path actual vs el esperado para la fecha actual.
+     * - Para rotación por tamaño: consultamos el tamaño real y delegamos la regla al VO.
+     */
+    async shouldRotate(policy, currentDate) {
+        switch (policy.by) {
+            case "none":
+                return false;
+            case "day":
+                return this.shouldRotateByDay(currentDate);
+            case "size":
+                return this.shouldRotateBySize(policy);
+            default:
+                // Defensive: si el tipo llegara corrupto por casting/JS.
+                return false;
+        }
+    }
+    /**
+     * Rotación por día:
+     * - Si no hay currentFilePath, se considera que “debe rotar/crear” para inicializar.
+     * - Si el nombre esperado para la fecha actual difiere del actual, debe rotar.
+     *
+     * Importante:
+     * - Este método NO muta currentFilePath (solo calcula).
+     */
+    shouldRotateByDay(currentDate) {
+        if (!this.currentFilePath)
+            return true;
+        const expectedPath = this.computePathForDate(currentDate);
+        return !this.currentFilePath.equals(expectedPath);
+    }
+    /**
+     * Rotación por tamaño:
+     * - Si no hay currentFilePath, no rotamos (no hay “archivo actual” que evaluar).
+     * - Si no hay maxSize en la policy, no rotamos.
+     * - Si se puede medir tamaño, delegamos al VO para la regla (>= maxSize).
+     */
+    async shouldRotateBySize(policy) {
+        if (!this.currentFilePath)
+            return false;
+        if (!policy.maxSize)
+            return false;
+        const currentFileSize = await this.getFileSize(this.currentFilePath);
+        return policy.shouldRotateBySize(currentFileSize);
+    }
+}
+exports.FileRotatorAdapter = FileRotatorAdapter;
+// Regex precalculada para encontrar tokens del tipo {yyyy}, {MM}, etc.
+FileRotatorAdapter.TOKEN_REGEX = /\{(yyyy|MM|dd|HH|mm|ss)\}/g;
+/**
+ * Escapa caracteres especiales para construir RegExp seguro desde strings (basename/ext).
+ */
+// function escapeRegExp(input: string): string {
+//   return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// }

package/dist/infrastructure/adapters/fileSystem-datasource.adapter.d.ts

@@ -0,0 +1,26 @@
+import type { ILogDatasource, LogEntry as CoreLogEntry, LogSearchRequest, LogRecord } from "@jmlq/logger";
+import type { FindLogsUseCase, IPersistLogUseCase } from "../../application/use-cases";
+import type { ILogStreamWriterPort } from "../../domain/ports";
+export declare class FsDatasourceAdapter implements ILogDatasource {
+    private readonly persistLogUseCase;
+    private readonly streamWriterPort;
+    private readonly findLogsUseCase?;
+    readonly name = "fs";
+    constructor(persistLogUseCase: IPersistLogUseCase, streamWriterPort: ILogStreamWriterPort, findLogsUseCase?: FindLogsUseCase | undefined);
+    /**
+     * Firma EXACTA requerida por @jmlq/logger:
+     * save(log: LogEntry): Promise<void>
+     */
+    save(log: CoreLogEntry): Promise<void>;
+    /**
+     * Firma típica de @jmlq/logger (si existe en tu interface):
+     * find?(filter?: LogFilterRequest): Promise<ILogResponse[]>
+     *
+     * Por ahora, dejamos una implementación mínima coherente:
+     * - Si aún no soportas lectura, devuelve [] (o lanza un error explícito).
+     * - Te recomiendo implementar find en serio (tail/list+parse) como acordamos.
+     */
+    find?(filter?: LogSearchRequest): Promise<LogRecord[]>;
+    flush(): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/infrastructure/adapters/fileSystem-datasource.adapter.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsDatasourceAdapter = void 0;
+class FsDatasourceAdapter {
+    constructor(persistLogUseCase, streamWriterPort, findLogsUseCase) {
+        this.persistLogUseCase = persistLogUseCase;
+        this.streamWriterPort = streamWriterPort;
+        this.findLogsUseCase = findLogsUseCase;
+        this.name = "fs";
+    }
+    /**
+     * Firma EXACTA requerida por @jmlq/logger:
+     * save(log: LogEntry): Promise<void>
+     */
+    async save(log) {
+        const dto = {
+            log,
+        };
+        await this.persistLogUseCase.execute(dto);
+    }
+    /**
+     * Firma típica de @jmlq/logger (si existe en tu interface):
+     * find?(filter?: LogFilterRequest): Promise<ILogResponse[]>
+     *
+     * Por ahora, dejamos una implementación mínima coherente:
+     * - Si aún no soportas lectura, devuelve [] (o lanza un error explícito).
+     * - Te recomiendo implementar find en serio (tail/list+parse) como acordamos.
+     */
+    async find(filter) {
+        if (!this.findLogsUseCase)
+            return [];
+        // mapeo 1:1 (misma estructura)
+        const internalFilter = filter;
+        const internal = (await this.findLogsUseCase.execute(internalFilter));
+        // mapeo 1:1
+        return internal;
+    }
+    async flush() {
+        await this.streamWriterPort.flush();
+    }
+    async dispose() {
+        await this.streamWriterPort.close();
+    }
+}
+exports.FsDatasourceAdapter = FsDatasourceAdapter;

package/dist/infrastructure/adapters/filesystem-log-file-enumerator.adapter.d.ts

@@ -0,0 +1,6 @@
+import { ILogFileEnumeratorPort } from "../../domain/ports";
+export declare class FileSystemLogFileEnumeratorAdapter implements ILogFileEnumeratorPort {
+    private readonly basePath;
+    constructor(basePath: string);
+    listLogFiles(): Promise<string[]>;
+}

package/dist/infrastructure/adapters/filesystem-log-file-enumerator.adapter.js

@@ -0,0 +1,54 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSystemLogFileEnumeratorAdapter = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class FileSystemLogFileEnumeratorAdapter {
+    constructor(basePath) {
+        this.basePath = basePath;
+    }
+    async listLogFiles() {
+        const entries = await fs.promises.readdir(this.basePath, {
+            withFileTypes: true,
+        });
+        return (entries
+            .filter((e) => e.isFile() && e.name.endsWith(".log"))
+            .map((e) => path.join(this.basePath, e.name))
+            // opcional: ordenar por nombre para estabilidad
+            .sort());
+    }
+}
+exports.FileSystemLogFileEnumeratorAdapter = FileSystemLogFileEnumeratorAdapter;

package/dist/infrastructure/adapters/filesystem-log-file-line-reader.adapter.d.ts

@@ -0,0 +1,4 @@
+import { ILogFileLineReaderPort } from "../../domain/ports";
+export declare class FileSystemLogFileLineReaderAdapter implements ILogFileLineReaderPort {
+    readLines(filePath: string): AsyncIterable<string>;
+}

package/dist/infrastructure/adapters/filesystem-log-file-line-reader.adapter.js

@@ -0,0 +1,53 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSystemLogFileLineReaderAdapter = void 0;
+const fs = __importStar(require("fs"));
+const readline = __importStar(require("readline"));
+class FileSystemLogFileLineReaderAdapter {
+    async *readLines(filePath) {
+        const stream = fs.createReadStream(filePath, { encoding: "utf8" });
+        const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+        try {
+            for await (const line of rl)
+                yield line;
+        }
+        finally {
+            rl.close();
+            stream.close();
+        }
+    }
+}
+exports.FileSystemLogFileLineReaderAdapter = FileSystemLogFileLineReaderAdapter;

package/dist/infrastructure/adapters/filesystem-provider.adapter.d.ts

@@ -0,0 +1,122 @@
+import { IFileSystemProviderPort } from "../../domain/ports";
+/**
+ * Adapter de infraestructura que implementa IFsProviderPort
+ * utilizando la API nativa de Node.js (fs/promises).
+ *
+ * Responsabilidad:
+ * - Encapsular el acceso al filesystem real.
+ * - Traducir operaciones de alto nivel del Port (exists, read, write, etc.)
+ *   a llamadas concretas de Node.js.
+ *
+ * Beneficios:
+ * - Aísla el dominio y la capa de aplicación de Node.js.
+ * - Permite testear fácilmente mediante mocks del port.
+ * - Facilita reemplazar esta implementación (memfs, fs remoto, etc.).
+ */
+export declare class FileSystemProviderAdapter implements IFileSystemProviderPort {
+    /**
+     * Verifica si una ruta existe y es accesible.
+     *
+     * Decisión de diseño:
+     * - Se usa fs.access() porque es una operación liviana.
+     * - Si ocurre cualquier error (no existe, permisos, etc.),
+     *   se interpreta como "no accesible".
+     *
+     * Nota:
+     * - Esto no distingue entre "no existe" y "sin permisos".
+     * - Para casos más estrictos, podría usarse fs.stat() y revisar el código de error.
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Crea un directorio en el filesystem.
+     *
+     * @param path Ruta del directorio a crear.
+     * @param options Opciones de creación (por ejemplo, recursive).
+     *
+     * Decisión de diseño:
+     * - Se delega completamente en fs.mkdir().
+     * - No se captura el error: si falla, el error debe propagarse
+     *   para que la capa superior decida cómo manejarlo.
+     */
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * Lee el contenido completo de un archivo.
+     *
+     * @param path Ruta absoluta del archivo.
+     * @returns Buffer con el contenido del archivo.
+     *
+     * Nota:
+     * - El adapter no interpreta el contenido (texto/binario).
+     * - La capa superior decide cómo procesar el Buffer.
+     */
+    readFile(path: string): Promise<Buffer>;
+    /**
+     * Escribe datos en un archivo, reemplazando su contenido si existe.
+     *
+     * @param path Ruta absoluta del archivo.
+     * @param data Contenido a escribir (string o Buffer).
+     *
+     * Decisión de diseño:
+     * - Usa fs.writeFile(), que crea el archivo si no existe.
+     * - Errores de escritura se propagan.
+     */
+    writeFile(path: string, data: string | Buffer): Promise<void>;
+    /**
+     * Agrega datos al final de un archivo existente.
+     *
+     * @param path Ruta absoluta del archivo.
+     * @param data Contenido a agregar.
+     *
+     * Nota:
+     * - Si el archivo no existe, fs.appendFile() lo crea.
+     */
+    appendFile(path: string, data: string | Buffer): Promise<void>;
+    /**
+     * Obtiene información básica de un archivo.
+     *
+     * @param path Ruta absoluta del archivo.
+     * @returns Objeto reducido con:
+     *   - size: tamaño del archivo en bytes.
+     *   - mtime: fecha de última modificación.
+     *
+     * Decisión de diseño:
+     * - Se expone solo la metadata necesaria para el dominio/app.
+     * - No se filtra el objeto fs.Stats completo para evitar acoplamiento.
+     */
+    stat(path: string): Promise<{
+        size: number;
+        mtime: Date;
+    }>;
+    /**
+     * Lista los archivos y carpetas dentro de un directorio.
+     *
+     * @param path Ruta absoluta del directorio.
+     * @returns Array de nombres (no rutas completas).
+     *
+     * Nota:
+     * - Se devuelve string[] porque el dominio no necesita fs.Dirent.
+     */
+    readdir(path: string): Promise<string[]>;
+    /**
+     * Elimina un archivo del filesystem.
+     *
+     * @param path Ruta absoluta del archivo a eliminar.
+     *
+     * Decisión de diseño:
+     * - No se captura el error: si falla, la capa superior debe decidir
+     *   cómo manejar la situación (log, retry, ignore, etc.).
+     */
+    unlink(path: string): Promise<void>;
+    /**
+     * Renombra o mueve un archivo dentro del filesystem.
+     *
+     * @param oldPath Ruta actual del archivo.
+     * @param newPath Nueva ruta del archivo.
+     *
+     * Nota:
+     * - fs.rename() puede usarse tanto para renombrar como para mover archivos.
+     */
+    rename(oldPath: string, newPath: string): Promise<void>;
+}