@probitas/client-connectrpc

ConnectRPC client for Probitas scenario testing framework.

This package provides a ConnectRPC-based client with Server Reflection support, designed for integration testing of gRPC and Connect protocol services.

Features

Protocol Support: Connect, gRPC, and gRPC-Web protocols
Server Reflection: Auto-discover services and methods at runtime
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-connectrpc

Quick Start

import { createConnectRpcClient } from "@probitas/client-connectrpc";

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

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

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

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

await client.close();

Testing Error Responses

// Test error responses without throwing
const errorResponse = await client.call(
  "echo.EchoService",
  "echo",
  { invalid: true },
  { throwOnError: false }
);

if (!errorResponse.ok) {
  console.log("Error code:", errorResponse.code);  // INVALID_ARGUMENT = 3
}

Using with `using` Statement

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

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

Package	Description
`@probitas/client`	Core utilities and types
`@probitas/client-grpc`	gRPC client (wrapper with `protocol: "grpc"`)

Installation

deno add jsr:@probitas/client-connectrpc

Classes

class

#ConnectRpcError

class ConnectRpcError extends ClientError

ExtendsClientError

Base error class for ConnectRPC/gRPC errors.

Name	Description
`name`	—
`kind`	—
`code`	—
`rawMessage`	—
`metadata`	—
`details`	—

Constructor

new ConnectRpcError(message: string, code: ConnectRpcStatusCode, rawMessage: string, options?: ConnectRpcErrorOptions)

Properties

readonlynamestring
readonlykind"connectrpc"
readonlycodeConnectRpcStatusCode
readonlyrawMessagestring
readonlymetadata?Record<string, string>
readonlydetailsreadonly ErrorDetail[]

class

#ConnectRpcInternalError

class ConnectRpcInternalError extends ConnectRpcError

ExtendsConnectRpcError

Error thrown for internal server errors (code 13).

Name	Description
`name`	—
`code`	—

Constructor

new ConnectRpcInternalError(rawMessage: string, options?: ConnectRpcErrorOptions)

Properties

readonlyname"ConnectRpcInternalError"
readonlycode13

class

#ConnectRpcNotFoundError

class ConnectRpcNotFoundError extends ConnectRpcError

ExtendsConnectRpcError

Error thrown when the requested resource is not found (code 5).

Name	Description
`name`	—
`code`	—

Constructor

new ConnectRpcNotFoundError(rawMessage: string, options?: ConnectRpcErrorOptions)

Properties

readonlyname"ConnectRpcNotFoundError"
readonlycode5

class

#ConnectRpcPermissionDeniedError

class ConnectRpcPermissionDeniedError extends ConnectRpcError

ExtendsConnectRpcError

Error thrown when the client lacks permission (code 7).

Name	Description
`name`	—
`code`	—

Constructor

new ConnectRpcPermissionDeniedError(rawMessage: string, options?: ConnectRpcErrorOptions)

Properties

readonlyname"ConnectRpcPermissionDeniedError"
readonlycode7

class

#ConnectRpcResourceExhaustedError

class ConnectRpcResourceExhaustedError extends ConnectRpcError

ExtendsConnectRpcError

Error thrown when a resource is exhausted (code 8).

Name	Description
`name`	—
`code`	—

Constructor

new ConnectRpcResourceExhaustedError(rawMessage: string, options?: ConnectRpcErrorOptions)

Properties

readonlyname"ConnectRpcResourceExhaustedError"
readonlycode8

class

#ConnectRpcResponseImpl

class ConnectRpcResponseImpl implements ConnectRpcResponse

ImplementsConnectRpcResponse

Implementation of ConnectRpcResponse.

Name	Description
`type`	—
`ok`	—
`code`	—
`message`	—
`headers`	—
`trailers`	—
`duration`	—
`data`()	—
`raw`()	—

Constructor

new ConnectRpcResponseImpl(options: ConnectRpcResponseOptions)

