@jmlq/logger 0.1.0-alpha.13 → 0.1.0-alpha.16

package/README.md

@@ -16,195 +16,185 @@ npm install @jmlq/logger-plugin-postgresql # Para PostgreSQL
 
 ## 🚀 Uso Básico
 
-### Configuración Simple
+Con esta configuración se busca:
 
-```typescript
-import { LoggerFactory, LogLevel } from "@jmlq/logger";
+- Tener un **logger centralizado** basado en `@jmlq/logger`.
+- Enviar logs a uno o varios de estos destinos (**opcionales** y combinables):
+  - Sistema de archivos (`@jmlq/logger-plugin-fs`)
+  - MongoDB (`@jmlq/logger-plugin-mongo`)
+  - PostgreSQL (`@jmlq/logger-plugin-postgresql`)
+- Integrar el logger con:
+  - Express (por request) mediante un middleware (`req.logger` + `req.requestId`).
+  - El ciclo de vida de la app: arranque, apagado limpio y fallos no controlados.
 
-// Crear un datasource en memoria (para testing/desarrollo)
-const memoryDatasource = {
-  name: "memory",
-  async save(log) {
-    console.log("LOG:", log);
-  },
-  async find(filter) {
-    return [];
-  },
-  async flush() {},
-  async dispose() {},
-};
-
-// Crear el logger
-const logger = LoggerFactory.create({
-  datasources: memoryDatasource,
-  minLevel: LogLevel.INFO,
-  redactorOptions: {
-    enabled: true,
-    deep: true,
-    includeDefaults: true,
-  },
-});
+---
 
-// Usar el logger
-await logger.info("Usuario conectado", {
-  userId: "123",
-  email: "user@example.com",
-});
-await logger.error("Error en el sistema", {
-  error: "Database connection failed",
-});
-```
+## 🎯 Características Principales
 
-### Con Múltiples Datasources
+### Niveles de Log
 
-```typescript
-import { LoggerFactory } from "@jmlq/logger";
-import { FileSystemDatasource } from "@jmlq/logger-plugin-fs";
-import { MongoDatasource } from "@jmlq/logger-plugin-mongo";
+- `TRACE` (10) - Información muy detallada
+- `DEBUG` (20) - Información de depuración
+- `INFO` (30) - Información general
+- `WARN` (40) - Advertencias
+- `ERROR` (50) - Errores
+- `FATAL` (60) - Errores críticos
 
-const logger = LoggerFactory.create({
-  datasources: [
-    new FileSystemDatasource({ basePath: "./logs" }),
-    new MongoDatasource({ url: "mongodb://localhost:27017", dbName: "logs" }),
-  ],
-  minLevel: LogLevel.INFO,
-});
+### Enmascarado PII Automático
 
-await logger.warn("Latencia alta", { endpoint: "/api/users", duration: 850 });
-```
+El logger detecta y enmascara automáticamente datos sensibles utilizando patrones personalizados:
 
-## 🎯 Características Principales
+```js
 
-### Niveles de Log
+      patterns: [
+      // Tarjetas de crédito
+      {
+        pattern: "\\b\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}\\b",
+        replaceWith: "****-****-****-****",
+      },
+      // Números de cuenta bancaria
+      {
+        pattern: "\\b\\d{10,20}\\b",
+        replaceWith: "****ACCOUNT****",
+      },
+      // Tokens JWT
+      {
+        pattern: "eyJ[A-Za-z0-9-_=]+\\.[A-Za-z0-9-_=]+\\.?[A-Za-z0-9-_.+/=]*",
+        replaceWith: "****JWT****",
+      },
+    ],
 
-- `TRACE` (0) - Información muy detallada
-- `DEBUG` (1) - Información de depuración
-- `INFO` (2) - Información general
-- `WARN` (3) - Advertencias
-- `ERROR` (4) - Errores
-- `FATAL` (5) - Errores críticos
+```
 
-### Enmascarado PII Automático
+Por ejemplo se tiene la siguiente información:
 
-El logger detecta y enmascara automáticamente datos sensibles:
+```js
+[
+  {
+    id: "1",
+    name: "John Doe",
+    email: "john.doe@example.com",
+    card: "1234-5678-9012-3456",
+  },
+  {
+    id: "2",
+    name: "Jane Doe",
+    email: "jane.doe@example.com",
+    card: "6258-3842-9524-3251",
+  },
+];
+```
 
