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

package/dist/domain/value-objects/file-path.vo.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilePath = void 0;
+/**
+ * FilePath (Value Object)
+ * -----------------------------------------------------------------------------
+ * Representa una ruta de archivo ya normalizada e inmutable.
+ *
+ * Características (DDD / Clean Architecture):
+ * - Es un Value Object (igualdad por valor).
+ * - No depende de Node.js ni del módulo `path`.
+ * - No realiza IO ni lógica de infraestructura.
+ * - Asume que la normalización fuerte ocurre en adapters.
+ *
+ * Su responsabilidad es:
+ * - Encapsular el concepto de "ruta de archivo válida"
+ * - Proteger invariantes básicas (no null, no vacío)
+ * - Exponer acceso seguro a sus partes
+ */
+class FilePath {
+    /**
+     * Crea un FilePath a partir de props ya normalizadas.
+     *
+     * Nota de diseño:
+     * - Este constructor NO calcula rutas ni usa `path`.
+     * - Solo valida invariantes mínimas del dominio.
+     */
+    constructor(props) {
+        const { absolutePath, directory, filename, extension, basename, kind } = props;
+        // Validación de ruta absoluta
+        if (!absolutePath ||
+            typeof absolutePath !== "string" ||
+            !absolutePath.trim()) {
+            throw new Error("FilePath: absolutePath must be a non-empty string");
+        }
+        // Validación de directorio
+        if (!directory || typeof directory !== "string" || !directory.trim()) {
+            throw new Error("FilePath: directory must be a non-empty string");
+        }
+        if (kind !== "file" && kind !== "dir") {
+            throw new Error('FilePath: kind must be "file" or "dir"');
+        }
+        if (kind === "file") {
+            // Validación de filename completo
+            if (!filename || typeof filename !== "string" || !filename.trim()) {
+                throw new Error("FilePath: filename must be a non-empty string");
+            }
+            // Validación de extensión (puede ser vacía, pero debe ser string)
+            if (typeof extension !== "string") {
+                throw new Error("FilePath: extension must be a string");
+            }
+            // Validación de basename
+            if (!basename || typeof basename !== "string" || !basename.trim()) {
+                throw new Error("FilePath: basename must be a non-empty string");
+            }
+        }
+        // Asignación inmutable
+        this._absolutePath = absolutePath;
+        this._directory = directory;
+        this._filename = filename;
+        this._extension = extension;
+        this._basename = basename;
+    }
+    /**
+     * Valor principal del Value Object.
+     * Alias explícito de `absolutePath` para uso genérico.
+     */
+    get value() {
+        return this._absolutePath;
+    }
+    /**
+     * Ruta absoluta completa del archivo.
+     */
+    get absolutePath() {
+        return this._absolutePath;
+    }
+    /**
+     * Directorio contenedor del archivo.
+     */
+    get directory() {
+        return this._directory;
+    }
+    get filename() {
+        return this._filename;
+    }
+    get extension() {
+        return this._extension;
+    }
+    get basename() {
+        return this._basename;
+    }
+    /**
+     * Comparación por valor.
+     * Dos FilePath son iguales si representan la misma ruta absoluta.
+     */
+    equals(other) {
+        return this._absolutePath === other._absolutePath;
+    }
+}
+exports.FilePath = FilePath;

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

@@ -0,0 +1,51 @@
+import { FileSize } from ".";
+import { FsRotationBy } from "../types";
+/**
+ * FileRotationPolicy (Value Object)
+ * -----------------------------------------------------------------------------
+ * Encapsula la política de rotación de logs en filesystem.
+ *
+ * Contiene:
+ * - Estrategia de rotación (by): "none" | "day" | "size"
+ * - Parámetros opcionales:
+ *   - maxSize: umbral de tamaño (solo aplica para "size")
+ *   - maxFiles: máximo de archivos rotados a conservar (opcional)
+ *
+ * Propiedades del VO:
+ * - Inmutable
+ * - Valida invariantes en el constructor
+ * - Incluye comportamiento de dominio relacionado (ej. rotación por tamaño)
+ */
+export declare class FileRotationPolicy {
+    private readonly _by;
+    private readonly _maxSize?;
+    private readonly _maxFiles?;
+    /**
+     * Crea una política de rotación.
+     *
+     * Nota:
+     * - maxSizeMB se interpreta en megabytes si la estrategia es "size".
+     * - Para otras estrategias, maxSizeMB se ignora.
+     */
+    constructor(by: FsRotationBy, maxSize?: number, maxFiles?: number);
+    /**
+     * Estrategia de rotación configurada.
+     */
+    get by(): FsRotationBy;
+    /**
+     * Umbral de tamaño (solo relevante cuando by === "size").
+     */
+    get maxSize(): FileSize | undefined;
+    /**
+     * Máximo de archivos rotados a conservar (opcional).
+     */
+    get maxFiles(): number | undefined;
+    /**
+     * Indica si, según esta política, corresponde rotar por tamaño.
+     * Regla: rota si currentSize >= maxSize.
+     *
+     * Nota:
+     * - No hace IO; asume que alguien ya consultó el tamaño actual.
+     */
+    shouldRotateBySize(currentSize: FileSize): boolean;
+}

