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

package/dist/domain/ports/file/log-stream-writer.port.d.ts

@@ -0,0 +1,70 @@
+import { FilePath } from "../../value-objects";
+/**
+ * IFileSystemWriterPort
+ * -----------------------------------------------------------------------------
+ * Puerto de salida (Outbound Port) que abstrae un writer basado en stream.
+ *
+ * Uso típico:
+ *  - open(path)
+ *  - write(line)
+ *  - flush() (opcional, antes de rotar o cerrar)
+ *  - close() (cerrar el stream actual, con posibilidad de reabrir)
+ *  - end()   (finalizar definitivamente / liberar recursos)
+ *
+ * Implementación típica en infraestructura:
+ *  - Node.js fs.createWriteStream + manejo de backpressure ("drain")
+ */
+export interface ILogStreamWriterPort {
+    /**
+     * Escribe datos al stream actual.
+     *
+     * Retorna:
+     * - true: la escritura fue aceptada sin saturar el buffer
+     * - false: hay backpressure (buffer lleno) y conviene esperar antes de seguir
+     *
+     * Nota de diseño:
+     * - Si la implementación "await" internamente hasta que drene, el boolean pierde valor.
+     *   En ese caso considera devolver Promise<void> y ocultar backpressure.
+     */
+    write(data: string): Promise<boolean>;
+    /**
+     * Abre un stream para un archivo específico.
+     * Debe dejar el writer listo para recibir write().
+     */
+    open(filePath: FilePath): Promise<void>;
+    /**
+     * Cierra el stream actual (si existe) SIN implicar "dispose definitivo".
+     * Útil para rotación: cerrar -> renombrar -> open(nuevo).
+     *
+     * Recomendación:
+     * - Define claramente si close() es idempotente (llamar dos veces no falla).
+     */
+    close(): Promise<void>;
+    /**
+     * Fuerza a que todo lo pendiente se escriba antes de continuar.
+     *
+     * Importante:
+     * - Define qué garantiza: ¿solo vaciar buffer en memoria? ¿fsync a disco?
+     * - Es clave si la rotación requiere consistencia antes de renombrar/mover.
+     */
+    flush(): Promise<void>;
+    /**
+     * Indica si el writer está abierto y listo para recibir escrituras.
+     * Útil para evitar errores por write() sin open().
+     */
+    isOpen(): boolean;
+    /**
+     * Devuelve el FilePath actualmente abierto para escritura, o null si no hay.
+     * Útil para diagnóstico o para decidir rotación desde la aplicación.
+     */
+    getCurrentPath(): FilePath | null;
+    /**
+     * Finaliza definitivamente el writer.
+     * Debe liberar recursos y dejar el objeto en estado no reutilizable
+     * (o al menos documentar si se puede reabrir).
+     *
+     * Recomendación:
+     * - Aclara la diferencia exacta con close().
+     */
+    end(): Promise<void>;
+}

package/dist/domain/ports/file/log-stream-writer.port.js

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

package/dist/domain/ports/filesystem-provider.port.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Es una abstracción del sistema de archivos (fs) que la capa de dominio puede solicitar sin depender directamente del módulo fs de Node
+ */
+export interface IFileSystemProviderPort {
+    /**
+     * Permite saber si un archivo o carpeta existe
+     * @param path Ruta del archivo o directorio
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Permite crear directorios
+     * @param path Ruta del directorio
+     * @param options Opciones de creación. Actualmente solo soporta 'recursive' (Indica si se deben crear directorios padres si no existen)
+     */
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * Se usa para leer registros existentes
+     * @param path Ruta del archivo
+     */
+    readFile(path: string): Promise<Buffer>;
+    /**
+     * Se usa para escribir registros nuevos
+     * @param path Ruta del archivo
+     * @param data Datos a escribir
+     */
+    writeFile(path: string, data: string | Buffer): Promise<void>;
+    /**
+     * Se usa para agregar registros nuevos al final del archivo
+     * @param path Ruta del archivo
+     * @param data Datos a agregar
+     */
+    appendFile(path: string, data: string | Buffer): Promise<void>;
+    /**
+     * Permite obtener metadata del archivo o directorio
+     * - Ver tamaño actual → política de RotationPolicy.
+     * - Ver fecha de modificación → rotación diaria/semanal.
+     * @param path Ruta del archivo o directorio
+     */
+    stat(path: string): Promise<{
+        size: number;
+        mtime: Date;
+    }>;
+    /**
+     * Necesario para rotación por índice y descubrimiento de archivos app.log.1, app.log.2, etc.
+     * @param path Ruta del directorio
+     */
+    readdir(path: string): Promise<string[]>;
+    /**
+     * Eliminar archivos antiguos.
+     * @param path Ruta del archivo
+     */
+    unlink(path: string): Promise<void>;
+    /**
+     * Clave para renombrar archivos cuando rotan.
+     * @param oldPath Ruta actual del archivo o directorio
+     * @param newPath Nueva ruta del archivo o directorio
+     */
+    rename(oldPath: string, newPath: string): Promise<void>;
+}

