Skip to main content

Error filter

Error filters translate an exception into a gRPC status. @CatchError() marks the filter and applies @injectable(). @UseErrorFilter() attaches it to a service or to one RPC. Bind the filter class.

interface ErrorFilter<
TError = unknown,
TRequest = any,
TResponse = any,
TResult = any,
> {
catch(
error: TError,
request: TRequest,
response: TResponse,
): Promise<TResult> | TResult;
}

request is the @grpc/grpc-js call. response is the callback when the RPC has one, and the call otherwise.

The adapter already handles GrpcError and its subclasses. A filter for one of your own errors can throw a GrpcError. That second error is sent as the status, including for streaming RPCs.

import {
CatchError,
type ErrorFilter,
NotFoundGrpcError,
RPC,
Service,
UseErrorFilter,
} from '@inversifyjs/grpc-core';

import {
type HeroRequest,
type HeroResponse,
heroServiceDefinition,
} from './loadHeroServiceDefinition.js';

export class HeroNotFoundError extends Error {
public readonly id: string;

constructor(id: string) {
super(`Hero ${id} was not found`);

this.id = id;
}
}

@CatchError(HeroNotFoundError)
export class HeroNotFoundErrorFilter implements ErrorFilter {
public catch(error: HeroNotFoundError): never {
throw new NotFoundGrpcError(error.message);
}
}

@Service(heroServiceDefinition)
@UseErrorFilter(HeroNotFoundErrorFilter)
export class FilteredHeroService {
@RPC('GetHero')
public getHero(call: { request: HeroRequest }): HeroResponse {
if (call.request.id === 'missing') {
throw new HeroNotFoundError(call.request.id);
}

return {
name: call.request.id,
};
}
}

@Service(heroServiceDefinition)
export class UnfilteredHeroService {
@RPC('GetHero')
public getHero(call: { request: HeroRequest }): HeroResponse {
if (call.request.id === 'missing') {
throw new HeroNotFoundError(call.request.id);
}

return {
name: call.request.id,
};
}
}

FilteredHeroService uses @UseErrorFilter(). UnfilteredHeroService throws the same error for a global filter:

adapter.useGlobalFilters(HeroNotFoundErrorFilter);

Register global filters before the server handles calls.

a global filter can win over a method or class filter

Lookup walks the error's class chain, from the thrown error's class toward its parents, and the first error class that has a filter wins. For the same error class, a method filter is chosen before a class filter, which is chosen before a global filter. Because the error class is checked first, a global filter for TypeError handles a thrown TypeError even when the method has a filter for Error. A filter for GrpcError also sees subclasses when no filter is registered for the subclass. @CatchError() with no error class is the fallback for every other error.

overriding error filters for the same error type

When more than one filter catches the same error type at the same level, the last filter applied overrides the previous ones:

  • Within a single @UseErrorFilter() call, filters are applied in the order they are listed.
  • Global filters are applied in the order they are registered with useGlobalFilters().
  • Class filters are applied before method filters, so a method filter overrides a class filter for the same error type. This is expected and is not reported.

A warning is logged when a filter overrides a different filter attached at the same level.

@Discriminated('hero-not-found') on an error class indexes that error by a string or symbol. A filter registered for the error class is also registered for each discriminator. At each step of the class chain, a discriminator match is used before the class match.

A filter can write the status itself by calling the unary callback or emitting an error on a stream. Throwing a GrpcError keeps that logic in one place for every RPC kind.