package/dist/domain/value-objects/file-rotation-policy.vo.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileRotationPolicy = void 0;
+const _1 = require(".");
+/**
+ * FileRotationPolicy (Value Object)
+ * -----------------------------------------------------------------------------
+ * Encapsula la política de rotación de logs en filesystem.
+ *
+ * Contiene:
+ * - Estrategia de rotación (by): "none" | "day" | "size"
+ * - Parámetros opcionales:
+ *   - maxSize: umbral de tamaño (solo aplica para "size")
+ *   - maxFiles: máximo de archivos rotados a conservar (opcional)
+ *
+ * Propiedades del VO:
+ * - Inmutable
+ * - Valida invariantes en el constructor
+ * - Incluye comportamiento de dominio relacionado (ej. rotación por tamaño)
+ */
+class FileRotationPolicy {
+    /**
+     * Crea una política de rotación.
+     *
+     * Nota:
+     * - maxSizeMB se interpreta en megabytes si la estrategia es "size".
+     * - Para otras estrategias, maxSizeMB se ignora.
+     */
+    constructor(by, maxSize, maxFiles) {
+        // Invariante: si se rota por tamaño, se requiere un maxSize positivo
+        if (by === "size" && (maxSize == null || maxSize <= 0)) {
+            throw new Error("FileRotationPolicy: maxSizeMB must be positive for size rotation");
+        }
+        // Invariante: si se define maxFiles, debe ser positivo
+        if (maxFiles != null && maxFiles <= 0) {
+            throw new Error("FileRotationPolicy: maxFiles must be positive");
+        }
+        this._by = by;
+        // Construcción del VO FileSize a partir de MB (si aplica)
+        this._maxSize =
+            maxSize != null ? _1.FileSize.fromMegabytes(maxSize) : undefined;
+        this._maxFiles = maxFiles;
+    }
+    /**
+     * Estrategia de rotación configurada.
+     */
+    get by() {
+        return this._by;
+    }
+    /**
+     * Umbral de tamaño (solo relevante cuando by === "size").
+     */
+    get maxSize() {
+        return this._maxSize;
+    }
+    /**
+     * Máximo de archivos rotados a conservar (opcional).
+     */
+    get maxFiles() {
+        return this._maxFiles;
+    }
+    /**
+     * Indica si, según esta política, corresponde rotar por tamaño.
+     * Regla: rota si currentSize >= maxSize.
+     *
+     * Nota:
+     * - No hace IO; asume que alguien ya consultó el tamaño actual.
+     */
+    shouldRotateBySize(currentSize) {
+        return this._by === "size" && !!this._maxSize
+            ? currentSize.isGreaterThan(this._maxSize) ||
+                currentSize.equals(this._maxSize)
+            : false;
+    }
+}
+exports.FileRotationPolicy = FileRotationPolicy;

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

