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

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
+
+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
+```

package/package.json

@@ -1,22 +1,50 @@
 {
   "name": "@jmlq/logger-plugin-fs",
-  "version": "0.1.0-alpha.1",
-  "author": "MLahuasi",
+  "description": "Filesystem plugin for JMLQ Logger implementing Clean Architecture principles.",
+  "version": "0.1.0-alpha.10",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "pnpm build"
+    "dev": "rimraf dist && mkdir dist && tsc -p tsconfig.json",
+    "build": "rimraf dist && mkdir dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "example:help": "tsx examples/index.example.ts help",
+    "example:all": "tsx examples/index.example.ts",
+    "example:value-objects": "tsx examples/index.example.ts value-objects",
+    "example:infrastructure-adapters": "tsx examples/index.example.ts infrastructure-adapters",
+    "example:application-use-cases": "tsx examples/index.example.ts application-use-cases",
+    "example:application-services": "tsx examples/index.example.ts application-services",
+    "example:application-factories": "tsx examples/index.example.ts application-factories"
   },
+  "keywords": [
+    "logger",
+    "filesystem",
+    "clean-architecture",
+    "typescript"
+  ],
+  "author": "MLahuasi",
+  "license": "MIT",
   "devDependencies": {
-    "@types/node": "^24.3.0",
-    "tsx": "^4.20.5",
-    "typescript": "^5.9.2"
+    "@swc/core": "^1.3.95",
+    "@swc/jest": "^0.2.29",
+    "@types/bcryptjs": "^2.4.5",
+    "@types/jest": "^29.5.8",
+    "@types/node": "^20.8.10",
+    "jest": "^29.7.0",
+    "rimraf": "^6.1.2",
+    "tsx": "^4.1.4",
+    "typescript": "^5.2.2"
   },
-  "peerDependencies": {
-    "@jmlq/logger": "^0.1.0-alpha.0"
+  "files": [
+    "dist",
+    "README.md",
+    "architecture.md",
+    "install.md"
+  ],
+  "dependencies": {
+    "@jmlq/logger": "^0.1.0-alpha.20"
   }
 }