feature: logger hook functions (#10)

* added hooks functions ability for each log level or all

* updated jsdoc

Author: idbenami

src/context-logger.spec.ts

@@ -15,9 +15,9 @@ describe('ContextLogger', () => {
 
   beforeEach(() => {
     jest.clearAllMocks();
-    
+
     jest.spyOn(ContextStore, 'getContext').mockReturnValue(CONTEXT);
-    
+
     mockLogger = {
       log: spyLog,
       debug: spyDebug,
@@ -29,7 +29,7 @@ describe('ContextLogger', () => {
     // Reset the internal logger for each test to ensure clean state
     (ContextLogger as any).internalLogger = null;
     ContextLogger.init(mockLogger);
-    
+
     contextLogger = new ContextLogger(MODULE_NAME);
   });
 
@@ -59,7 +59,7 @@ describe('ContextLogger', () => {
 
       expect(mockLogger.log).toHaveBeenCalledWith(CONTEXT, message, MODULE_NAME);
     });
-    
+
     it('should call log method when info is called', () => {
       const message = 'Test message';
       const bindings = { someBinding: 'value' };
@@ -245,7 +245,7 @@ describe('ContextLogger', () => {
         // Reset the internal logger for each test to ensure clean state
         (ContextLogger as any).internalLogger = null;
       });
-      
+
       it('should group only bindings when bindingsKey provided', () => {
         const logger = new ContextLogger(MODULE_NAME);
         ContextLogger.init(mockLogger, { groupFields: { bindingsKey: 'params' } });
@@ -318,7 +318,7 @@ describe('ContextLogger', () => {
         // Reset the internal logger for each test to ensure clean state
         (ContextLogger as any).internalLogger = null;
       });
-      
+
       it('should group both bindings and context under specified keys', () => {
         const logger = new ContextLogger(MODULE_NAME);
         ContextLogger.init(mockLogger, {
@@ -369,7 +369,7 @@ describe('ContextLogger', () => {
       // Reset the internal logger for each test to ensure clean state
       (ContextLogger as any).internalLogger = null;
     });
-    
+
     it('should adapt context when adapter is provided', () => {
       const logger = new ContextLogger(MODULE_NAME);
       ContextLogger.init(mockLogger, {
@@ -413,7 +413,7 @@ describe('ContextLogger', () => {
       // Reset the internal logger for each test to ensure clean state
       (ContextLogger as any).internalLogger = null;
     });
-    
+
     it('should ignore bootstrap logs when ignoreBootstrapLogs is true', () => {
       const logger = new ContextLogger(MODULE_NAME);
       ContextLogger.init(mockLogger, { ignoreBootstrapLogs: true });
@@ -452,4 +452,65 @@ describe('ContextLogger', () => {
       );
     });
   });
+
+  describe('hook functions', () => {
+    it('should call hook function when provided', () => {
+      const logger = new ContextLogger(MODULE_NAME);
+      const logMessage = 'Test message';
+      const bindings = { someBinding: 'value' };
+      const hookSpy = jest.fn();
+
+      ContextLogger.init(mockLogger, {
+        hooks: {
+          log: [hookSpy],
+        },
+      });
+
+      logger.log(logMessage, bindings);
+
+      expect(hookSpy).toHaveBeenCalledWith(logMessage, { ...bindings, ...CONTEXT });
+    });
+
+    it('should call multiple hook function when provided', () => {
+      const logger = new ContextLogger(MODULE_NAME);
+      const logMessage = 'Test message';
+      const bindings = { someBinding: 'value' };
+      const hookSpy1 = jest.fn();
+      const hookSpy2 = jest.fn();
+      const hookSpy3 = jest.fn();
+
+      ContextLogger.init(mockLogger, {
+        hooks: {
+          log: [hookSpy1, hookSpy2, hookSpy3],
+        },
+      });
+
+      logger.log(logMessage, bindings);
+
+      expect(hookSpy1).toHaveBeenCalledWith(logMessage, { ...bindings, ...CONTEXT });
+      expect(hookSpy2).toHaveBeenCalledWith(logMessage, { ...bindings, ...CONTEXT });
+      expect(hookSpy3).toHaveBeenCalledWith(logMessage, { ...bindings, ...CONTEXT });
+    });
+
+    it('should call \'all\' hook function when provided', () => {
+      const logger = new ContextLogger(MODULE_NAME);
+      const logMessage = 'Test message';
+      const bindings = { someBinding: 'value' };
+      const hookSpy = jest.fn();
+      const allHookSpy = jest.fn();
+
+      ContextLogger.init(mockLogger, {
+        hooks: {
+          log: [hookSpy],
+          all: [allHookSpy],
+        },
+      });
+
+      logger.log(logMessage, bindings);
+      logger.debug(logMessage, bindings);
+
+      expect(hookSpy).toHaveBeenCalledTimes(1);
+      expect(allHookSpy).toHaveBeenCalledTimes(2);
+    });
+  });
 });

src/context-logger.ts

@@ -1,15 +1,9 @@
-import { Logger as NestLogger } from '@nestjs/common';
+import { LogLevel, Logger as NestLogger } from '@nestjs/common';
 import { Logger as NestJSPinoLogger } from 'nestjs-pino';
 import { ContextStore } from './store/context-store';
 import { omitBy, isNil, isEmpty } from 'lodash';
 import { ContextLoggerFactoryOptions } from './interfaces/context-logger.interface';
-
-type Bindings = Record<string, any>;
-
-export interface LogEntry {
-  [key: string]: any;
-  err?: Error | string;
-}
+import { Bindings, LogEntry } from './types';
 
 export class ContextLogger {
   private static internalLogger: NestJSPinoLogger;
@@ -85,7 +79,7 @@ export class ContextLogger {
     this.callInternalLogger('error', message, adaptedBindings, error);
   }
 
-  private callInternalLogger(level: string, message: string, bindings: Bindings, error?: Error | string) {
+  private callInternalLogger(level: LogLevel, message: string, bindings: Bindings, error?: Error | string) {
     // If it's a bootstrap log and ignoreBootstrapLogs is true, do nothing
     if (typeof bindings === 'string' && ContextLogger.options?.ignoreBootstrapLogs) {
       return;
@@ -99,6 +93,7 @@ export class ContextLogger {
       logObject = this.createLogEntry(bindings, error);
     }
     const logger = ContextLogger.internalLogger ?? this.fallbackLogger;
+    this.callHooks(level, message, logObject);
     return logger[level](logObject, ...[message, this.moduleName]);
   }
 
@@ -133,4 +128,18 @@ export class ContextLogger {
 
     return { [key]: obj };
   }
+
+  private callHooks(level: LogLevel, message: string, bindings: Bindings): void {
+    const hooks = ContextLogger.options?.hooks;
+
+    if (!hooks) {
+      return;
+    }
+
+    [...(hooks[level] || []), ...(hooks['all'] || [])].forEach((hook) => {
+      hook(message, bindings);
+    });
+
+    return;
+  }
 }

src/interfaces/context-logger.interface.ts

@@ -1,5 +1,6 @@
 import { ExecutionContext, ModuleMetadata } from '@nestjs/common';
 import { Params } from 'nestjs-pino';
+import { Bindings, LoggerHookKeys } from '../types';
 
 export interface ContextLoggerFactoryOptions extends Params {
   /**
@@ -8,14 +9,14 @@ export interface ContextLoggerFactoryOptions extends Params {
    * Specify keys to group specific fields:
    * - bindingsKey: Groups runtime bindings under this key
    * - contextKey: Groups context data under this key
-   * 
+   *
    * @example
    * // Group both bindings and context
    * groupFields: { bindingsKey: 'params', contextKey: 'metadata' }
-   * 
+   *
    * // Group only bindings, spread context at root
    * groupFields: { bindingsKey: 'params' }
-   * 
+   *
    * // Group only context, spread bindings at root
    * groupFields: { contextKey: 'metadata' }
    */
@@ -43,7 +44,7 @@ export interface ContextLoggerFactoryOptions extends Params {
   /**
    * Optional function to transform the context before it is included in the log entry.
    * Useful for filtering, renaming, or restructuring context data.
-   * 
+   *
    * @param context - The current context object
    * @returns The transformed context object
    */
@@ -59,6 +60,31 @@ export interface ContextLoggerFactoryOptions extends Params {
   enrichContext?: (
     context: ExecutionContext
   ) => Record<string, any> | Promise<Record<string, any>>;
+
+  /**
+   * Optional hooks to execute when a log is created.
+   * These callbacks allow you to extend logging behavior, such as reporting to external systems,
+   * incrementing metrics, or performing side effects based on log level.
+   *
+   * ⚠️ Note: All callbacks are executed **synchronously and sequentially**.
+   * This means each hook will block the next one, potentially introducing latency
+   * to the logging process. Use with caution, especially when performing async-like tasks.
+   *
+   * @example
+   * hooks: {
+   *   all: [
+   *     (message: string, bindings: Bindings) => {
+   *       // do something for all logs
+   *     },
+   *   ],
+   *   error: [
+   *     (message: string, bindings: Bindings) => {
+   *       // do something specific for error logs
+   *     },
+   *   ],
+   * }
+   */
+  hooks?: Partial<Record<LoggerHookKeys, Array<(message: string, bindings: Bindings) => void>>>;
 }
 
 export interface ContextLoggerAsyncOptions extends Pick<ModuleMetadata, 'imports'> {

src/types.ts

@@ -0,0 +1,10 @@
+import { LogLevel } from '@nestjs/common';
+
+export type Bindings = Record<string, any>;
+
+export interface LogEntry {
+  [key: string]: any;
+  err?: Error | string;
+}
+
+export type LoggerHookKeys = LogLevel | 'all';