RPC

One type shared by both ends of the wire: routes chained so their paths, inputs and responses become a type, a client built from that type alone, refusals and statuses the client can tell apart, and the same client inside tests and inside other services. The docs' RPC guide, section by section, on the cats API.

lessons: 7
level: intermediate
time: 2.5 hours

Start with Chained routes

One type, two sides

What a chain of routes puts into typeof app, and what a client built from that type can do.

1
Chained routes
Make the cats API's routes part of its type by chaining them on the Hono instance, export that type, and watch a client built from nothing but the type call every route with autocompletion.
Read the theory
2
The client
Wrap hc in a module the rest of an app can call: list(), find() and add() over the typed client, statuses narrowed into a Cat, a null or an ApiError, and a base URL that tests and production both pass in.
Read the theory

Everything on the wire

Statuses the client can narrow on, and the parameters, query values and headers a request carries.

3
Statuses as types
Three habits that answer correctly and tell the client nothing: a .then() chain, c.notFound(), and c.json() without a status. Fix each on a cats API that reads from an asynchronous store, and read a refusal with parseResponse.
Read the theory
4
Params, queries and headers
Send everything a request carries through the typed client: a path parameter, a query value, a header the route's validator demands, and URLs and paths built from the same type with $url() and $path().
Read the theory

Bigger apps

The types across a split app, a service calling another service, and tests written through the client.

5
Larger applications
Keep the RPC types when the API is split into one Hono per resource: chain each sub-app's routes, chain the route() calls that mount them, export the type of the chain's result, and compute the client's type once for every caller.
Read the theory
6
Service to service
A gateway in front of the cats service: a dashboard that aggregates what the service knows and an adoption route that forwards a request and passes the service's refusals through, both over a client built from the service's type with the service's own request() as its fetch.
Read the theory
7
Testing with the client
Rewrite the cats API's spec with testClient from hono/testing, the typed client over app.request(), and prove the tests mean something by catching four bugs planted in the code.
Read the theory