@adatechnology/logger 0.0.2

package/src/implementations/winston/winston.logger.module.ts

@@ -0,0 +1,305 @@
+import { DynamicModule, Module, Provider } from "@nestjs/common";
+import { createLogger, format, transports, LoggerOptions } from "winston";
+import { inspect } from "util";
+import { WinstonLoggerProvider } from "./winston.logger.provider";
+import {
+  WINSTON_LOGGER,
+  WINSTON_RAW,
+  WINSTON_OBFUSCATOR,
+} from "./winston.logger.token";
+import type { LoggerConfig } from "../../logger.config";
+import { DEFAULT_LOG_LEVEL } from "./winston.logger.constants";
+import { buildDefaultObfuscator } from "../../obfuscator";
+
+@Module({})
+export class WinstonImplementationModule {
+  static forRoot(config?: LoggerConfig): DynamicModule {
+    const providers = this.createProviders(config);
+
+    return {
+      module: WinstonImplementationModule,
+      providers,
+      exports: [WINSTON_LOGGER],
+    };
+  }
+
+  static forRootAsync(options: {
+    imports?: any[];
+    useFactory: (...args: any[]) => Promise<LoggerConfig> | LoggerConfig;
+    inject?: any[];
+  }): DynamicModule {
+    return {
+      module: WinstonImplementationModule,
+      imports: options.imports || [],
+      providers: [
+        {
+          provide: "LOGGER_CONFIG",
+          useFactory: options.useFactory,
+          inject: options.inject || [],
+        },
+        {
+          provide: WINSTON_RAW,
+          useFactory: (config: LoggerConfig) => {
+            return this.createWinstonLogger(config);
+          },
+          inject: ["LOGGER_CONFIG"],
+        },
+        {
+          provide: WINSTON_OBFUSCATOR,
+          useFactory: (config: LoggerConfig) => {
+            return (
+              config?.obfuscator ??
+              buildDefaultObfuscator(config?.obfuscatorKeys)
+            );
+          },
+          inject: ["LOGGER_CONFIG"],
+        },
+        {
+          provide: WINSTON_LOGGER,
+          useClass: WinstonLoggerProvider,
+        },
+      ],
+      exports: [WINSTON_LOGGER],
+    };
+  }
+
+  private static createProviders(config?: LoggerConfig): Provider[] {
+    const winstonLogger = this.createWinstonLogger(config);
+    const obfuscator =
+      config?.obfuscator ?? buildDefaultObfuscator(config?.obfuscatorKeys);
+
+    return [
+      {
+        provide: WINSTON_RAW,
+        useValue: winstonLogger,
+      },
+      {
+        provide: WINSTON_OBFUSCATOR,
+        useValue: obfuscator,
+      },
+      {
+        provide: WINSTON_LOGGER,
+        useClass: WinstonLoggerProvider,
+      },
+    ];
+  }
+
+  private static createWinstonLogger(config?: LoggerConfig) {
+    const isProduction =
+      config?.isProduction ?? process.env.NODE_ENV === "production";
+    const useColors = config?.colorize !== false;
+
+    // Standard fields we want to ensure are in the log object
+    const standardFields = format((info) => {
+      // Extract requestId and context from meta if they exist there
+      const meta = info.meta as any;
+      if (meta) {
+        if (meta.requestId && !info.requestId) {
+          info.requestId = meta.requestId;
+          delete meta.requestId;
+        }
+        if (meta.context && !info.context) {
+          info.context = meta.context;
+          delete meta.context;
+        }
+
+        // Extract source (used for className.methodName)
+        if (meta.source && !info.source) {
+          info.source = meta.source;
+          delete meta.source;
+        }
+
+        // Support lib identification from metadata
+        if (meta.lib && !info.lib) {
+          info.lib = meta.lib;
+          delete meta.lib;
+        }
+
+        // Support lib version identification from metadata
+        if (meta.libVersion && !info.libVersion) {
+          info.libVersion = meta.libVersion;
+          delete meta.libVersion;
+        }
+
+        // Support lib method identification
+        if (meta.libMethod && !info.libMethod) {
+          info.libMethod = meta.libMethod;
+          delete meta.libMethod;
+        }
+
+        // Support app identification from metadata
+        if (meta.appName && !info.appName) {
+          info.appName = meta.appName;
+          delete meta.appName;
+        }
+
+        // Support app version identification from metadata
+        if (meta.appVersion && !info.appVersion) {
+          info.appVersion = meta.appVersion;
+          delete meta.appVersion;
+        }
+
+        // Support logContext object from some providers
+        if (meta.logContext && !info.source) {
+          const lc = meta.logContext;
+          if (lc.className && lc.methodName) {
+            info.source = `${lc.className}.${lc.methodName}`;
+          } else if (lc.className) {
+            info.source = lc.className;
+          } else if (lc.methodName) {
+            info.source = lc.methodName;
+          }
+        }
+      }
+
+      // Default values
+      info.requestId = info.requestId || "no-request-id";
+      info.context = info.context || config?.context || "App";
+      info.appName = info.appName || config?.appName;
+      info.appVersion = info.appVersion || config?.appVersion;
+      info.lib = info.lib || config?.lib;
+      info.libVersion = info.libVersion || config?.libVersion;
+      
+      return info;
+    });
+
+    const levelColorizer = format.colorize();
+
+    // Custom format for development (colorful and intuitive)
+    const developmentFormat = format.printf(
+      (info) => {
+        const { 
+          level, message, timestamp, requestId, context, source, 
+          meta, stack, appName, appVersion, lib, libMethod, libVersion 
+        } = info;
+        
+        // Colors (using ANSI codes for precision)
+        const colors = {
+          reset: "\x1b[0m",
+          gray: "\x1b[90m",
+          cyan: "\x1b[36m",
+          magenta: "\x1b[35m",
+          yellow: "\x1b[33m",
+          red: "\x1b[31m",
+          green: "\x1b[32m",
+          bold: "\x1b[1m",
+        };
+
+        const colorize = (color: string, text: string) => 
+          useColors ? `${color}${text}${colors.reset}` : text;
+
+        // No trailing space for the level itself, but keep it uppercase
+        const coloredLevel = useColors 
+          ? levelColorizer.colorize(level, level.toUpperCase()) 
+          : level.toUpperCase();
+          
+        const coloredTime = colorize(colors.gray, timestamp);
+        const coloredRequestId = colorize(colors.cyan, requestId);
+        
+        // App identification: [App-example@0.0.3]
+        let appDisplay = "";
+        if (appName) {
+          const appText = appVersion ? `${appName}@${appVersion}` : appName;
+          appDisplay = `[${colorize(colors.green, `App-${appText}`)}]`;
+        }
+
+        // Lib identification: [@adatechnology/http-client:0.0.2]
+        let libDisplay = "";
+        if (lib) {
+          const libText = libVersion ? `${lib}:${libVersion}` : lib;
+          libDisplay = `[${colorize(colors.yellow, libText)}]`;
+        }
+
+        const mag = colors.magenta;
+
+        // Context formatting logic:
+        // [Source] (Magenta) - From the caller (e.g., HttpClientController.listPokemon)
+        // [Context.Method] (Magenta) - From the lib itself (e.g., HttpRedisClient.get)
+        let sourceDisplay = "";
+        let libMethodDisplay = "";
+
+        if (source) {
+          sourceDisplay = `[${colorize(mag, source)}]`;
+        }
+
+        if (lib) {
+          // Inside a library log
+          const methodPath = libMethod ? `${context}.${libMethod}` : context;
+          libMethodDisplay = `[${colorize(mag, methodPath)}]`;
+          
+          // If source is the same as context or methodPath, we can omit it to avoid duplication
+          if (source === context || source === methodPath) {
+            sourceDisplay = "";
+          }
+        } else if (!source) {
+          // App-only log without source: use context
+          libMethodDisplay = `[${colorize(mag, context)}]`;
+        } else if (source.startsWith(`${context}.`) || source === context) {
+          // App-only log where source is more specific than context: use source only
+          libMethodDisplay = `[${colorize(mag, source)}]`;
+          sourceDisplay = "";
+        } else {
+          // App-only log with different context and source
+          libMethodDisplay = `[${colorize(mag, context)}]`;
+          sourceDisplay = `[${colorize(mag, source)}]`;
+        }
+
+        // Header line: [App][Lib][requestId][timestamp][Source][LibMethod][LEVEL]
+        let output = `${appDisplay}${libDisplay}[${coloredRequestId}][${coloredTime}]${sourceDisplay}${libMethodDisplay}[${coloredLevel}] - ${message}`;
+
+        // Meta data (Pretty printed if not empty)
+        if (meta && typeof meta === "object" && Object.keys(meta).length > 0) {
+          const inspectedMeta = inspect(meta, {
+            colors: useColors,
+            depth: null,
+            compact: true,
+            sorted: true,
+            breakLength: Infinity,
+          });
+          output += ` - ${inspectedMeta}`;
+        }
+
+        // Error stack trace
+        if (stack) {
+          output += `\n${colorize(colors.red, stack)}`;
+        }
+
+        return output;
+      }
+    );
+
+    const formats = [
+      format.timestamp(),
+      format.errors({ stack: true }),
+      format.splat(),
+      standardFields(),
+    ];
+
+    if (isProduction) {
+      formats.push(format.json());
+    } else {
+      formats.push(developmentFormat);
+    }
+
+    const defaultFormat = format.combine(...formats);
+
+    const consoleTransport = new transports.Console({
+      format: defaultFormat,
+    });
+
+    const defaultOptions: LoggerOptions = {
+      level:
+        config?.level || (process.env.LOG_LEVEL as any) || DEFAULT_LOG_LEVEL,
+      format: defaultFormat,
+      transports: [consoleTransport],
+    };
+
+    const mergedOptions: LoggerOptions = Object.assign(
+      {},
+      defaultOptions,
+      config?.loggerOptions || {},
+    );
+
+    return createLogger(mergedOptions);
+  }
+}

