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

package/dist/infrastructure/adapters/filesystem-provider.adapter.js

@@ -0,0 +1,182 @@
+"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.FileSystemProviderAdapter = void 0;
+const fs = __importStar(require("fs/promises"));
+/**
+ * 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.).
+ */
+class FileSystemProviderAdapter {
+    /**
+     * 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.
+     */
+    async exists(path) {
+        try {
+            await fs.access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 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.
+     */
+    async mkdir(path, options) {
+        await fs.mkdir(path, options);
+    }
+    /**
+     * 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.
+     */
+    async readFile(path) {
+        return fs.readFile(path);
+    }
+    /**
+     * 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.
+     */
+    async writeFile(path, data) {
+        await fs.writeFile(path, data);
+    }
+    /**
+     * 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.
+     */
+    async appendFile(path, data) {
+        await fs.appendFile(path, data);
+    }
+    /**
+     * 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.
+     */
+    async stat(path) {
+        const stats = await fs.stat(path);
+        return {
+            size: stats.size,
+            mtime: stats.mtime,
+        };
+    }
+    /**
+     * 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.
+     */
+    async readdir(path) {
+        return fs.readdir(path);
+    }
+    /**
+     * 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.).
+     */
+    async unlink(path) {
+        await fs.unlink(path);
+    }
+    /**
+     * 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.
+     */
+    async rename(oldPath, newPath) {
+        await fs.rename(oldPath, newPath);
+    }
+}
+exports.FileSystemProviderAdapter = FileSystemProviderAdapter;

package/dist/infrastructure/adapters/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./file-rotator.adapter";
+export * from "./fileSystem-datasource.adapter";
+export * from "./filesystem-log-file-enumerator.adapter";
+export * from "./filesystem-log-file-line-reader.adapter";
+export * from "./filesystem-provider.adapter";
+export * from "./log-stream-writer.adapter";
+export * from "./system-clock.adapter";
+export * from "./system-file-path.adapter";

package/dist/infrastructure/adapters/index.js

@@ -0,0 +1,24 @@
+"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-rotator.adapter"), exports);
+__exportStar(require("./fileSystem-datasource.adapter"), exports);
+__exportStar(require("./filesystem-log-file-enumerator.adapter"), exports);
+__exportStar(require("./filesystem-log-file-line-reader.adapter"), exports);
+__exportStar(require("./filesystem-provider.adapter"), exports);
+__exportStar(require("./log-stream-writer.adapter"), exports);
+__exportStar(require("./system-clock.adapter"), exports);
+__exportStar(require("./system-file-path.adapter"), exports);

package/dist/infrastructure/adapters/log-stream-writer.adapter.d.ts

@@ -0,0 +1,80 @@
+import { ILogStreamWriterPort } from "../../domain/ports";
+import { FilePath } from "../../domain/value-objects";
+/**
+ * Adapter de infraestructura que implementa IStreamWriterPort
+ * usando streams de escritura de Node.js.
+ *
+ * Responsabilidad:
+ * - Gestionar el ciclo de vida de un WriteStream (open → write → flush → close).
+ * - Manejar backpressure correctamente usando el evento "drain".
+ * - Encapsular errores de I/O en FileOperationError.
+ *
+ * Este adapter NO:
+ * - Decide cuándo rotar.
+ * - Decide qué escribir.
+ * - Conoce reglas de negocio.
+ *
+ * Solo escribe datos de forma eficiente.
+ */
+export declare class LogStreamWriterAdapter implements ILogStreamWriterPort {
+    /**
+     * Stream activo de escritura.
+     * Es null cuando no hay archivo abierto.
+     */
+    private stream;
+    /**
+     * Ruta del archivo actualmente abierto.
+     * Se mantiene para:
+     * - diagnóstico
+     * - errores más informativos
+     */
+    private currentPath;
+    /**
+     * Escribe datos en el stream actual.
+     *
+     * Maneja backpressure:
+     * - Si write() devuelve false, espera al evento "drain".
+     *
+     * @param data Cadena a escribir (ya serializada).
+     * @returns true cuando la escritura fue aceptada por el stream.
+     */
+    write(data: string): Promise<boolean>;
+    /**
+     * Abre un archivo para escritura en modo append.
+     *
+     * Si ya existe un stream abierto:
+     * - Se cierra primero de forma segura.
+     *
+     * @param path FilePath del archivo a abrir.
+     */
+    open(path: FilePath): Promise<void>;
+    /**
+     * Cierra el stream actual de forma ordenada.
+     *
+     * - Llama a stream.end().
+     * - Limpia el estado interno.
+     *
+     * Es seguro llamar varias veces.
+     */
+    close(): Promise<void>;
+    /**
+     * Alias semántico de close().
+     * Útil cuando el writer se usa como “sink” final.
+     */
+    end(): Promise<void>;
+    /**
+     * Espera a que el buffer interno del stream se vacíe.
+     *
+     * No fuerza fsync; solo asegura que el buffer JS esté drenado.
+     */
+    flush(): Promise<void>;
+    /**
+     * Indica si hay un stream abierto actualmente.
+     */
+    isOpen(): boolean;
+    /**
+     * Devuelve la ruta del archivo actualmente abierto.
+     * Puede ser null si no hay stream activo.
+     */
+    getCurrentPath(): FilePath | null;
+}

