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

package/architecture.md

@@ -0,0 +1,299 @@
+# Arquitectura del Plugin - @jmlq/logger-plugin-fs
+
+## Visión General del Plugin
+
+`@jmlq/logger-plugin-fs` es un plugin datasource especializado que resuelve la persistencia de logs en sistema de archivos para el ecosistema `@jmlq/logger`. Su arquitectura está diseñada bajo principios de Clean Architecture, proporcionando un sistema robusto de escritura de logs con capacidades avanzadas de rotación automática.
+
+El plugin aporta al ecosistema `@jmlq/logger` la capacidad de persistir logs en archivos con gestión inteligente de rotación, asegurando que las aplicaciones puedan mantener historial de logs sin comprometer el rendimiento ni el espacio en disco. Su diseño modular permite diferentes estrategias de rotación y serialización según las necesidades específicas de cada aplicación.
+
+Como datasource, el plugin implementa la interfaz `ILogDatasource` de `@jmlq/logger`, actuando como un adaptador entre el logger principal y el sistema de archivos, encapsulando toda la complejidad de gestión de archivos, rotación y escritura asíncrona.
+
+## Principios de Arquitectura
+
+### Clean Architecture
+
+El plugin implementa Clean Architecture con separación clara de responsabilidades en capas concéntricas, donde las dependencias fluyen hacia adentro (Infrastructure → Application → Domain).
+
+### Ports & Adapters (Hexagonal Architecture)
+
+Utiliza el patrón Ports & Adapters para aislar la lógica de negocio de las implementaciones concretas del filesystem, permitiendo testabilidad y flexibilidad en las implementaciones.
+
+### Domain Driven Design (DDD)
+
+Implementa conceptos de DDD con Value Objects que encapsulan reglas de negocio y comportamientos específicos del dominio de logging y gestión de archivos.
+
+### Dependency Inversion
+
+Las capas internas definen interfaces (ports) que las capas externas implementan, invirtiendo las dependencias y manteniendo la independencia del dominio.
+
+## Estructura del Proyecto
+
+### `/src/domain/` - Capa de Dominio
+
+Contiene la lógica de negocio pura y las abstracciones fundamentales del plugin.
+
+#### `/domain/model/`
+
+- **[`log-entry.model.ts`](src/domain/model/log-entry.model.ts)**: Modelo de dominio que representa una entrada de log con sus propiedades y comportamientos
+
+#### `/domain/value-objects/`
+
+- **[`file-path.vo.ts`](src/domain/value-objects/file-path.vo.ts)**: Encapsula una ruta de archivo como objeto inmutable con validaciones
+- **[`file-size.vo.ts`](src/domain/value-objects/file-size.vo.ts)**: Representa el tamaño de archivos con conversiones y comparaciones
+- **[`file-name-pattern.vo.ts`](src/domain/value-objects/file-name-pattern.vo.ts)**: Maneja patrones de nombres con tokens de fecha para generación dinámica
+- **[`file-rotation-policy.vo.ts`](src/domain/value-objects/file-rotation-policy.vo.ts)**: Define las reglas de rotación de archivos según diferentes estrategias
+- **[`log-level.vo.ts`](src/domain/value-objects/log-level.vo.ts)**: Encapsula los niveles de log con lógica de comparación
+
+#### `/domain/ports/`
+
+- **[`filesystem-provider.port.ts`](src/domain/ports/filesystem-provider.port.ts)**: Contrato para operaciones del sistema de archivos (stat, mkdir, readdir, etc.)
+- **[`system-clock.port.ts`](src/domain/ports/system-clock.port.ts)**: Abstracción del tiempo del sistema
+
+#### `/domain/ports/file/`
+
+- **[`file-path.port.ts`](src/domain/ports/file/file-path.port.ts)**: Contrato para manipulación y normalización de rutas
+- **[`file-rotator.port.ts`](src/domain/ports/file/file-rotator.port.ts)**: Define operaciones de rotación de archivos
+- **[`log-stream-writer.port.ts`](src/domain/ports/file/log-stream-writer.port.ts)**: Abstracción para escritura de streams de logs
+
+#### `/domain/ports/logs/`
+
+- **[`log-datasource.port.ts`](src/domain/ports/logs/log-datasource.port.ts)**: Contrato principal del datasource compatible con @jmlq/logger
+
+#### `/domain/ports/logs/find/`
+
+- **[`log-file-line-reader.port.ts`](src/domain/ports/logs/find/log-file-line-reader.port.ts)**: Contrato para lectura línea por línea de archivos de log
+- **[`log-file-numerator.port.ts`](src/domain/ports/logs/find/log-file-numerator.port.ts)**: Abstracción para enumeración de archivos de log
+
+#### `/domain/request/` y `/domain/response/`
+
+- **[`save-log.request.ts`](src/domain/request/save-log.request.ts)**: DTO para solicitudes de guardado de logs
+- **[`log-filter.request.ts`](src/domain/request/log-filter.request.ts)**: Parámetros para filtrado y búsqueda de logs
+- **[`log.response.ts`](src/domain/response/log.response.ts)**: Estructura de respuesta para logs encontrados
+
+#### `/domain/types/`
+
+- **[`fs-rotation-by.type.ts`](src/domain/types/fs-rotation-by.type.ts)**: Define los tipos de rotación disponibles (`"none"`, `"day"`, `"size"`)
+
+### `/src/application/` - Capa de Aplicación
+
+Orquesta los casos de uso del plugin y coordina entre dominio e infraestructura.
+
+#### `/application/use-cases/`
+
+- **[`persist-log.use-case.ts`](src/application/use-cases/persist-log.use-case.ts)**: Caso de uso principal que orquesta la persistencia de logs
+- **[`append-log.use-case.ts`](src/application/use-cases/append-log.use-case.ts)**: Maneja la escritura física de logs al archivo actual
+- **[`rotate-if-needed.use-case.ts`](src/application/use-cases/rotate-if-needed.use-case.ts)**: Evalúa y ejecuta rotación de archivos según políticas
+- **[`ensure-directory.use-case.ts`](src/application/use-cases/ensure-directory.use-case.ts)**: Garantiza la existencia del directorio base
+- **[`find-logs-use-case.ts`](src/application/use-cases/find-logs-use-case.ts)**: Implementa búsqueda y filtrado de logs históricos
+
+#### `/application/factory/`
+
+- **[`create-fs-datasource.factory.ts`](src/application/factory/create-fs-datasource.factory.ts)**: Factory principal que ensambla todos los componentes del plugin
+
+#### `/application/dto/`
+
+- **[`rotate-if-needed.request.ts`](src/application/dto/rotate-if-needed.request.ts)**: DTO específico para el caso de uso de rotación
+
+#### `/application/types/`
+
+- **[`filesystem-datasource-options.type.ts`](src/application/types/filesystem-datasource-options.type.ts)**: Opciones de configuración del datasource de filesystem
+
+### `/src/infrastructure/` - Capa de Infraestructura
+
+Implementaciones concretas de los ports del dominio usando tecnologías específicas de Node.js.
+
+#### `/infrastructure/adapters/`
+
+- **[`system-file-path.adapter.ts`](src/infrastructure/adapters/system-file-path.adapter.ts)**: Implementación usando el módulo `path` de Node.js
+- **[`filesystem-provider.adapter.ts`](src/infrastructure/adapters/filesystem-provider.adapter.ts)**: Adaptador del módulo `fs` de Node.js
+- **[`system-clock.adapter.ts`](src/infrastructure/adapters/system-clock.adapter.ts)**: Proporciona acceso al tiempo del sistema
+- **[`log-stream-writer.adapter.ts`](src/infrastructure/adapters/log-stream-writer.adapter.ts)**: Maneja WriteStream de Node.js con control de backpressure
+- **[`file-rotator.adapter.ts`](src/infrastructure/adapters/file-rotator.adapter.ts)**: Implementa lógica de rotación y generación de paths basados en fechas
+- **[`fileSystem-datasource.adapter.ts`](src/infrastructure/adapters/fileSystem-datasource.adapter.ts)**: Implementación principal de ILogDatasource
+- **[`filesystem-log-file-enumerator.adapter.ts`](src/infrastructure/adapters/filesystem-log-file-enumerator.adapter.ts)**: Enumera archivos .log en directorios del filesystem
+- **[`filesystem-log-file-line-reader.adapter.ts`](src/infrastructure/adapters/filesystem-log-file-line-reader.adapter.ts)**: Lee archivos línea por línea usando streams
+
+#### `/infrastructure/errors/`
+
+- **[`file-operation.error.ts`](src/infrastructure/errors/file-operation.error.ts)**: Jerarquía de errores específicos para operaciones de filesystem
+
+#### `/infrastructure/errors/types/`
+
+- **[`file-operation-error-options.type.ts`](src/infrastructure/errors/types/file-operation-error-options.type.ts)**: Opciones para errores de operaciones de archivo
+- **[`file-operation.type.ts`](src/infrastructure/errors/types/file-operation.type.ts)**: Tipos de operaciones de archivo para categorización de errores
+- **[`fs-error-scope.type.ts`](src/infrastructure/errors/types/fs-error-scope.type.ts)**: Ámbitos de errores del filesystem
+
+#### `/infrastructure/filesystem/types/`
+
+- **[`filesystem-rotation.type.ts`](src/infrastructure/filesystem/types/filesystem-rotation.type.ts)**: Configuración específica de rotación para filesystem
+
+### `/src/index.ts`
+
+**[`index.ts`](src/index.ts)**: Punto de entrada principal del plugin que expone la API pública
+
+## Política de Rotación
+
+### Estrategias Implementadas
+
+#### Rotación por Día (`"day"`)
+
+La rotación se basa en cambios de fecha. El sistema evalúa si el archivo actual corresponde a la fecha presente y rota cuando detecta un cambio de día.
+
+#### Rotación por Tamaño (`"size"`)
+
+La rotación se activa cuando el archivo supera el límite configurado en `maxSizeMB`. Se puede configurar un límite de archivos rotados con `maxFiles`.
+
+#### Sin Rotación (`"none"`)
+
+El archivo crece indefinidamente sin intervención del sistema de rotación.
+
+### Generación de Nombres de Archivos
+
+El sistema utiliza [`FileNamePattern`](src/domain/value-objects/file-name-pattern.vo.ts) para generar nombres dinámicamente con placeholders:
+
+- `{yyyy}` - Año de 4 dígitos
+- `{MM}` - Mes con padding (01-12)
+- `{dd}` - Día con padding (01-31)
+
+## Flujo Principal del Datasource
+
+### Pipeline de Escritura
+
+1. **Recepción**: [`FsDatasourceAdapter.save()`](src/infrastructure/adapters/fileSystem-datasource.adapter.ts) recibe el log desde @jmlq/logger
+
+2. **Orquestación**: [`PersistLogUseCase`](src/application/use-cases/persist-log.use-case.ts) coordina el proceso:
+
+   - Asegura directorio base ([`EnsureDirectoryUseCase`](src/application/use-cases/ensure-directory.use-case.ts))
+   - Evalúa rotación ([`RotateIfNeededUseCase`](src/application/use-cases/rotate-if-needed.use-case.ts))
+   - Ejecuta escritura ([`AppendLogUseCase`](src/application/use-cases/append-log.use-case.ts))
+
+3. **Escritura**: [`LogStreamWriterAdapter`](src/infrastructure/adapters/log-stream-writer.adapter.ts) maneja la escritura física usando Node.js WriteStream
+
+### Pipeline de Búsqueda
+
+1. **Enumeración**: [`FileSystemLogFileEnumeratorAdapter`](src/infrastructure/adapters/filesystem-log-file-enumerator.adapter.ts) encuentra archivos .log
+
+2. **Lectura**: [`FileSystemLogFileLineReaderAdapter`](src/infrastructure/adapters/filesystem-log-file-line-reader.adapter.ts) lee líneas de archivos
+
+3. **Filtrado**: [`FindLogsUseCase`](src/application/use-cases/find-logs-use-case.ts) aplica filtros de nivel, fecha y contenido
+
+## Dependencias entre Capas
+
+```
+┌─────────────────────────────────────────────────────┐
+│                Infrastructure                       │
+│  ┌─────────────────┐    ┌─────────────────────────┐ │
+│  │    Adapters     │    │      Filesystem         │ │
+│  │  - FsWriter     │    │  - RotationPolicy       │ │
+│  │  - FileRotator  │    │  - FileNamePattern      │ │
+│  │  - FsProvider   │    │  - Types & Ports        │ │
+│  │  - NodeClock    │    │                         │ │
+│  │  - NodeFilePath │    │                         │ │
+│  └─────────────────┘    └─────────────────────────┘ │
+└─────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────┐
+│                  Application                        │
+│  ┌─────────────────┐    ┌─────────────────────────┐ │
+│  │   Use Cases     │    │    Factory & Service    │ │
+│  │  - PersistLog   │    │  - createFsDatasource   │ │
+│  │  - AppendLog    │    │  - FsDatasourceService  │ │
+│  │  - RotateIfNeed │    │                         │ │
+│  │  - EnsureDir    │    │                         │ │
+│  └─────────────────┘    └─────────────────────────┘ │
+└─────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────┐
+│                    Domain                           │
+│  ┌─────────────────┐    ┌─────────────────────────┐ │
+│  │  Value Objects  │    │        Ports            │ │
+│  │  - FilePath     │    │  - IStreamWriterPort    │ │
+│  │  - FileSize     │    │  - IFileRotatorPort     │ │
+│  │                 │    │  - IFsProviderPort      │ │
+│  │                 │    │  - IClockPort           │ │
+│  └─────────────────┘    └─────────────────────────┘ │
+└─────────────────────────────────────────────────────┘
+```
+
+## Patrones Técnicos Implementados
+
+### Adapter Pattern
+
+Los adaptadores (`FsWriterAdapter`, `FileRotatorAdapter`, etc.) implementan interfaces del dominio, adaptando APIs externas (Node.js filesystem) a las necesidades del plugin.
+
+### Strategy Pattern
+
+`RotationPolicy` encapsula diferentes estrategias de rotación (`"day"`, `"size"`, `"none"`) que pueden intercambiarse dinámicamente.
+
+### Value Object Pattern
+
+`FilePath`, `FileSize`, `FileNamePattern` y `RotationPolicy` implementan el patrón Value Object, proporcionando inmutabilidad y encapsulación de conceptos del dominio.
+
+### Factory Pattern
+
+`createFsDatasource` implementa el patrón Factory, encapsulando la complejidad de creación y configuración de dependencias.
+
+### Port & Adapter Pattern
+
+Las interfaces en `/domain/ports/` definen contratos que las implementaciones en `/infrastructure/adapters/` cumplen, permitiendo inversión de dependencias.
+
+## Interacción con @jmlq/logger
+
+### Integración como Datasource
+
+El plugin se integra implementando `ILogDatasource`:
+
+```typescript
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+import { LoggerFactory } from "@jmlq/logger";
+
+const fsDatasource = createFsDatasource({
+  basePath: "./logs",
+  rotation: { by: "day" },
+});
+
+const logger = LoggerFactory.create({
+  datasources: [fsDatasource],
+});
+```
+
+### Flujo de Integración
+
+1. `LoggerFactory` registra el datasource creado por `createFsDatasource`
+2. Cuando se ejecuta `logger.info()`, `logger.error()`, etc., el logger principal invoca `FsDatasourceService.save()`
+3. El plugin procesa el log a través de su arquitectura interna
+4. El resultado se persiste en el filesystem según la configuración
+
+### Lifecycle Management
+
+```typescript
+// Flush de buffers pendientes
+await fsDatasource.flush();
+
+// Cierre limpio de recursos
+await fsDatasource.dispose();
+```
+
+## Consideraciones Técnicas
+
+### Gestión de Concurrencia
+
+El plugin maneja escritura asíncrona usando WriteStream de Node.js con control de backpressure a través de eventos `drain` y gestión de estado interno.
+
+### Manejo de Errores
+
+La arquitectura proporciona tres niveles de error:
+
+- `FsPluginError`: Errores generales del plugin
+- `FileOperationError`: Errores específicos de operaciones de archivo
+- `RotationError`: Errores relacionados con rotación de archivos
+
+### Limitaciones Arquitecturales
+
+1. **Dependencia de Node.js**: El plugin está acoplado al runtime de Node.js para operaciones de filesystem
+2. **Rotación Síncrona por Fecha**: La evaluación de rotación por día se basa en comparación de paths, no en metadata de archivos
+3. **Sin Compresión**: No incluye compresión automática de archivos rotados
+4. **Estrategias de Rotación Limitadas**: Solo soporta rotación por día, tamaño o ninguna
+5. **Sin Limpieza Automática**: La limpieza de archivos antiguos debe implementarse externamente usando `maxFiles` como referencia

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

