feat: add skipToken support and queryOptions override to TanStack Query useQuery hooks

[nmokkenstorm]

Summary

Adds skipToken support and queryOptions override to generated useQuery hooks for TanStack Query plugins (React, Preact).

• useQuery hooks are now generated by default (no config flag needed)
• skipToken is always supported — pass it instead of options to conditionally disable a query
• queryOptions override parameter allows customizing the underlying query options
• Use useQuery: false to opt out of generating useQuery hooks

Closes #2766

Breaking changes

None. This is additive and backwards-compatible:

• Existing queryOptions and queryKeys continue to work as before
• useQuery hooks are new generated output (enabled by default, opt-out with useQuery: false)
• skipToken support is wired into queryOptions automatically

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

@nmokkenstorm 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]

🦋 Changeset detected

Latest commit: 2ffe100

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@hey-api/openapi-ts	Minor

Not sure what this means? Click here to learn what changesets are.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 39.20%. Comparing base (d61d2b1) to head (2ffe100).
⚠️ Report is 44 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3528      +/-   ##
==========================================
- Coverage   39.37%   39.20%   -0.18%     
==========================================
  Files         506      513       +7     
  Lines       18572    18804     +232     
  Branches     5511     5573      +62     
==========================================
+ Hits         7313     7372      +59     
- Misses       9088     9239     +151     
- Partials     2171     2193      +22     

Flag	Coverage Δ
unittests	39.20% <ø> (-0.18%)	⬇️

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@3528

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

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

@hey-api/nuxt

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

@hey-api/openapi-ts

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

@hey-api/shared

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

@hey-api/types

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

@hey-api/vite-plugin

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

commit: 4ea3c27

[mrlubos]

@nmokkenstorm Why is it an optional configuration flag? Why not add it for everyone?

[mrlubos]

@nandorojo will like this

[mrlubos]

@nmokkenstorm I updated your description with linked issue

[nmokkenstorm]

@nmokkenstorm Why is it an optional configuration flag? Why not add it for everyone?

habit to make it opt-in tbh. I think the skipToken is a breaking change too on type level and it also slightly increases the generated bundle size but I will check.

[mrlubos]

@nmokkenstorm I didn't look at the code yet, stopped after seeing the configuration haha. If it's going to be breaking either way, I'd much rather deprecate the old approach because we wouldn't want new users to start with the flag disabled, realize one day they need to enable it, and face a lot of breaking changes. We can talk through it when you feel the pull request is more ready. I'm pretty sure there was another thread where we talked about skip tokens but can't find it, I'd like to ideally avoid another breaking change when that thread gets addressed

[nmokkenstorm]

@nmokkenstorm I didn't look at the code yet, stopped after seeing the configuration haha. If it's going to be breaking either way, I'd much rather deprecate the old approach because we wouldn't want new users to start with the flag disabled, realize one day they need to enable it, and face a lot of breaking changes. We can talk through it when you feel the pull request is more ready. I'm pretty sure there was another thread where we talked about skip tokens but can't find it, I'd like to ideally avoid another breaking change when that thread gets addressed

I'll double check, I think it's definately doable to have it be backwards compatible without a breaking change. The useQuery/Mutation stuff was opt in so I stuck to the pattern but I think this can be done without losing ergonomics.

I'll update the pr description and ping you if it's reviewable, I needed a remote public ref to do some internal testing with first anyways.

Thanks for the feedback!

[mrlubos]

@nmokkenstorm Can you clarify what do you mean by "add useQuery hooks" in the title? React/Preact Query already support generating useQuery hooks so I'm confused what it's referencing

[nmokkenstorm]

@nmokkenstorm Can you clarify what do you mean by "add useQuery hooks" in the title? React/Preact Query already support generating useQuery hooks so I'm confused what it's referencing

its about having the generated useQuery hooks exist per entity, with queryoptions and skiptoken enabled. the reason it's named like that is because the original code/branch orginates from a fork that pre-dates the support we had in our project.

still tinkering on this, nothing to see/review here yet!

[mrlubos]

Just making sure we're aligned on the scope! I shall retreat once more