@jmlq/logger 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/tests/domain/services/to-pii-regex.spec.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const services_1 = require("../../../src/domain/services");
+describe("toPiiRegex()", () => {
+    // ---------------------------------------------------------------------------
+    // 1️⃣ Patrón válido con flags por defecto (g)
+    // ---------------------------------------------------------------------------
+    it("debe crear un RegExp válido con flags 'g' por defecto", () => {
+        const props = {
+            pattern: "\\d+",
+            replaceWith: "[NUM]",
+        };
+        const regex = (0, services_1.toPiiRegex)(props);
+        expect(regex).toBeInstanceOf(RegExp);
+        expect(regex.source).toBe("\\d+");
+        expect(regex.flags).toBe("g");
+        const result = "abc123def456".replace(regex, props.replaceWith);
+        expect(result).toBe("abc[NUM]def[NUM]");
+    });
+    // ---------------------------------------------------------------------------
+    // 2️⃣ Patrón válido con flags personalizados
+    // ---------------------------------------------------------------------------
+    it("debe respetar los flags personalizados si son válidos", () => {
+        const props = {
+            pattern: "test",
+            flags: "gi",
+            replaceWith: "X",
+        };
+        const regex = (0, services_1.toPiiRegex)(props);
+        expect(regex.source).toBe("test");
+        expect(regex.flags).toBe("gi");
+        expect("TeSt 1, test 2".replace(regex, props.replaceWith)).toBe("X 1, X 2");
+    });
+    // ---------------------------------------------------------------------------
+    // 3️⃣ Patrón inválido → debe retornar el RegExp fallback /$a/
+    // ---------------------------------------------------------------------------
+    it("debe retornar un RegExp imposible (/\\$a/) si el patrón es inválido", () => {
+        const props = {
+            pattern: "[unclosed",
+            flags: "g",
+            replaceWith: "X",
+        };
+        const regex = (0, services_1.toPiiRegex)(props);
+        // El fallback esperado es /$a/
+        expect(regex).toBeInstanceOf(RegExp);
+        expect(regex.source).toBe("$a");
+        expect(regex.test("cualquier texto")).toBe(false);
+    });
+    // ---------------------------------------------------------------------------
+    // 4️⃣ Flags inválidos → también debe usar el fallback
+    // ---------------------------------------------------------------------------
+    it("debe usar el fallback si los flags son inválidos", () => {
+        const props = {
+            pattern: "\\d+",
+            flags: "z", // flag inválido
+            replaceWith: "X",
+        };
+        const regex = (0, services_1.toPiiRegex)(props);
+        expect(regex.source).toBe("$a");
+        expect(regex.test("123")).toBe(false);
+    });
+    // ---------------------------------------------------------------------------
+    // 5️⃣ Asegura que el fallback nunca hace match con ejemplos comunes
+    // ---------------------------------------------------------------------------
+    it("el fallback nunca debe hacer match con strings comunes", () => {
+        const props = {
+            pattern: "\\", // clarísimamente inválido
+            replaceWith: "X",
+        };
+        const regex = (0, services_1.toPiiRegex)(props);
+        const samples = [
+            "",
+            "abc",
+            "123",
+            "user@test.com",
+            "tarjeta 4111-1111-1111-1111",
+        ];
+        for (const s of samples) {
+            expect(regex.test(s)).toBe(false);
+        }
+    });
+});

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const infrastructure_1 = require("src/infrastructure");
+const src_1 = require("../../../src");
+describe("DataSourceService", () => {
+    const log = {
+        level: src_1.LogLevel.INFO,
+        message: "test log",
+        timestamp: Date.now(),
+        meta: {
+            userId: "12345",
+        },
+    };
+    const makeDsMock = () => ({
+        name: "mock",
+        save: jest.fn(),
+        find: jest.fn(),
+        flush: jest.fn(),
+        dispose: jest.fn(),
+    });
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    // -------------------------------------------------------------------------
+    // SAVE
+    // -------------------------------------------------------------------------
+    test("save() debe ejecutar save en todos los datasources", async () => {
+        const ds1 = makeDsMock();
+        const ds2 = makeDsMock();
+        const service = new infrastructure_1.DataSourceService([ds1, ds2]);
+        await service.save(log);
+        expect(ds1.save).toHaveBeenCalledWith(log);
+        expect(ds2.save).toHaveBeenCalledWith(log);
+        expect(ds1.save).toHaveBeenCalledTimes(1);
+        expect(ds2.save).toHaveBeenCalledTimes(1);
+    });
+    test("save() debe continuar incluso si uno de los datasources falla y llamar al error handler", async () => {
+        const ds1 = makeDsMock();
+        const ds2 = makeDsMock();
+        ds1.save.mockResolvedValue(undefined);
+        ds2.save.mockRejectedValue(new Error("failure"));
+        const onError = jest.fn();
+        const service = new infrastructure_1.DataSourceService([ds1, ds2], onError);
+        await service.save(log);
+        expect(ds1.save).toHaveBeenCalled();
+        expect(ds2.save).toHaveBeenCalled();
+        expect(onError).toHaveBeenCalledTimes(1);
+        expect(onError).toHaveBeenCalledWith(expect.objectContaining({
+            operation: "save",
+            datasourceName: "mock",
+        }));
+        // Opcional: validar que la razón sea el Error original
+        expect(onError.mock.calls[0][0].reason).toBeInstanceOf(Error);
+        expect(onError.mock.calls[0][0].reason.message).toBe("failure");
+    });
+    // -------------------------------------------------------------------------
+    // FIND
+    // -------------------------------------------------------------------------
+    test("find() debe concatenar resultados de varios datasources y ordenarlos desc por timestamp", async () => {
+        const ds1 = makeDsMock();
+        const ds2 = makeDsMock();
+        const logs1 = [
+            { level: src_1.LogLevel.INFO, message: "a", timestamp: 100 },
+            { level: src_1.LogLevel.WARN, message: "b", timestamp: 300 },
+        ];
+        const logs2 = [
+            { level: src_1.LogLevel.ERROR, message: "c", timestamp: 200 },
+        ];
+        ds1.find.mockResolvedValue(logs1);
+        ds2.find.mockResolvedValue(logs2);
+        const service = new infrastructure_1.DataSourceService([ds1, ds2]);
+        const result = await service.find();
+        expect(result).toHaveLength(3);
+        expect(result.map((l) => l.timestamp)).toEqual([300, 200, 100]);
+    });
+    test("find() ignora datasources que retornen error en find() y llama al error handler", async () => {
+        const ds1 = makeDsMock();
+        const ds2 = makeDsMock();
+        ds1.find.mockRejectedValue(new Error("ds1 fail"));
+        ds2.find.mockResolvedValue([
+            { id: "1", level: src_1.LogLevel.INFO, message: "ok", timestamp: 123 },
+        ]);
+        const onError = jest.fn();
+        const service = new infrastructure_1.DataSourceService([ds1, ds2], onError);
+        const result = await service.find();
+        // Sigue devolviendo solo los logs válidos
+        expect(result).toHaveLength(1);
+        expect(result[0].level).toBe(src_1.LogLevel.INFO);
+        // Y registra el error del datasource que falló
+        expect(onError).toHaveBeenCalledTimes(1);
+        expect(onError).toHaveBeenCalledWith(expect.objectContaining({
+            operation: "find",
+            datasourceName: "mock",
+        }));
+        expect(onError.mock.calls[0][0].reason).toBeInstanceOf(Error);
+        expect(onError.mock.calls[0][0].reason.message).toBe("ds1 fail");
+    });
+    // -------------------------------------------------------------------------
+    // FLUSH
+    // -------------------------------------------------------------------------
+    test("flush() debe llamar flush en todos los datasources que implementen flush()", async () => {
+        const ds1 = makeDsMock();
+        const ds2 = makeDsMock();
+        const service = new infrastructure_1.DataSourceService([ds1, ds2]);
+        await service.flush();
+        expect(ds1.flush).toHaveBeenCalledTimes(1);
+        expect(ds2.flush).toHaveBeenCalledTimes(1);
+    });
+    // -------------------------------------------------------------------------
+    // DISPOSE
+    // -------------------------------------------------------------------------
+    test("dispose() debe llamar dispose en todos los datasources", async () => {
+        const ds1 = makeDsMock();
+        const ds2 = makeDsMock();
+        const service = new infrastructure_1.DataSourceService([ds1, ds2]);
+        await service.dispose();
+        expect(ds1.dispose).toHaveBeenCalledTimes(1);
+        expect(ds2.dispose).toHaveBeenCalledTimes(1);
+    });
+    // -------------------------------------------------------------------------
+    // CONSTRUCTOR DEFENSIVO
+    // -------------------------------------------------------------------------
+    test("constructor debe filtrar targets inválidos (null/undefined)", async () => {
+        const ds1 = makeDsMock();
+        const service = new infrastructure_1.DataSourceService([ds1, null, undefined]);
+        expect(service.targets).toHaveLength(1);
+    });
+});

