English for oRPC Developers

oRPC is a TypeScript library for building end-to-end type-safe APIs using an RPC (remote procedure call) model instead of hand-written REST or GraphQL schemas — the client calls a function, and the types flow from server to client without codegen. Because it sits at the intersection of “API design” and “type system” conversations, review discussions mix contract vocabulary with TypeScript vocabulary. Here’s the English you need to talk about it clearly.

Procedures and Contracts

Procedure — the basic unit of an oRPC API, a single callable function exposed to clients, roughly analogous to a REST endpoint or a GraphQL resolver.

“Let’s keep this as one procedure instead of splitting it into three — the client only ever needs to call it as a single unit.”

Contract-first — defining the shape of inputs and outputs (via a schema) before implementing the procedure’s logic, so the type contract exists independently of any one implementation.

“We went contract-first here so the frontend team could start on the UI before the resolver was even written.”

Input/output schema — the validation schema (often Zod) attached to a procedure that defines and enforces its accepted arguments and return shape.

“The 400 you’re seeing is the input schema rejecting the request — the payload is missing the userId field.”

Type Safety and Inference

End-to-end type safety — the property that a change to a server-side procedure’s types is immediately reflected as a type error on the client, without manual synchronization.

“That’s the whole value proposition here — rename a field on the server and the client call site turns red in your editor before you even run anything.”

Type inference — TypeScript automatically deriving a procedure’s input/output types from its schema, rather than the developer manually writing matching interfaces on both sides.

“We’re not maintaining a shared types package anymore — inference handles it, so there’s one less thing that can drift out of sync.”

Router — the object that groups related procedures into a nested, callable namespace on the client (e.g., client.users.get, client.users.create).

“Move that procedure under the billing router — it doesn’t belong under users conceptually, even though it currently lives there.”

Middleware and Transport

Middleware — reusable logic (auth checks, logging, rate limiting) that runs before a procedure’s handler, composable across multiple procedures.

“Add the auth middleware to this procedure — right now it’s callable without a session, which is a real gap.”

RPC-over-HTTP — oRPC’s approach of serializing procedure calls as HTTP requests under the hood, while still presenting a function-call interface to the developer.

“It still speaks plain HTTP under the hood, so we can hit these procedures with curl for debugging even though the client never does.”

Adapter — the piece of code connecting oRPC’s router to a specific server framework (Node’s http, Hono, Next.js route handlers, etc.).

“We’re not locked into one framework — swapping the adapter to Hono didn’t require touching a single procedure definition.”

Common Mistakes

• Saying “the type is wrong” without specifying whether the mismatch originates in the schema, the procedure’s return statement, or the client’s usage — each needs a different fix.
• Treating “contract” and “schema” as unrelated concepts in review, when the schema is the concrete implementation of the contract.
• Forgetting that middleware order matters, then being confused when an auth check runs after a database call it was supposed to guard.

Practice Exercise

1. Explain, in two sentences, the difference between a procedure and a router to a developer coming from REST.
2. Write a short PR description for adding an auth middleware to a previously unprotected procedure.
3. Draft a code review comment explaining why a shared types package is unnecessary given end-to-end type inference.

Related Resources

• English for TypeScript Developers
• English for API Design Reviews
• English for tRPC Developers

Navigating the Nuances: Practical English for oRPC Teams

The core vocabulary of oRPC – encompassing concepts like contracts, middleware, and even RPC itself – can feel surprisingly dense when trying to communicate effectively within a development team. It’s easy to fall into overly technical jargon or struggle to articulate precisely what needs to be done, especially when dealing with complex interactions between different services. This section focuses on translating those technical terms into clear, actionable English, particularly relevant for non-native English speakers striving for professional clarity in their discussions. The goal isn’t simply to use the correct words, but to express intent and expectations effectively – a crucial element often missed in purely technical communication.

Consider a scenario during code review: “This request modifies the User contract’s validation rules. We need to ensure backwards compatibility with existing consumers of this service.” This statement is precise, yet potentially intimidating for someone less familiar with the nuances of contracts and versioning. A more approachable phrasing might be: “We’re updating the way we validate user data in this request, but we want to make sure old versions of the service can still read and process these users correctly.” Notice how the revised wording avoids overly technical terms like “validation rules” and instead focuses on the outcome – ensuring existing consumers continue to function. Similarly, when describing a new middleware component – “This middleware handles authentication using JWT tokens” - a clearer explanation could be: “This piece of code checks if a user is allowed access to this service by verifying their credentials.”

Furthermore, proactive communication about potential problems is key. Instead of saying “There’s an impedance mismatch,” a developer should aim for something like, “The data structure being returned doesn’t perfectly align with the expectations defined in the contract. We need to address this before deploying.” This emphasizes the problem – the misalignment – rather than throwing around jargon. Learning to frame technical issues within a user-centric perspective—how it impacts the end-user or other services—is invaluable. Effective communication builds trust and avoids misunderstandings, leading to smoother development cycles.

Here’s an example of using curl to interact with an oRPC service:

curl -X POST \
  http://orpc-service/users \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  }'

This simple command demonstrates the practical application of understanding API requests and responses – a core element of oRPC communication, regardless of your native language. The key is to translate the intent of the command into clear English: “We’re sending this data to the users endpoint of the oRPC service to create a new user account.”