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

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

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileNamePattern = void 0;
+/**
+ * representa el patrón de nombrado de archivos de log
+ */
+class FileNamePattern {
+    constructor(pattern) {
+        if (!pattern || typeof pattern !== "string") {
+            throw new Error("FileNamePattern: pattern must be a non-empty string");
+        }
+        this._pattern = pattern.trim();
+    }
+    /**
+     * Retorna el valor inmutable
+     */
+    get pattern() {
+        return this._pattern;
+    }
+    /**
+     * Indica si el patrón contiene tokens de fecha
+     * Útil para detectar si el nombre del archivo depende de fecha
+     * @returns true si el patrón contiene tokens de fecha, false en caso contrario
+     */
+    hasDateTokens() {
+        return /\{(yyyy|MM|dd|HH|mm|ss)\}/.test(this._pattern);
+    }
+    /**
+     * Devuelve todos los tokens encerrados en llaves presentes en el patrón
+     * @returns Array de tokens encontrados en el patrón
+     */
+    getTokens() {
+        const matches = this._pattern.match(/\{([^}]+)\}/g);
+        return matches ? matches.map((m) => m.slice(1, -1)) : [];
+    }
+}
+exports.FileNamePattern = FileNamePattern;

package/dist/infrastructure/filesystem/value-objects/index.d.ts

@@ -0,0 +1 @@
+export * from "./file-name-pattern.vo";

package/dist/infrastructure/{datasources → filesystem/value-objects}/index.js

@@ -14,4 +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("./fs.datasource"), exports);
+__exportStar(require("./file-name-pattern.vo"), exports);

package/dist/shared/errors/file-operation.error.d.ts

@@ -0,0 +1,12 @@
+export declare class FileOperationError extends Error {
+    readonly operation: string;
+    readonly filePath?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, operation: string, filePath?: string | undefined, cause?: Error | undefined);
+    static create(operation: string, filePath: string, cause?: Error): FileOperationError;
+    static createForRead(filePath: string, cause?: Error): FileOperationError;
+    static createForWrite(filePath: string, cause?: Error): FileOperationError;
+    static createForDelete(filePath: string, cause?: Error): FileOperationError;
+    static createForMkdir(filePath: string, cause?: Error): FileOperationError;
+    static createForMove(filePath: string, cause?: Error): FileOperationError;
+}

package/dist/shared/errors/file-operation.error.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileOperationError = void 0;
+class FileOperationError extends Error {
+    constructor(message, operation, filePath, cause) {
+        super(message);
+        this.operation = operation;
+        this.filePath = filePath;
+        this.cause = cause;
+        this.name = "FileOperationError";
+    }
+    static create(operation, filePath, cause) {
+        const message = `Failed to ${operation} file: ${filePath}`;
+        return new FileOperationError(message, operation, filePath, cause);
+    }
+    static createForRead(filePath, cause) {
+        return FileOperationError.create("read", filePath, cause);
+    }
+    static createForWrite(filePath, cause) {
+        return FileOperationError.create("write", filePath, cause);
+    }
+    static createForDelete(filePath, cause) {
+        return FileOperationError.create("delete", filePath, cause);
+    }
+    static createForMkdir(filePath, cause) {
+        return FileOperationError.create("create directory", filePath, cause);
+    }
+    static createForMove(filePath, cause) {
+        return FileOperationError.create("move", filePath, cause);
+    }
+}
+exports.FileOperationError = FileOperationError;

package/dist/shared/errors/fs-plugin.error.d.ts

@@ -0,0 +1,4 @@
+export declare class FsPluginError extends Error {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}

package/dist/shared/errors/fs-plugin.error.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FsPluginError = void 0;
+class FsPluginError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "FsPluginError";
+    }
+}
+exports.FsPluginError = FsPluginError;

package/dist/shared/errors/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./file-operation.error";
+export * from "./fs-plugin.error";
+export * from "./rotation.error";

package/dist/shared/errors/index.js

@@ -0,0 +1,19 @@
+"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("./file-operation.error"), exports);
+__exportStar(require("./fs-plugin.error"), exports);
+__exportStar(require("./rotation.error"), exports);

package/dist/shared/errors/rotation.error.d.ts

