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