@jmlq/logger-plugin-fs 0.1.0-alpha.7 → 0.1.0-alpha.9

package/README.md

@@ -8,6 +8,12 @@ Plugin de **sistema de archivos** para [`@jmlq/logger`](https://www.npmjs.com/pa
 npm install @jmlq/logger @jmlq/logger-plugin-fs
 ```
 
+### Dependencias
+
+El plugin requiere como peer dependency:
+
+- `@jmlq/logger` >= 0.1.0-alpha.12
+
 > **Nota:** Este plugin requiere [`@jmlq/logger`](https://www.npmjs.com/package/@jmlq/logger) como dependencia principal.
 
 ## 🚀 Uso rápido

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

@@ -1,3 +1 @@
-export * from "./rotation-check.dto";
-export * from "./save-log.dto";
-export * from "./write-operation.dto";
+export * from "./rotate-if-needed.request";

package/dist/application/dto/index.js

@@ -14,6 +14,4 @@ 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("./rotation-check.dto"), exports);
-__exportStar(require("./save-log.dto"), exports);
-__exportStar(require("./write-operation.dto"), exports);
+__exportStar(require("./rotate-if-needed.request"), exports);

package/dist/application/dto/rotate-if-needed.request.d.ts

@@ -0,0 +1,10 @@
+import { FileRotationPolicy } from "../../domain/value-objects";
+/**
+ * DTO de entrada para el caso de uso RotateIfNeeded.
+ * - currentDate: fecha/hora actual (inyectada desde un clock para tests deterministas)
+ * - rotationPolicy: política de rotación (VO de dominio)
+ */
+export interface RotateIfNeededRequest {
+    currentDate: Date;
+    rotationPolicy: FileRotationPolicy;
+}

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

@@ -1,3 +1,16 @@
-import { ILogDatasource } from "@jmlq/logger";
 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

@@ -1,26 +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("../use-cases");
-const services_1 = require("../services");
-const filesystem_1 = require("../../infrastructure/filesystem");
+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) {
-    // Crear Value Objects
-    const fileNamePattern = new filesystem_1.FileNamePattern(options.fileNamePattern || "app-{yyyy}{MM}{dd}.log");
-    const rotationPolicy = new filesystem_1.RotationPolicy(options.rotation?.by || "day", options.rotation?.maxSizeMB, options.rotation?.maxFiles);
-    // Crear adaptadores
-    const clockAdapter = new adapters_1.NodeClockAdapter();
-    const filePathAdapter = new adapters_1.NodeFilePathAdapter();
-    const fsProviderAdapter = new adapters_1.FsProviderAdapter();
-    const streamWriterAdapter = new adapters_1.FsWriterAdapter();
-    const fileRotatorAdapter = new adapters_1.FileRotatorAdapter(fsProviderAdapter, filePathAdapter, fileNamePattern, options.basePath);
-    // Crear casos de uso
-    const ensureDirectoryUseCase = new use_cases_1.EnsureDirectoryUseCase(fsProviderAdapter, options.basePath, options.mkdir);
-    const appendLogUseCase = new use_cases_1.AppendLogUseCase(streamWriterAdapter, options.serializer);
-    const rotateIfNeededUseCase = new use_cases_1.RotateIfNeededUseCase(fileRotatorAdapter, streamWriterAdapter, options.onRotate);
-    const persistLogUseCase = new use_cases_1.PersistLogUseCase(clockAdapter, fileRotatorAdapter, streamWriterAdapter, rotationPolicy, rotateIfNeededUseCase, appendLogUseCase, ensureDirectoryUseCase, options.onError);
-    // Inicializar directorio
-    ensureDirectoryUseCase.execute();
-    return new services_1.FsDatasourceService(persistLogUseCase, streamWriterAdapter);
+    // ---------------------------------------------------------------------------
+    // 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/use-cases/append-log.use-case.d.ts

@@ -1,12 +1,30 @@
-import { ISaveLogDto } from "../dto/save-log.dto";
-import { IStreamWriterPort } from "../../domain/ports/stream-writer.port";
-import { IFsSerializer } from "../../infrastructure/filesystem";
+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: ISaveLogDto): Promise<void>;
+    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 streamWriterPort;
-    private readonly serializer?;
-    constructor(streamWriterPort: IStreamWriterPort, serializer?: IFsSerializer | undefined);
-    execute(dto: ISaveLogDto): Promise<void>;
+    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

@@ -1,26 +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(streamWriterPort, serializer) {
-        this.streamWriterPort = streamWriterPort;
-        this.serializer = serializer;
+    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;
-        if (this.serializer) {
-            serializedData = this.serializer.serialize(log);
-        }
-        else {
-            // Serialización por defecto
-            serializedData = JSON.stringify(log);
-        }
-        // Agregar salto de línea si no lo tiene
+        serializedData = JSON.stringify(log);
+        // 2) Asegurar salto de línea para escritura line-by-line
         if (!serializedData.endsWith("\n")) {
             serializedData += "\n";
         }
-        await this.streamWriterPort.write(serializedData);
+        // 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

@@ -1,11 +1,58 @@
-import { IFsProviderPort } from "../../domain/ports";
+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 {
-    private readonly fsProvider;
+    /**
+     * 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(fsProvider: IFsProviderPort, basePath: string, createIfNotExists?: boolean);
+    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

@@ -1,26 +1,63 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EnsureDirectoryUseCase = void 0;
-const errors_1 = require("../../shared/errors");
+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(fsProvider, basePath, createIfNotExists = true) {
-        this.fsProvider = fsProvider;
+    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 crear
-            const exists = await this.fsProvider.exists(this.basePath);
+            // El basePath ES el directorio que queremos asegurar.
+            const exists = await this.fileSystemProvider.exists(this.basePath);
             if (!exists) {
-                await this.fsProvider.mkdir(this.basePath, { recursive: true });
+                await this.fileSystemProvider.mkdir(this.basePath, {
+                    recursive: true,
+                });
             }
         }
         catch (error) {
-            throw errors_1.FileOperationError.createForMkdir(this.basePath, error);
+            // Error de dominio (no infraestructura) para mantener la dirección de dependencias.
+            throw errors_1.FileOperationError.create("mkdir", this.basePath, error);
         }
     }
 }

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

@@ -2,3 +2,4 @@ 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

@@ -18,3 +18,4 @@ __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

@@ -1,19 +1,96 @@
-import { IClockPort, IStreamWriterPort } from "../../domain/ports";
-import { ISaveLogDto } from "../dto";
+import { ISystemClockPort, ILogStreamWriterPort, IFileRotatorPort } from "../../domain/ports";
+import { SaveLogRequest } from "../../domain/request";
 import { IAppendLogUseCase, IEnsureDirectoryUseCase, IRotateIfNeededUseCase } from ".";
-import { IFileRotatorPort, RotationPolicy } from "../../infrastructure/filesystem";
+import { FileRotationPolicy } from "../../domain/value-objects";
+/**
+ * Contrato del caso de uso principal para persistir logs.
+ */
 export interface IPersistLogUseCase {
-    execute(dto: ISaveLogDto): Promise<void>;
+    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 {
-    private readonly clockPort;
-    private readonly fileRotatorPort;
-    private readonly streamWriterPort;
+    /**
+     * 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(clockPort: IClockPort, fileRotatorPort: IFileRotatorPort, streamWriterPort: IStreamWriterPort, rotationPolicy: RotationPolicy, rotateIfNeededUseCase: IRotateIfNeededUseCase, appendLogUseCase: IAppendLogUseCase, ensureDirectoryUseCase: IEnsureDirectoryUseCase, onError?: ((error: Error) => void | Promise<void>) | undefined);
-    execute(dto: ISaveLogDto): Promise<void>;
+    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>;
 }