-```typescript
-await logger.info("Pago procesado", {
-  email: "user@example.com", // → user@[EMAIL]
-  card: "4111-1111-1111-1111", // → ****-****-****-****
-  password: "secret123", // → [REDACTED]
-});
+Los logs registrarán lo siguiente:
+
+> - **File .log** (`@jmlq/logger-plugin-fs`)
+
+```js
+{
+  "level": 30,
+  "message": "Users listed successfully",
+  "meta": {
+    "count": 2,
+    "result": [
+      {
+        "id": "1",
+        "name": "John Doe",
+        "email": "***@***",
+        "card": "****-****-****-****"
+      },
+      {
+        "id": "2",
+        "name": "Jane Doe",
+        "email": "***@***",
+        "card": "****-****-****-****"
+      }
+    ]
+  },
+  "timestamp": 1765400661565,
+  "_id": "6939e0556925736129e1008d"
+}
 ```
 
+> - **MongoDB** (`@jmlq/logger-plugin-mongo`)
+
+![MongoDB log](./assets/mongo-log.png)
+
+> - **MongoDB** (`@jmlq/logger-plugin-mongo`)
+
+![Postgresql log](./assets/pg-log.png)
+
 ### Filtros y Consultas
 
-```typescript
-// Obtener logs de errores de las últimas 24 horas
-const errors = await logger.getLogs({
-  levelMin: LogLevel.ERROR,
-  since: Date.now() - 24 * 60 * 60 * 1000,
-  limit: 50,
-});
+#### 1. Obtener todos los logs de nivel WARN o superior (en este caso retorna WARN, ERROR y FATAL)
 
