@golevelup/nestjs-discovery

What is @golevelup/nestjs-discovery?

@golevelup/nestjs-discovery is a utility library for the NestJS framework that provides tools for discovering and interacting with providers, controllers, and other components within a NestJS application. It simplifies the process of dynamically finding and using these components.

What are @golevelup/nestjs-discovery's main functionalities?

Discover Providers

This feature allows you to discover all providers that have a specific metadata key. This can be useful for dynamically interacting with certain providers based on custom metadata.

const providers = await discoveryService.providersWithMetaAtKey('someMetaKey');

Discover Controllers

Similar to discovering providers, this feature lets you find all controllers that have a specific metadata key. This can be useful for dynamically routing or handling requests based on controller metadata.

const controllers = await discoveryService.controllersWithMetaAtKey('someMetaKey');

Discover Methods

This feature allows you to discover all methods within your application that have a specific metadata key. This can be useful for dynamically invoking methods or applying certain behaviors based on method metadata.

const methods = await discoveryService.methodsWithMetaAtKey('someMetaKey');

Other packages similar to @golevelup/nestjs-discovery

nestjs-query

nestjs-query is a package that provides a set of tools for building GraphQL and REST APIs with NestJS. It offers features like automatic CRUD operations and filtering, which can be compared to the dynamic discovery and interaction capabilities of @golevelup/nestjs-discovery.

README

@golevelup/nestjs-discovery

Description

This module provides access to the DiscoveryService which can be used to query the various modules, providers, controllers and handlers that make up your NestJS application.

Motivation

When building modules that extend NestJS functionality, it's common to use custom Decorators to attach metadata to different parts of the application. Once metdata is attached, the module will then need to be able to "discover" all the metadata to be able to connect it's functionality. For example, the official @nestjs/graphql package needs to be able to discover all the @Mutation and @Resolver decorated classes in order to properly build the GraphQL schema.

NestJS provides the MetadataScanner class to be able to retrieve this data but doesn't expose a friendly API to be able to easily and quickly find the components in question. The DiscoveryService fills this gap by exposing common discovery patterns that can be used when building module extensions to NestJS

Usage

Install

npm install ---save @golevelup/nestjs-discovery

or

yarn add @golevelup/nestjs-discovery

Import

Import and add DiscoveryModule to the imports section of the module you wish to implement Discovery features in. It's common to inject it directly into consuming Module's contructor so that it can be used during the onModuleInit lifecycle hook at application startup.

import { DiscoveryModule } from '@golevelup/nestjs-discovery';
import { Module } from '@nestjs/common';

@Module({
  imports: [DiscoveryModule],
})
export class ExampleModule implements OnModuleInit {
  constructor(private readonly discover: DiscoveryService) {}

  public async onModuleInit() {
    // const providers = await this.discover.providersWithMetaAtKey<number>('metaKey')
  }
}

Discover

The DiscoveryService exposes several different querying patterns for your app's components that are well documented with comments. This will also provide intellisense for querying in a TypeScript compatible IDE.

In the case of querying for providers or controllers, the service returns the following interfaces:

export interface DiscoveredModule {
  name: string;
  instance: {};
  injectType?: Type<{}>;
  dependencyType: Type<{}>;
}

export interface DiscoveredClass extends DiscoveredModule {
  parentModule: DiscoveredModule;
}

This gives access to the (singleton) instance of the matching provider or controller created by the NestJS Dependency Injection container.

The injectType can contain the constructor function of the provider token if it is provided as an @Injectable class. In the case of custom providers, this value will either contain the type of the factory function that created the dependency, or undefined if a value was directly provided with useValue.

The dependencyType is a shortcut to retrieve the constructor function of the actual provided dependency itself. For @Injectable providers/controllers this will simply be the decorated class but for dyanmic providers it will return the constructor function of whatever dependency was actually returned from useValue or useFactory.

It also provides the string based name for convenience. A DiscoveredClass contains a parentModule which provides the same set of information for the @Module class that the dependency was discovered in.

When querying for methods on providers or controllers the following interface is returned:

export interface DiscoveredMethod {
  handler: (...args: any[]) => any;
  methodName: string;
  parentClass: DiscoveredClass;
}

This gives access to the handler which is the actual class method implementation as well as the ability to navigate back up the dependency tree with the attached parentClass.

When specifically querying for components in the context of looking for decorator metadata, the ...WithMetaAtKey<T> service methods return the types above along with the metadata that was discovered.

export interface DiscoveredMethodWithMeta<T> {
  discoveredMethod: DiscoveredMethod;
  meta: T;
}

export interface DiscoveredClassWithMeta<T> {
  discoveredClass: DiscoveredClass;
  meta: T;
}

Example

Assuming you were using a custom decorator in your application that attached metadata at a key called exampleKey:

const ExampleDecorator = (meta: string) => SetMetadata('exampleKey', meta);

Find all controller methods that have been decorated with @ExampleDecorator and retrieve the value they set for meta:

const exampleMethodsMeta = await this.discover.controllerMethodsWithMetaAtKey<
  string
>('exampleKey');

Contribute

Contributions welcome! Read the contribution guidelines first.

License

MIT License