nice-grpc-error-details

Rich error model implementation for nice-grpc.

This package is experimental and its API should not be considered stable.

Provides extensions to ServerError and ClientError which carry extra error details, as well as server and client middleware to communicate these details via trailing metadata.

Installation

npm install nice-grpc-error-details

Usage

Server

Attach the middleware to a server:

import {errorDetailsServerMiddleware} from 'nice-grpc-error-details';

const server = createServer().use(errorDetailsServerMiddleware);

Throw RichServerError from a service implementation method:

import {ServerError, Status} from 'nice-grpc';
import {RichServerError, BadRequest} from 'nice-grpc-error-details';

const exampleServiceImpl: ServiceImplementation<
  typeof ExampleServiceDefinition
> = {
  async exampleUnaryMethod(
    request: ExampleRequest,
  ): Promise<DeepPartial<ExampleResponse>> {
    if (!request.someField)
      throw new RichServerError(
        Status.INVALID_ARGUMENT,
        "Missing required field 'some_field'",
        [
          BadRequest.fromPartial({
            fieldViolations: [
              {
                field: 'some_field',
                description: 'Field is required',
              },
            ],
          }),
        ],
      );

    // ... method logic
  },
};

Client

Attach the middleware to a client factory:

import {errorDetailsClientMiddleware} from 'nice-grpc-error-details';

const clientFactory = createClientFactory().use(errorDetailsClientMiddleware);

If an error with details is returned from a server, the client will receive RichClientError:

import {Status} from 'nice-grpc';
import {RichClientError, BadRequest} from 'nice-grpc-error-details';

const fieldViolations: BadRequest_FieldViolation[] = [];

try {
  await client.exampleUnaryMethod(request);
} catch (error: unknown) {
  if (
    error instanceof RichClientError &&
    error.code === Status.INVALID_ARGUMENT
  ) {
    // loop through error details to find `BadRequest`
    for (const detail of error.extra) {
      if (detail.$type === BadRequest.$type) {
        fieldViolations.push(...detail.fieldViolations);
      }
    }
  } else {
    throw error;
  }
}