@@ -0,0 +1,10 @@
+export declare class RotationError extends Error {
+    readonly rotationType: string;
+    readonly filePath?: string | undefined;
+    readonly cause?: Error | undefined;
+    constructor(message: string, rotationType: string, filePath?: string | undefined, cause?: Error | undefined);
+    static createForPolicyViolation(policy: string, reason: string): RotationError;
+    static createForFileRotation(filePath: string, cause?: Error): RotationError;
+    static createForSizeCheck(filePath: string, cause?: Error): RotationError;
+    static createForDateCheck(filePath: string, cause?: Error): RotationError;
+}

package/dist/shared/errors/rotation.error.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RotationError = void 0;
+class RotationError extends Error {
+    constructor(message, rotationType, filePath, cause) {
+        super(message);
+        this.rotationType = rotationType;
+        this.filePath = filePath;
+        this.cause = cause;
+        this.name = "RotationError";
+    }
+    static createForPolicyViolation(policy, reason) {
+        return new RotationError(`Rotation policy '${policy}' violation: ${reason}`, policy);
+    }
+    static createForFileRotation(filePath, cause) {
+        return new RotationError(`Failed to rotate file: ${filePath}`, "file", filePath, cause);
+    }
+    static createForSizeCheck(filePath, cause) {
+        return new RotationError(`Failed to check file size for rotation: ${filePath}`, "size-check", filePath, cause);
+    }
+    static createForDateCheck(filePath, cause) {
+        return new RotationError(`Failed to check file date for rotation: ${filePath}`, "date-check", filePath, cause);
+    }
+}
+exports.RotationError = RotationError;

package/install.md