package/src/implementations/winston/winston.logger.provider.ts

@@ -0,0 +1,98 @@
+import { Injectable, Inject } from "@nestjs/common";
+import { Logger as WinstonLoggerType } from "winston";
+import {
+  type LogPayload,
+  type LoggerProviderInterface,
+  LoggerLevel,
+  type LogParams,
+} from "../../logger.interface";
+import type { Obfuscator } from "./winston.logger.types";
+import { getContext } from "../../context/async-context.service";
+import { EMPTY_STRING } from "../../logger.constant";
+import { WINSTON_RAW, WINSTON_OBFUSCATOR } from "./winston.logger.token";
+
+@Injectable()
+export class WinstonLoggerProvider implements LoggerProviderInterface {
+  private context?: string;
+
+  constructor(
+    @Inject(WINSTON_RAW) private readonly logger: WinstonLoggerType,
+    @Inject(WINSTON_OBFUSCATOR) private readonly obfuscator?: Obfuscator,
+  ) {}
+
+  debug(payload: LogPayload): void;
+  debug(message: string, meta?: Record<string, unknown>, context?: string): void;
+  debug(messageOrPayload: string | LogPayload, meta?: Record<string, unknown>, context?: string): void {
+    this.handleLog(LoggerLevel.DEBUG, messageOrPayload, meta, context);
+  }
+
+  info(payload: LogPayload): void;
+  info(message: string, meta?: Record<string, unknown>, context?: string): void;
+  info(messageOrPayload: string | LogPayload, meta?: Record<string, unknown>, context?: string): void {
+    this.handleLog(LoggerLevel.INFO, messageOrPayload, meta, context);
+  }
+
+  warn(payload: LogPayload): void;
+  warn(message: string, meta?: Record<string, unknown>, context?: string): void;
+  warn(messageOrPayload: string | LogPayload, meta?: Record<string, unknown>, context?: string): void {
+    this.handleLog(LoggerLevel.WARN, messageOrPayload, meta, context);
+  }
+
+  error(payload: LogPayload): void;
+  error(message: string, meta?: Record<string, unknown>, context?: string): void;
+  error(messageOrPayload: string | LogPayload, meta?: Record<string, unknown>, context?: string): void {
+    this.handleLog(LoggerLevel.ERROR, messageOrPayload, meta, context);
+  }
+
+  setContext(context: string): void {
+    this.context = context;
+  }
+
+  private handleLog(
+    level: LoggerLevel,
+    messageOrPayload: string | LogPayload,
+    meta?: Record<string, unknown>,
+    context?: string,
+  ): void {
+    let payload: LogPayload;
+
+    if (typeof messageOrPayload === "string") {
+      payload = {
+        message: messageOrPayload,
+        meta,
+        context: context || this.context,
+      };
+    } else {
+      payload = {
+        ...messageOrPayload,
+        context: messageOrPayload.context || context || this.context,
+        meta: { ...messageOrPayload.meta, ...meta },
+      };
+    }
+
+    this.log({ level, payload });
+  }
+
+  private log(params: LogParams) {
+    const { level, payload } = params;
+    // Extract standard fields but keep the rest to pass to Winston
+    const { message, context, meta, ...rest } = payload as any;
+    
+    const messageText = message ?? EMPTY_STRING;
+    const messageContext = context ?? this.context;
+    const obfuscatedMeta = this.obfuscator ? this.obfuscator(meta) : meta;
+
+    const requestContext = getContext();
+    const requestIdFromContext = (requestContext as Record<string, unknown> | undefined)?.requestId;
+    
+    // Merge everything into a flat info object for Winston
+    const logInfo: Record<string, unknown> = {
+      ...rest,
+      context: messageContext,
+      requestId: requestIdFromContext || payload.requestId,
+      meta: obfuscatedMeta,
+    };
+
+    this.logger.log(level as unknown as string, messageText, logInfo);
+  }
+}

