@jmlq/logger 0.1.0-alpha.12 → 0.1.0-alpha.14

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/application/factory/logger.factory.d.ts

@@ -1,4 +1,4 @@
-import { ILoggerFactoryConfig, ILoggerService } from "../../domain/ports";
+import { ILoggerFactoryConfig, ILogger } from "../../domain/ports";
 /**
  * Factory principal de @jmlq/logger.
  * Se encarga de:
@@ -8,5 +8,5 @@ import { ILoggerFactoryConfig, ILoggerService } from "../../domain/ports";
  *  - Exponer un servicio de logger de alto nivel
  */
 export declare class LoggerFactory {
-    static create(config: ILoggerFactoryConfig): ILoggerService;
+    static create(config: ILoggerFactoryConfig): ILogger;
 }

package/dist/domain/ports/index.d.ts

@@ -3,4 +3,3 @@ export * from "./logger.port";
 export * from "./pii-redactor.port";
 export * from "./create-logger-options.port";
 export * from "./logger-factory-config.port";
-export * from "./logger-service.port";

package/dist/domain/ports/index.js

@@ -19,4 +19,4 @@ __exportStar(require("./logger.port"), exports);
 __exportStar(require("./pii-redactor.port"), exports);
 __exportStar(require("./create-logger-options.port"), exports);
 __exportStar(require("./logger-factory-config.port"), exports);
-__exportStar(require("./logger-service.port"), exports);
+// export * from "./logger-service.port";

package/dist/domain/ports/logger.port.d.ts

@@ -1,10 +1,15 @@
+import { IGetLogsFilterProps } from "../request";
+import { ILogResponse } from "../response";
+import { LogMessage } from "../types";
+import { LogLevel } from "../value-objects";
 export interface ILogger {
-    trace: (message: unknown, meta?: unknown) => void | Promise<void>;
-    debug: (message: unknown, meta?: unknown) => void | Promise<void>;
-    info: (message: unknown, meta?: unknown) => void | Promise<void>;
-    warn: (message: unknown, meta?: unknown) => void | Promise<void>;
-    error: (message: unknown, meta?: unknown) => void | Promise<void>;
-    fatal: (message: unknown, meta?: unknown) => void | Promise<void>;
-    flush?: () => Promise<void>;
-    dispose?: () => Promise<void>;
+    log(level: LogLevel, message: LogMessage, meta?: unknown): Promise<void>;
+    trace(message: LogMessage, meta?: unknown): Promise<void>;
+    debug(message: LogMessage, meta?: unknown): Promise<void>;
+    info(message: LogMessage, meta?: unknown): Promise<void>;
+    warn(message: LogMessage, meta?: unknown): Promise<void>;
+    error(message: LogMessage, meta?: unknown): Promise<void>;
+    fatal(message: LogMessage, meta?: unknown): Promise<void>;
+    getLogs(filter?: IGetLogsFilterProps): Promise<ILogResponse[]>;
+    flush(): Promise<void>;
 }

package/dist/infrastructure/services/datasource.service.d.ts

@@ -6,6 +6,7 @@ export declare class DataSourceService implements ILogDatasource {
     private readonly targets;
     private readonly onError?;
     readonly name = "composite";
+    private logs;
     constructor(targets: ILogDatasource[], onError?: DataSourceErrorHandler | undefined);
     private handleError;
     save(log: ILogProps): Promise<void>;

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

@@ -6,6 +6,7 @@ class DataSourceService {
         this.targets = targets;
         this.onError = onError;
         this.name = "composite";
+        this.logs = [];
         this.targets = (targets ?? []).filter(Boolean);
     }
     handleError(op, i, reason) {
@@ -29,19 +30,47 @@ class DataSourceService {
             }
         });
     }
+    // async find(filter?: IGetLogsFilterProps) {
+    //   const results = await Promise.allSettled(
+    //     this.targets.map((ds) => ds.find?.(filter))
+    //   );
+    //   const logs: ILogResponse[] = [];
+    //   results.forEach((r, i) => {
+    //     if (r.status === "fulfilled" && Array.isArray(r.value)) {
+    //       logs.push(...r.value);
+    //     } else if (r.status === "rejected") {
+    //       this.handleError("find", i, r.reason);
+    //     }
+    //   });
+    //   logs.sort((a, b) => b.timestamp - a.timestamp);
+    //   return logs;
+    // }
     async find(filter) {
-        const results = await Promise.allSettled(this.targets.map((ds) => ds.find?.(filter)));
-        const logs = [];
-        results.forEach((r, i) => {
-            if (r.status === "fulfilled" && Array.isArray(r.value)) {
-                logs.push(...r.value);
-            }
-            else if (r.status === "rejected") {
-                this.handleError("find", i, r.reason);
-            }
-        });
-        logs.sort((a, b) => b.timestamp - a.timestamp);
-        return logs;
+        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?.()));