@@ -0,0 +1,520 @@
+# Instalación y Configuración - @jmlq/logger-plugin-fs
+
+## Introducción Técnica
+
+`@jmlq/logger-plugin-fs` es un plugin para el sistema de logging `@jmlq/logger` que proporciona persistencia en sistema de archivos con capacidades avanzadas de rotación. Implementa Clean Architecture y está diseñado para aplicaciones Node.js que requieren logging persistente con gestión automática de archivos.
+
+El plugin se integra como un datasource del logger principal, permitiendo escribir logs en archivos con políticas de rotación configurables (diaria, por tamaño, o sin rotación). Incluye funcionalidades como creación automática de directorios, serialización personalizable y callbacks para eventos de rotación.
+
+## Instalación
+
+### Dependencias Requeridas
+
+```bash
+npm install @jmlq/logger @jmlq/logger-plugin-fs
+```
+
+### Dependencias de Peer
+
+El plugin requiere como peer dependency:
+
+- `@jmlq/logger` >= 0.1.0-alpha.12
+
+## Configuración del FileSystemDatasource
+
+### Factory Principal
+
+El plugin proporciona la función `createFsDatasource` que actúa como factory principal:
+
+```typescript
+import { createFsDatasource } from '@jmlq/logger-plugin-fs';
+import { IFilesystemDatasourceOptions } from '@jmlq/logger-plugin-fs';
+
+const datasource = createFsDatasource(options: IFilesystemDatasourceOptions);
+```
+
+### Parámetros de Configuración
+
+#### IFilesystemDatasourceOptions
+
+```typescript
+interface IFilesystemDatasourceOptions {
+  basePath: string; // OBLIGATORIO
+  mkdir?: boolean; // Opcional, default: undefined
+  fileNamePattern?: string; // Opcional, default: "app-{yyyy}{MM}{dd}.log"
+  rotation?: IFileRotationConfig; // Opcional
+  serializer?: IFsSerializer; // Opcional
+  onRotate?: (oldPath: FilePath, newPath: FilePath) => void | Promise<void>;
+  onError?: (error: Error) => void | Promise<void>;
+}
+```
+
+#### Descripción de Parámetros
+
+- **`basePath`** (string): Directorio base donde se crearán los archivos de log. Es el único parámetro obligatorio.
+
+- **`mkdir`** (boolean, opcional): Si es `true`, crea automáticamente el directorio `basePath` usando `fs.mkdir({ recursive: true })` si no existe.
+
+- **`fileNamePattern`** (string, opcional): Patrón para nombres de archivo. Default: `"app-{yyyy}{MM}{dd}.log"`. Admite placeholders:
+
+  - `{yyyy}` - Año de 4 dígitos
+  - `{MM}` - Mes de 2 dígitos (01-12)
+  - `{dd}` - Día de 2 dígitos (01-31)
+
+- **`rotation`** (IFileRotationConfig, opcional): Configuración de política de rotación.
+
+- **`serializer`** (IFsSerializer, opcional): Estrategia personalizada de serialización de logs a string.
+
+- **`onRotate`** (función, opcional): Callback ejecutado cuando se rota un archivo. Útil para notificaciones o envío a servicios externos.
+
+- **`onError`** (función, opcional): Callback centralizado para manejo de errores del datasource.
+
+## Política de Rotación (RotationPolicy)
+
+### Configuración IFileRotationConfig
+
+```typescript
+interface IFileRotationConfig {
+  by: FsRotationBy; // "none" | "day" | "size"
+  maxSizeMB?: number; // Solo para by: "size"
+  maxFiles?: number; // Número máximo de archivos rotados a mantener
+}
+```
+
+### Tipos de Rotación Soportados
+
+#### 1. Sin Rotación (`"none"`)
+
+```typescript
+const datasource = createFsDatasource({
+  basePath: "./logs",
+  rotation: {
+    by: "none",
+  },
+});
+```
+
+El archivo crece indefinidamente sin rotación.
+
+#### 2. Rotación Diaria (`"day"`)
+
+```typescript
+const datasource = createFsDatasource({
+  basePath: "./logs",
+  fileNamePattern: "app-{yyyy}-{MM}-{dd}.log",
+  rotation: {
+    by: "day",
+    maxFiles: 7, // Mantener últimos 7 días
+  },
+});
+```
+
+Crea un archivo nuevo cada día basado en el patrón de fecha.
+
+#### 3. Rotación por Tamaño (`"size"`)
+
+```typescript
+const datasource = createFsDatasource({
+  basePath: "./logs",
+  rotation: {
+    by: "size",
+    maxSizeMB: 10, // OBLIGATORIO para rotación por tamaño
+    maxFiles: 5, // Mantener últimos 5 archivos
+  },
+});
+```
+
+**Importante**: Para `by: "size"`, el parámetro `maxSizeMB` debe ser un número positivo.
+
+## Serialización Personalizada
+
+### Interface IFsSerializer
+
+```typescript
+interface IFsSerializer {
+  serialize(entry: unknown): string;
+}
+```
+
+### Implementación de Serializer Personalizado
+
+```typescript
+const customSerializer: IFsSerializer = {
+  serialize(log: any): string {
+    // Ejemplo: formato personalizado con timestamp ISO
+    const timestamp = new Date(log.timestamp).toISOString();
+    return `[${timestamp}] ${log.level.toUpperCase()}: ${log.message}\n`;
+  },
+};
+
+const datasource = createFsDatasource({
+  basePath: "./logs",
+  serializer: customSerializer,
+});
+```
+
+## Ejemplos Técnicos Completos
+
+### Configuración Básica
+
+```typescript
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+import { LoggerFactory } from "@jmlq/logger";
+
+// Crear datasource con configuración mínima
+const fsDatasource = createFsDatasource({
+  basePath: "./logs",
+  mkdir: true,
+});
+
+// Integrar con LoggerFactory
+const logger = LoggerFactory.create({
+  datasources: [fsDatasource],
+});
+
+// Uso básico
+logger.info("Aplicación iniciada");
+logger.error("Error de conexión a base de datos");
+```
+
+### Configuración con Rotación por Día y Callbacks
+
+```typescript
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+import { LoggerFactory } from "@jmlq/logger";
+import { FilePath } from "@jmlq/logger-plugin-fs";
+
+const fsDatasource = createFsDatasource({
+  basePath: "./logs/production",
+  fileNamePattern: "app-{yyyy}-{MM}-{dd}.log",
+  mkdir: true,
+  rotation: {
+    by: "day",
+    maxFiles: 30, // Mantener logs de últimos 30 días
+  },
+  serializer: {
+    serialize(log: any): string {
+      return (
+        JSON.stringify({
+          timestamp: new Date(log.timestamp).toISOString(),
+          level: log.level,
+          message: log.message,
+          ...log.extra,
+        }) + "\n"
+      );
+    },
+  },
+  onRotate: async (oldPath: FilePath, newPath: FilePath) => {
+    console.log(
+      `Log rotado: ${oldPath.absolutePath} → ${newPath.absolutePath}`
+    );
+    // Aquí podrías enviar el archivo a S3, comprimir, etc.
+  },
+  onError: async (error: Error) => {
+    console.error("Error en filesystem datasource:", error.message);
+    // Enviar métricas de error, notificar administradores, etc.
+  },
+});
+
+const logger = LoggerFactory.create({
+  datasources: [fsDatasource],
+});
+```
+
+### Configuración con Rotación por Tamaño
+
+```typescript
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+import { LoggerFactory } from "@jmlq/logger";
+
+const fsDatasource = createFsDatasource({
+  basePath: "./logs/high-volume",
+  fileNamePattern: "app.log",
+  mkdir: true,
+  rotation: {
+    by: "size",
+    maxSizeMB: 50, // Rotar cuando el archivo alcance 50MB
+    maxFiles: 10, // Mantener últimos 10 archivos rotados
+  },
+});
+
+const logger = LoggerFactory.create({
+  datasources: [fsDatasource],
+});
+
+// Para aplicaciones con alto volumen de logs
+for (let i = 0; i < 10000; i++) {
+  logger.debug(`Procesando registro ${i}`, {
+    userId: i,
+    operation: "bulk-process",
+  });
+}
+
+// Forzar escritura al archivo
+await fsDatasource.flush();
+```
+
+## Uso en Frameworks
+
+### Integración con Express
+
+```typescript
+import express from "express";
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+import { LoggerFactory, LogLevel } from "@jmlq/logger";
+
+// Configurar datasource para Express
+const fsDatasource = createFsDatasource({
+  basePath: "./logs/express",
+  fileNamePattern: "express-{yyyy}-{MM}-{dd}.log",
+  mkdir: true,
+  rotation: {
+    by: "day",
+    maxFiles: 15,
+  },
+  serializer: {
+    serialize(log: any): string {
+      return `${new Date(log.timestamp).toISOString()} [${log.level}] ${
+        log.message
+      }\n`;
+    },
+  },
+});
+
+const logger = LoggerFactory.create({
+  datasources: [fsDatasource],
+});
+
+const app = express();
+
+// Middleware de logging
+app.use((req, res, next) => {
+  logger.info(`${req.method} ${req.path}`, {
+    ip: req.ip,
+    userAgent: req.get("User-Agent"),
+  });
+  next();
+});
+
+// Manejo de errores con logging
+app.use(
+  (
+    err: Error,
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction
+  ) => {
+    logger.error("Error en aplicación Express", {
+      error: err.message,
+      stack: err.stack,
+      url: req.url,
+      method: req.method,
+    });
+    res.status(500).json({ error: "Internal Server Error" });
+  }
+);
+
+app.listen(3000, () => {
+  logger.info("Servidor Express iniciado en puerto 3000");
+});
+
+// Cerrar correctamente el datasource al terminar la aplicación
+process.on("SIGINT", async () => {
+  logger.info("Cerrando aplicación...");
+  await fsDatasource.flush();
+  await fsDatasource.dispose();
+  process.exit(0);
+});
+```
+
+### Integración con NestJS
+
+```typescript
+import { Injectable, Module, OnModuleDestroy } from "@nestjs/common";
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+import { LoggerFactory, ILogDatasource } from "@jmlq/logger";
+
+@Injectable()
+export class LoggingService implements OnModuleDestroy {
+  private readonly fsDatasource: ILogDatasource;
+  private readonly logger: any;
+
+  constructor() {
+    this.fsDatasource = createFsDatasource({
+      basePath: "./logs/nestjs",
+      fileNamePattern: "nest-{yyyy}-{MM}-{dd}.log",
+      mkdir: true,
+      rotation: {
+        by: "day",
+        maxFiles: 30,
+      },
+      serializer: {
+        serialize(log: any): string {
+          return (
+            JSON.stringify({
+              timestamp: new Date(log.timestamp).toISOString(),
+              level: log.level,
+              message: log.message,
+              context: log.context || "Application",
+              ...log.extra,
+            }) + "\n"
+          );
+        },
+      },
+      onError: async (error: Error) => {
+        console.error("[FS Logger Plugin]", error.message);
+      },
+    });
+
+    this.logger = LoggerFactory.create({
+      datasources: [this.fsDatasource],
+    });
+  }
+
+  log(message: string, context?: string, extra?: any) {
+    this.logger.info(message, { context, ...extra });
+  }
+
+  error(message: string, trace?: string, context?: string, extra?: any) {
+    this.logger.error(message, { trace, context, ...extra });
+  }
+
+  warn(message: string, context?: string, extra?: any) {
+    this.logger.warn(message, { context, ...extra });
+  }
+
+  debug(message: string, context?: string, extra?: any) {
+    this.logger.debug(message, { context, ...extra });
+  }
+
+  async onModuleDestroy() {
+    await this.fsDatasource.flush();
+    await this.fsDatasource.dispose();
+  }
+}
+
+@Module({
+  providers: [LoggingService],
+  exports: [LoggingService],
+})
+export class LoggingModule {}
+```
+
+## Variables de Entorno
+
+El plugin no maneja variables de entorno directamente. Para usarlas, mapéalas manualmente en la configuración:
+
+```typescript
+import { createFsDatasource } from "@jmlq/logger-plugin-fs";
+
+const fsDatasource = createFsDatasource({
+  basePath: process.env.LOG_DIR || "./logs",
+  mkdir: process.env.NODE_ENV !== "development",
+  fileNamePattern: process.env.LOG_FILE_PATTERN || "app-{yyyy}-{MM}-{dd}.log",
+  rotation: {
+    by: (process.env.LOG_ROTATION_TYPE as any) || "day",
+    maxSizeMB: process.env.LOG_MAX_SIZE_MB
+      ? parseInt(process.env.LOG_MAX_SIZE_MB)
+      : undefined,
+    maxFiles: process.env.LOG_MAX_FILES
+      ? parseInt(process.env.LOG_MAX_FILES)
+      : 7,
+  },
+});
+```
+
+Ejemplo de archivo `.env`:
+
+```env
+LOG_DIR=./logs/production
+LOG_FILE_PATTERN=myapp-{yyyy}-{MM}-{dd}.log
+LOG_ROTATION_TYPE=day
+LOG_MAX_FILES=30
+# Para rotación por tamaño:
+# LOG_ROTATION_TYPE=size
+# LOG_MAX_SIZE_MB=100
+```
+
+## Consideraciones Técnicas
+
+### Permisos del Sistema de Archivos
+
+- Asegúrate de que el proceso Node.js tenga permisos de escritura en el directorio `basePath`.
+- Para producción, considera usar directorios como `/var/log/tu-app` en sistemas Unix.
+- En contenedores Docker, monta volúmenes para persistir los logs:
+
+```dockerfile
+VOLUME ["/app/logs"]
+```
+
+### Gestión de Recursos
+
+#### Flush Explícito
+
+```typescript
+// Forzar escritura de buffers pendientes
+await datasource.flush();
+```
+
+#### Cierre Correcto
+
+```typescript
+// Cerrar streams y liberar recursos
+await datasource.dispose();
+```
+
+#### Manejo de Shutdown Graceful
+
+```typescript
+process.on("SIGTERM", async () => {
+  await datasource.flush();
+  await datasource.dispose();
+  process.exit(0);
+});
+```
+
+### Rendimiento y Recomendaciones
+
+- **Rotación por tamaño**: Más eficiente para aplicaciones con volumen variable de logs.
+- **Rotación diaria**: Mejor para aplicaciones con logs predecibles y análisis temporal.
+- **Serializer personalizado**: Optimiza el formato según tus necesidades de análisis posterior.
+- **Callbacks `onRotate`**: Úsalos para automatizar tareas como compresión o envío a servicios externos.
+- **Callback `onError`**: Implementa logging secundario o métricas de monitoreo.
+
+### Limitaciones Conocidas
+
+- El plugin funciona únicamente con Node.js (no browser).
+- La rotación por tamaño requiere especificar `maxSizeMB` obligatoriamente.
+- Los placeholders en `fileNamePattern` están limitados a: `{yyyy}`, `{MM}`, `{dd}`.
+- La rotación se basa en la fecha del sistema local.
+
+## Troubleshooting
+
+### Error: "maxSizeMB must be positive for size rotation"
+
+Especifica `maxSizeMB` mayor a 0 cuando uses `rotation.by = "size"`:
+
+```typescript
+rotation: {
+  by: 'size',
+  maxSizeMB: 10  // Obligatorio y > 0
+}
+```
+
+### Error: Permisos insuficientes
+
+Verifica permisos del directorio:
+
+```bash
+chmod 755 /ruta/a/logs
+chown node:node /ruta/a/logs
+```
+
+### Logs no aparecen inmediatamente
+
+Llama `flush()` para forzar escritura:
+
+```typescript
+logger.info("Mensaje importante");
+await datasource.flush(); // Fuerza escritura inmediata
+```