@jmlq/logger 0.1.0-alpha.1 → 0.1.0-alpha.11

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.1",
-  "author": "MLahuasi",
+  "description": "logger package with clean architecture",
+  "version": "0.1.0-alpha.11",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepublishOnly": "npm run 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 { IGetLogsFilter, ILogDatasource, ILog } from "../config";
-export declare class CompositeDatasource implements ILogDatasource {
-    private readonly datasources;
-    constructor(datasources: ILogDatasource[]);
-    save(log: ILog): Promise<void>;
-    find(filter?: IGetLogsFilter): Promise<ILog[]>;
-    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/config/index.d.ts

@@ -1,2 +0,0 @@
-export * from "./interfaces";
-export * from "./types";

package/dist/config/interfaces/index.d.ts

@@ -1,67 +0,0 @@
-import { LogLevel, LogMessage, PiiReplacement } from "..";
-export interface ILog {
-    level: LogLevel;
-    message: string;
-    meta?: unknown;
-    timestamp: number;
-}
-export interface IGetLogsFilter {
-    levelMin?: LogLevel;
-    since?: number;
-    until?: number;
-}
-export interface ILogDatasource {
-    save(log: ILog): Promise<void>;
-    find?(filter?: IGetLogsFilter): Promise<ILog[]>;
-    flush?(): Promise<void>;
-    dispose?(): Promise<void>;
-}
-export interface ILogger {
-    trace: (msg: LogMessage, meta?: unknown) => Promise<void>;
-    debug: (msg: LogMessage, meta?: unknown) => Promise<void>;
-    info: (msg: LogMessage, meta?: unknown) => Promise<void>;
-    warn: (msg: LogMessage, meta?: unknown) => Promise<void>;
-    error: (msg: LogMessage, meta?: unknown) => Promise<void>;
-    fatal: (msg: LogMessage, meta?: unknown) => Promise<void>;
-    flush?: () => Promise<void>;
-    dispose?: () => Promise<void>;
-}
-export interface IPiiPattern {
-    /** (Opcional) Nombre del patrón para debug/telemetría */
-    name?: string;
-    /** Expresión regular a aplicar sobre strings */
-    regex: RegExp;
-    /** Reemplazo, por defecto "[REDACTED]" si no se provee */
-    replacement?: PiiReplacement;
-}
-export interface IPiiRedactorOptions {
-    /** Habilita/deshabilita redacción (permite control fino además del flag redactPII) */
-    enabled?: boolean;
-    /**
-     * Incluye patrones default (true) y fusiona con los custom. Si false, usa solo los personalizados
-     * por el cliente.
-     */
-    includeDefaultPatterns?: boolean;
-    /** Patrones adicionales o propios del cliente */
-    patterns?: IPiiPattern[];
-    /**
-     * Redactar por nombre de clave (deep). Cualquier key que haga match será redacatada
-     * con "[REDACTED]". Acepta exacto o RegExp.
-     */
-    redactKeys?: Array<string | RegExp>;
-    /**
-     * Claves que NO se deben redactar aunque coincidan con patrones o redactKeys.
-     * Prioridad: preserveKeys > redactKeys > patterns.
-     */
-    preserveKeys?: Array<string | RegExp>;
-}
-export interface ICreateLoggerOptions {
-    minLevel?: LogLevel;
-    /** compatibilidad con lo que ya tienes */
-    redactPII?: boolean;
-    /** NUEVO: bloque de configuración PII */
-    pii?: IPiiRedactorOptions & {
-        /** atajo para permitir que el cliente mande solo patterns sin escribir PiiRedactorOptions */
-        patterns?: IPiiPattern[];
-    };
-}

package/dist/config/types/index.d.ts

@@ -1,10 +0,0 @@
-export declare enum LogLevel {
-    TRACE = 0,
-    DEBUG = 1,
-    INFO = 2,
-    WARN = 3,
-    ERROR = 4,
-    FATAL = 5
-}
-export type PiiReplacement = string | ((match: string, keyPath: string[]) => string);
-export type LogMessage = string | Record<string, unknown> | Error;

package/dist/config/types/index.js

@@ -1,13 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LogLevel = void 0;
-// ---- Types ----
-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 = {}));

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

@@ -1 +0,0 @@
-export * from "./pii-redactor";

package/dist/domain/services/pii-redactor.d.ts

@@ -1,27 +0,0 @@
-/**
- * Domain Service: PiiRedactor
- *
- * Propósito:
- * - Redactar/anonimizar PII en strings, objetos y arrays (deep).
- * - Permitir que el cliente pase patrones adicionales/propios.
- * - Controlar redacción por nombre de clave (whitelist/blacklist).
- */
-import { IPiiPattern, IPiiRedactorOptions } from "../../config";
-export declare class PiiRedactor {
-    private readonly enabled;
-    private readonly patterns;
-    private readonly redactKeys;
-    private readonly preserveKeys;
-    constructor(opts?: IPiiRedactorOptions);
-    /** Patrones por defecto (seguros y genéricos). Ajusta según tu dominio/región si lo deseas. */
-    static defaultPatterns(): IPiiPattern[];
-    /** Punto de entrada público: redacción deep de cualquier estructura */
-    redact<T = unknown>(value: T): T;
-    /** === Internos === */
-    private redactValue;
-    private applyPatterns;
-    private isRedactedKey;
-    private isPreservedKey;
-    private keyRedactionReplacement;
-    private clone;
-}