feat: enhance introspection capabilities

Author: kamilmysliwiec

packages/common/interfaces/nest-application-context-options.interface.ts

@@ -53,4 +53,18 @@ export class NestApplicationContextOptions {
    * @default 'reference'
    */
   moduleIdGeneratorAlgorithm?: 'deep-hash' | 'reference';
+
+  /**
+   * Instrument the application context.
+   * This option allows you to add custom instrumentation to the application context.
+   */
+  instrument?: {
+    /**
+     * Function that decorates each instance created by the application context.
+     * This function can be used to add custom properties or methods to the instance.
+     * @param instance The instance to decorate.
+     * @returns The decorated instance.
+     */
+    instanceDecorator: (instance: unknown) => unknown;
+  };
 }

packages/common/services/console-logger.service.ts

@@ -346,6 +346,23 @@ export class ConsoleLogger implements LoggerService {
       writeStreamType?: 'stdout' | 'stderr';
       errorStack?: unknown;
     },
+  ) {
+    const logObject = this.getJsonLogObject(message, options);
+    const formattedMessage =
+      !this.options.colors && this.inspectOptions.compact === true
+        ? JSON.stringify(logObject, this.stringifyReplacer)
+        : inspect(logObject, this.inspectOptions);
+    process[options.writeStreamType ?? 'stdout'].write(`${formattedMessage}\n`);
+  }
+
+  protected getJsonLogObject(
+    message: unknown,
+    options: {
+      context: string;
+      logLevel: LogLevel;
+      writeStreamType?: 'stdout' | 'stderr';
+      errorStack?: unknown;
+    },
   ) {
     type JsonLogObject = {
       level: LogLevel;
@@ -370,12 +387,7 @@ export class ConsoleLogger implements LoggerService {
     if (options.errorStack) {
       logObject.stack = options.errorStack;
     }
-
-    const formattedMessage =
-      !this.options.colors && this.inspectOptions.compact === true
-        ? JSON.stringify(logObject, this.stringifyReplacer)
-        : inspect(logObject, this.inspectOptions);
-    process[options.writeStreamType ?? 'stdout'].write(`${formattedMessage}\n`);
+    return logObject;
   }
 
   protected formatPid(pid: number) {

packages/core/adapters/http-adapter.ts

@@ -12,6 +12,9 @@ export abstract class AbstractHttpAdapter<
 > implements HttpServer<TRequest, TResponse>
 {
   protected httpServer: TServer;
+  protected onRouteTriggered:
+    | ((requestMethod: RequestMethod, path: string) => void)
+    | undefined;
 
   constructor(protected instance?: any) {}
 
@@ -143,6 +146,16 @@ export abstract class AbstractHttpAdapter<
     return path;
   }
 
+  public setOnRouteTriggered(
+    onRouteTriggered: (requestMethod: RequestMethod, path: string) => void,
+  ) {
+    this.onRouteTriggered = onRouteTriggered;
+  }
+
+  public getOnRouteTriggered() {
+    return this.onRouteTriggered;
+  }
+
   abstract close();
   abstract initHttpServer(options: NestApplicationOptions);
   abstract useStaticAssets(...args: any[]);
@@ -174,4 +187,6 @@ export abstract class AbstractHttpAdapter<
     version: VersionValue,
     versioningOptions: VersioningOptions,
   ): (req: TRequest, res: TResponse, next: () => void) => Function;
+  abstract setOnRequestHook?(onRequestHook: Function): void;
+  abstract setOnResponseHook?(onResponseHook: Function): void;
 }

packages/core/helpers/http-adapter-host.ts

@@ -1,4 +1,4 @@
-import { Observable, Subject } from 'rxjs';
+import { Observable, ReplaySubject, Subject } from 'rxjs';
 import { AbstractHttpAdapter } from '../adapters/http-adapter';
 
 /**
@@ -18,6 +18,7 @@ export class HttpAdapterHost<
 > {
   private _httpAdapter?: T;
   private _listen$ = new Subject<void>();
+  private _init$ = new ReplaySubject<void>();
   private isListening = false;
 
   /**
@@ -27,6 +28,9 @@ export class HttpAdapterHost<
    */
   set httpAdapter(httpAdapter: T) {
     this._httpAdapter = httpAdapter;
+
+    this._init$.next();
+    this._init$.complete();
   }
 
   /**
@@ -47,6 +51,14 @@ export class HttpAdapterHost<
     return this._listen$.asObservable();
   }
 
+  /**
+   * Observable that allows to subscribe to the `init` event.
+   * This event is emitted when the HTTP application is initialized.
+   */
+  get init$(): Observable<void> {
+    return this._init$.asObservable();
+  }
+
   /**
    * Sets the listening state of the application.
    */

packages/core/injector/container.ts

@@ -67,6 +67,10 @@ export class NestContainer {
     return this._applicationConfig;
   }
 
+  get contextOptions(): NestApplicationContextOptions | undefined {
+    return this._contextOptions;
+  }
+
   public setHttpAdapter(httpAdapter: any) {
     this.internalProvidersStorage.httpAdapter = httpAdapter;
 

packages/core/injector/injector.ts

@@ -84,8 +84,26 @@ export interface InjectorDependencyContext {
 
 export class Injector {
   private logger: LoggerService = new Logger('InjectorLogger');
+  private readonly instanceDecorator: (target: unknown) => unknown = (
+    target: unknown,
+  ) => target;
 
-  constructor(private readonly options?: { preview: boolean }) {}
+  constructor(
+    private readonly options?: {
+      /**
+       * Whether to enable preview mode.
+       */
+      preview: boolean;
+      /**
+       * Function to decorate a freshly created instance.
+       */
+      instanceDecorator?: (target: unknown) => unknown;
+    },
+  ) {
+    if (options?.instanceDecorator) {
+      this.instanceDecorator = options.instanceDecorator;
+    }
+  }
 
   public loadPrototype<T>(
     { token }: InstanceWrapper<T>,
@@ -768,11 +786,14 @@ export class Injector {
             new (metatype as Type<any>)(...instances),
           )
         : new (metatype as Type<any>)(...instances);
+
+      instanceHost.instance = this.instanceDecorator(instanceHost.instance);
     } else if (isInContext) {
       const factoryReturnValue = (targetMetatype.metatype as any as Function)(
         ...instances,
       );
       instanceHost.instance = await factoryReturnValue;
+      instanceHost.instance = this.instanceDecorator(instanceHost.instance);
     }
     instanceHost.isResolved = true;
     return instanceHost.instance;

packages/core/injector/internal-core-module/internal-core-module-factory.ts

@@ -27,7 +27,11 @@ export class InternalCoreModuleFactory {
       const logger = new Logger(LazyModuleLoader.name, {
         timestamp: false,
       });
-      const injector = new Injector();
+      const injector = new Injector({
+        preview: container.contextOptions?.preview!,
+        instanceDecorator:
+          container.contextOptions?.instrument?.instanceDecorator,
+      });
       const instanceLoader = new InstanceLoader(
         container,
         injector,

packages/core/injector/module-ref.ts

@@ -23,7 +23,7 @@ export interface ModuleRefGetOrResolveOpts {
 }
 
 export abstract class ModuleRef extends AbstractInstanceResolver {
-  protected readonly injector = new Injector();
+  protected readonly injector: Injector;
   private _instanceLinksHost: InstanceLinksHost;
 
   protected get instanceLinksHost() {
@@ -35,6 +35,12 @@ export abstract class ModuleRef extends AbstractInstanceResolver {
 
   constructor(protected readonly container: NestContainer) {
     super();
+
+    this.injector = new Injector({
+      preview: container.contextOptions?.preview!,
+      instanceDecorator:
+        container.contextOptions?.instrument?.instanceDecorator,
+    });
   }
 
   /**

packages/core/injector/module.ts

@@ -384,13 +384,16 @@ export class Module {
     enhancerSubtype?: EnhancerSubtype,
   ) {
     const { useValue: value, provide: providerToken } = provider;
+
+    const instanceDecorator =
+      this.container.contextOptions?.instrument?.instanceDecorator;
     collection.set(
       providerToken,
       new InstanceWrapper({
         token: providerToken,
         name: (providerToken as Function)?.name || providerToken,
         metatype: null!,
-        instance: value,
+        instance: instanceDecorator ? instanceDecorator(value) : value,
         isResolved: true,
         async: value instanceof Promise,
         host: this,

packages/core/injector/modules-container.ts

@@ -1,14 +1,41 @@
+import { Observable, ReplaySubject } from 'rxjs';
 import { uid } from 'uid';
 import { Module } from './module';
 
 export class ModulesContainer extends Map<string, Module> {
   private readonly _applicationId = uid(21);
+  private readonly _rpcTargetRegistry$ = new ReplaySubject<any>();
 
+  /**
+   * Unique identifier of the application instance.
+   */
   get applicationId(): string {
     return this._applicationId;
   }
 
+  /**
+   * Retrieves a module by its identifier.
+   * @param id The identifier of the module to retrieve.
+   * @returns The module instance if found, otherwise undefined.
+   */
   public getById(id: string): Module | undefined {
     return Array.from(this.values()).find(moduleRef => moduleRef.id === id);
   }
+
+  /**
+   * Returns the RPC target registry as an observable.
+   * This registry contains all RPC targets registered in the application.
+   * @returns An observable that emits the RPC target registry.
+   */
+  public getRpcTargetRegistry<T>(): Observable<T> {
+    return this._rpcTargetRegistry$.asObservable();
+  }
+
+  /**
+   * Adds an RPC target to the registry.
+   * @param target The RPC target to add.
+   */
+  public addRpcTarget<T>(target: T): void {
+    this._rpcTargetRegistry$.next(target);
+  }
 }