grpc-boom

library3.0.12jsnpmunverified

A gRPC implementation of the Boom library for creating gRPC-friendly error objects in Node.js. Version 3.0.12 is current. It maps HTTP error concepts to gRPC status codes, supporting metadata, boomiify, and convenience methods for all 16 gRPC status codes. Zero external dependencies (only peer dependency @grpc/grpc-js v1.8.14). Ships TypeScript types. Differentiators: mimics hapi/boom API, easy integration with gRPC callback patterns, and supports custom error details.

testing

npm install grpc-boom

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPC-BOOM

grpc-boom

testingjavascriptv3.0.12

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.

GrpcBoom

✓ import GrpcBoom from 'grpc-boom'

✗ import { GrpcBoom } from 'grpc-boom'

Default export only; named import will fail.

default export

✓ const GrpcBoom = require('grpc-boom').default

✗ const GrpcBoom = require('grpc-boom')

CommonJS users must use .default; the library is ESM-first.

GrpcBoom type

✓ import type { GrpcBoom } from 'grpc-boom'

✗ import { GrpcBoom } from 'grpc-boom'

For type-only imports, use 'import type' to avoid runtime errors.

Creates a gRPC-friendly error with metadata using the invalidArgument convenience method.

import GrpcBoom from 'grpc-boom'; import { Metadata } from '@grpc/grpc-js'; function sayHello(call, callback) { const name = call.request.name; if (!name) { const metadata = new Metadata(); metadata.set('errorField', 'name'); return callback(GrpcBoom.invalidArgument('Name is required', metadata)); } callback(null, { message: `Hello ${name}` }); } // Alternatively, use boomify try { somethingRisky(); } catch (err) { const boomErr = GrpcBoom.boomify(err, { code: grpc.status.INTERNAL }); callback(boomErr); }

Debug

Known issues

breakingv3.0.0 changed from CommonJS to ESM-only; require() will fail without .default.

fix

Use import or const GrpcBoom = require('grpc-boom').default;

affects: >=3.0.0

breakingv3.0.0 removed the 'message' parameter from convenience methods; now it's optional with default 'Unknown error'.

fix

Update calls to pass message as first argument or rely on default.

affects: >=3.0.0 <4.0.0

gotchaGrpcBoom.boomify expects an Error object; passing a string will cause a runtime error.

fix

Wrap strings in new Error('message') before passing to boomify.

affects: *

gotchaThe library does not validate metadata type; passing a non-Metadata object may cause issues with gRPC serialization.

fix

Always pass an instance of Metadata from @grpc/grpc-js or undefined.

affects: *

deprecatedGrpcBoom.create() method is deprecated in favor of constructor new GrpcBoom().

fix

Use new GrpcBoom(message, options) or convenience methods.

affects: >=2.0.0 <4.0.0

Errors

Common errors & fixes

TypeError: grpc_boom_1.default is not a function

Using CommonJS require without .default on ESM bundle

fix

Use const GrpcBoom = require('grpc-boom').default;

Error: [object Object] is not a valid status code

Passing a numeric status code that does not correspond to gRPC status values

fix

Use grpc.status constants or numbers between 0 and 16 inclusive.

Cannot find module '@grpc/grpc-js'

Missing peer dependency

fix

Run npm install @grpc/grpc-js

TypeError: Boom.boomify is not a function

Importing the hapi/boom library's boomify instead of grpc-boom's GrpcBoom.boomify

fix

Use GrpcBoom.boomify from 'grpc-boom'

Upgrade

Version history

3.0.12latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredRuntime peer dependency required for gRPC status codes and Metadata class

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/nicolaspearson/kalos ↗

packagegrpc-boom ↗

homepagehttps://github.com/nicolaspearson/kalos#readme ↗