@@ -0,0 +1,75 @@
+/**
+ * FileSize (Value Object)
+ * -----------------------------------------------------------------------------
+ * Representa el tamaño de un archivo, almacenado internamente en bytes.
+ *
+ * DDD / Clean Architecture:
+ * - Inmutable
+ * - Igualdad por valor (bytes)
+ * - No depende de infraestructura (fs, streams, etc.)
+ * - Expone comportamiento de dominio: conversiones y comparaciones
+ */
+export declare class FileSize {
+    /**
+     * Valor interno en bytes.
+     * Invariante: entero no negativo.
+     */
+    private readonly _bytes;
+    /**
+     * Construye un FileSize desde bytes.
+     * - bytes debe ser entero no negativo
+     */
+    constructor(bytes: number);
+    /**
+     * Bytes exactos (unidad base del VO).
+     */
+    get bytes(): number;
+    /**
+     * Tamaño en kilobytes (KiB, base 1024).
+     * Nota: retorna number (puede tener decimales).
+     */
+    get kilobytes(): number;
+    /**
+     * Tamaño en megabytes (MiB, base 1024).
+     * Nota: retorna number (puede tener decimales).
+     */
+    get megabytes(): number;
+    /**
+     * Tamaño en gigabytes (GiB, base 1024).
+     * Nota: retorna number (puede tener decimales).
+     */
+    get gigabytes(): number;
+    /**
+     * Crea un FileSize a partir de megabytes.
+     *
+     * Nota:
+     * - Permite mb con decimales.
+     * - Se convierte a bytes y se aplica Math.floor (redondeo hacia abajo).
+     */
+    static fromMegabytes(mb: number): FileSize;
+    /**
+     * Crea un FileSize a partir de kilobytes.
+     *
+     * Nota:
+     * - Permite kb con decimales.
+     * - Se convierte a bytes y se aplica Math.floor (redondeo hacia abajo).
+     */
+    static fromKilobytes(kb: number): FileSize;
+    /**
+     * Comparación: this > other
+     */
+    isGreaterThan(other: FileSize): boolean;
+    /**
+     * Comparación: this < other
+     */
+    isLessThan(other: FileSize): boolean;
+    /**
+     * Igualdad por valor (bytes exactos).
+     */
+    equals(other: FileSize): boolean;
+    /**
+     * Representación legible para logs/diagnóstico.
+     * Selecciona la unidad más adecuada y muestra 2 decimales en KB/MB/GB.
+     */
+    toString(): string;
+}

