Registry / testing / nestjs-grpc-exceptions

nestjs-grpc-exceptions

library0.2.2jsnpmunverified

A lightweight library (v0.2.2) for NestJS that provides gRPC exception wrappers corresponding to standard gRPC status codes (e.g., NotFound, InvalidArgument). It includes a server-side exception filter (GrpcServerExceptionFilter) to automatically convert thrown exceptions to gRPC errors, and client-side interceptors (GrpcToHttpInterceptor, HttpToGrpcInterceptor) to bridge between HTTP and gRPC error formats. Requires @grpc/grpc-js, @nestjs/common, @nestjs/core, and @nestjs/microservices as peer dependencies. Compatible with NestJS 9 and 10. Actively maintained with TypeScript types included.

testing

npm install nestjs-grpc-exceptions

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NESTJS-GRPC-EXCEPT

nestjs-grpc-exceptions

testingjavascriptv0.2.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GrpcServerExceptionFilter

✓ import { GrpcServerExceptionFilter } from 'nestjs-grpc-exceptions'

✗ const { GrpcServerExceptionFilter } = require('nestjs-grpc-exceptions')

ESM import is recommended; CommonJS require() may cause issues with certain bundlers or NestJS versions.

GrpcNotFoundException

✓ import { GrpcNotFoundException } from 'nestjs-grpc-exceptions'

✗ import GrpcNotFoundException from 'nestjs-grpc-exceptions'

Named export only; default import is not available.

GrpcToHttpInterceptor

✓ import { GrpcToHttpInterceptor } from 'nestjs-grpc-exceptions'

Used as an @Injectable() interceptor in NestJS controllers.

Shows how to import and use the global exception filter and throw gRPC exceptions in a NestJS module.

import { Module } from '@nestjs/common'; import { APP_FILTER } from '@nestjs/core'; import { GrpcServerExceptionFilter, GrpcNotFoundException, GrpcInvalidArgumentException } from 'nestjs-grpc-exceptions'; @Module({ providers: [ { provide: APP_FILTER, useClass: GrpcServerExceptionFilter, }, ], }) export class GrpcModule {} // In a service: throw new GrpcNotFoundException('User not found.'); throw new GrpcInvalidArgumentException('Invalid input.');

Debug

Known issues

gotchaGrpcServerExceptionFilter must be registered as a global filter (APP_FILTER) to catch all exceptions; if registered locally, it may not intercept unhandled exceptions.

fix

Use APP_FILTER provider as shown in the documentation.

affects: <0.2.0

breakingUpgrading from v0.1.x to v0.2.0 changed export paths: previously exceptions were available under 'nestjs-grpc-exceptions/exceptions'.

fix

Import all symbols directly from 'nestjs-grpc-exceptions'.

affects: >=0.2.0

gotchaThe library only supports NestJS gRPC microservices; it does not work with standalone gRPC servers or other frameworks.

fix

Ensure your application uses @nestjs/microservices gRPC transport.

affects: >=0.0.0

gotchaGrpcToHttpInterceptor converts gRPC errors to HTTP exceptions and requires the client to handle HTTP exceptions appropriately; if not set up, errors may be lost.

fix

Apply the interceptor to controller methods that call gRPC services.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'nestjs-grpc-exceptions' or its corresponding type declarations.

Package not installed or TypeScript compiler cannot resolve types.

fix

Run 'npm install nestjs-grpc-exceptions' and ensure tsconfig.json includes 'node_modules/@types'.

GrpcNotFoundException is not a constructor

Using CommonJS require incorrectly with a named export.

fix

Use ES6 import syntax: import { GrpcNotFoundException } from 'nestjs-grpc-exceptions'

No provider for 'GrpcServerExceptionFilter' (appears in error stack)

The filter is not registered as a provider in any module.

fix

Add it to a module's providers array, preferably as an APP_FILTER.

Upgrade

Version history

0.2.2latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredRequired for gRPC error codes and gRPC client/server implementation.

@nestjs/commonrequiredRequired for NestJS decorators, filters, and interceptors.

@nestjs/corerequiredRequired for NestJS application framework and dependency injection.

@nestjs/microservicesrequiredRequired for NestJS microservices support including gRPC transport.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/mohsenbostan/nestjs-grpc-exceptions ↗

packagenestjs-grpc-exceptions ↗

homepagehttps://github.com/mohsenbostan/nestjs-grpc-exceptions ↗