-// Buscar logs que contengan "usuario"
-const userLogs = await logger.getLogs({
-  query: "usuario",
-  limit: 100,
+```ts
+const errors = await _req.logger?.getLogs({
+  levelMin: parseLogLevel("WARN"),
 });
 ```
 
-## 🔧 Configuración con Variables de Entorno
+Resultado:
 
-```env
-# Nivel mínimo de logs
-LOG_LEVEL=info
+```ini
+[2025-12-10T21:19:58.804Z] [50] app.error {"name":"AppError","code":"INTERNAL","message":"Unhandled exception","retryable":false,"meta":null,"cause":{"cause":{}},"stack":"AppError: Unhandled exception\n    at AppError.internal (D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\shared\\errors\\app-error.js:61:16)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\presentation\\middlewares\\http\\error.middleware.js:36:40\n    at Layer.handleError (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\lib\\layer.js:116:17)\n
+   at trimPrefix (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:340:13)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:297:9\n    at processParams (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:582:12)\n    at Immediate.next (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:291:5)\n    at Immediate._onImmediate (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:688:15)\n    at process.processImmediate (node:internal/timers:485:21)"}
+[2025-12-10T21:19:58.804Z] [50] app.error {"code":"INTERNAL","name":"AppError","cause":{"cause":{}},"stack":"AppError: Unhandled exception\n    at AppError.internal (D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\shared\\errors\\app-error.js:61:16)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\presentation\\middlewares\\http\\error.middleware.js:36:40\n    at Layer.handleError (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\lib\\layer.js:116:17)\n    at trimPrefix (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:340:13)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:297:9\n    at processParams (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:582:12)\n    at Immediate.next (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:291:5)\n    at Immediate._onImmediate (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:688:15)\n    at process.processImmediate (node:internal/timers:485:21)","message":"Unhandled exception","retryable":false}
 
-# Filesystem
-LOGGER_FS_PATH=./logs
+```
 
-# MongoDB
-MONGO_URL=mongodb://localhost:27017
-MONGO_DB_NAME=logs
+**NOTA**: `parseLogLevel` es un helper para convertir un `string` a `LogLevel`.
 
-# PostgreSQL
-POSTGRES_URL=postgresql://user:pass@localhost:5432/logs
+#### 2. Filtrar por rango de fechas
 
-# PII Protection
-LOGGER_PII_ENABLED=true
+```ts
+const yesterday = Date.now() - 24 * 60 * 60 * 1000;
+const recentLogs = await _req.logger?.getLogs({
+  since: yesterday,
+  until: Date.now(),
+});
 ```
 
-## 📁 Ejemplos Prácticos
-
-El proyecto incluye ejemplos completos en el directorio [`examples/`](examples/):
+Resultado:
 
-```bash
-# Ver todos los ejemplos disponibles
-npm run example:help
-
-# Ejecutar ejemplos específicos
-npm run example:factories      # LoggerFactory
-npm run example:use-cases     # SaveLog, GetLogs, FlushBuffers
-npm run example:domain-services # PII, normalización
-npm run example:all           # Todos los ejemplos
+```ini
+[2025-12-10T22:21:58.500Z] [30] app.shutdown.begin {"reason":"SIGINT"}
+[2025-12-10T21:12:59.216Z] [50] app.error {"name":"AppError","code":"INTERNAL","message":"Unhandled exception","retryable":false,"meta":null,"cause":{"cause":{}},"stack":"AppError: Unhandled exception\n    at AppError.internal (D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\shared\\errors\\app-error.js:61:16)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\dist\\presentation\\middlewares\\http\\error.middleware.js:36:40\n    at Layer.handleError (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\lib\\layer.js:116:17)\n    at trimPrefix (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:340:13)\n    at D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:297:9\n    at processParams (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:582:12)\n    at Immediate.next (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:291:5)\n    at Immediate._onImmediate (D:\\Fuentes\\Core\\ml-dev-rest-api\\node_modules\\router\\index.js:688:15)\n    at process.processImmediate (node:internal/timers:485:21)"}
+[2025-12-10T21:04:21.565Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","name":"John Doe","email":"***@***","card":"****-****-****-****"},{"id":"2","name":"Jane Doe","email":"***@***","card":"****-****-****-****"}]}
+[2025-12-10T21:04:21.565Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","card":"****-****-****-****","name":"John Doe","email":"***@***"},{"id":"2","card":"****-****-****-****","name":"Jane Doe","email":"***@***"}]}
+[2025-12-10T21:03:32.910Z] [30] http.start {"host":"127.0.0.1","port":3000}
 ```
 
-### Ejemplo Express
-
-```typescript
-import express from "express";
-import { LoggerFactory, LogLevel } from "@jmlq/logger";
+#### 3. Búsqueda por texto (en el campo mensaje del log)
 
-const app = express();
-const logger = LoggerFactory.create({
-  datasources: /* tu datasource */,
-  minLevel: LogLevel.INFO
+```ts
+const userLogs = await _req.logger?.getLogs({
+  query: "Users",
 });
+```
 
-app.use(async (req, res, next) => {
-  await logger.info("Request iniciado", {
-    method: req.method,
-    url: req.url,
-    ip: req.ip
-  });
-  next();
-});
+Resultado:
 
-app.get("/users/:id", async (req, res) => {
-  try {
-    await logger.info("Obteniendo usuario", { userId: req.params.id });
-    // ... tu lógica
-    res.json({ user: data });
-  } catch (error) {
-    await logger.error("Error al obtener usuario", {
-      userId: req.params.id,
-      error: error.message
-    });
-    res.status(500).json({ error: "Internal server error" });
-  }
+```ini
+[2025-12-10T22:58:09.874Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","card":"****-****-****-****","name":"John Doe","email":"***@***"},{"id":"2","card":"****-****-****-****","name":"Jane Doe","email":"***@***"}]}
+[2025-12-10T22:57:28.483Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","name":"John Doe","email":"***@***","card":"****-****-****-****"},{"id":"2","name":"Jane Doe","email":"***@***","card":"****-****-****-****"}]}
+```
+
+#### 4. Combinación de filtros
+
+```ts
+const logs = await _req.logger?.getLogs({
+  levelMin: parseLogLevel("INFO"),
+  since: Date.now() - 2 * 60 * 60 * 1000, // Últimas 2 horas
+  query: "successfully",
 });
 ```
 
-### Ejemplo NestJS
-
-```typescript
-@Injectable()
-export class AppService {
-  constructor(@Inject("LOGGER") private readonly logger: ILoggerService) {}
-
-  async createUser(userData: any) {
-    await this.logger.info("Creando usuario", { userData });
-    try {
-      // ... lógica
-      await this.logger.info("Usuario creado", { userId: result.id });
-      return result;
-    } catch (error) {
-      await this.logger.error("Error creando usuario", {
-        error: error.message,
-      });
-      throw error;
-    }
-  }
-}
+Resultado:
+
+```ini
+[2025-12-10T23:05:31.791Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","name":"John Doe","email":"***@***","card":"****-****-****-****"},{"id":"2","name":"Jane Doe","email":"***@***","card":"****-****-****-****"}]}
+[2025-12-10T23:05:31.791Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","card":"****-****-****-****","name":"John Doe","email":"***@***"},{"id":"2","card":"****-****-****-****","name":"Jane Doe","email":"***@***"}]}
+[2025-12-10T22:58:09.874Z] [30] Users listed successfully {"count":2,"result":[{"id":"1","name":"John Doe","email":"***@***","card":"****-****-****-****"},{"id":"2","name":"Jane Doe","email":"***@***","card":"****-****-****-****"}]}
 ```
 
 ## 🏗️ Arquitectura
@@ -246,56 +236,6 @@ src/
 | `@jmlq/logger-plugin-mongo`      | Persistencia en MongoDB    | [npm](https://npmjs.com/package/@jmlq/logger-plugin-mongo)      |
 | `@jmlq/logger-plugin-postgresql` | Persistencia en PostgreSQL | [npm](https://npmjs.com/package/@jmlq/logger-plugin-postgresql) |
 
-## 🧪 Testing
-
-```typescript
-import { LoggerFactory, LogLevel } from "@jmlq/logger";
-
-describe("Logger Tests", () => {
-  it("debe enmascarar PII correctamente", async () => {
-    const logs: any[] = [];
-    const mockDatasource = {
-      name: "mock",
-      async save(log: any) {
-        logs.push(log);
-      },
-      async find() {
-        return [];
-      },
-      async flush() {},
-      async dispose() {},
-    };
-
-    const logger = LoggerFactory.create({
-      datasources: mockDatasource,
-      redactorOptions: { enabled: true },
-    });
-
-    await logger.info("Usuario: user@example.com");
-
-    expect(logs[0].message).not.toContain("user@example.com");
-    expect(logs[0].message).toContain("[EMAIL]");
-  });
-});
-```
-
-## 🚨 Troubleshooting
-
-**Error: No datasources válidos**
-
-- Asegúrate de configurar al menos un datasource
-- Verifica las variables de entorno
-
-**MongoDB no conecta**
-
-- Verifica la URL de conexión
-- Incluye `authSource=admin` si usas usuarios root
-
-**Alto uso de memoria**
-
-- Implementa límites en las consultas
-- Usa `flush()` periódicamente para vaciar buffers
-
 ## 📄 Más Información
 
 - **[Arquitectura Detallada](./architecture.md)** - Documentación técnica completa

package/dist/infrastructure/services/datasource.service.js

@@ -43,6 +43,34 @@ class DataSourceService {
         logs.sort((a, b) => b.timestamp - a.timestamp);
         return logs;
     }
+    // async find(filter?: IGetLogsFilterProps): Promise<ILogResponse[]> {
+    //   let results = [...this.logs];
+    //   if (filter?.levelMin !== undefined) {
+    //     results = results.filter((log) => log.level >= filter.levelMin!);
+    //   }
+    //   if (filter?.since !== undefined) {
+    //     results = results.filter((log) => log.timestamp >= filter.since!);
+    //   }
+    //   if (filter?.until !== undefined) {
+    //     results = results.filter((log) => log.timestamp <= filter.until!);
+    //   }
+    //   if (filter?.query) {
+    //     const q = filter.query.toLowerCase();
+    //     results = results.filter((log) => {
+    //       const msg =
+    //         typeof log.message === "string"
+    //           ? log.message.toLowerCase()
+    //           : JSON.stringify(log.message).toLowerCase();
+    //       return msg.includes(q);
+    //     });
+    //   }
+    //   // Ordenar por timestamp ascendente (opcional pero útil para visualizar)
+    //   results.sort((a, b) => a.timestamp - b.timestamp);
+    //   // Paginación
+    //   const offset = filter?.offset ?? 0;
+    //   const limit = filter?.limit ?? results.length;
+    //   return results.slice(offset, offset + limit);
+    // }
     async flush() {
         const results = await Promise.allSettled(this.targets.map((ds) => ds.flush?.()));
         results.forEach((r, i) => {