@@ -0,0 +1 @@
+export * from "./rotate-if-needed.request";

package/dist/application/dto/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("./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/dto/rotate-if-needed.request.js

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

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

@@ -0,0 +1,16 @@
+import { ILogDatasource } from "../../domain/ports";
+import { IFilesystemDatasourceOptions } from "../types";
+/**
+ * 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

@@ -0,0 +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("../../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) {
+    // ---------------------------------------------------------------------------
+    // 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/factory/index.d.ts

@@ -0,0 +1 @@
+export * from "./create-fs-datasource.factory";

package/dist/application/factory/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("./create-fs-datasource.factory"), exports);

package/dist/application/types/filesystem-datasource-options.type.d.ts

@@ -0,0 +1,45 @@
+import { FilePath } from "../../domain/value-objects";
+import { IFileSystemRotationConfig } from "../../infrastructure/filesystem/types";
+/**
+ * Opciones de configuración para la fuente de datos del sistema de archivos.
+ * Es el objeto de configuración para un datasource de logs basado en filesystem
+ */
+export interface IFilesystemDatasourceOptions {
+    /**
+     * Directorio base donde se van a crear/leer los archivos de log.
+     */
+    basePath: string;
+    /**
+     * Indica si se deben crear los directorios padres si no existen
+     * Si es true, la implementación puede crear el basePath (con fs.mkdir({ recursive: true })) si no existe.
+     * Si es false o undefined, o no lo crea o depende de tu implementación.
+     */
+    mkdir?: boolean;
+    /**
+     * Patrón de nombre del archivo de log
+     */
+    fileNamePattern?: string;
+    /**
+     * Conecta con la política de rotación: "none" | "day" | "size", tamaño máximo, número de archivos, etc
+     */
+    rotation?: IFileSystemRotationConfig;
+    /**
+     * Hook que se dispara cuando se rota un archivo de log. Útil para:
+     * - Notificar a otro sistema.
+     * - Enviar el archivo rotado a S3.
+     * - Hacer limpieza adicional.
+     * @param oldPath Ruta del archivo de log antes de la rotación
+     * @param newPath Ruta del archivo de log después de la rotación
+     * @returns
+     */
+    onRotate?: (oldPath: FilePath, newPath: FilePath) => void | Promise<void>;
+    /**
+     * Hook centralizado para manejar errores del datasource:
+     * - Loggear en otro canal.
+     * - Enviar métricas / alertas.
+     * - Evitar que el logger “reviente” la app.
+     * @param error Error ocurrido en el datasource
+     * @returns
+     */
+    onError?: (error: Error) => void | Promise<void>;
+}

package/dist/application/types/filesystem-datasource-options.type.js

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

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

@@ -0,0 +1 @@
+export * from "./filesystem-datasource-options.type";

package/dist/application/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("./filesystem-datasource-options.type"), exports);

package/dist/application/use-cases/append-log.use-case.d.ts

@@ -0,0 +1,30 @@
+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: 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 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

@@ -0,0 +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(
+    // 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;
+        serializedData = JSON.stringify(log);
+        // 2) Asegurar salto de línea para escritura line-by-line
+        if (!serializedData.endsWith("\n")) {
+            serializedData += "\n";
+        }
+        // 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

@@ -0,0 +1,58 @@
+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 {
+    /**
+     * 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(
+    /**
+     * 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>;
+}