package/dist/infrastructure/adapters/log-stream-writer.adapter.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogStreamWriterAdapter = void 0;
+const fs_1 = require("fs");
+const errors_1 = require("../errors");
+/**
+ * Adapter de infraestructura que implementa IStreamWriterPort
+ * usando streams de escritura de Node.js.
+ *
+ * Responsabilidad:
+ * - Gestionar el ciclo de vida de un WriteStream (open → write → flush → close).
+ * - Manejar backpressure correctamente usando el evento "drain".
+ * - Encapsular errores de I/O en FileOperationError.
+ *
+ * Este adapter NO:
+ * - Decide cuándo rotar.
+ * - Decide qué escribir.
+ * - Conoce reglas de negocio.
+ *
+ * Solo escribe datos de forma eficiente.
+ */
+class LogStreamWriterAdapter {
+    constructor() {
+        /**
+         * Stream activo de escritura.
+         * Es null cuando no hay archivo abierto.
+         */
+        this.stream = null;
+        /**
+         * Ruta del archivo actualmente abierto.
+         * Se mantiene para:
+         * - diagnóstico
+         * - errores más informativos
+         */
+        this.currentPath = null;
+    }
+    // ---------------------------------------------------------------------------
+    // Escritura
+    // ---------------------------------------------------------------------------
+    /**
+     * Escribe datos en el stream actual.
+     *
+     * Maneja backpressure:
+     * - Si write() devuelve false, espera al evento "drain".
+     *
+     * @param data Cadena a escribir (ya serializada).
+     * @returns true cuando la escritura fue aceptada por el stream.
+     */
+    async write(data) {
+        // Protección: no se puede escribir sin haber abierto un stream
+        if (!this.stream) {
+            throw errors_1.FileOperationError.fs("write", this.currentPath?.absolutePath, "Stream not opened");
+        }
+        return new Promise((resolve, reject) => {
+            // write() devuelve false si el buffer interno está lleno
+            const accepted = this.stream.write(data);
+            if (!accepted) {
+                // Esperar a que el buffer se drene
+                this.stream.once("drain", () => resolve(true));
+                // Error del stream (I/O real)
+                this.stream.once("error", reject);
+            }
+            else {
+                resolve(true);
+            }
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Apertura
+    // ---------------------------------------------------------------------------
+    /**
+     * Abre un archivo para escritura en modo append.
+     *
+     * Si ya existe un stream abierto:
+     * - Se cierra primero de forma segura.
+     *
+     * @param path FilePath del archivo a abrir.
+     */
+    async open(path) {
+        // Si hay un stream previo, cerrarlo primero
+        if (this.stream) {
+            await this.close();
+        }
+        const pathString = path.absolutePath;
+        // Creamos el stream, pero NO lo asignamos todavía
+        const stream = (0, fs_1.createWriteStream)(pathString, { flags: "a" });
+        return new Promise((resolve, reject) => {
+            // El evento "open" garantiza que el archivo está listo
+            stream.once("open", () => {
+                this.stream = stream;
+                this.currentPath = path;
+                resolve();
+            });
+            // Error durante apertura (permisos, path inválido, etc.)
+            stream.once("error", (err) => {
+                reject(errors_1.FileOperationError.fs("write", pathString, err));
+            });
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Cierre
+    // ---------------------------------------------------------------------------
+    /**
+     * Cierra el stream actual de forma ordenada.
+     *
+     * - Llama a stream.end().
+     * - Limpia el estado interno.
+     *
+     * Es seguro llamar varias veces.
+     */
+    async close() {
+        if (!this.stream)
+            return;
+        return new Promise((resolve) => {
+            this.stream.end(() => {
+                this.stream = null;
+                this.currentPath = null;
+                resolve();
+            });
+        });
+    }
+    /**
+     * Alias semántico de close().
+     * Útil cuando el writer se usa como “sink” final.
+     */
+    async end() {
+        return this.close();
+    }
+    /**
+     * Espera a que el buffer interno del stream se vacíe.
+     *
+     * No fuerza fsync; solo asegura que el buffer JS esté drenado.
+     */
+    async flush() {
+        if (!this.stream)
+            return;
+        return new Promise((resolve) => {
+            if (this.stream.writableNeedDrain) {
+                this.stream.once("drain", () => resolve());
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Estado
+    // ---------------------------------------------------------------------------
+    /**
+     * Indica si hay un stream abierto actualmente.
+     */
+    isOpen() {
+        return this.stream !== null;
+    }
+    /**
+     * Devuelve la ruta del archivo actualmente abierto.
+     * Puede ser null si no hay stream activo.
+     */
+    getCurrentPath() {
+        return this.currentPath;
+    }
+}
+exports.LogStreamWriterAdapter = LogStreamWriterAdapter;

package/dist/infrastructure/adapters/system-clock.adapter.d.ts

@@ -0,0 +1,25 @@
+import { ISystemClockPort } from "../../domain/ports";
+/**
+ * Adapter de infraestructura que implementa IClockPort
+ * utilizando el reloj real del sistema.
+ *
+ * Responsabilidad:
+ * - Proveer la fecha y hora actual al sistema.
+ *
+ * Propósito arquitectónico:
+ * - Evitar el uso directo de `new Date()` en dominio y aplicación.
+ * - Permitir tests deterministas mediante clocks falsos (FixedClock, MockClock).
+ * - Centralizar la noción de "tiempo actual" del sistema.
+ *
+ * Nota:
+ * - No depende de APIs específicas de Node.js.
+ * - Funciona en cualquier entorno JavaScript.
+ */
+export declare class SystemClockAdapter implements ISystemClockPort {
+    /**
+     * Retorna la fecha y hora actual del sistema.
+     *
+     * @returns Date actual (timestamp UTC con representación local).
+     */
+    now(): Date;
+}

package/dist/infrastructure/adapters/system-clock.adapter.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SystemClockAdapter = void 0;
+/**
+ * Adapter de infraestructura que implementa IClockPort
+ * utilizando el reloj real del sistema.
+ *
+ * Responsabilidad:
+ * - Proveer la fecha y hora actual al sistema.
+ *
+ * Propósito arquitectónico:
+ * - Evitar el uso directo de `new Date()` en dominio y aplicación.
+ * - Permitir tests deterministas mediante clocks falsos (FixedClock, MockClock).
+ * - Centralizar la noción de "tiempo actual" del sistema.
+ *
+ * Nota:
+ * - No depende de APIs específicas de Node.js.
+ * - Funciona en cualquier entorno JavaScript.
+ */
+class SystemClockAdapter {
+    /**
+     * Retorna la fecha y hora actual del sistema.
+     *
+     * @returns Date actual (timestamp UTC con representación local).
+     */
+    now() {
+        return new Date();
+    }
+}
+exports.SystemClockAdapter = SystemClockAdapter;

package/dist/infrastructure/adapters/system-file-path.adapter.d.ts

@@ -0,0 +1,47 @@
+import { FilePath } from "../../domain/value-objects";
+import { IFilePathPort } from "../../domain/ports";
+/**
+ * SystemFilePathAdapter
+ * --------------------
+ * Adapter de infraestructura que implementa IFilePathPort usando el módulo `path`
+ * del entorno de ejecución (típicamente Node.js).
+ *
+ * Responsabilidad:
+ * - Aceptar rutas crudas (relativas o absolutas).
+ * - Normalizar y resolver siempre a una ruta absoluta.
+ * - Construir y transformar el Value Object FilePath de forma consistente.
+ *
+ * Nota de diseño:
+ * - Este adapter centraliza TODA la lógica "dependiente del sistema" (path/OS).
+ * - El dominio no debería usar `path.*` directamente.
+ */
+export declare class SystemFilePathAdapter implements IFilePathPort {
+    /**
+     * Crea un FilePath desde una ruta cruda (relativa o absoluta).
+     * La implementación:
+     * - valida input
+     * - normaliza
+     * - resuelve a absoluta (path.resolve)
+     */
+    fromRaw(inputPath: string): FilePath;
+    /**
+     * Une segmentos a la ruta base.
+     *
+     * Nota importante:
+     * - Aquí es clave definir semántica. Para evitar el caso raro:
+     *     "/logs/app.log" + "x" -> "/logs/app.log/x"
+     *   unimos los segmentos al DIRECTORIO del FilePath.
+     *
+     * Si tu intención era tratar FilePath como "basePath" que puede ser directorio,
+     * entonces tu VO debería representar directorios explícitamente.
+     */
+    join(filePath: FilePath, ...segments: string[]): FilePath;
+    /**
+     * Construye un FilePath resolviendo y normalizando en UN SOLO lugar.
+     *
+     * Redundancia corregida:
+     * - Antes se hacía path.resolve() en métodos públicos y también en el builder.
+     * - Ahora todos pasan por este helper y aquí se aplica resolve/normalize.
+     */
+    private buildFromAnyPath;
+}