oRPC Client

@orpc/client is the consumption half of oRPC, a contract-first RPC toolkit for TypeScript. Given a router or contract type defined with @orpc/server, it produces a fully-typed proxy client — calling a nested procedure reads like calling a plain function, with input, output, and error types inferred end-to-end and no code-generation step. Transport is abstracted behind swappable “links”: an RPC link over fetch for standard HTTP APIs, a WebSocket link for bidirectional and streaming calls, and a message-port link for cross-realm communication such as iframes, workers, or Electron’s main/renderer boundary.

Beyond the base client, the package ships a plugin system for the fetch link — retry with backoff, Retry-After-aware retry, response de-duplication, request batching, timeouts, and gzip/br compression — plus async-iterator utilities so a single procedure call can stream incremental results. Errors thrown by the server round-trip as typed, discriminated error objects instead of opaque exceptions, and deprecated exports are kept as typed re-exports pointing at their replacements as the API evolves toward a 2.0 release.

What You Get

• Fully typed proxy client generated from a router/contract type — no manual API bindings or codegen step.
• Fetch-based RPC link for standard HTTP APIs, exposed via a dedicated ./fetch subpath export.
• WebSocket link and message-port link for streaming and cross-realm communication (iframes, workers, Electron).
• Built-in plugin support: retry, retry-after, timeout, dedupe, batching, and request/response compression.
• Typed error propagation (error.ts/error-utils.ts) that replaces generic thrown exceptions with discriminated, inferable errors.
• Async-iterator utilities for consuming streamed or subscribable procedure responses.

Common Use Cases

• Calling a Next.js/Express/Hono backend built with @orpc/server from a browser or Node client with full type inference.
• Consuming a long-lived WebSocket API (chat, live dashboards) where individual procedures resolve or stream over the same socket.
• Communicating between an Electron main process and renderer, or a page and a worker/iframe, via the message-port link instead of HTTP.
• Adding resilience — retries, response dedupe, request batching — to client calls without hand-rolling interceptor logic.

Under The Hood

Architecture The client centers on createORPCClient (client.ts), which builds a recursive Proxy that caches child clients per path segment and threads input/options through an intercept call chain before delegating to a ClientLink.call() implementation; the actual network behavior is factored into interchangeable “links” under adapters/ (standard/link.ts as the shared core, with fetch/rpc-link.ts, websocket/rpc-link.ts, and message-port/rpc-link.ts as concrete transports), each split further into a codec (encode input to a StandardRequest / decode a StandardLazyResponse) and a transport (actually sending bytes) — letting one core standard link support three unrelated transports, and letting dynamic-link.ts swap the concrete link at runtime without touching call sites. Cross-cutting behavior (retry, retry-after, timeout, dedupe, batch, compression) is implemented as StandardLinkPlugins composed onto the standard link rather than baked into the client or transports, keeping each concern transport-agnostic and independently testable.

Tech Stack Written in strict TypeScript targeting ES2022 (tsconfig.base.json enables strict, noUncheckedIndexedAccess, isolatedModules), built with unbuild into dual ESM output declared via publishConfig.exports, with granular subpath exports (., /plugins, /standard, /fetch, /websocket, /message-port) so consumers only bundle the adapters they actually use. Runtime dependencies are minimal — @orpc/shared (workspace) plus the @standardserver/* family (core, fetch, peer) supplying the standard request/response primitives shared across the whole oRPC ecosystem. The monorepo is pnpm-workspace-managed, tested with Vitest including a dedicated benchmark suite wired to CodSpeed in CI, and linted via @antfu/eslint-config.

Code Quality Every source module under src/ has a co-located behavioral test file and, for public-facing types, a companion type-level test file — dozens of test/type-test files against roughly a dozen implementation modules — with unit tests exercising retry backoff, dedupe collapsing, batch splitting, and error decoding via Vitest mocks rather than live network calls. Error handling is explicit and typed rather than throwing raw exceptions across the client boundary, naming is consistent throughout, and CI runs workspace-wide type-checking, tests, and zero-warning linting on every change.

API Design Getting started requires no code generation or manual bindings — createORPCClient(link) alone produces a fully-typed callable client whose shape mirrors the server router, and swapping HTTP for WebSocket or message-port transport means constructing a different link, not rewriting call sites. Deprecated exports are kept as typed re-exports with inline documentation pointing at their replacements, which is unusually considerate given the repo is mid-migration to a new major version while still patch-releasing the current one. The plugin model turns concerns normally hand-rolled per project — retry, dedupe, batching, timeouts — into one-line composition.