grpcdes

library1.0.1jsnpmunverified

grpc-helper is a gRPC client wrapper for grpc-node that adds promised-based calls, client-side load balancing, service health checking, service discovery (static, DNS SRV, etcd v3), circuit breaking, retry logic, and Prometheus metrics. Version 1.0.x is currently the latest, with moderate release cadence. It improves upon raw grpc-node by providing a higher-level, feature-rich client with TypeScript support and built-in resilience patterns, differentiating itself from alternatives like grpc-ts or custom wrappers by combining discovery, balancing, and observability out of the box.

devops

npm install grpcdes

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPCDES

grpcdes

devopsjavascriptv1.0.1

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.

GRPCHelper

✓ import { GRPCHelper } from 'grpc-helper'

✗ const GRPCHelper = require('grpc-helper').GRPCHelper

Named export; CommonJS users may mistakenly use default import or destructure incorrectly.

default

✓ import GRPCHelper from 'grpc-helper'

✗ const GRPCHelper = require('grpc-helper')

Mixing default and named exports – the package does not provide a default export; only named export { GRPCHelper }.

types

✓ import type { Options } from 'grpc-helper'

✗ import { Options } from 'grpc-helper'

For type-only imports use 'import type' or rely on declaration files. Options type is exported for configuration.

Creates a GRPCHelper instance with static service discovery, waits for readiness, and makes a unary gRPC call.

import { GRPCHelper } from 'grpc-helper'; import path from 'path'; async function main() { const helper = new GRPCHelper({ packageName: 'helloworld', serviceName: 'Greeter', protoPath: path.resolve(__dirname, './hello.proto'), sdUri: 'static://localhost:50051', }); await helper.waitForReady(); const res = await helper.SayHello({ name: 'world' }); console.log('Greeting:', res.message); } main().catch(console.error);

Debug

Known issues

breakinggrpc-helper does not support grpc-js; it depends on the older grpc package (grpc-node). Use only with grpc, not @grpc/grpc-js.

fix

Install grpc package (npm install grpc) as peer dependency, or consider migrating to a library that supports @grpc/grpc-js.

affects: <2

gotchaThe package name on npm is 'grpc-helper' but the repository is named differently (grpcDES). Ensure you install 'grpc-helper' not 'grpcdes'.

fix

npm install grpc-helper

affects: *

deprecatedThe grpc package (grpc-node) is deprecated and will not receive updates. It is recommended to use @grpc/grpc-js instead, but grpc-helper does not support it.

fix

Consider using an alternative library that wraps @grpc/grpc-js, or manually handle the migration.

affects: *

breakingRequires Node.js >=4, but modern gRPC usage typically needs Node >=10. Older Node versions may cause unexpected failures.

fix

Ensure Node.js version >=10 (preferably LTS) for best compatibility.

affects: *

gotchaService discovery URI format must be exactly as documented. For example, 'static://localhost:50051' not 'static://localhost:50051/'.

fix

Follow the URI pattern: static://host:port,host:port ; dns://_grpc._tcp.service?intervalMs=N ; etcd3://prefix?cluster

affects: *

gotchaThe 'resolveFullResponse' option changes the return type of RPC calls. Not understanding this can cause unexpected destructuring errors.

fix

Set resolveFullResponse: true if you need metadata, peer, or status; otherwise the response is just the message.

affects: *

Errors

Common errors & fixes

TypeError: grpc.loadPackageDefinition is not a function

Incompatibility between grpc-helper and @grpc/grpc-js; grpc-helper expects the old grpc API.

fix

Ensure you have the old grpc package installed (npm install grpc) and not @grpc/grpc-js.

Error: Cannot find module 'grpc'

Peer dependency grpc is not installed.

fix

Run: npm install grpc

TypeError: GRPCHelper is not a constructor

Incorrect import – using default import when only named export is available.

fix

Use: import { GRPCHelper } from 'grpc-helper'

Error: Invalid URI: static://

Missing host and port in service discovery URI.

fix

Provide correct URI like 'static://localhost:50051'.

Error: No ready backends found

Backend service is down or unreachable, or waitForReady() not awaited.

fix

Check backend status and ensure await helper.waitForReady() before making calls.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

grpcrequiredPeer dependency – core gRPC client library required to operate

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/tony-liuql/grpcDES ↗

packagegrpcdes ↗

homepagehttps://github.com/tony-liuql/grpcDES#readme ↗