Properties

readonlytype"connectrpc"
readonlyokboolean
readonlycodeConnectRpcStatusCode
readonlymessagestring
readonlyheadersRecord<string, string>
readonlytrailersRecord<string, string>
readonlydurationnumber

Methods

data(): unknown

raw(): unknown

class

#ConnectRpcUnauthenticatedError

class ConnectRpcUnauthenticatedError extends ConnectRpcError

ExtendsConnectRpcError

Error thrown when the client is not authenticated (code 16).

Name	Description
`name`	—
`code`	—

Constructor

new ConnectRpcUnauthenticatedError(rawMessage: string, options?: ConnectRpcErrorOptions)

Properties

readonlyname"ConnectRpcUnauthenticatedError"
readonlycode16

class

#ConnectRpcUnavailableError

class ConnectRpcUnavailableError extends ConnectRpcError

ExtendsConnectRpcError

Error thrown when the service is unavailable (code 14).

Name	Description
`name`	—
`code`	—

Constructor

new ConnectRpcUnavailableError(rawMessage: string, options?: ConnectRpcErrorOptions)

Properties

readonlyname"ConnectRpcUnavailableError"
readonlycode14

Interfaces

interface

#ConnectRpcClient

interface ConnectRpcClient extends AsyncDisposable

ConnectRPC client interface.

Name	Description
`config`	Client configuration
`reflection`	Reflection API (only available when schema: "reflection")
`call`()	Make a unary RPC call.
`serverStream`()	Make a server streaming RPC call.
`clientStream`()	Make a client streaming RPC call.
`bidiStream`()	Make a bidirectional streaming RPC call.
`close`()	Close the client connection.

Properties

readonlyconfigConnectRpcClientConfig
Client configuration
readonlyreflectionReflectionApi
Reflection API (only available when schema: "reflection")

Methods

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

Make a unary RPC call.

Parameters

serviceNamestring
- Service name (e.g., "echo.EchoService")
methodNamestring
- Method name (e.g., "echo")
requestTRequest
- Request message
options?ConnectRpcOptions
- Call options

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

Make a server streaming RPC call.

Parameters

serviceNamestring
- Service name
methodNamestring
- Method name
requestTRequest
- Request message
options?ConnectRpcOptions
- Call options

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

Make a client streaming RPC call.

Parameters

serviceNamestring
- Service name
methodNamestring
- Method name
requestsAsyncIterable<TRequest>
- Async iterable of request messages
options?ConnectRpcOptions
- Call options

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

Make a bidirectional streaming RPC call.

Parameters

serviceNamestring
- Service name
methodNamestring
- Method name
requestsAsyncIterable<TRequest>
- Async iterable of request messages
options?ConnectRpcOptions
- Call options

close(): Promise<void>

Close the client connection.

interface

#ConnectRpcClientConfig

interface ConnectRpcClientConfig extends CommonOptions

Configuration for creating a ConnectRPC client.

Name	Description
`url`	Server URL for ConnectRPC connections.
`protocol`	Protocol to use.
`httpVersion`	HTTP version to use.
`tls`	TLS configuration.
`metadata`	Default metadata to send with every request.
`schema`	Schema resolution configuration.
`useBinaryFormat`	Whether to use binary format for messages.
`throwOnError`	Whether to throw ConnectRpcError on non-OK responses (code !== 0).

Properties

readonlyurlstring | ConnectRpcConnectionConfig
Server URL for ConnectRPC connections.