package/src/implementations/winston/winston.logger.token.ts

@@ -0,0 +1,3 @@
+export const WINSTON_LOGGER = "WINSTON_LOGGER";
+export const WINSTON_RAW = "WINSTON_RAW";
+export const WINSTON_OBFUSCATOR = "WINSTON_OBFUSCATOR";

package/src/implementations/winston/winston.logger.types.ts

@@ -0,0 +1,16 @@
+import { LoggerOptions } from "winston";
+
+export interface ObfuscatorKey {
+  key: string;
+  obfuscator: Obfuscator;
+}
+
+export interface WinstonModuleConfig {
+  loggerOptions?: LoggerOptions;
+  obfuscator?: Obfuscator;
+  obfuscatorKeys?: Array<string | ObfuscatorKey>;
+}
+
+export type Obfuscator = (value: unknown) => unknown;
+
+export type SensitiveEntry = string | { key: string; obfuscator: Obfuscator };

package/src/index.ts

@@ -0,0 +1,11 @@
+export { LoggerModule } from "./logger.module";
+export { LOGGER_PROVIDER } from "./logger.token";
+export type {
+  LoggerProviderInterface,
+  LogPayload,
+  LoggerLevel,
+} from "./logger.interface";
+export { RequestContextMiddleware } from "./middleware/request-context.middleware";
+export { getContext, runWithContext } from "./context/async-context.service";
+export type { LoggerConfig } from "./logger.config";
+export { DEFAULT_LOGGER_CONFIG } from "./logger.config";