package/dist/tests/test-utils/create-pii-redactor-mock.d.ts

@@ -0,0 +1,5 @@
+import { IPiiRedactor } from "../../src/domain/ports";
+export type PiiRedactorMock = IPiiRedactor & {
+    redact: jest.Mock;
+};
+export declare function createPiiRedactorMock(): PiiRedactorMock;

package/dist/tests/test-utils/create-pii-redactor-mock.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPiiRedactorMock = createPiiRedactorMock;
+function createPiiRedactorMock() {
+    const redact = jest.fn((value) => value);
+    return {
+        redact,
+        updateOptions: jest.fn(),
+    };
+}

package/install.md

@@ -0,0 +1,367 @@
+# Guía de Instalación y Configuración para @jmlq/logger
+
+## Instalación
+
+```bash
+npm install @jmlq/logger
+```
+
+## Configuración Básica
+
+### NestJS
+
+1. Crear el módulo de Logger
+
+```typescript
+// src/logger/logger.module.ts
+import { Module, Global } from "@nestjs/common";
+import { ConfigModule, ConfigService } from "@nestjs/config";
+import { LoggerFactory } from "@jmlq/logger";
+
+@Global()
+@Module({
+  imports: [ConfigModule],
+  providers: [
+    {
+      provide: "LOGGER",
+      useFactory: async (configService: ConfigService) => {
+        // Configurar datasources según necesidades
+        const datasources = [];
+
+        // Ejemplo: Plugin de filesystem (requiere @jmlq/logger-plugin-fs)
+        if (configService.get("LOG_FS_ENABLED") === "true") {
+          const { FileSystemDatasource } = await import(
+            "@jmlq/logger-plugin-fs"
+          );
+          datasources.push(
+            new FileSystemDatasource({
+              basePath: configService.get("LOG_FS_PATH", "./logs"),
+            })
+          );
+        }
+
+        return LoggerFactory.create({
+          datasources,
+          minLevel: configService.get("LOG_LEVEL", "info"),
+          redactorOptions: {
+            enabled: true,
+            deep: true,
+            includeDefaults: true,
+          },
+        });
+      },
+      inject: [ConfigService],
+    },
+  ],
+  exports: ["LOGGER"],
+})
+export class LoggerModule {}
+```
+
+2. Usar en servicios
+
+```typescript
+// src/users/users.service.ts
+import { Injectable, Inject } from "@nestjs/common";
+import { ILogger } from "@jmlq/logger";
+
+@Injectable()
+export class UsersService {
+  constructor(@Inject("LOGGER") private readonly logger: ILogger) {}
+
+  async createUser(userData: any) {
+    try {
+      await this.logger.info("Creando usuario", { userData });
+      // ... lógica del servicio
+      await this.logger.info("Usuario creado exitosamente", {
+        userId: result.id,
+      });
+      return result;
+    } catch (error) {
+      await this.logger.error("Error al crear usuario", {
+        error: error.message,
+        userData,
+      });
+      throw error;
+    }
+  }
+}
+```
+
+### Express
+
+1. Configurar logger en app.js
+
+```ts
+// src/logger.ts
+import { LoggerFactory, LogLevel } from "@jmlq/logger";
+
+export const createLogger = async () => {
+  const datasources = [];
+
+  // Configurar datasources según variables de entorno
+  if (process.env.LOG_FS_ENABLED === "true") {
+    const { FileSystemDatasource } = await import("@jmlq/logger-plugin-fs");
+    datasources.push(
+      new FileSystemDatasource({
+        basePath: process.env.LOG_FS_PATH || "./logs",
+      })
+    );
+  }
+
+  return LoggerFactory.create({
+    datasources,
+    minLevel: process.env.LOG_LEVEL || LogLevel.INFO,
+    redactorOptions: {
+      enabled: true,
+      deep: true,
+      includeDefaults: true,
+      patterns: [
+        {
+          pattern: "\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b",
+          replaceWith: "****-****-****-****",
+        },
+      ],
+    },
+  });
+};
+```
+
+2. Middleware de logging
+
+```ts
+// src/middleware/logger.middleware.ts
+import { Request, Response, NextFunction } from "express";
+import { ILogger } from "@jmlq/logger";
+
+export const createLoggerMiddleware = (logger: ILogger) => {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    const startTime = Date.now();
+
+    await logger.info("Request iniciado", {
+      method: req.method,
+      url: req.url,
+      ip: req.ip,
+      userAgent: req.get("User-Agent"),
+    });
+
+    res.on("finish", async () => {
+      const duration = Date.now() - startTime;
+      const level = res.statusCode >= 400 ? "error" : "info";
+
+      await logger[level]("Request completado", {
+        method: req.method,
+        url: req.url,
+        statusCode: res.statusCode,
+        duration,
+      });
+    });
+
+    next();
+  };
+};
+```
+
+3. Usar en la aplicación
+
+```ts
+// src/app.ts
+import express from "express";
+import { createLogger } from "./logger";
+import { createLoggerMiddleware } from "./middleware/logger.middleware";
+
+const app = express();
+const logger = await createLogger();
+
+app.use(createLoggerMiddleware(logger));
+
+app.get("/users/:id", async (req, res) => {
+  try {
+    await logger.info("Obteniendo usuario", { userId: req.params.id });
+    // ... lógica
+    res.json(user);
+  } catch (error) {
+    await logger.error("Error al obtener usuario", {
+      userId: req.params.id,
+      error: error.message,
+    });
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+```
+
+## Configuración de PII (Datos Sensibles)
+
+### Patrones Predefinidos
+
+El logger incluye patrones comunes para enmascarar datos sensibles:
+
+```ts
+const logger = LoggerFactory.create({
+  datasources,
+  redactorOptions: {
+    enabled: true,
+    deep: true, // Busca en objetos anidados
+    includeDefaults: true, // Incluye patrones predefinidos (email, teléfono, etc.)
+  },
+});
+```
+
+Patrones Personalizados
+
+```ts
+const logger = LoggerFactory.create({
+  datasources,
+  redactorOptions: {
+    enabled: true,
+    deep: true,
+    includeDefaults: true,
+    patterns: [
+      // Tarjetas de crédito
+      {
+        pattern: "\\b\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}\\b",
+        replaceWith: "****-****-****-****",
+      },
+      // CURP (México)
+      {
+        pattern: "[A-Z]{4}\\d{6}[HM][A-Z]{5}[A-Z0-9]\\d",
+        replaceWith: "****CURP****",
+      },
+      // 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****",
+      },
+    ],
+  },
+});
+```
+
+## Filtrado de Registros
+
+### Filtros Básicos
+
+```ts
+// Obtener todos los logs de nivel ERROR o superior
+const errors = await logger.getLogs({
+  levelMin: LogLevel.ERROR,
+});
+
+// Filtrar por rango de fechas
+const yesterday = Date.now() - 24 * 60 * 60 * 1000;
+const recentLogs = await logger.getLogs({
+  since: yesterday,
+  until: Date.now(),
+});
+
+// Búsqueda por texto
+const userLogs = await logger.getLogs({
+  query: "usuario",
+  limit: 50,
+});
+```
+
+### Filtros Avanzados
+
+```ts
+// Combinación de filtros
+const criticalRecentErrors = await logger.getLogs({
+  levelMin: LogLevel.ERROR,
+  since: Date.now() - 2 * 60 * 60 * 1000, // Últimas 2 horas
+  query: "database connection",
+  limit: 20,
+  offset: 0,
+});
+
+// Paginación
+const page1 = await logger.getLogs({ limit: 10, offset: 0 });
+const page2 = await logger.getLogs({ limit: 10, offset: 10 });
+```
+
+## Variables de Entorno
+
+```bash
+# Nivel mínimo de logs
+LOG_LEVEL=info
+
+# Filesystem
+LOG_FS_ENABLED=true
+LOG_FS_PATH=./logs
+
+# MongoDB (si usas @jmlq/logger-plugin-mongo)
+LOG_MONGO_ENABLED=true
+LOG_MONGO_URL=mongodb://localhost:27017
+LOG_MONGO_DB=logs
+
+# PostgreSQL (si usas @jmlq/logger-plugin-postgresql)
+LOG_PG_ENABLED=true
+LOG_PG_HOST=localhost
+LOG_PG_PORT=5432
+LOG_PG_DATABASE=logs
+LOG_PG_USERNAME=logger
+LOG_PG_PASSWORD=secret
+```
+
+## Ejemplo Completo
+
+```ts
+import { LoggerFactory, LogLevel } from "@jmlq/logger";
+
+// Configuración completa
+const logger = await LoggerFactory.create({
+  datasources: [
+    // Múltiples datasources
+    new FileSystemDatasource({ basePath: "./logs" }),
+    new MongoDatasource({ url: "mongodb://localhost:27017", dbName: "logs" }),
+  ],
+  minLevel: LogLevel.DEBUG,
+  redactorOptions: {
+    enabled: true,
+    deep: true,
+    includeDefaults: true,
+    patterns: [
+      {
+        pattern: "\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b",
+        replaceWith: "****-****-****-****",
+      },
+    ],
+  },
+});
+
+// Uso con diferentes niveles
+await logger.debug("Debug info", { userId: 123 });
+await logger.info("User login", { email: "user@example.com" });
+await logger.warn("High latency", { endpoint: "/api/users", duration: 950 });
+await logger.error("Database error", { error: "Connection timeout" });
+await logger.fatal("System crash", { stack: error.stack });
+
+// Filtrar y consultar logs
+const recentErrors = await logger.getLogs({
+  levelMin: LogLevel.ERROR,
+  since: Date.now() - 24 * 60 * 60 * 1000,
+  limit: 100,
+});
+
+// Limpiar buffers (útil antes de cerrar la aplicación)
+await logger.flush();
+```
+
+## Plugins Disponibles
+
+> - `@jmlq/logger-plugin-fs`: Persistencia en archivos
+> - `@jmlq/logger-plugin-mongo`: Persistencia en MongoDB
+> - `@jmlq/logger-plugin-postgresql`: Persistencia en PostgreSQL
+
+Cada plugin se instala por separado según las necesidades de tu aplicación.
+
+## Consideraciones de Rendimiento
+
+Los logs se procesan de forma asíncrona
+Múltiples datasources escriben en paralelo
+Usa [flush()](./examples/logger-factory.example.ts) antes de cerrar la aplicación para asegurar que todos los logs se persistan
+Configura límites apropiados en las consultas para evitar sobrecarga de memoria

