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

package/README.md

@@ -1,208 +1,222 @@
 # @jmlq/logger-plugin-fs
 
-Datasource de `sistema de archivos` para [`@jmlq/logger`](https://www.npmjs.com/package/@jmlq/logger).
-Escribe cada evento de log como **línea** (JSONL por defecto) y soporta `rotación por día` o por `tamaño`, manejo de `backpressure/drain`, `flush()` y `dispose()`.
-
----
+Plugin de **sistema de archivos** para [`@jmlq/logger`](https://www.npmjs.com/package/@jmlq/logger). Permite persistir logs en archivos con soporte para rotación automática, manejo de backpressure y configuración flexible de formato y estructura de archivos.
 
 ## 📦 Instalación
 
 ```bash
-# Con npm
-npm i @jmlq/logger @jmlq/logger-plugin-fs
-
-```
-
-Este plugin **depende** de [`@jmlq/logger`](https://www.npmjs.com/package/@jmlq/logger). Asegúrate de instalar ambos paquetes.
-
-## 🧱 Estructura del paquete
-
-### 📝 Resumen rápido
-
-> - **`src/domain/`** — Reglas del negocio del plugin (sin dependencias de Node).
->   > - **`contracts/`**
->   >   > - `clock.contract.ts` — Puerto que abstrae el tiempo actual (`now()`), permite testear rotación sin depender de `Date.now()`.
->   >   > - `file-rotator.port.ts` — Puerto para rotación: calcula path esperado, tamaño, índice, etc.
->   >   > - `stream-writer.port.ts` — Puerto para escritura secuencial: `write`, `once("drain")`, `end`.
->   > - **`value-objects/`**
->   >   > - `file-name-pattern.vo.ts` — VO que encapsula el patrón de nombres (`{yyyy}{MM}{dd}`) con validación.
->   >   > - `rotation-policy.vo.ts` — VO que define estrategia de rotación (`none | day | size`) con invariantes (`maxSizeMB > 0`).
->   > - **`types/`**
->   >   > - `options.type.ts` — Define `FsDatasourceOptions` y `IFsSerializer` (contrato de serialización de líneas).
-
-> - **`src/application/`** — Casos de uso (orquestan, no dependen de Node).
->   > - **`dto/`**
->   >   > - `save-log.dto.ts` — DTO de entrada: `{ log: ILog }`.
->   > - **`use-cases/`**
->   >   > - `rotate-if-needed.usecase.ts` — Decide si se rota: compara fecha/tamaño contra `RotationPolicy`.
->   >   > - `append-log.usecase.ts` — Serializa y escribe línea; maneja backpressure (`write=false` → espera `drain`).
->   >   > - `persist-log.usecase.ts` — Orquesta: asegura writer, rota si corresponde, escribe, dispara hooks.
->   > - **`services/`**
->   >   > - `fs-datasource.service.ts` — Implementa `ILogDatasource` del core usando los UC anteriores.
-
-> - **`src/infrastructure/`** — Adaptadores técnicos (Node.js).
->   > - **`fs/`**
->   >   > - `fs-provider.ts` — Wrapper de `fs`/`fs.promises` (mockeable en tests).
->   >   > - `path-utils.ts` — Utilidades para `join`, `splitBaseExt`, `formatPattern` (UTC).
->   >   > - `file-rotator.adapter.ts` — Implementa `IFileRotatorPort` usando `fs-provider` y `path-utils`.
->   >   > - `fs-writer.adapter.ts` — Implementa `IStreamWriterPort` con `fs.createWriteStream`.
->   >   > - `node-clock.adapter.ts` — Implementa `IClock` devolviendo `new Date()`.
-
-> - **`src/presentation/`** — API pública (cara del paquete).
->   > - **`factory/`**
->   >   > - `create-fs-datasource.ts` — Ensambla VO + adaptadores + casos de uso y devuelve un `ILogDatasource`.
->   > - `index.ts` — Barrel: reexporta la factory y VO/contratos públicos (`RotationPolicy`, `FileNamePattern`).
-
-#### [VER MAS](./ARQUITECTURA.md)
-
-## 🧩 Configuración
-
-### 🔐 Variables de Entorno (.env)
-
-```ini
-# Ruta base (carpeta) para los archivos de log
-LOGGER_FS_PATH=./logs
-
-# Patrón (opcional). Si omites, usa "app-{yyyy}{MM}{dd}.log"
-LOGGER_FS_PATTERN=app-{yyyy}{MM}{dd}.log
-
-# Rotación: "day" | "size" | "none"
-LOGGER_FS_ROTATION=day
-LOGGER_FS_MAX_SIZE_MB=50
-
-# Logger core
-LOGGER_LEVEL=info  # trace|debug|info|warn|error|fatal
-
+npm install @jmlq/logger @jmlq/logger-plugin-fs
 ```
 
----
+> **Nota:** Este plugin requiere [`@jmlq/logger`](https://www.npmjs.com/package/@jmlq/logger) como dependencia principal.
 
-### 🚀 Uso del paquete
+## 🚀 Uso rápido
 
-```tsx
-import { createLogger, LogLevel } from "@jmlq/logger";
+```typescript
+import { LoggerFactory } from "@jmlq/logger";
 import { createFsDatasource } from "@jmlq/logger-plugin-fs";
 
-const ds = createFsDatasource({
-  basePath: "./logs", // Carpeta destino
-  mkdir: true, // Crea carpeta si no existe
-  fileNamePattern: "app-{yyyy}{MM}{dd}.log", // Rotación diaria por fecha (UTC)
-  // Alternativa por tamaño:
-  // rotation: { by: "size", maxSizeMB: 50 }
+// Crear datasource de filesystem
+const fsDatasource = createFsDatasource({
+  basePath: "./logs",
+  fileNamePattern: "app-{yyyy}{MM}{dd}.log",
   rotation: { by: "day" },
-  // Serializador opcional (por defecto JSON.stringify)
-  // serializer: { serialize: (log) => formatMyLine(log) },
-  onRotate: (oldP, newP) => console.log("[fs] rotated:", oldP, "->", newP),
-  onError: (e) => console.error("[fs] error:", e),
 });
 
-const logger = createLogger(ds, { minLevel: LogLevel.INFO });
+// Crear logger usando la factory
+const logger = LoggerFactory.create([fsDatasource]);
 
-logger.info("Servidor iniciado", { pid: process.pid });
+// Usar el logger
+logger.info("Aplicación iniciada", { timestamp: new Date(), pid: process.pid });
+logger.error("Error de conexión", { service: "database", retries: 3 });
 
 // Cierre elegante
 process.on("SIGTERM", async () => {
-  await logger.flush?.();
-  await logger.dispose?.();
+  await logger.flush();
+  await logger.dispose();
   process.exit(0);
 });
 ```
 
-También:
+## ⚙️ Configuración del datasource
 
-```ts
-import { createLogger, LogLevel } from "@jmlq/logger";
-import {
-  createFsDatasource,
-  RotationPolicy,
-  FileNamePattern,
-} from "@jmlq/logger-plugin-fs";
+El datasource de filesystem acepta las siguientes opciones de configuración:
 
-// Validación/invariantes tempranas con VO (throws si es inválido)
-const pt = new FileNamePattern("app-{yyyy}{MM}{dd}.log");
-const rt = new RotationPolicy("size", 50 /* maxSizeMB */);
+### Opciones principales
 
-const ds = createFsDatasource({
-  basePath: "./logs",
-  mkdir: true,
-  // La factory acepta primitives; usamos los VO arriba solo para validar/centrar la decisión
-  fileNamePattern: pt.pattern,
-  rotation: { by: rt.by, maxSizeMB: rotation.maxSizeMB },
-});
+| Opción            | Tipo             | Descripción                                            | Por defecto                 |
+| ----------------- | ---------------- | ------------------------------------------------------ | --------------------------- |
+| `basePath`        | `string`         | Directorio base donde se guardarán los archivos de log | `"./logs"`                  |
+| `fileNamePattern` | `string`         | Patrón para nombrar archivos con tokens de fecha       | `"app-{yyyy}{MM}{dd}.log"`  |
+| `rotation`        | `RotationConfig` | Configuración de política de rotación                  | `{ by: "day" }`             |
+| `mkdir`           | `boolean`        | Crear directorio base si no existe                     | `true`                      |
+| `serializer`      | `LogSerializer`  | Serializador personalizado para el formato de líneas   | Serializer JSON por defecto |
+
+### Configuración de rotación
 
-const logger = createLogger(ds, { minLevel: LogLevel.INFO });
+```typescript
+interface RotationConfig {
+  by: "none" | "day" | "size";
+  maxSizeMB?: number; // Para rotación por tamaño
+  maxFiles?: number; // Límite de archivos rotados
+}
 ```
 
-#### ⚙️ Opciones soportadas
+### Patrones de nombre de archivo
 
-> - `basePath: string` – carpeta donde se guardan los logs.
-> - `mkdir?: boolean` – crea la carpeta si no existe.
-> - `fileNamePattern?: string` – tokens {yyyy}{MM}{dd} (formateados en UTC).
->   > - Ejemplos: `"app-{yyyy}{MM}{dd}.log"`, `"service.log"`.
-> - `rotation?: { by: "none" | "day" | "size"; maxSizeMB?: number; maxFiles?: number }`
->   > - `day` → rota al cambiar la fecha (UTC).
->   > - `size` → rota al alcanzar `maxSizeMB` (genera app.1.log, app.2.log, …).
-> - `serializer?: { serialize(entry: unknown): string }` – una línea sin `\n`.
-> - `onRotate?: (oldPath, newPath) => void | Promise<void>`
-> - `onError?: (err) => void | Promise<void>`
+Utiliza tokens que se reemplazan con valores de fecha (UTC):
 
----
+- `{yyyy}` - Año completo (ej: 2024)
+- `{MM}` - Mes con ceros (ej: 01, 12)
+- `{dd}` - Día con ceros (ej: 01, 31)
 
-### 🗂️ Formato de archivo
+**Ejemplos:**
 
-> - **Una línea por evento** (JSONL por defecto).
-> - El `serializer` determina el formato de cada línea (sin salto).
-> - El plugin agrega `"\n"` y maneja `backpressure`/`drain` del stream.
+- `"app-{yyyy}{MM}{dd}.log"` → `app-20241201.log`
+- `"service-{yyyy}-{MM}-{dd}.log"` → `service-2024-12-01.log`
+- `"application.log"` → `application.log` (sin rotación por fecha)
 
----
+## 🔁 Políticas de rotación
 
-### 🔁 Rotación
+### Rotación por fecha
 
-**Por día **(`rotation: { by: "day" }`)
+Crea un archivo nuevo cada día basado en fecha UTC:
 
-> - El archivo activo se calcula con `fileNamePattern` usando la `fecha UTC actual`.
-> - Si al persistir cambia el día → `cierra` el stream anterior, abre uno nuevo y dispara `onRotate(old, new)`.
+```typescript
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
 
-**Por tamaño** (`rotation: { by: "size", maxSizeMB }`)
+const datasource = createFsDatasource({
+  basePath: "./logs",
+  fileNamePattern: "app-{yyyy}{MM}{dd}.log",
+  rotation: { by: "day" },
+  onRotate: (oldPath, newPath) => {
+    console.log(
+      `Log rotado: ${oldPath.absolutePath} → ${newPath.absolutePath}`
+    );
+  },
+});
+```
 
-> - Comprueba el tamaño del archivo activo. Si `>= maxSizeMB` → rota a `app.1.log`, `app.2.log`, … (buscando el siguiente índice libre).
+### Rotación por tamaño
 
----
+Rota cuando el archivo alcanza el tamaño máximo especificado:
 
-### 🧯 Backpressure & drain (cómo evita perder logs)
+```typescript
+const datasource = createFsDatasource({
+  basePath: "./logs",
+  fileNamePattern: "app.log",
+  rotation: {
+    by: "size",
+    maxSizeMB: 50, // Rota al alcanzar 50MB
+    maxFiles: 10, // Mantiene máximo 10 archivos rotados
+  },
+  onRotate: (oldPath, newPath) => {
+    console.log(
+      `Archivo rotado por tamaño: ${oldPath.absolutePath} → ${newPath.absolutePath}`
+    );
+  },
+});
+```
 
-Node.js devuelve `false` en `stream.write()` cuando el **buffer interno está lleno** (backpressure).
-El plugin:
+### Sin rotación
 
-1. Serializa el log + `"\n"`.
-2. Llama `write(...)`.
-3. Si devuelve `false`, **espera el evento** `drain` antes de continuar.
-4. `flush()` espera a que se libere el buffer si `writableNeedDrain` es `true`.
-5. `dispose()` cierra el stream actual drenando el buffer pendiente.
+Mantiene un único archivo que crece indefinidamente:
 
----
+```typescript
+const datasource = createFsDatasource({
+  basePath: "./logs",
+  fileNamePattern: "application.log",
+  rotation: { by: "none" },
+});
+```
 
-### 🌐 Zona horaria
+## 🧩 Ejemplo completo
 
-> - El formateo `{yyyy}{MM}{dd}` del patrón se realiza en **UTC** para evitar desfases por huso horario (máquinas/CI distintas).
-> - Si necesitas otro criterio (p.ej., “día de Guayaquil”), puedes:
->   > - Ajustar el **IClock** para proveer el “ahora” en otro huso y/o
->   > - Reemplazar el util de formateo si deseas `{…}` en local time.
+```typescript
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+import { LogLevel } from "@jmlq/logger";
 
----
+const datasource = createFsDatasource({
+  basePath: "./logs",
+  fileNamePattern: "app-{yyyy}-{MM}-{dd}.log",
+  rotation: { by: "day" },
+  mkdir: true,
+  serializer: {
+    serialize(log: any) {
+      return JSON.stringify(log, null, 2);
+    },
+  },
+  onRotate: (oldPath, newPath) => {
+    console.log(`Rotación: ${oldPath.absolutePath} → ${newPath.absolutePath}`);
+  },
+  onError: (err) => {
+    console.error("Error en datasource:", err.message);
+  },
+});
 
-## ❓ FAQ
+// Guardar logs
+await datasource.save({
+  level: LogLevel.INFO,
+  message: "Servidor iniciado correctamente",
+  timestamp: Date.now(),
+});
 
-**¿Puedo usar mi propio serializador?**
-Sí. Pasa serializer: { serialize: (log) => "mi-línea" }. Debe devolver una sola línea sin `\n`.
+await datasource.save({
+  level: LogLevel.DEBUG,
+  message: "Conectando a base de datos...",
+  timestamp: Date.now(),
+});
 
-**¿Qué pasa si el proceso se detiene en medio de un write?**
-Usamos los mecanismos de `Writable` (buffer + `drain`) y exponemos `flush()`/`dispose()` para el cierre. Llama a ambos en shutdown.
+// Cierre
+await datasource.flush();
+await datasource.dispose();
+```
+
+## 🧪 Testing
+
+```typescript
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+import * as fs from "fs";
+import * as path from "path";
+
+describe("FileSystem Datasource", () => {
+  const testLogsPath = "./test-logs";
+
+  beforeEach(() => {
+    if (fs.existsSync(testLogsPath)) {
+      fs.rmSync(testLogsPath, { recursive: true });
+    }
+  });
+
+  test("debe crear archivo de log", async () => {
+    const datasource = createFsDatasource({
+      basePath: testLogsPath,
+      fileNamePattern: "test.log",
+      rotation: { by: "none" },
+    });
+
+    await datasource.save({
+      level: "info",
+      message: "Test message",
+      timestamp: new Date(),
+    });
+
+    await datasource.flush();
+
+    const logFile = path.join(testLogsPath, "test.log");
+    expect(fs.existsSync(logFile)).toBe(true);
+
+    const content = fs.readFileSync(logFile, "utf8");
+    expect(content).toContain("Test message");
+  });
+});
+```
 
-**¿Puedo rotar por hora?**
-No out-of-the-box. Puedes implementar un **FileNamePattern** por hora (ej. `app-{yyyy}{MM}{dd}-{HH}.log`) + un `RotateIfNeededUseCase` extendido.
+## 📄 Más Información
 
----
+- **[Arquitectura Detallada](./architecture.md)** - Documentación técnica completa
+- **[Guía de Instalación](./install.md)** - Configuración paso a paso
+- **[Ejemplos](./examples/)** - Códigos de ejemplo funcionales
 
 ## 📄 Licencia