package/src/logger.config.ts

@@ -0,0 +1,57 @@
+import type { WinstonModuleConfig } from "./implementations/winston/winston.logger.types";
+import { LoggerLevel } from "./logger.interface";
+
+export interface LoggerConfig extends WinstonModuleConfig {
+  /**
+   * Define se o provider do logger deve ser request-scoped
+   */
+  requestScoped?: boolean;
+
+  /**
+   * Nível de log padrão (string compatível com winston)
+   */
+  level?: LoggerLevel | string;
+
+  /**
+   * Contexto padrão para os logs
+   */
+  context?: string;
+
+  /**
+   * Define se o log deve ser formatado para produção (ex.: JSON)
+   */
+  isProduction?: boolean;
+
+  /**
+   * Define se deve colorir a saída (útil para desenvolvimento local)
+   */
+  colorize?: boolean;
+
+  /**
+   * Nome da aplicação para exibição nos logs
+   */
+  appName?: string;
+
+  /**
+   * Versão da aplicação para exibição nos logs
+   */
+  appVersion?: string;
+
+  /**
+   * Identificação da biblioteca/módulo que está gerando o log
+   */
+  lib?: string;
+
+  /**
+   * Versão da biblioteca/módulo que está gerando o log
+   */
+  libVersion?: string;
+}
+
+export const DEFAULT_LOGGER_CONFIG: LoggerConfig = {
+  requestScoped: false,
+  level: "info",
+  colorize: true,
+};
+
+export default DEFAULT_LOGGER_CONFIG;

