`tsgo` causes major issues with `@hono/zod-openapi` route chain accumulation -- documentation update recommended?

[daviduzumeri]

Which middleware is the feature for?

@hono/zod-openapi

What is the feature you are proposing?

Hey, sorry. Claude got a little zealous and posted a comment without the ability for me to write a human forward and explain where this came from.

I've converted an almost comically large API surface from express-openapi-validator and spec-first to Hono using @hono/zod-openapi (we have a Swift client!) and Hono RPC, and am moving everything into a monorepo structure, just as part of a general modernization effort (and also since it's worth doing while tokens are cheap). We've been on tsgo and oxlint-tsgolint for a while, and have very inference-heavy Kysely usage, so I figured going all-in on TS inference with Hono wouldn't be that big of a deal. Instead, it made my M1 Air basically cry itself to sleep, took way longer than expected on my Core i9, and required significantly increasing our GHA runner resource class for CI.

So I spent a bunch of time trying to figure out what was going on, since while I was expecting some tradeoff, this seemed orders of magnitude worse than what I expected. I'll let Claude take it from here, but I've got numbers that have been independently verified, and some reproduction repos. I don't think this is necessarily Hono's problem to solve, and I'll also be sharing these results with the tsgo team, but in case this is too architecturally deep to be fixed in time for 7.0 GA I figured I'd post about it here with the amelioration tactic that's been successful for us in case y'all want to update the best-practices guidelines so other people don't run into this same footgun when they upgrade to tsgo and discover that it's somehow slower.

Claude from here:
Some data that may be useful here: the "excessively deep" cost from .openapi() is largely an accumulation effect, and there's a behavior-preserving way to sidestep it.

Building an OpenAPIHono by chaining .openapi(route, handler) accumulates the route-schema generic at every link. For the same routes, handlers, and emitted OpenAPI spec, registering each route on its own single-route app and combining with .route() is dramatically cheaper to type-check.

Type instantiations (tsc --extendedDiagnostics), N=60 routes, realistic schemas — tsc 5.9.3 and @typescript/native-preview (tsgo) 7.0.0-dev:

variant	tsc	tsgo
chained .openapi()	4.71M	4.69M
.route()-merged	1.50M	1.49M
chained + hc<> client	5.13M	9.80M
merged + hc<> client	1.74M	3.23M

Two takeaways:

• App side: .route()-merging is ~3× cheaper than chaining, under both compilers.
• Client side: the hc<> instantiation increment over a chained app is ~+0.4M under tsc but ~+5.1M under tsgo (~12×). As the native port approaches GA, zod-openapi RPC consumers are where this will bite hardest — and the merge cuts it ~3× there too.

(Plain zValidator .get/.post RPC doesn't show this — it's already cheap and merging makes it worse; the effect is specific to .openapi()'s accumulation.)

Workaround — identical routing and OpenAPI output:

export const app = new OpenAPIHono()
  .route("/", new OpenAPIHono().openapi(routeA, handlerA))
  .route("/", new OpenAPIHono().openapi(routeB, handlerB));

Minimal repro (one command, runs tsc + tsgo per variant): https://github.com/daviduzumeri/hono-zod-openapi-rpc-typecheck-perf

Could .openapi() accumulate via a flatter representation, and/or could the docs recommend the .route()-merge pattern for large RPC apps ahead of tsgo GA?

[daviduzumeri]

Update / correction on the numbers above.

The TypeScript-native (tsgo) team pointed out my earlier + hc<> client figures were measured under tsgo's default parallel checkers. With --checkers 1, tsgo matches tsc almost exactly — so there's no tsc-vs-tsgo divergence; the inflated client number was just --extendedDiagnostics summing instantiations across checkers (the recursive hc<> client type is instantiated once per checker):

variant (N=60)	tsc 6.0	tsgo (default)	tsgo --checkers 1
chained app	4.70M	4.69M	4.69M
chained + hc<> client	5.13M	9.80M	5.11M
merged + hc<> client	1.75M	3.23M	1.73M

The actionable finding is unchanged and compiler-agnostic: building a sub-app by chaining .openapi(route, handler) costs ~3× the type instantiations of merging single-route apps via .route() — under both tsc and tsgo, at any checker count (app-side instantiations are checker-invariant: 4.70M chained vs ~1.50M merged). The .route()-merge is a behavior-preserving way to cut that:

export const app = new OpenAPIHono()
  .route("/", new OpenAPIHono().openapi(routeA, handlerA))
  .route("/", new OpenAPIHono().openapi(routeB, handlerB));

Two practical notes for large @hono/zod-openapi RPC apps on tsgo:

• Because the recursive client type is re-instantiated per checker, default multi-checker runs use more peak memory for it. The .route()-merge lowers the per-checker cost, so it compounds across checkers.
• If you're memory-constrained (OOM on CI), --checkers 1 trades wall-time for lower peak memory — but it's not needed for correctness or to see the chaining-vs-merge difference.

Repro updated with the --checkers 1 column: https://github.com/daviduzumeri/hono-zod-openapi-rpc-typecheck-perf

[yusukebe]

@daviduzumeri

Very interesting! Thanks.

Regarding the performance difference between the chained and merged patterns, is it a good idea to add a description to the README, like in #1919? What do you think of it?

[daviduzumeri]

@daviduzumeri

Very interesting! Thanks.

Regarding the performance difference between the chained and merged patterns, is it a good idea to add a description to the README, like in #1919? What do you think of it?

Yeah, or if there's a shorthand where it instantiates stuff behind the scenes with a sexier interface that might work too? Either way I think a docs update would save people pain! We had a huge API surface that was all hand-rolled OpenAPI YAML that we converted to Zod-first with Claude (we need the OpenAPI doc because we have a generated Swift client) and it was a shockingly smooth process outside of this one hiccup. With this pattern it's incredibly clean and performant, though.

And thanks for the amazing library, we made the switch from Express with express-openapi-validator to Hono with @hono/node-server and @hono/zod-openapi about a month ago and it's been an absolute joy in comparison. Thanks for helping drag this ecosystem kicking and screaming into the future :)

[thekiwi]

Hey @daviduzumeri, I'm also using @hono/zod-openapi in a relatively large codebase (two Hono APIs plus multiple UIs interacting via Hono RPC in a large monorepo) and have been looking at ways to improve the inference performance. I submitted PR #1988 which results in a significant reduction of type instantiations, check time and memory usage. In the benchmarks I was seeing 50-60% reduction of type instantiations but in my actual monorepo, it was ~75% reduction.

It sounds like you're in a similar situation with your "almost comically large API", so I'm curious if you might see similar benefits from my PR. It doesn't require any code changes, it's simply an optimisation of the generic definitions in @hono/zod-openapi.

Related to that, another thing that helped on our codebase was the introduction of the new .openapiRoutes([ ... ]) batch function, introduced in #1752 back in April and published in @hono/zod-openapi@1.3.0. Just switching our APIs to use that batching function dropped instantiations from 24.8M to 7.1M (−71%) and check time from 41.5s to 10.2s (~4× faster).