@jmlq/logger 0.1.0-alpha.0 → 0.1.0-alpha.10

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,19 +1,42 @@
 {
   "name": "@jmlq/logger",
-  "version": "0.1.0-alpha.0",
-  "author": "MLahuasi",
+  "description": "logger package with clean architecture",
+  "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"
+    "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: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": {
-    "@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",
+    "tsx": "^4.1.4",
+    "typescript": "^5.2.2"
+  },
+  "files": [
+    "dist",
+    "architecture.md",
+    "install.md"
+  ]
 }

package/dist/Composite/index.d.ts

@@ -1,9 +0,0 @@
-import { GetLogsFilter, ILogDatasource, Log } from "..";
-export declare class CompositeDatasource implements ILogDatasource {
-    private readonly datasources;
-    constructor(datasources: ILogDatasource[]);
-    save(log: Log): Promise<void>;
-    find(filter?: GetLogsFilter): Promise<Log[]>;
-    flush(): Promise<void>;
-    dispose(): Promise<void>;
-}

package/dist/Composite/index.js

@@ -1,23 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CompositeDatasource = void 0;
-// ---- Composite fan-out ----
-class CompositeDatasource {
-    constructor(datasources) {
-        this.datasources = datasources;
-    }
-    async save(log) {
-        await Promise.allSettled(this.datasources.map((ds) => ds.save(log)));
-    }
-    async find(filter = {}) {
-        const primary = this.datasources[0];
-        return (await primary?.find?.(filter)) ?? [];
-    }
-    async flush() {
-        await Promise.all(this.datasources.map((ds) => ds.flush?.() ?? Promise.resolve()));
-    }
-    async dispose() {
-        await Promise.all(this.datasources.map((ds) => ds.dispose?.() ?? Promise.resolve()));
-    }
-}
-exports.CompositeDatasource = CompositeDatasource;

package/dist/Factory/index.d.ts

@@ -1,5 +0,0 @@
-import { ILogDatasource, Logger, LogLevel } from "..";
-export declare function createLogger(ds: ILogDatasource, opts: {
-    minLevel: LogLevel;
-    redactPII?: boolean;
-}): Logger;

package/dist/Factory/index.js

@@ -1,23 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createLogger = createLogger;
-const __1 = require("..");
-function createLogger(ds, opts) {
-    const write = async (level, message, meta) => {
-        if (level < opts.minLevel)
-            return;
-        // (Opcional) redactor PII aquí si opts.redactPII === true
-        await ds.save({ level, message, meta, timestamp: Date.now() });
-    };
-    const logger = {
-        trace: (m, meta) => write(__1.LogLevel.TRACE, m, meta),
-        debug: (m, meta) => write(__1.LogLevel.DEBUG, m, meta),
-        info: (m, meta) => write(__1.LogLevel.INFO, m, meta),
-        warn: (m, meta) => write(__1.LogLevel.WARN, m, meta),
-        error: (m, meta) => write(__1.LogLevel.ERROR, m, meta),
-        fatal: (m, meta) => write(__1.LogLevel.FATAL, m, meta),
-        flush: () => ds.flush?.() ?? Promise.resolve(),
-        dispose: () => ds.dispose?.() ?? Promise.resolve(),
-    };
-    return logger;
-}

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-export * from "./interfaces";
-export * from "./Factory";
-export * from "./Composite";

package/dist/interfaces/index.d.ts

@@ -1,35 +0,0 @@
-export declare enum LogLevel {
-    TRACE = 0,
-    DEBUG = 1,
-    INFO = 2,
-    WARN = 3,
-    ERROR = 4,
-    FATAL = 5
-}
-export interface Log {
-    level: LogLevel;
-    message: string;
-    meta?: unknown;
-    timestamp: number;
-}
-export interface GetLogsFilter {
-    levelMin?: LogLevel;
-    since?: number;
-    until?: number;
-}
-export interface ILogDatasource {
-    save(log: Log): Promise<void>;
-    find?(filter?: GetLogsFilter): Promise<Log[]>;
-    flush?(): Promise<void>;
-    dispose?(): Promise<void>;
-}
-export interface Logger {
-    trace: (msg: string, meta?: unknown) => Promise<void>;
-    debug: (msg: string, meta?: unknown) => Promise<void>;
-    info: (msg: string, meta?: unknown) => Promise<void>;
-    warn: (msg: string, meta?: unknown) => Promise<void>;
-    error: (msg: string, meta?: unknown) => Promise<void>;
-    fatal: (msg: string, meta?: unknown) => Promise<void>;
-    flush?: () => Promise<void>;
-    dispose?: () => Promise<void>;
-}

package/dist/interfaces/index.js

@@ -1,13 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLevel = void 0;
-// ---- Types & contratos ----
-var LogLevel;
-(function (LogLevel) {
-    LogLevel[LogLevel["TRACE"] = 0] = "TRACE";
-    LogLevel[LogLevel["DEBUG"] = 1] = "DEBUG";
-    LogLevel[LogLevel["INFO"] = 2] = "INFO";
-    LogLevel[LogLevel["WARN"] = 3] = "WARN";
-    LogLevel[LogLevel["ERROR"] = 4] = "ERROR";
-    LogLevel[LogLevel["FATAL"] = 5] = "FATAL";
-})(LogLevel || (exports.LogLevel = LogLevel = {}));