@probitas/client-grpc

gRPC client for Probitas scenario testing framework.

This package provides a gRPC client with Server Reflection support, designed for integration testing of gRPC services. It is a thin wrapper around `@probitas/client-connectrpc` with protocol: "grpc" pre-configured.

Features

• Native gRPC: Uses gRPC protocol (HTTP/2 with binary protobuf)
• Server Reflection: Auto-discover services and methods at runtime
• Field Name Conversion: Automatic snake_case ↔ camelCase conversion
• TLS Support: Configure secure connections with custom certificates
• Duration Tracking: Built-in timing for performance monitoring
• Error Handling: Test error responses without throwing exceptions
• Resource Management: Implements AsyncDisposable for proper cleanup

Installation

deno add jsr:@probitas/client-grpc

Quick Start

import { createGrpcClient } from "@probitas/client-grpc";

// Create client (uses reflection by default)
const client = createGrpcClient({
  url: "http://localhost:50051",
});

// Call a method
const response = await client.call(
  "echo.EchoService",
  "echo",
  { message: "Hello!" }
);
console.log(response.data);

await client.close();

Service Discovery

import { createGrpcClient } from "@probitas/client-grpc";

const client = createGrpcClient({ url: "http://localhost:50051" });

// Discover available services
const services = await client.reflection.listServices();
console.log("Services:", services);

// Get method information
const info = await client.reflection.getServiceInfo("echo.EchoService");
console.log("Methods:", info.methods);

await client.close();

Field Name Conventions

The client automatically handles field name conversion between protobuf and JavaScript:

• Request: Accept both snake_case (protobuf) and camelCase (JavaScript) field names
• Response:
  • response.data — Plain JSON with camelCase fields (no $typeName)
  • response.raw — Original protobuf Message with metadata (includes $typeName)

import { createGrpcClient } from "@probitas/client-grpc";

const client = createGrpcClient({ url: "http://localhost:50051" });

// Request: Both camelCase and snake_case work
const response = await client.call("echo.Echo", "echoWithDelay", {
  message: "hello",
  delayMs: 100,        // camelCase (recommended for JavaScript)
  // delay_ms: 100,    // snake_case (protobuf style) also works
});

// Response data: JSON with camelCase fields
console.log(response.data);
// { message: "hello", metadata: {...} }  ← no $typeName

// Response raw: protobuf Message with metadata
console.log(response.raw);
// { $typeName: "echo.EchoResponse", message: "hello", ... }

await client.close();

Using with using Statement

import { createGrpcClient } from "@probitas/client-grpc";

await using client = createGrpcClient({ url: "http://localhost:50051" });

const res = await client.call("echo.EchoService", "echo", { message: "test" });
console.log(res.data);
// Client automatically closed when block exits

Related Packages

Links

• GitHub Repository
• Probitas Framework
• gRPC

deno add jsr:@probitas/client-grpc

class GrpcError extends ClientError

new GrpcError(
  message: string,
  statusCode: ConnectRpcStatusCode,
  statusMessage: string,
  options?: ConnectRpcErrorOptions,
)

class GrpcNetworkError extends ClientError

new GrpcNetworkError(message: string, options?: ErrorOptions)

interface ErrorDetail

interface GrpcClient extends AsyncDisposable

const client = createConnectRpcClient({ url: "http://localhost:50051" });

// Request: Both formats work
await client.call("echo.Echo", "echoWithDelay", {
  message: "hello",
  delayMs: 100,        // camelCase (recommended)
  // delay_ms: 100,    // snake_case also works
});

// Response: data is JSON, raw is protobuf Message
const response = await client.call("echo.Echo", "echo", { message: "test" });
console.log(response.data);  // { message: "test", metadata: {...} }
console.log(response.raw);   // { $typeName: "echo.EchoResponse", message: "test", ... }

call<TRequest>(
  serviceName: string,
  methodName: string,
  request: TRequest,
  options?: ConnectRpcOptions,
): Promise<ConnectRpcResponse>

serverStream<TRequest>(
  serviceName: string,
  methodName: string,
  request: TRequest,
  options?: ConnectRpcOptions,
): AsyncIterable<ConnectRpcResponse>

