wsgrpc

library3.2.3jsnpmunverified

A code generator and runtime for RPC stubs from gRPC proto files, targeting TypeScript. Current version 3.2.3. Supports h1 transport (grpc, grpc-web, grpc-web+proto, JSON) and WebSocket for streaming. Generates client and server stub code. Supports repeated fields and enums but not maps. Notable: known issue with client stream message processing not in time. Differentiator: lightweight, browser-friendly, with WebSocket support for full streaming.

testing

npm install wsgrpc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WSGRPC

wsgrpc

testingjavascriptv3.2.3

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.

default import

✓ import wsgrpc from 'wsgrpc'

✗ const wsgrpc = require('wsgrpc')

Package is ESM-only; requires 'type': 'module' or .mjs extension

generate RPC stubs

✓ import { generateStub } from 'wsgrpc'

✗ const { generateStub } = require('wsgrpc')

generateStub is a named export; CJS require won't work in Node < 12 or without esm package

GrpcWebClient

✓ import { GrpcWebClient } from 'wsgrpc'

✗ import GrpcWebClient from 'wsgrpc'

GrpcWebClient is a named export, not a default one

WsClient

✓ import { WsClient } from 'wsgrpc'

WebSocket client class for streaming

codegen CLI

✓ npx wsgrpc <src.proto> <dst.ts>

✗ npx wsgrpc generate <src.proto>

CLI expects exactly two positional arguments without a 'generate' subcommand

Generates TypeScript stubs from a .proto file using the CLI, then uses the generated client to call a unary RPC method.

// 1. Generate stub from proto file // npx wsgrpc myapi.proto myapi.proto.generated.ts // 2. Use generated stubs import { GrpcWebClient, generateStub } from 'wsgrpc'; import { MyService } from './myapi.proto.generated'; const client = new GrpcWebClient('https://api.example.com'); const service = new MyService(client, { baseURL: '/api/v1' }); async function callUnary() { const response = await service.myMethod({ field: 'value' }); console.log(response); } callUnary().catch(console.error);

Debug

Known issues

breakingPackage is ESM-only; CommonJS require() fails with ERR_REQUIRE_ESM.

fix

Use import syntax and set "type": "module" in package.json, or use .mjs extension.

affects: >=3.0.0

breakinggenerateStub was a synchronous function in v2; now returns Promise or uses callback.

fix

Use await generateStub() or callback pattern if migrating from v2.

affects: >=3.0.0

deprecatedGrpcClient (non-Web) is deprecated; renamed to GrpcWebClient.

fix

Replace imported symbol with GrpcWebClient.

affects: >=2.5.0

gotchaWhen using h1 transport, streaming requests/responses are not supported; only works with WebSocket.

fix

Use WsClient with websocket transport for streaming RPCs.

affects: >=1.0.0

gotchaClient stream messages are not processed in time; known issue with Throttle.

fix

Avoid heavy message rate in client streaming; use buffering or increase Throttle limit if configurable.

affects: >=3.0.0

gotchaMap fields in protobuf are not supported; library will fail to parse.

fix

Avoid map types in proto; use repeated key-value messages instead.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/wsgrpc/index.mjs not supported.

Using require() to import ESM-only package.

fix

Switch to import syntax or use dynamic import() in CJS context.

TypeError: generateStub is not a function

Importing default instead of named export.

fix

Use import { generateStub } from 'wsgrpc';

Error: unknown transport type. Must be one of: grpc, grpc-web, grpc-web+proto, json

Invalid transport option passed to client.

fix

Specify correct transport: 'grpc-web' for base64, 'grpc-web+proto' for binary, etc.

Error: RPC method requires stream but transports do not support stream.

Using h1 transport with a streaming RPC.

fix

Change to WsClient and use WebSocket transport.

Upgrade

Version history

3.2.3latest on npm

Audit

Dependencies

protobufjsrequiredProtobuf loading and serialization

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/tsangpo/wsgrpc-ts ↗

packagewsgrpc ↗

homepagehttps://github.com/tsangpo/wsgrpc-ts#readme ↗