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

package/architecture.md

@@ -18,9 +18,9 @@ El plugin implementa Clean Architecture con separación clara de responsabilidad
 
 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.
 
-### Separation of Concerns
+### Domain Driven Design (DDD)
 
-Cada componente tiene una responsabilidad específica y bien definida, desde la gestión de Value Objects hasta la escritura física de archivos.
+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
 
@@ -30,196 +30,106 @@ Las capas internas definen interfaces (ports) que las capas externas implementan
 
 ### `/src/domain/` - Capa de Dominio
 
-**Responsabilidad**: Contiene la lógica de negocio pura y las abstracciones fundamentales del plugin.
+Contiene la lógica de negocio pura y las abstracciones fundamentales del plugin.
 
-**Contenido**:
+#### `/domain/model/`
 
-- `/ports/` - Interfaces que definen contratos con infraestructura
-- `/value-objects/` - Objetos de valor inmutables del dominio
+- **[`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
 
-### `/src/application/` - Capa de Aplicación
-
-**Responsabilidad**: Orquesta los casos de uso del plugin y coordina entre dominio e infraestructura.
-
-**Contenido**:
-
-- `/dto/` - Data Transfer Objects para casos de uso
-- `/factory/` - Factories para creación de componentes
-- `/services/` - Servicios de aplicación que implementan `ILogDatasource`
-- `/use-cases/` - Casos de uso específicos del plugin
-
-### `/src/infrastructure/` - Capa de Infraestructura
-
-**Responsabilidad**: Implementaciones concretas de los ports del dominio y adaptadores específicos.
-
-**Contenido**:
+#### `/domain/value-objects/`
 
-- `/adapters/` - Implementaciones concretas de ports del dominio
-- `/filesystem/` - Tipos, políticas y ports específicos del filesystem
+- **[`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
 
-### `/src/shared/` - Utilitarios Compartidos
+#### `/domain/ports/`
 
-**Responsabilidad**: Errores y utilidades transversales al plugin.
+- **[`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
 
-**Contenido**:
+#### `/domain/ports/file/`
 
-- `/errors/` - Jerarquía de errores específicos del plugin
+- **[`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
 
-## Componentes Internos
+#### `/domain/ports/logs/`
 
-### Value Objects del Dominio
+- **[`log-datasource.port.ts`](src/domain/ports/logs/log-datasource.port.ts)**: Contrato principal del datasource compatible con @jmlq/logger
 
-#### FilePath
+#### `/domain/ports/logs/find/`
 
-```typescript
-class FilePath {
-  constructor(props: IFilePathProps);
-  get absolutePath(): string;
-  get directory(): string;
-  get filename(): string;
-  get extension(): string;
-  get basename(): string;
-  equals(other: FilePath): boolean;
-}
-```
-
-**Responsabilidad**: Encapsula una ruta de archivo completa como objeto inmutable, garantizando consistencia en la representación de paths a través del sistema.
-
-#### FileSize
-
-```typescript
-class FileSize {
-  constructor(bytes: number);
-  get bytes(): number;
-  get megabytes(): number;
-  isGreaterThan(other: FileSize): boolean;
-  equals(other: FileSize): boolean;
-}
-```
+- **[`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
 
-**Responsabilidad**: Representa el tamaño de archivos como concepto del dominio, proporcionando métodos de comparación y conversión de unidades.
+#### `/domain/request/` y `/domain/response/`
 
-### Value Objects de Infraestructura
+- **[`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
 
-#### FileNamePattern
-
-```typescript
-class FileNamePattern {
-  constructor(pattern: string);
-  get pattern(): string;
-  hasDateTokens(): boolean;
-  getTokens(): string[];
-}
-```
-
-**Responsabilidad**: Encapsula patrones de nombres de archivo con placeholders para fechas, permitiendo generación dinámica de nombres basados en timestamps.
-
-#### RotationPolicy
-
-```typescript
-class RotationPolicy {
-  constructor(by: FsRotationBy, maxSizeMB?: number, maxFiles?: number);
-  get by(): FsRotationBy;
-  get maxSizeMB(): number | undefined;
-  get maxFiles(): number | undefined;
-  shouldRotateBySize(currentSize: FileSize): boolean;
-}
-```
-
-**Responsabilidad**: Define las reglas de rotación de archivos, encapsulando la lógica de cuándo y cómo rotar archivos según diferentes estrategias.
-
-### Tipos del Sistema
-
-#### FsRotationBy
-
-```typescript
-type FsRotationBy = "none" | "day" | "size";
-```
+#### `/domain/types/`
 
-**Responsabilidad**: Define las estrategias de rotación disponibles en el sistema.
+- **[`fs-rotation-by.type.ts`](src/domain/types/fs-rotation-by.type.ts)**: Define los tipos de rotación disponibles (`"none"`, `"day"`, `"size"`)
 
-### Adaptadores de Infraestructura
-
-#### FsWriterAdapter
-
-```typescript
-class FsWriterAdapter implements IStreamWriterPort {
-  async write(data: string): Promise<boolean>;
-  async open(path: FilePath): Promise<void>;
-  async close(): Promise<void>;
-  async flush(): Promise<void>;
-  isOpen(): boolean;
-  getCurrentPath(): FilePath | null;
-}
-```
+### `/src/application/` - Capa de Aplicación
 
-**Responsabilidad**: Maneja la escritura física en archivos usando Node.js WriteStream, con gestión de estado y control de flujo.
+Orquesta los casos de uso del plugin y coordina entre dominio e infraestructura.
 
-#### FileRotatorAdapter
+#### `/application/use-cases/`
 
-```typescript
-class FileRotatorAdapter implements IFileRotatorPort {
-  getCurrentPath(): FilePath | null;
-  getExpectedPathForDate(date: Date): FilePath;
-  async getFileSize(filePath: FilePath): Promise<FileSize>;
-  async shouldRotate(
-    policy: RotationPolicy,
-    currentDate: Date
-  ): Promise<boolean>;
-}
-```
+- **[`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
 
-**Responsabilidad**: Implementa la lógica de rotación de archivos, generación de paths basados en fechas y evaluación de políticas de rotación.
+#### `/application/factory/`
 
-#### FsProviderAdapter
+- **[`create-fs-datasource.factory.ts`](src/application/factory/create-fs-datasource.factory.ts)**: Factory principal que ensambla todos los componentes del plugin
 
-```typescript
-class FsProviderAdapter implements IFsProviderPort
-```
+#### `/application/dto/`
 
-**Responsabilidad**: Abstrae operaciones del filesystem (stat, readdir, mkdir) proporcionando una interfaz uniforme para el dominio.
+- **[`rotate-if-needed.request.ts`](src/application/dto/rotate-if-needed.request.ts)**: DTO específico para el caso de uso de rotación
 
-#### NodeClockAdapter
+#### `/application/types/`
 
-```typescript
-class NodeClockAdapter implements IClockPort
-```
+- **[`filesystem-datasource-options.type.ts`](src/application/types/filesystem-datasource-options.type.ts)**: Opciones de configuración del datasource de filesystem
 
-**Responsabilidad**: Proporciona acceso al tiempo del sistema de forma abstraída.
+### `/src/infrastructure/` - Capa de Infraestructura
 
-#### NodeFilePathAdapter
+Implementaciones concretas de los ports del dominio usando tecnologías específicas de Node.js.
 
-```typescript
-class NodeFilePathAdapter implements IFilePathAdapterPort
-```
+#### `/infrastructure/adapters/`
 
-**Responsabilidad**: Maneja operaciones de manipulación de paths usando el módulo `path` de Node.js.
+- **[`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
 
-### Services de Aplicación
+#### `/infrastructure/errors/`
 
-#### FsDatasourceService
+- **[`file-operation.error.ts`](src/infrastructure/errors/file-operation.error.ts)**: Jerarquía de errores específicos para operaciones de filesystem
 
-```typescript
-class FsDatasourceService implements ILogDatasource {
-  async save(log: ILogProps): Promise<void>;
-  async flush(): Promise<void>;
-  async dispose(): Promise<void>;
-}
-```
+#### `/infrastructure/errors/types/`
 
-**Responsabilidad**: Implementa la interfaz `ILogDatasource` del logger principal, actuando como punto de entrada del plugin y delegando a los casos de uso correspondientes.
+- **[`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
 
-### Factory Principal
+#### `/infrastructure/filesystem/types/`
 
-#### createFsDatasource
+- **[`filesystem-rotation.type.ts`](src/infrastructure/filesystem/types/filesystem-rotation.type.ts)**: Configuración específica de rotación para filesystem
 
-```typescript
-function createFsDatasource(
-  options: IFilesystemDatasourceOptions
-): ILogDatasource;
-```
+### `/src/index.ts`
 
-**Responsabilidad**: Factory function que ensambla todos los componentes del plugin, creando e inyectando dependencias según la configuración proporcionada.
+**[`index.ts`](src/index.ts)**: Punto de entrada principal del plugin que expone la API pública
 
 ## Política de Rotación
 
@@ -227,19 +137,11 @@ function createFsDatasource(
 
 #### 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:
-
-1. **Evaluación**: Compara el path actual con el path esperado para la fecha actual
-2. **Decisión**: Si difieren, se requiere rotación
-3. **Proceso**: Cierra el stream actual y abre uno nuevo con el path actualizado
+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:
-
-1. **Evaluación**: Compara el tamaño actual del archivo con `maxSizeMB` usando `FileSize.isGreaterThan()`
-2. **Decisión**: Se rota cuando el tamaño es mayor o igual al límite
-3. **Proceso**: Se crea un nuevo archivo y el anterior se mantiene según `maxFiles`
+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"`)
 
@@ -247,62 +149,33 @@ El archivo crece indefinidamente sin intervención del sistema de rotación.
 
 ### Generación de Nombres de Archivos
 
-El sistema utiliza `FileNamePattern` para generar nombres dinámicamente:
-
-**Placeholders soportados**:
+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)
-- `{HH}` - Hora con padding (00-23)
-- `{mm}` - Minutos con padding (00-59)
-- `{ss}` - Segundos con padding (00-59)
-
-**Proceso**:
-
-1. `FileRotatorAdapter.buildPathForDate()` toma la fecha actual
-2. Reemplaza cada placeholder con el valor correspondiente de la fecha
-3. Combina con `basePath` usando `NodeFilePathAdapter`
-4. Retorna un `FilePath` completo
-
-## Flujo Interno del Datasource
-
-### Pipeline de Escritura de Logs
-
-```
-ILogProps → ISaveLogDto → PersistLogUseCase → Filesystem
-     ↓            ↓              ↓               ↓
-  [Logger]   [Application]   [Domain]    [Infrastructure]
-```
 
-### Secuencia Detallada
+## Flujo Principal del Datasource
 
-1. **Recepción**: `FsDatasourceService.save()` recibe `ILogProps` desde el logger principal
+### Pipeline de Escritura
 
-2. **Transformación**: Se encapsula en `ISaveLogDto` para el caso de uso
+1. **Recepción**: [`FsDatasourceAdapter.save()`](src/infrastructure/adapters/fileSystem-datasource.adapter.ts) recibe el log desde @jmlq/logger
 
-3. **Orquestación**: `PersistLogUseCase.execute()` coordina el proceso:
+2. **Orquestación**: [`PersistLogUseCase`](src/application/use-cases/persist-log.use-case.ts) coordina el proceso:
 
-   - Asegura que el directorio existe (`EnsureDirectoryUseCase`)
-   - Evalúa necesidad de rotación (`RotateIfNeededUseCase`)
-   - Verifica estado del stream de escritura
-   - Delega escritura (`AppendLogUseCase`)
+   - 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))
 
-4. **Evaluación de Rotación**: `RotateIfNeededUseCase`:
+3. **Escritura**: [`LogStreamWriterAdapter`](src/infrastructure/adapters/log-stream-writer.adapter.ts) maneja la escritura física usando Node.js WriteStream
 
-   - Consulta `FileRotatorAdapter.shouldRotate()`
-   - Si requiere rotación, cierra stream actual y abre uno nuevo
-   - Ejecuta callback `onRotate` si está configurado
+### Pipeline de Búsqueda
 
-5. **Escritura**: `AppendLogUseCase`:
+1. **Enumeración**: [`FileSystemLogFileEnumeratorAdapter`](src/infrastructure/adapters/filesystem-log-file-enumerator.adapter.ts) encuentra archivos .log
 
-   - Serializa el log usando `IFsSerializer`
-   - Escribe en el stream actual via `FsWriterAdapter`
+2. **Lectura**: [`FileSystemLogFileLineReaderAdapter`](src/infrastructure/adapters/filesystem-log-file-line-reader.adapter.ts) lee líneas de archivos
 
-6. **Gestión de Stream**: `FsWriterAdapter`:
-   - Maneja WriteStream de Node.js
-   - Controla backpressure y drenaje
-   - Gestiona apertura/cierre de archivos
+3. **Filtrado**: [`FindLogsUseCase`](src/application/use-cases/find-logs-use-case.ts) aplica filtros de nivel, fecha y contenido
 
 ## Dependencias entre Capas
 

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

@@ -1,5 +1,5 @@
-import { IFilesystemDatasourceOptions } from "../../infrastructure/filesystem";
 import { ILogDatasource } from "../../domain/ports";
+import { IFilesystemDatasourceOptions } from "../types";
 /**
  * createFsDatasource
  * -----------------------------------------------------------------------------

package/dist/{infrastructure/filesystem → application}/types/filesystem-datasource-options.type.d.ts

@@ -1,5 +1,5 @@
-import { FilePath } from "../../../domain/value-objects";
-import { IFileSystemRotationConfig } from ".";
+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

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/index.d.ts

@@ -1,3 +1,4 @@
 export { FilePath, FileSize, FileRotationPolicy, FileNamePattern, } from "./domain/value-objects";
 export { createFsDatasource } from "./application/factory";
-export { IFilesystemDatasourceOptions, IFileSystemRotationConfig, } from "./infrastructure/filesystem";
+export { IFilesystemDatasourceOptions } from "./application/types";
+export { IFileSystemRotationConfig } from "./infrastructure/filesystem";

package/dist/infrastructure/filesystem/types/index.d.ts

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

package/dist/infrastructure/filesystem/types/index.js

@@ -14,5 +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("./filesystem-datasource-options.type"), exports);
 __exportStar(require("./filesystem-rotation.type"), exports);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jmlq/logger-plugin-fs",
   "description": "Filesystem plugin for JMLQ Logger implementing Clean Architecture principles.",
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.11",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -25,8 +25,6 @@
     "clean-architecture",
     "typescript"
   ],
-  "author": "MLahuasi",
-  "license": "MIT",
   "devDependencies": {
     "@swc/core": "^1.3.95",
     "@swc/jest": "^0.2.29",
@@ -41,10 +39,11 @@
   "files": [
     "dist",
     "README.md",
-    "architecture.md",
-    "install.md"
+    "architecture.md"
   ],
   "dependencies": {
     "@jmlq/logger": "^0.1.0-alpha.20"
-  }
+  },
+  "author": "MLahuasi",
+  "license": "MIT"
 }