OpenRPC Client JS

OpenRPC Client JS is a lightweight, browser-compatible JSON-RPC 2.0 client for JavaScript and TypeScript. It decouples the request lifecycle from the wire protocol through a pluggable transport layer, so the same client code can talk to a server over HTTP/HTTPS, WebSocket, PostMessage (window or iframe), or an in-process EventEmitter without changing how you make calls.

Built around a small Client facade backed by a RequestManager and one or more Transport implementations, it handles request/response correlation, notifications, batching, and typed error propagation. With zero framework lock-in and full TypeScript typings, it is a common building block for Ethereum JSON-RPC tooling, wallet integrations, and any app that needs to call a JSON-RPC endpoint from the browser or Node.

What You Get

• A browser- and Node-compatible JSON-RPC 2.0 client with a tiny public API surface
• Five interchangeable transports: HTTP/HTTPS, WebSocket, PostMessageWindow, PostMessageIframe, and EventEmitter
• Request batching plus fire-and-forget notifications and a notification listener
• Typed JSONRPCError objects with error codes for timeouts, missing IDs, and transport failures
• First-class TypeScript type definitions and a browser build entry point

Common Use Cases

• Calling Ethereum and other blockchain JSON-RPC nodes from a dapp or wallet
• Communicating with a JSON-RPC backend over WebSocket for realtime, bidirectional messaging
• Bridging a web page and an embedded iframe or child window via PostMessage transports
• Wiring an in-process EventEmitter transport for tests or same-process JSON-RPC dispatch

Under The Hood

Architecture — The library layers cleanly from src/index.ts: a Client (Client.ts) facade delegates to a RequestManager (RequestManager.ts) that assigns request IDs, tracks pending promises, and fans requests out to one or more Transport instances. Each concrete transport (HTTPTransport.ts, WebSocketTransport.ts, PostMessageWindowTransport.ts, PostMessageIframeTransport.ts, EventEmitterTransport.ts) extends the abstract Transport base (transports/Transport.ts), which owns a TransportRequestManager that correlates raw wire responses back to their originating request via a StrictEventEmitter channel (pending/response/notification/error events). Batching is coordinated by startBatch/stopBatch on the RequestManager.

Tech Stack — Written in TypeScript 5.9 targeting both browser and Node, with a deliberately small runtime dependency set: isomorphic-ws and ws for cross-environment WebSockets and strict-event-emitter-types for typed event channels. The package ships ESM with a dedicated browser export, builds via a Bun-driven build.ts plus tsc for declarations and TypeDoc for docs, and is Apache-2.0 licensed.

Code Quality — Testing is thorough: nine Jest test suites (jest --coverage) cover the client, request manager, error handling, and every transport, backed by mocks under src/__mocks__. Errors are modeled explicitly with a custom JSONRPCError class carrying numeric codes (ERR_TIMEOUT, ERR_MISSIING_ID, ERR_UNKNOWN) and a prototype-chain fix for reliable instanceof checks. The codebase is fully typed with ESLint + Prettier enforcement and conventional-commit / semantic-release automation.

API Design — The public API is intentionally minimal and ergonomic: build a transport, wrap it in a RequestManager, pass it to Client, then await client.request({ method, params }). Transports are swappable without touching call sites, notifications and batching are one-liners, and the README documents each transport with a runnable example. Full TypeScript typings and JSDoc on the Client methods keep discovery and autocomplete strong.