Skip to content

Commit 19cffa0

Browse files
committed
docs: 📝 Updated readme
1 parent 269d4aa commit 19cffa0

File tree

1 file changed

+32
-38
lines changed

1 file changed

+32
-38
lines changed

README.md

Lines changed: 32 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,8 @@
11
# node-grpc-error-details
22

3-
[![Version](https://img.shields.io/npm/v/@stackpath/node-grpc-error-details.svg)](https://www.npmjs.com/package/@stackpath/node-grpc-error-details)
4-
[![License](https://img.shields.io/npm/l/@stackpath/node-grpc-error-details.svg)](https://www.npmjs.com/package/@stackpath/node-grpc-error-details)
5-
[![Build Status](https://travis-ci.org/stackpath/node-grpc-error-details.svg?branch=master)](https://travis-ci.org/stackpath/node-grpc-error-details)
3+
[![Build and test](https://github.com/Q42Philips/node-grpc-error-details/actions/workflows/build-and-test.yaml/badge.svg)](https://github.com/Q42Philips/node-grpc-error-details/actions/workflows/build-and-test.yaml)
64

7-
Utility function for deserializing the `grpc-status-details-bin` metadata value when using the [node grpc](https://github.com/grpc/grpc-node/tree/master/packages/grpc-native-core) package. Error details allow sending/receiving additional data along with an error. For instance, if a request sends invalid data, a gRPC server could send back a [BadRequest](./src/proto/error_details.proto#L119) message identifying the field and why it failed validation.
5+
Utility function for deserializing the `grpc-status-details-bin` metadata value when using the [grpc-js](https://github.com/grpc/grpc-node) package. Error details allow sending/receiving additional data along with an error. For instance, if a request sends invalid data, a gRPC server could send back a [BadRequest](./src/proto/error_details.proto#L119) message identifying the field and why it failed validation.
86

97
gRPC services that send rich error details place information in the `grpc-status-details-bin` metadata property of the [ServiceError](https://grpc.io/grpc/node/grpc.html#~ServiceError) passed to the callback of a failed gRPC method call. The value of the `grpc-status-details-bin` field is a serialized [Status](./src/proto/status.proto) message. The Status message's details field is an array of [Any](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/any.proto#L122) messages, which consist of a type field and the serialized data for that message type.
108

@@ -13,11 +11,8 @@ This library, given an error, returns back the deserialized Status message and a
1311
## Install
1412

1513
```bash
16-
# yarn
17-
yarn add @stackpath/node-grpc-error-details
18-
1914
# npm
20-
npm install @stackpath/node-grpc-error-details
15+
npm install @q42philips/node-grpc-error-details
2116
```
2217

2318
## Usage
@@ -36,43 +31,29 @@ where `status` is a [Google rpc Status message](./src/proto/status.proto) and `d
3631
`deserializeGrpcStatusDetails` allows passing in the `deserializeMap` argument, where each key is a message type and each value is its corresponding deserialize function.
3732

3833
`deserializeGoogleGrpcStatusDetails` behaves exactly the same as `deserializeGrpcStatusDetails`, but provides a default deserializeMap using [Google's rpc error details types](./src/proto/error_details.proto).
39-
40-
### deserializeGrpcStatusDetails(error, deserializeMap)
34+
### deserializeGoogleGrpcStatusDetails(error)
4135

4236
Example:
4337

44-
```js
45-
import { deserializeGrpcStatusDetails } from "@stackpath/node-grpc-error-details";
38+
```ts
4639
import {
47-
RetryInfo,
48-
DebugInfo,
49-
QuotaFailure,
50-
PreconditionFailure,
51-
CustomError
52-
} from "./custom_error_pb";
53-
54-
// Define the types of errors we want to deserialize
55-
const deserializeMap = {
56-
"stackpath.rpc.RetryInfo": RetryInfo.deserializeBinary,
57-
"stackpath.rpc.DebugInfo": DebugInfo.deserializeBinary,
58-
"stackpath.rpc.QuotaFailure": QuotaFailure.deserializeBinary,
59-
"stackpath.rpc.PreconditionFailure": PreconditionFailure.deserializeBinary,
60-
"stackpath.rpc.CustomError": CustomError.deserializeBinary
61-
};
40+
deserializeGoogleGrpcStatusDetails,
41+
BadRequest
42+
} from "@q42philips/node-grpc-error-details";
6243

6344
const point = { latitude: 409146138, longitude: -746188906 };
6445

6546
// Make grpc call that fails and returns a Status object with
6647
// details in the `grpc-status-details-bin` Metadata property
6748
stub.getFeature(point, function(err, feature) {
6849
if (err) {
69-
const grpcErrorDetails = deserializeGrpcStatusDetails(err, deserializeMap);
50+
const grpcErrorDetails = deserializeGoogleGrpcStatusDetails(err);
7051
if (grpcErrorDetails) {
7152
const { status, details } = grpcErrorDetails;
7253

73-
// Search for an instance of CustomError in details and do something if found
54+
// Search for an instance of BadRequest in details and do something if found
7455
for (let i = 0; i < details.length; i++) {
75-
if (details[i] instanceof CustomError) {
56+
if (details[i] instanceof BadRequest) {
7657
console.log(details[i].toObject());
7758
}
7859
}
@@ -83,29 +64,42 @@ stub.getFeature(point, function(err, feature) {
8364
});
8465
```
8566

86-
### deserializeGoogleGrpcStatusDetails(error)
67+
### deserializeGrpcStatusDetails(error, deserializeMap)
8768

8869
Example:
8970

90-
```js
71+
```ts
72+
import { deserializeGrpcStatusDetails } from "@q42philips/node-grpc-error-details";
9173
import {
92-
deserializeGoogleGrpcStatusDetails,
93-
BadRequest
94-
} from "@stackpath/node-grpc-error-details";
74+
RetryInfo,
75+
DebugInfo,
76+
QuotaFailure,
77+
PreconditionFailure,
78+
CustomError
79+
} from "./custom_error_pb";
80+
81+
// Define the types of errors we want to deserialize
82+
const deserializeMap = {
83+
"stackpath.rpc.RetryInfo": RetryInfo.deserializeBinary,
84+
"stackpath.rpc.DebugInfo": DebugInfo.deserializeBinary,
85+
"stackpath.rpc.QuotaFailure": QuotaFailure.deserializeBinary,
86+
"stackpath.rpc.PreconditionFailure": PreconditionFailure.deserializeBinary,
87+
"stackpath.rpc.CustomError": CustomError.deserializeBinary
88+
};
9589

9690
const point = { latitude: 409146138, longitude: -746188906 };
9791

9892
// Make grpc call that fails and returns a Status object with
9993
// details in the `grpc-status-details-bin` Metadata property
10094
stub.getFeature(point, function(err, feature) {
10195
if (err) {
102-
const grpcErrorDetails = deserializeGoogleGrpcStatusDetails(err);
96+
const grpcErrorDetails = deserializeGrpcStatusDetails(err, deserializeMap);
10397
if (grpcErrorDetails) {
10498
const { status, details } = grpcErrorDetails;
10599

106-
// Search for an instance of BadRequest in details and do something if found
100+
// Search for an instance of CustomError in details and do something if found
107101
for (let i = 0; i < details.length; i++) {
108-
if (details[i] instanceof BadRequest) {
102+
if (details[i] instanceof CustomError) {
109103
console.log(details[i].toObject());
110104
}
111105
}

0 commit comments

Comments
 (0)