ExceptionFilterMetadata

Kind: Interface

Source: packages/common/interfaces/exceptions/exception-filter-metadata.interface.ts

Part of: Common

ExceptionFilterMetadata describes the runtime metadata Nest uses to associate an exception filter handler with the exception classes it can process. It stores the filter's catch function alongside the exception metatypes registered through decorators such as @Catch().

Properties

Diagram

mermaid
graph LR
  A["@Catch(HttpException)"] --> B["ExceptionFilterMetadata"]
  C["Exception Filter instance"] --> D["func: filter.catch"]
  A --> E["exceptionMetatypes: Type<any>[]"]
  D --> B
  E --> B
  B --> F["Exceptions handler selects matching filter"]

Usage

ts
import { ArgumentsHost, Catch, ExceptionFilter, HttpException } from '@nestjs/common';
import { ExceptionFilterMetadata } from '@nestjs/common/interfaces/exceptions/exception-filter-metadata.interface';

@Catch(HttpException)
class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const response = host.switchToHttp().getResponse();

    response.status(exception.getStatus()).json({
      message: exception.message,
    });
  }
}

const filter = new HttpExceptionFilter();

const metadata: ExceptionFilterMetadata = {
  func: filter.catch.bind(filter),
  exceptionMetatypes: [HttpException],
};

AI Coding Instructions

• Keep func compatible with ExceptionFilter['catch']; bind it to the filter instance when invoking it outside Nest's normal filter context.
• Populate exceptionMetatypes with exception constructors, such as HttpException or custom error classes, not instantiated exceptions.
• Treat this interface as internal runtime metadata used by Nest's exception-handler resolution flow.
• Preserve the relationship between a filter's catch handler and its declared @Catch() exception types when extending exception-filter infrastructure.

How it works

ExceptionFilterMetadata is an exported TypeScript interface for the two values needed to select and invoke an exception filter: a catch function and an array of exception constructor types. It declares no executable logic, validation, errors, or side effects itself. exception-filter-metadata.interface.ts:4-7

• func has the type of ExceptionFilter['catch']. That method receives an exception and an ArgumentsHost, and may return any value. exception-filter-metadata.interface.ts:5 exception-filter.interface.ts:10-18
• exceptionMetatypes is an array of constructible function types (Type<any>); Type<T> extends Function and has a new (...args) signature. exception-filter-metadata.interface.ts:6 type.interface.ts:1-3

Filter-context construction creates metadata objects by binding each filter instance’s catch method to that instance and reading its catch-type metadata through reflection. base-exception-filter-context.ts:26-36 The @Catch() decorator writes the supplied exception types under the metadata key that this reflection reads. catch.decorator.ts:21-27 A filter can be registered through @UseFilters() as a class or instance; that decorator accepts functions or objects whose catch member is a function, otherwise it can throw InvalidDecoratorItemException. exception-filters.decorator.ts:29-30 exception-filters.decorator.ts:40-60 validate-each.util.ts:23-29

When selecting metadata for an exception, selectExceptionFilterMetadata() returns the first entry whose exceptionMetatypes array is empty or contains a constructor for which the exception is an instanceof; it returns undefined when no entry matches. select-exception-filter-metadata.util.ts:3-13

ExceptionsHandler stores an array of these objects, invokes the selected entry’s func(exception, ctx), and reports whether a matching entry existed. If no custom filter matches, its next() method delegates to the base exception handler. exceptions-handler.ts:9-17 exceptions-handler.ts:26-37 Its setCustomFilters() method requires the supplied value to be an array and throws InvalidExceptionFilterException otherwise; it does not inspect the shape of each array entry in the shown code. exceptions-handler.ts:19-24

Used by

4 references from 4 files. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.

Imported by (4)

• ExceptionsHandler — packages/core/exceptions/exceptions-handler.ts:9
• ExternalExceptionFilterContext — packages/core/exceptions/external-exception-filter-context.ts:14
• ExternalExceptionsHandler — packages/core/exceptions/external-exceptions-handler.ts:8
• WsExceptionsHandler — packages/websockets/exceptions/ws-exceptions-handler.ts:12