Can be a URL string or a connection configuration object.
readonlyprotocol?ConnectProtocol
Protocol to use.
readonlyhttpVersion?HttpVersion
HTTP version to use.
readonlytls?TlsConfig
TLS configuration. If not provided, uses insecure credentials.
readonlymetadata?Record<string, string>
Default metadata to send with every request.
readonlyschema?"reflection" | string | Uint8Array | FileDescriptorSet
Schema resolution configuration.
- "reflection": Use Server Reflection to discover services dynamically (default)
- string: Path to FileDescriptorSet binary file (from buf build --output set.binpb)
- Uint8Array: FileDescriptorSet binary data
- FileDescriptorSet: Pre-parsed FileDescriptorSet message object
readonlyuseBinaryFormat?boolean
Whether to use binary format for messages.
readonlythrowOnError?boolean
Whether to throw ConnectRpcError on non-OK responses (code !== 0). Can be overridden per-request via ConnectRpcOptions.throwOnError.

interface

#ConnectRpcConnectionConfig

interface ConnectRpcConnectionConfig extends CommonConnectionConfig

ConnectRPC connection configuration.

Extends CommonConnectionConfig with ConnectRPC-specific options.

Name	Description
`protocol`	Protocol to use.
`path`	Service path prefix.

Properties

readonlyprotocol?"http" | "https"
Protocol to use.
readonlypath?string
Service path prefix.

interface

#ConnectRpcErrorOptions

interface ConnectRpcErrorOptions extends ErrorOptions

Options for ConnectRpcError construction.

Name	Description
`metadata`	Headers/metadata from the ConnectRPC response.
`details`	Rich error details from google.rpc.Status.

Properties

readonlymetadata?Record<string, string>
Headers/metadata from the ConnectRPC response.
readonlydetails?readonly ErrorDetail[]
Rich error details from google.rpc.Status.

interface

#ConnectRpcOptions

interface ConnectRpcOptions extends CommonOptions

Options for individual ConnectRPC calls.

Name	Description
`metadata`	Metadata to send with the request.
`throwOnError`	Whether to throw ConnectRpcError on non-OK responses (code !== 0).

Properties

readonlymetadata?Record<string, string>
Metadata to send with the request.
readonlythrowOnError?boolean
Whether to throw ConnectRpcError on non-OK responses (code !== 0). Overrides ConnectRpcClientConfig.throwOnError.

interface

#ConnectRpcResponse

interface ConnectRpcResponse

ConnectRPC response interface.

Name	Description
`type`	Result type identifier
`ok`	Whether the request was successful (code === 0).
`code`	ConnectRPC/gRPC status code.
`message`	Status message (empty string for successful responses).
`headers`	Response headers
`trailers`	Response trailers (sent at end of RPC)
`duration`	Response time in milliseconds.
`data`()	Get deserialized response data.
`raw`()	Get raw response message.

Properties

readonlytype"connectrpc"
Result type identifier
readonlyokboolean
Whether the request was successful (code === 0).
readonlycodeConnectRpcStatusCode
ConnectRPC/gRPC status code.
readonlymessagestring
Status message (empty string for successful responses).
readonlyheadersRecord<string, string>
Response headers
readonlytrailersRecord<string, string>
Response trailers (sent at end of RPC)
readonlydurationnumber
Response time in milliseconds.

Methods

data<T = any>(): T | null

Get deserialized response data. Returns the response message as-is (already deserialized by Connect). Returns null if the response is an error or has no data.

raw(): unknown

Get raw response message.

interface

#ConnectRpcResponseOptions

interface ConnectRpcResponseOptions

Options for creating a ConnectRpcResponse.

Name	Description
`code`	—
`message`	—
`headers`	—
`trailers`	—
`duration`	—
`responseMessage`	—

Properties

readonlycodeConnectRpcStatusCode
readonlymessagestring
readonlyheadersRecord<string, string>
readonlytrailersRecord<string, string>
readonlydurationnumber
readonlyresponseMessageunknown

interface

#ErrorDetail

interface ErrorDetail

Rich error detail from google.rpc.Status.

ConnectRPC errors can include structured details encoded in error responses. These details follow the google.protobuf.Any format with a type URL and value.

Name	Description
`typeUrl`	Type URL identifying the error detail type.
`value`	Decoded error detail value.