package/dist/domain/ports/filesystem-provider.port.js

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

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

@@ -0,0 +1,5 @@
+export * from "./system-clock.port";
+export * from "./filesystem-provider.port";
+export * from "./file/log-stream-writer.port";
+export * from "./file";
+export * from "./logs";

package/dist/domain/ports/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("./system-clock.port"), exports);
+__exportStar(require("./filesystem-provider.port"), exports);
+__exportStar(require("./file/log-stream-writer.port"), exports);
+__exportStar(require("./file"), exports);
+__exportStar(require("./logs"), exports);

package/dist/domain/ports/logs/find/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./log-file-line-reader.port";
+export * from "./log-file-numerator.port";

package/dist/domain/ports/logs/find/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./log-file-line-reader.port"), exports);
+__exportStar(require("./log-file-numerator.port"), exports);

package/dist/domain/ports/logs/find/log-file-line-reader.port.d.ts

@@ -0,0 +1,3 @@
+export interface ILogFileLineReaderPort {
+    readLines(filePath: string): AsyncIterable<string>;
+}

package/dist/domain/ports/logs/find/log-file-line-reader.port.js

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

package/dist/domain/ports/logs/find/log-file-numerator.port.d.ts

@@ -0,0 +1,3 @@
+export interface ILogFileEnumeratorPort {
+    listLogFiles(): Promise<string[]>;
+}

package/dist/domain/ports/logs/find/log-file-numerator.port.js

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

package/dist/domain/ports/logs/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./find";
+export * from "./log-datasource.port";

package/dist/domain/ports/logs/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./find"), exports);
+__exportStar(require("./log-datasource.port"), exports);

package/dist/domain/ports/logs/log-datasource.port.d.ts

@@ -0,0 +1,10 @@
+import { LogFilterRequest } from "../../request";
+import { LogEntry } from "../../model";
+import { ILogResponse } from "../../response";
+export interface ILogDatasource {
+    save(log: LogEntry): Promise<void>;
+    find?(filter?: LogFilterRequest): Promise<ILogResponse[]>;
+    flush?(): Promise<void>;
+    dispose?(): Promise<void>;
+    readonly name?: string;
+}

package/dist/domain/ports/logs/log-datasource.port.js

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

package/dist/domain/ports/system-clock.port.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Representa una abstracción del reloj del sistema dentro de la capa domain.
+ * Su único propósito es permitir que el dominio pueda obtener la hora actual
+ * sin depender directamente de new Date() ni de Date.now()
+ */
+export interface ISystemClockPort {
+    now(): Date;
+}

package/dist/domain/ports/system-clock.port.js

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

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

@@ -0,0 +1,2 @@
+export * from "./log-filter.request";
+export * from "./save-log.request";

package/dist/domain/request/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./log-filter.request"), exports);
+__exportStar(require("./save-log.request"), exports);

package/dist/domain/request/log-filter.request.d.ts

@@ -0,0 +1,9 @@
+import { LogLevel } from "../value-objects";
+export interface LogFilterRequest {
+    levelMin?: LogLevel;
+    since?: number;
+    until?: number;
+    limit?: number;
+    offset?: number;
+    query?: string;
+}

package/dist/domain/request/log-filter.request.js

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

package/dist/domain/request/save-log.request.d.ts

@@ -0,0 +1,7 @@
+import { LogEntry } from "../model";
+/**
+ * Request model del caso de uso SaveLog.
+ */
+export interface SaveLogRequest {
+    log: LogEntry;
+}

package/dist/domain/request/save-log.request.js

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

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

@@ -0,0 +1 @@
+export * from "./log.response";

package/dist/domain/response/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("./log.response"), exports);

package/dist/domain/response/log.response.d.ts

@@ -0,0 +1,8 @@
+import { LogLevel } from "../value-objects";
+export interface ILogResponse {
+    source: string;
+    level: LogLevel;
+    message: string | Record<string, unknown>;
+    meta?: unknown;
+    timestamp: number;
+}

package/dist/domain/response/log.response.js

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

package/dist/domain/types/fs-rotation-by.type.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Es un tipo discriminado que define cómo se realizará la rotación de logs dentro del sistema.
+ * Los valores significan:
+ * "none" → Sin rotación. El archivo crece indefinidamente.
+ * "day"  → Rotación diaria (por fecha).
+ * "size" → Rotación por tamaño (normalmente basado en maxSizeMB).
+ */
+export type FsRotationBy = "none" | "day" | "size";

package/dist/domain/types/fs-rotation-by.type.js

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

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

@@ -0,0 +1 @@
+export * from "./fs-rotation-by.type";

package/dist/domain/types/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./fs-rotation-by.type"), exports);

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

