trpc-msw

packages/trpc-msw (npm trpc-msw) answers a tRPC client's calls at the network, inside a test. A test registers a resolver per procedure through a proxy typed off the router — trpcMsw.resource.readResource.query(({ input }) => …) — and every request the client sends is served by a router built from those resolvers, on the consumer's own initTRPC result, through tRPC's own handlers. Nothing about tRPC's wire format is written in the package: batching, the transformer, the error formatter, FormData and octet input, method override, server-sent events and the WebSocket protocol are all tRPC's.

It replaced msw-trpc, an adapter between the same two engines that re-implemented the wire format by hand, and is the worked example of the absorption flow in dependency admission.

How a call is answered

flowchart TD
  client["tRPC client<br/>any link"]
  msw["msw interceptor"]
  http{"Transport"}
  bypass{"Any procedure<br/>registered?"}
  next["next msw handler<br/>or the network"]
  fetchHandler["fetchRequestHandler<br/>batch, SSE, FormData"]
  wssHandler["applyWSSHandler<br/>per-connection router"]
  router["mock router<br/>on the consumer's t"]
  registry["resolver registry<br/>read at call time"]
  client --> msw
  msw --> http
  http -->|HTTP| bypass
  bypass -->|"no, and onUnhandledProcedure is Bypass"| next
  bypass -->|yes, or Error| fetchHandler
  http -->|WebSocket| wssHandler
  fetchHandler --> router
  wssHandler --> router
  router --> registry

• One HTTP handler matches everything under the endpoint and hands the request to fetchRequestHandler, over a router built from every path registered so far. A batch carries several procedures behind one url, which is why the unit is the endpoint and never the procedure.
• Resolvers are read when a procedure is called, not when the router is built. A resolver a test replaces answers the next call on any transport, and a path whose resolver was cleared by reset answers tRPC's NOT_FOUND.
• WebSockets are bridged by presenting each msw client connection as the ws.WebSocket tRPC's applyWSSHandler drives. tRPC binds a connection to the router it was accepted with, so registering a path the current router lacks closes the open connections on the spot; the client queues its next call, reconnects and resubscribes onto the new router. tRPC's reconnect notification is not used for this: the client reads it only on its next turn, and a call sent before then would reach the old router.
• The mock router is built on the consumer's own t, so a thrown TRPCError reaches the client through the real error formatter, and a resolver returns the procedure's output before the transformer rather than its serialized envelope.

Upstream

Every msw-trpc issue and pull request, with its verdict. The four verdicts and what each owes are the triage on the dependency admission page; a defect's proof is the named test in packages/trpc-msw/src/createTRPCMsw.test.ts or the type test in src/models/TRPCMswRouterRecord.test-d.ts.

Never ported: observable subscriptions. tRPC 11 deprecates them in favour of async generators, so a subscription resolver here returns an async iterable and nothing else.

Key files

Sources

• maloguertin/msw-trpc — the package replaced, its issues and pull requests.
• Fetch adapter (tRPC) — fetchRequestHandler, which serves batches, method override and server-sent events.
• WebSockets (tRPC) — applyWSSHandler, the connection handler and the reconnect notification.
• Subscriptions (tRPC) — async generators as the subscription shape, observables deprecated.
• Mocking WebSocket (msw) — ws.link and the client connection the adapter wraps.