Properties

readonlytypeUrlstring
Type URL identifying the error detail type. Common types include:
- "type.googleapis.com/google.rpc.BadRequest"
- "type.googleapis.com/google.rpc.DebugInfo"
- "type.googleapis.com/google.rpc.RetryInfo"
- "type.googleapis.com/google.rpc.QuotaFailure"
readonlyvalueunknown
Decoded error detail value. The structure depends on the typeUrl.

interface

#MethodInfo

interface MethodInfo

Method information from reflection.

Name	Description
`name`	Method name (e.g., "Echo")
`localName`	Local name (camelCase)
`kind`	Method kind
`inputType`	Input message type name
`outputType`	Output message type name
`idempotent`	Whether the method is idempotent

Properties

readonlynamestring
Method name (e.g., "Echo")
readonlylocalNamestring
Local name (camelCase)
readonlykind"unary" | "server_streaming" | "client_streaming" | "bidi_streaming"
Method kind
readonlyinputTypestring
Input message type name
readonlyoutputTypestring
Output message type name
readonlyidempotentboolean
Whether the method is idempotent

interface

#ReflectionApi

interface ReflectionApi

Reflection API for ConnectRPC client. Only available when client is created with schema: "reflection".

Name	Description
`enabled`	Check if reflection is enabled.
`listServices`()	List all available services on the server.
`getServiceInfo`()	Get detailed information about a specific service.
`listMethods`()	Get methods for a specific service.
`hasService`()	Check if a service exists.

Properties

readonlyenabledboolean
Check if reflection is enabled.

Methods

listServices(): Promise<ServiceInfo[]>

List all available services on the server.

getServiceInfo(serviceName: string): Promise<ServiceDetail>

Get detailed information about a specific service.

Parameters

serviceNamestring
- Fully qualified service name (e.g., "echo.EchoService")

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

Get methods for a specific service.

Parameters

serviceNamestring
- Fully qualified service name

hasService(serviceName: string): Promise<boolean>

Check if a service exists.

Parameters

serviceNamestring
- Fully qualified service name

interface

#ServiceDetail

interface ServiceDetail

Detailed service information.

Name	Description
`name`	Service name
`fullName`	Fully qualified service name
`packageName`	Package name
`protoFile`	Proto file name
`methods`	All methods

Properties

readonlynamestring
Service name
readonlyfullNamestring
Fully qualified service name
readonlypackageNamestring
Package name
readonlyprotoFilestring
Proto file name
readonlymethodsreadonly MethodInfo[]
All methods

interface

#ServiceInfo

interface ServiceInfo

Service information from reflection.

Name	Description
`name`	Fully qualified service name (e.g., "echo.EchoService")
`file`	Proto file name

Properties

readonlynamestring
Fully qualified service name (e.g., "echo.EchoService")
readonlyfilestring
Proto file name

interface

#TlsConfig

interface TlsConfig

TLS configuration for ConnectRPC connections.

Name	Description
`rootCerts`	Root CA certificate (PEM format).
`clientCert`	Client certificate (PEM format).
`clientKey`	Client private key (PEM format).
`insecure`	Skip server certificate verification (use only for testing).

Properties

readonlyrootCerts?Uint8Array
Root CA certificate (PEM format).
readonlyclientCert?Uint8Array
Client certificate (PEM format).
readonlyclientKey?Uint8Array
Client private key (PEM format).
readonlyinsecure?boolean
Skip server certificate verification (use only for testing).

Functions

function

#createConnectRpcClient

function createConnectRpcClient(config: ConnectRpcClientConfig): ConnectRpcClient

Create a new ConnectRPC client instance.

The client supports multiple protocols (Connect, gRPC, gRPC-Web) and provides Server Reflection for runtime service discovery without compile-time code generation.

Parameters

configConnectRpcClientConfig
- Client configuration including server URL and protocol options

Returns