package/src/logger.constant.ts

@@ -0,0 +1,32 @@
+export const DEFAULT_SENSITIVE_KEYS = [
+  "password",
+  "pass",
+  "pwd",
+  "token",
+  "accessToken",
+  "refreshToken",
+  "authorization",
+  "auth",
+  "secret",
+  "ssn",
+  "creditCard",
+];
+
+// constantes de contexto
+export const EMPTY_STRING = "";
+
+// máscara padrão usada para valores sensíveis
+// objeto com constantes relacionadas à máscara de valores sensíveis
+export const MASK = {
+  REPLACEMENT: "****",
+  MIN_LENGTH: 4,
+  EDGE_CHARS: 2,
+} as const;
+
+// exportações legadas para compatibilidade
+export const MASK_REPLACEMENT = MASK.REPLACEMENT;
+export const MASK_MIN_LENGTH = MASK.MIN_LENGTH;
+export const MASK_EDGE_CHARS = MASK.EDGE_CHARS;
+
+// separador usado no id fallback (Date.now() + separador + Math.random())
+export const ID_FALLBACK_SEPARATOR = "-";

package/src/logger.interface.ts

@@ -0,0 +1,25 @@
+export enum LoggerLevel {
+  DEBUG = "debug",
+  INFO = "info",
+  WARN = "warn",
+  ERROR = "error",
+}
+
+export interface LogPayload {
+  message: string;
+  context?: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface LoggerProviderInterface {
+  debug(payload: LogPayload): void;
+  info(payload: LogPayload): void;
+  warn(payload: LogPayload): void;
+  error(payload: LogPayload): void;
+  setContext?(context: string): void;
+}
+
+export type LogParams = {
+  level: LoggerLevel;
+  payload: LogPayload;
+};

package/src/logger.module.ts

@@ -0,0 +1,50 @@
+import { DynamicModule, Module, Scope, Provider, Global } from "@nestjs/common";
+import { LoggerProvider } from "./logger.provider";
+import { LOGGER_PROVIDER } from "./logger.token";
+import { WinstonImplementationModule } from "./implementations/winston/winston.logger.module";
+import type { LoggerConfig } from "./logger.config";
+
+@Global()
+@Module({})
+export class LoggerModule {
+  static forRoot(config?: LoggerConfig): DynamicModule {
+    const implModule = WinstonImplementationModule.forRoot(config);
+    const provider: Provider = {
+      provide: LOGGER_PROVIDER,
+      useClass: LoggerProvider,
+    };
+    if (config && config.requestScoped) {
+      provider.scope = Scope.REQUEST;
+    }
+
+    return {
+      module: LoggerModule,
+      imports: [implModule],
+      providers: [provider],
+      exports: [LOGGER_PROVIDER],
+    };
+  }
+
+  static forRootAsync(options: {
+    imports?: any[];
+    useFactory: (...args: any[]) => Promise<LoggerConfig> | LoggerConfig;
+    inject?: any[];
+  }): DynamicModule {
+    return {
+      module: LoggerModule,
+      imports: [
+        ...(options.imports || []),
+        WinstonImplementationModule.forRootAsync(options),
+      ],
+      providers: [
+        {
+          provide: LOGGER_PROVIDER,
+          useClass: LoggerProvider,
+        },
+      ],
+      exports: [LOGGER_PROVIDER],
+    };
+  }
+}
+
+export { LOGGER_PROVIDER } from "./logger.token";

package/src/logger.provider.ts

@@ -0,0 +1,53 @@
+import { Injectable, Inject } from "@nestjs/common";
+import type { LoggerProviderInterface, LogPayload } from "./logger.interface";
+import { WINSTON_LOGGER } from "./implementations/winston/winston.logger.token";
+
+@Injectable()
+export class LoggerProvider implements LoggerProviderInterface {
+  constructor(
+    @Inject(WINSTON_LOGGER)
+    private readonly implementation: LoggerProviderInterface,
+  ) {}
+
+  debug(payload: LogPayload): void;
+  debug(
+    message: string,
+    meta?: Record<string, unknown>,
+    context?: string,
+  ): void;
+  debug(...args: unknown[]): void {
+    // @ts-ignore - delegate to implementation which supports overloads
+    return this.implementation.debug(...(args as any));
+  }
+
+  info(payload: LogPayload): void;
+  info(message: string, meta?: Record<string, unknown>, context?: string): void;
+  info(...args: unknown[]): void {
+    // @ts-ignore
+    return this.implementation.info(...(args as any));
+  }
+
+  warn(payload: LogPayload): void;
+  warn(message: string, meta?: Record<string, unknown>, context?: string): void;
+  warn(...args: unknown[]): void {
+    // @ts-ignore
+    return this.implementation.warn(...(args as any));
+  }
+
+  error(payload: LogPayload): void;
+  error(
+    message: string,
+    meta?: Record<string, unknown>,
+    context?: string,
+  ): void;
+  error(...args: unknown[]): void {
+    // @ts-ignore
+    return this.implementation.error(...(args as any));
+  }
+  setContext?(context: string): void {
+    if (typeof this.implementation.setContext === "function") {
+      return this.implementation.setContext(context);
+    }
+    return;
+  }
+}

package/src/logger.token.ts

@@ -0,0 +1 @@
+export const LOGGER_PROVIDER = "LOGGER_PROVIDER";

package/src/middleware/request-context.middleware.ts

@@ -0,0 +1,26 @@
+import { Injectable, NestMiddleware } from "@nestjs/common";
+import { randomUUID } from "crypto";
+import { asyncLocalStorage } from "../context/async-context.service";
+import { HEADERS_PARAMS } from "../request-id.constants";
+import { ID_FALLBACK_SEPARATOR } from "../logger.constant";
+import type {
+  RequestLike,
+  ResponseLike,
+  NextFunctionLike,
+} from "./request-context.types";
+
+@Injectable()
+export class RequestContextMiddleware implements NestMiddleware {
+  use(req: RequestLike, _res: ResponseLike, next: NextFunctionLike) {
+    const existing =
+      (req.headers?.[HEADERS_PARAMS.REQUEST_ID] as string) ||
+      (req.headers?.[HEADERS_PARAMS.FALLBACKS[0]] as string);
+    const id =
+      existing ||
+      (typeof randomUUID === "function"
+        ? randomUUID()
+        : `${Date.now()}${ID_FALLBACK_SEPARATOR}${Math.random()}`);
+    // Run the rest of the request inside the async local storage context
+    asyncLocalStorage.run({ requestId: id }, () => next());
+  }
+}