feat: make TanStack Query plugin respect responseStyle: 'fields'

[JorrinKievit]

Problem

When using the TanStack Query plugin, there's no way to access the HTTP Response object — status codes, headers, or request metadata. The plugin always destructures { data } from the SDK response and discards everything else, even when responseStyle: 'fields' is configured.

This makes it impossible to:

• Check HTTP status codes on errors (e.g., show a 404 page, redirect on 401)
• Read response headers on success (e.g., pagination X-Total-Count, rate-limit headers)
• Implement global error handling based on status codes in QueryCache.onError

Related issues: #3628, #3632, #2070, #1762

Solution

This PR makes the TanStack Query plugin actually respect responseStyle. A new responseStyle config option is added to the plugin. I decided to have "data" as the default, since that kinda is happening right now for the plugin.

Plugin-level config

plugins: [
  {
    name: '@tanstack/react-query',
    responseStyle: 'fields', // opt-in
  },
]

Per-query override

Each generated function accepts a generic TStyle parameter, so you can override per-query without changing the global default:

// Default — same as today
const { data } = useQuery(getUserOptions());
data?.name; // TData directly

// Opt-in per query
const { data, error, isError } = useQuery(getUserOptions({ responseStyle: 'fields' }));
data?.data.name;              // typed response data
data?.response.status;        // HTTP status
data?.response.headers;       // response headers

if (isError) {
  error.response.status;      // 404
  error.error.message;        // typed error body
}

Also works the other way — if the plugin default is 'fields', you can override specific queries back to 'data'.

Discussion point

For me the primary reason is being able to access the response type on Errors so I can handle them globally. But also included it for succesfull responses because I saw other issues.

What I don't like is that I kinda want to enable it globally, but only for Errors and not for the data itself. Because that would mean I am gonna have nested data objects everywhere 🤔

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

Someone is attempting to deploy a commit to the Hey API Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9086190

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[codecov]

Codecov Report

❌ Patch coverage is 6.75676% with 138 lines in your changes missing coverage. Please review.
✅ Project coverage is 38.82%. Comparing base (46b7d3a) to head (9086190).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
...plugins/@tanstack/query-core/v5/mutationOptions.ts	5.00%	34 Missing and 4 partials ⚠️
...rc/plugins/@tanstack/query-core/v5/queryOptions.ts	5.12%	33 Missing and 4 partials ⚠️
...ns/@tanstack/query-core/v5/infiniteQueryOptions.ts	5.40%	31 Missing and 4 partials ⚠️
...i-ts/src/plugins/@tanstack/query-core/v5/plugin.ts	12.50%	20 Missing and 1 partial ⚠️
...c/plugins/@hey-api/client-angular/bundle/client.ts	0.00%	1 Missing and 1 partial ⚠️
...src/plugins/@hey-api/client-fetch/bundle/client.ts	0.00%	1 Missing and 1 partial ⚠️
...rc/plugins/@hey-api/client-ofetch/bundle/client.ts	0.00%	1 Missing and 1 partial ⚠️
...ts/src/plugins/@hey-api/client-ky/bundle/client.ts	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3662      +/-   ##
==========================================
- Coverage   38.98%   38.82%   -0.17%     
==========================================
  Files         518      518              
  Lines       18968    19072     +104     
  Branches     5606     5620      +14     
==========================================
+ Hits         7395     7405      +10     
- Misses       9367     9451      +84     
- Partials     2206     2216      +10     

Flag	Coverage Δ
unittests	38.82% <6.75%> (-0.17%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pkg-pr-new]

Open in StackBlitz

@hey-api/codegen-core

npm i https://pkg.pr.new/@hey-api/codegen-core@3662

@hey-api/json-schema-ref-parser

npm i https://pkg.pr.new/@hey-api/json-schema-ref-parser@3662

@hey-api/nuxt

npm i https://pkg.pr.new/@hey-api/nuxt@3662

@hey-api/openapi-ts

npm i https://pkg.pr.new/@hey-api/openapi-ts@3662

@hey-api/shared

npm i https://pkg.pr.new/@hey-api/shared@3662

@hey-api/spec-types

npm i https://pkg.pr.new/@hey-api/spec-types@3662

@hey-api/types

npm i https://pkg.pr.new/@hey-api/types@3662

@hey-api/vite-plugin

npm i https://pkg.pr.new/@hey-api/vite-plugin@3662

commit: 9086190

[pullfrog]

Reviewed PR #3662. Found a critical runtime/type mismatch bug where the default TStyle = 'fields' doesn't align with the runtime check options?.responseStyle === 'fields' (fails when undefined), a regression where .export(plugin.config.mutationOptions.exported) was dropped to .export(), and significant code duplication across three files. Review posted.

Task list (5/5 completed)

• Read the diff TOC and identify high-risk areas of change
• Review core plugin logic changes (non-snapshot files)
• Review generated code / snapshot changes for correctness
• Check for impact on existing APIs (breaking changes)
• Submit review with findings

  ^{｜ [View workflow run](https://github.com/hey-api/openapi-ts/actions/runs/23674544498/job/68974902316) ｜ Triggered by [Pullfrog](https://pullfrog.com) ｜ [𝕏](https://x.com/pullfrogai)}

[pullfrog]

Thanks for working on this — the feature is genuinely useful and the overall design (plugin-level config + per-query TStyle override) is solid. There is one critical runtime bug and a few other issues that need addressing before this can merge.

Critical: The runtime conditional options?.responseStyle === 'fields' does not match when responseStyle is undefined (the common case when the user omits it), yet the type-level default for TStyle is 'fields'. This causes a type-safety violation where TypeScript thinks the return is { data, request, response } but the actual runtime value is just the unwrapped data.

Other issues: a regression where .export(plugin.config.mutationOptions.exported) was changed to .export(), duplicate imports, and heavy code duplication across three files that could be reduced significantly.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ 𝕏}