ConnectRpcClient — A new ConnectRPC client instance

Examples

Basic usage with reflection

const client = createConnectRpcClient({
  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 with reflection

const client = createConnectRpcClient({
  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();

Using different protocols

// Connect protocol (HTTP/1.1 or HTTP/2)
const connectClient = createConnectRpcClient({
  url: "http://localhost:8080",
  protocol: "connect",
});

// gRPC protocol (HTTP/2 with binary protobuf)
const grpcClient = createConnectRpcClient({
  url: "http://localhost:50051",
  protocol: "grpc",
});

// gRPC-Web protocol (for browser compatibility)
const grpcWebClient = createConnectRpcClient({
  url: "http://localhost:8080",
  protocol: "grpc-web",
});

Using connection config object

const client = createConnectRpcClient({
  url: {
    host: "grpc.example.com",
    port: 443,
    protocol: "https",
  },
});

Using await using for automatic cleanup

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

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

function

#fromConnectError

function fromConnectError(error: ConnectError, metadata?: Record<string, string>): ConnectRpcError

Convert ConnectRPC's ConnectError to ConnectRpcError.

Parameters

errorConnectError
- The ConnectError from @connectrpc/connect
metadata?Record<string, string>
- Optional metadata from the response

Returns

ConnectRpcError — Appropriate ConnectRpcError subclass based on error code

function

#getStatusName

function getStatusName(code: ConnectRpcStatusCode): string

Get the name of a ConnectRPC/gRPC status code.

Parameters

codeConnectRpcStatusCode

Examples

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

function

#isConnectRpcStatusCode

function isConnectRpcStatusCode(code: number): code is ConnectRpcStatusCode

Check if a number is a valid ConnectRPC/gRPC status code.

Parameters

codenumber

Examples

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

Type Aliases

type

#ConnectProtocol

type ConnectProtocol = "connect" | "grpc" | "grpc-web"

Protocol to use for ConnectRPC transport.

type

#ConnectRpcStatusCode

type ConnectRpcStatusCode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16

ConnectRPC/gRPC status codes. These codes are used by both gRPC and ConnectRPC protocols.

type

#FileDescriptorSet

type FileDescriptorSet = MessageShape<FileDescriptorSetSchema>

FileDescriptorSet message type from @bufbuild/protobuf. This is the decoded protobuf message containing file descriptors.

type

#HttpVersion

type HttpVersion = "1.1" | "2"

HTTP version for transport.

Variables

const

#ConnectRpcStatus

const ConnectRpcStatus: { 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 }

Human-readable names for ConnectRPC/gRPC status codes.

Features

Installation

Quick Start

Testing Error Responses

Using with using Statement

Related Packages

Links

Installation

Classes

#ConnectRpcError

Constructor

Properties

Links

#ConnectRpcInternalError

Constructor

Properties

Links

#ConnectRpcNotFoundError

Constructor

Properties

Links

#ConnectRpcPermissionDeniedError

Constructor

Properties

Links

#ConnectRpcResourceExhaustedError

Constructor

Properties

Links

#ConnectRpcResponseImpl

Constructor

Properties

Methods

Links

#ConnectRpcUnauthenticatedError

Constructor

Properties

Links

#ConnectRpcUnavailableError

Constructor

Properties

Links

Interfaces

#ConnectRpcClient

Properties

Methods

Parameters

Parameters

Parameters

Parameters

Links

#ConnectRpcClientConfig

Properties

Links

#ConnectRpcConnectionConfig

Properties

Links

#ConnectRpcErrorOptions

Properties

Links

#ConnectRpcOptions

Properties

Links

#ConnectRpcResponse

Properties

Methods

Links

#ConnectRpcResponseOptions

Properties

Links

#ErrorDetail

Properties

#MethodInfo

Properties

#ReflectionApi

Properties

Methods

Parameters

Parameters

Parameters

Using with `using` Statement