clientStream<TRequest>(
  serviceName: string,
  methodName: string,
  requests: AsyncIterable<TRequest>,
  options?: ConnectRpcOptions,
): Promise<ConnectRpcResponse>

bidiStream<TRequest>(
  serviceName: string,
  methodName: string,
  requests: AsyncIterable<TRequest>,
  options?: ConnectRpcOptions,
): AsyncIterable<ConnectRpcResponse>

close(): Promise<void>

interface GrpcClientConfig extends Omit<ConnectRpcClientConfig, "protocol">

interface GrpcErrorOptions extends ErrorOptions

interface GrpcOptions extends CommonOptions

interface GrpcResponseError<T = any> extends ConnectRpcResponseBase<T>

interface GrpcResponseFailure<T = any> extends ConnectRpcResponseBase<T>

interface GrpcResponseSuccess<T = any> extends ConnectRpcResponseBase<T>

interface MethodInfo

interface ReflectionApi

listServices(): Promise<ServiceInfo[]>

getServiceInfo(serviceName: string): Promise<ServiceDetail>

listMethods(serviceName: string): Promise<MethodInfo[]>

hasService(serviceName: string): Promise<boolean>

interface ServiceDetail

interface ServiceInfo

interface TlsConfig

function createGrpcClient(config: GrpcClientConfig): ConnectRpcClient

import { createGrpcClient } from "@probitas/client-grpc";

const client = createGrpcClient({
  url: "http://localhost:50051",
});

// Call a method
const response = await client.call(
  "echo.EchoService",
  "echo",
  { message: "Hello!" }
);
console.log(response.data);

await client.close();

import { createGrpcClient } from "@probitas/client-grpc";

const client = createGrpcClient({
  url: "http://localhost:50051",
});

// Discover available services
const services = await client.reflection.listServices();
console.log("Available services:", services);

// Get method information
const info = await client.reflection.getServiceInfo("echo.EchoService");
console.log("Methods:", info.methods);

await client.close();

import { createGrpcClient } from "@probitas/client-grpc";

const client = createGrpcClient({ url: "http://localhost:50051" });

const response = await client.call(
  "user.UserService",
  "getUser",
  { id: "non-existent" },
  { throwOnError: false }
);

if (!response.ok) {
  console.log("Error code:", response.statusCode);  // NOT_FOUND = 5
}

await client.close();

import { createGrpcClient } from "@probitas/client-grpc";

await using client = createGrpcClient({
  url: "http://localhost:50051",
});

const res = await client.call("echo.EchoService", "echo", { message: "test" });
console.log(res.data);
// Client automatically closed when scope exits

function getGrpcStatusName(code: ConnectRpcStatusCode): string

getStatusName(0);  // "OK"
getStatusName(5);  // "NOT_FOUND"
getStatusName(16); // "UNAUTHENTICATED"

function isGrpcStatusCode(code: number): code is ConnectRpcStatusCode

isConnectRpcStatusCode(0);   // true
isConnectRpcStatusCode(16);  // true
isConnectRpcStatusCode(99);  // false

type FileDescriptorSet = MessageShape<FileDescriptorSetSchema>

type GrpcResponse<T = any> = ConnectRpcResponseSuccess<T>
  | ConnectRpcResponseError<T>
  | ConnectRpcResponseFailure<T>

type GrpcStatusCode = unknown

const GrpcStatus: {
  OK: number;
  CANCELLED: number;
  UNKNOWN: number;
  INVALID_ARGUMENT: number;
  DEADLINE_EXCEEDED: number;
  NOT_FOUND: number;
  ALREADY_EXISTS: number;
  PERMISSION_DENIED: number;
  RESOURCE_EXHAUSTED: number;
  FAILED_PRECONDITION: number;
  ABORTED: number;
  OUT_OF_RANGE: number;
  UNIMPLEMENTED: number;
  INTERNAL: number;
  UNAVAILABLE: number;
  DATA_LOSS: number;
  UNAUTHENTICATED: number;
}