@@ -0,0 +1,36 @@
+/**
+ * FileNamePattern (Value Object)
+ * -----------------------------------------------------------------------------
+ * Representa un patrón de nombrado de archivos de log.
+ *
+ * Ejemplos:
+ * - "app.log"
+ * - "app-{yyyy}{MM}{dd}.log"
+ *
+ * Responsabilidades:
+ * - Garantizar invariantes (string no vacío, sin solo espacios)
+ * - Exponer el patrón inmutable
+ * - Ofrecer operaciones de dominio relacionadas (tokens)
+ */
+export declare class FileNamePattern {
+    private readonly _pattern;
+    /**
+     * Regex base para capturar tokens: "{...}"
+     * Centralizarlo evita inconsistencias entre métodos.
+     */
+    private static readonly TOKEN_REGEX;
+    /**
+     * Crea un patrón válido.
+     * Invariante: debe ser string no vacío y no solo whitespace.
+     */
+    constructor(pattern: string);
+    /**
+     * Retorna el valor inmutable del patrón.
+     */
+    get pattern(): string;
+    /**
+     * Devuelve todos los tokens encerrados en llaves presentes en el patrón.
+     * Ej: "app-{yyyy}{MM}.log" => ["yyyy", "MM"]
+     */
+    getTokens(): string[];
+}

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileNamePattern = void 0;
+/**
+ * FileNamePattern (Value Object)
+ * -----------------------------------------------------------------------------
+ * Representa un patrón de nombrado de archivos de log.
+ *
+ * Ejemplos:
+ * - "app.log"
+ * - "app-{yyyy}{MM}{dd}.log"
+ *
+ * Responsabilidades:
+ * - Garantizar invariantes (string no vacío, sin solo espacios)
+ * - Exponer el patrón inmutable
+ * - Ofrecer operaciones de dominio relacionadas (tokens)
+ */
+class FileNamePattern {
+    /**
+     * Crea un patrón válido.
+     * Invariante: debe ser string no vacío y no solo whitespace.
+     */
+    constructor(pattern) {
+        if (typeof pattern !== "string") {
+            throw new Error("FileNamePattern: pattern must be a non-empty string");
+        }
+        const trimmed = pattern.trim();
+        if (!trimmed) {
+            throw new Error("FileNamePattern: pattern must be a non-empty string");
+        }
+        this._pattern = trimmed;
+    }
+    /**
+     * Retorna el valor inmutable del patrón.
+     */
+    get pattern() {
+        return this._pattern;
+    }
+    /**
+     * Devuelve todos los tokens encerrados en llaves presentes en el patrón.
+     * Ej: "app-{yyyy}{MM}.log" => ["yyyy", "MM"]
+     */
+    getTokens() {
+        const matches = this._pattern.match(FileNamePattern.TOKEN_REGEX);
+        return matches ? matches.map((m) => m.slice(1, -1)) : [];
+    }
+}
+exports.FileNamePattern = FileNamePattern;
+/**
+ * Regex base para capturar tokens: "{...}"
+ * Centralizarlo evita inconsistencias entre métodos.
+ */
+FileNamePattern.TOKEN_REGEX = /\{([^}]+)\}/g;

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

@@ -0,0 +1,91 @@
+export type FilePathKind = "file" | "dir";
+/**
+ * Props requeridas para construir un FilePath.
+ *
+ * Importante:
+ * - Estas props representan una ruta YA normalizada.
+ * - La responsabilidad de construir valores coherentes
+ *   (resolver path, separar directorio, basename, extensión, etc.)
+ *   recae en la capa de infraestructura (adapters).
+ */
+export interface IFilePathProps {
+    /**
+     * Ruta absoluta completa del archivo.
+     * Ej: "/var/log/app/app-20251215.log"
+     */
+    absolutePath: string;
+    /**
+     * Directorio contenedor del archivo.
+     * Ej: "/var/log/app"
+     */
+    directory: string;
+    /**
+     * Nombre completo del archivo (basename + extensión).
+     * Ej: "app-20251215.log"
+     */
+    filename: string | null;
+    /**
+     * Extensión del archivo.
+     * Regla de dominio: debe ser string (puede ser vacío si no aplica).
+     * Ej: "log"
+     */
+    extension: string | null;
+    /**
+     * Nombre base del archivo sin extensión.
+     * Ej: "app-20251215"
+     */
+    basename: string | null;
+    kind: FilePathKind;
+}
+/**
+ * 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
+ */
+export declare class FilePath {
+    private readonly _absolutePath;
+    private readonly _directory;
+    private readonly _filename;
+    private readonly _extension;
+    private readonly _basename;
+    /**
+     * 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: IFilePathProps);
+    /**
+     * Valor principal del Value Object.
+     * Alias explícito de `absolutePath` para uso genérico.
+     */
+    get value(): string;
+    /**
+     * Ruta absoluta completa del archivo.
+     */
+    get absolutePath(): string;
+    /**
+     * Directorio contenedor del archivo.
+     */
+    get directory(): string;
+    get filename(): string | null;
+    get extension(): string | null;
+    get basename(): string | null;
+    /**
+     * Comparación por valor.
+     * Dos FilePath son iguales si representan la misma ruta absoluta.
+     */
+    equals(other: FilePath): boolean;
+}