package/dist/domain/value-objects/file-size.vo.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSize = void 0;
+/**
+ * FileSize (Value Object)
+ * -----------------------------------------------------------------------------
+ * Representa el tamaño de un archivo, almacenado internamente en bytes.
+ *
+ * DDD / Clean Architecture:
+ * - Inmutable
+ * - Igualdad por valor (bytes)
+ * - No depende de infraestructura (fs, streams, etc.)
+ * - Expone comportamiento de dominio: conversiones y comparaciones
+ */
+class FileSize {
+    /**
+     * Construye un FileSize desde bytes.
+     * - bytes debe ser entero no negativo
+     */
+    constructor(bytes) {
+        if (bytes < 0 || !Number.isInteger(bytes)) {
+            throw new Error("FileSize: bytes must be a non-negative integer");
+        }
+        this._bytes = bytes;
+    }
+    /**
+     * Bytes exactos (unidad base del VO).
+     */
+    get bytes() {
+        return this._bytes;
+    }
+    /**
+     * Tamaño en kilobytes (KiB, base 1024).
+     * Nota: retorna number (puede tener decimales).
+     */
+    get kilobytes() {
+        return this._bytes / 1024;
+    }
+    /**
+     * Tamaño en megabytes (MiB, base 1024).
+     * Nota: retorna number (puede tener decimales).
+     */
+    get megabytes() {
+        return this._bytes / (1024 * 1024);
+    }
+    /**
+     * Tamaño en gigabytes (GiB, base 1024).
+     * Nota: retorna number (puede tener decimales).
+     */
+    get gigabytes() {
+        return this._bytes / (1024 * 1024 * 1024);
+    }
+    /**
+     * Crea un FileSize a partir de megabytes.
+     *
+     * Nota:
+     * - Permite mb con decimales.
+     * - Se convierte a bytes y se aplica Math.floor (redondeo hacia abajo).
+     */
+    static fromMegabytes(mb) {
+        if (mb < 0) {
+            throw new Error("FileSize: megabytes must be non-negative");
+        }
+        return new FileSize(Math.floor(mb * 1024 * 1024));
+    }
+    /**
+     * Crea un FileSize a partir de kilobytes.
+     *
+     * Nota:
+     * - Permite kb con decimales.
+     * - Se convierte a bytes y se aplica Math.floor (redondeo hacia abajo).
+     */
+    static fromKilobytes(kb) {
+        if (kb < 0) {
+            throw new Error("FileSize: kilobytes must be non-negative");
+        }
+        return new FileSize(Math.floor(kb * 1024));
+    }
+    /**
+     * Comparación: this > other
+     */
+    isGreaterThan(other) {
+        return this._bytes > other._bytes;
+    }
+    /**
+     * Comparación: this < other
+     */
+    isLessThan(other) {
+        return this._bytes < other._bytes;
+    }
+    /**
+     * Igualdad por valor (bytes exactos).
+     */
+    equals(other) {
+        return this._bytes === other._bytes;
+    }
+    /**
+     * Representación legible para logs/diagnóstico.
+     * Selecciona la unidad más adecuada y muestra 2 decimales en KB/MB/GB.
+     */
+    toString() {
+        if (this._bytes >= 1024 * 1024 * 1024) {
+            return `${(this._bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+        }
+        if (this._bytes >= 1024 * 1024) {
+            return `${(this._bytes / (1024 * 1024)).toFixed(2)} MB`;
+        }
+        if (this._bytes >= 1024) {
+            return `${(this._bytes / 1024).toFixed(2)} KB`;
+        }
+        return `${this._bytes} bytes`;
+    }
+}
+exports.FileSize = FileSize;

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

@@ -0,0 +1,5 @@
+export * from "./file-path.vo";
+export * from "./file-size.vo";
+export * from "./file-rotation-policy.vo";
+export * from "./file-name-pattern.vo";
+export * from "./log-level.vo";

package/dist/domain/value-objects/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("./file-path.vo"), exports);
+__exportStar(require("./file-size.vo"), exports);
+__exportStar(require("./file-rotation-policy.vo"), exports);
+__exportStar(require("./file-name-pattern.vo"), exports);
+__exportStar(require("./log-level.vo"), exports);

package/dist/domain/value-objects/log-level.vo.d.ts

@@ -0,0 +1,8 @@
+export declare enum LogLevel {
+    TRACE = 10,
+    DEBUG = 20,
+    INFO = 30,
+    WARN = 40,
+    ERROR = 50,
+    FATAL = 60
+}

package/dist/domain/value-objects/log-level.vo.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogLevel = void 0;
+var LogLevel;
+(function (LogLevel) {
+    // Orden creciente permite comparar por severidad (trace < debug < ...)
+    LogLevel[LogLevel["TRACE"] = 10] = "TRACE";
+    LogLevel[LogLevel["DEBUG"] = 20] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 30] = "INFO";
+    LogLevel[LogLevel["WARN"] = 40] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 50] = "ERROR";
+    LogLevel[LogLevel["FATAL"] = 60] = "FATAL";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));

package/dist/index.d.ts

@@ -1,13 +1,4 @@
-import { ILogDatasource, Log } from "@jmlq/logger";
-type FsOpts = {
-    filePath: string;
-};
-export declare class FileSystemDatasource implements ILogDatasource {
-    private readonly opts;
-    private stream;
-    constructor(opts: FsOpts);
-    save(log: Log): Promise<void>;
-    flush(): Promise<void>;
-    dispose(): Promise<void>;
-}
-export {};
+export { FilePath, FileSize, FileRotationPolicy, FileNamePattern, } from "./domain/value-objects";
+export { createFsDatasource } from "./application/factory";
+export { IFilesystemDatasourceOptions } from "./application/types";
+export { IFileSystemRotationConfig } from "./infrastructure/filesystem";

package/dist/index.js

@@ -1,40 +1,12 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FileSystemDatasource = void 0;
-const node_fs_1 = __importDefault(require("node:fs"));
-class FileSystemDatasource {
-    constructor(opts) {
-        this.opts = opts;
-        // Abre una vez en modo append
-        this.stream = node_fs_1.default.createWriteStream(this.opts.filePath, { flags: "a" });
-    }
-    async save(log) {
-        if (!this.stream)
-            throw new Error("FS stream closed");
-        const line = JSON.stringify(log) + "\n";
-        if (!this.stream.write(line)) {
-            // backpressure: esperar a 'drain'
-            await new Promise((resolve) => this.stream.once("drain", resolve));
-        }
-    }
-    async flush() {
-        if (!this.stream)
-            return;
-        if (!this.stream.writableNeedDrain)
-            return;
-        await new Promise((resolve) => this.stream.once("drain", resolve));
-    }
-    async dispose() {
-        if (!this.stream)
-            return;
-        await new Promise((resolve, reject) => {
-            this.stream.end(() => resolve()); // end -> cierra el fd
-            this.stream.once("error", reject);
-        });
-        this.stream = null;
-    }
-}
-exports.FileSystemDatasource = FileSystemDatasource;
+exports.createFsDatasource = exports.FileNamePattern = exports.FileRotationPolicy = exports.FileSize = exports.FilePath = void 0;
+// Value Objects
+var value_objects_1 = require("./domain/value-objects");
+Object.defineProperty(exports, "FilePath", { enumerable: true, get: function () { return value_objects_1.FilePath; } });
+Object.defineProperty(exports, "FileSize", { enumerable: true, get: function () { return value_objects_1.FileSize; } });
+Object.defineProperty(exports, "FileRotationPolicy", { enumerable: true, get: function () { return value_objects_1.FileRotationPolicy; } });
+Object.defineProperty(exports, "FileNamePattern", { enumerable: true, get: function () { return value_objects_1.FileNamePattern; } });
+// Factory
+var factory_1 = require("./application/factory");
+Object.defineProperty(exports, "createFsDatasource", { enumerable: true, get: function () { return factory_1.createFsDatasource; } });

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).
+ */