package/package.json

@@ -1,32 +1,42 @@
 {
   "name": "@jmlq/logger",
-  "version": "0.1.0-alpha.7",
-  "author": "MLahuasi",
-  "license": "MIT",
+  "description": "logger package with clean architecture",
+  "version": "0.1.0-alpha.9",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",
     "test": "jest --passWithNoTests",
     "test:watch": "jest --watch",
-    "test:cov": "jest --coverage"
+    "test:coverage": "jest --coverage",
+    "example:help": "tsx examples/index.example.ts help",
+    "example:all": "tsx examples/index.example.ts",
+    "example:domain-services": "tsx examples/index.example.ts domain-services",
+    "example:services": "tsx examples/index.example.ts services",
+    "example:use-cases": "tsx examples/index.example.ts use-cases",
+    "example:factories": "tsx examples/index.example.ts factories"
   },
+  "keywords": [
+    "logger",
+    "clean-architecture",
+    "typescript"
+  ],
+  "author": "MLahuasi",
+  "license": "MIT",
   "devDependencies": {
-    "@swc/core": "^1.13.5",
-    "@swc/jest": "^0.2.39",
-    "@types/jest": "^30.0.0",
-    "@types/node": "^24.3.0",
-    "jest": "^30.1.3",
-    "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",
+    "tsx": "^4.1.4",
+    "typescript": "^5.2.2"
   },
-  "overrides": {
-    "test-exclude": "^7.0.1",
-    "glob": "^10.4.5",
-    "minimatch": "^9.0.5"
-  }
+  "files": [
+    "dist",
+    "architecture.md",
+    "install.md"
+  ]
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024-2025 mlahuasi
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the “Software”), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

package/dist/application/use-cases/flush-buffers.d.ts

@@ -1,6 +0,0 @@
-import { ILogDatasource } from "../../domain/contracts";
-export declare class FlushBuffers {
-    private readonly ds;
-    constructor(ds: ILogDatasource);
-    execute(): Promise<void>;
-}