refactor(pinia-colada): migrate queries to defineQueryOptions

[brolnickij]

• implement a defineQueryOptions factory for every xxxQuery
• normalized all parts of each query key using _JSONValue (so keys are consistent and type-safe)
• updated the docs for xxxQuery - kept only the "canonical usage" examples
• updated examples in openapi-ts-pinia-colada
• enhance generated query keys by serializing parameters into JSON-safe values via serializeQueryKeyValue instead of embedding raw body / query

Close #2597

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[changeset-bot]

🦋 Changeset detected

Latest commit: c0ca1c9

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	Patch

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

[vercel]

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

A member of the Team first needs to authorize it.

[mrlubos]

@brolnickij hold your horses on this one a bit, #2582 is almost ready and it contains some new concepts

[brolnickij]

@mrlubos

i didnt see your note and already implemented the core logic

totally fine if #2582 breaks this - i update my work and help with the migration once it lands!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 25.39%. Comparing base (612d9c1) to head (c0ca1c9).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2610      +/-   ##
==========================================
+ Coverage   25.23%   25.39%   +0.15%     
==========================================
  Files         386      387       +1     
  Lines       37188    37302     +114     
  Branches     1783     1826      +43     
==========================================
+ Hits         9385     9473      +88     
- Misses      27790    27816      +26     
  Partials       13       13              

Flag	Coverage Δ
unittests	25.39% <ø> (+0.15%)	⬆️

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

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/codegen-core@2610

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

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

npm i https://pkg.pr.new/hey-api/openapi-ts/@hey-api/vite-plugin@2610

commit: c0ca1c9

[mrlubos]

@brolnickij merged my big thing, seems there are no conflicts and you just need to re-run the snapshots

[mrlubos]

@brolnickij the only thing I want to discuss is this point

simplify generated query keys by removing body / headers

Why did you feel this was necessary? It creates an inconsistency with the TanStack Query plugin, too. Could this be something that's configurable?

tl;dr

1. Is the query key shape change necessary?
2. If yes, can it be configurable? What's the better default and why?
3. Whatever the change, let's keep it aligned with the TanStack Query plugin. I don't think there's any reason for these two to deviate?

[brolnickij]

@mrlubos

Why did you feel this was necessary?

while testing this PR in an internal project I ran into pretty weird cache behavior in Pinia Colada, and digging into the problem showed that Pinia Colada expects JSON-serializable values

this is confirmed in the official docs

• https://pinia-colada.esm.dev/guide/query-keys#:~:text=They%20are%20just%20an%20array%20of%20serializable%20properties
• https://pinia-colada.esm.dev/guide/query-keys#:~:text=Keys%20can%20contain%20strings%2C%20numbers%2C%20objects%2C%20and%20arrays.%20Anything%20that%20is%20serializable%20to%20JSON%20can%20be%20used%20in%20a%20key

also, looking at Pinia Colada source code I found that in src/entry-keys.ts the EntryKey type is restricted to JSON-serializable structures, and toCacheKey() runs JSON.stringify, so non-serializable values simply break the cache

It creates an inconsistency with the TanStack Query plugin, too.

the analysis above shows that Pinia Colada has its own behavior, and the way the TanStack Query plugin builds keys just doesnt fit Pinia Colada

---

Is the query key shape change necessary?

yes, definitely, because body / headers are arbitrary objects, often with functions, Blob, FormData, etc., and they dont fit JSON-serializable structures

If yes, can it be configurable? What's the better default and why?

i dont think that makes sense, because we would have to guarantee deep normalization of body / headers into JSON for Pinia Colada (extra work and still risky), or plainly warn the user that they take over serialization xDD

Whatever the change, let's keep it aligned with the TanStack Query plugin. I don't think there's any reason for these two to deviate?

Pinia Colada builds cache on a "string hash", while TanStack Query apparently uses a different mechanism

so yeah, to wrap it up, in this case I wouldnt try to “align” two different tools

---

@posva if you have a chance, please check whether my analysis is correct, thanks in advance!

[posva]

Yes, Pinia Colada has a serialization mechanism for keys that is needed for SSR. It also hashes them for a couple of other features. It's not configurable because in the vast majority of cases, keys are strings, numbers and plain objects, so users can manually serialize their keys if they contain anything else. That will ensure that keys are matched during hydration, in server side rendered apps

[mrlubos]

@brolnickij How do you ensure the query refetches on body change for example? I'm not so worried about headers in the grand scheme of things, but body is often used for search queries. And how does deduplication work if you now have multiple queries with the same key? Is the expectation that they'd override each other?

[brolnickij]

How do you ensure the query refetches on body change for example? I'm not so worried about headers in the grand scheme of things, but body is often used for search queries.

ye, i agree

after thinking a bit, removing body completely isnt a good idea, otherwise we end up with a lot of manual cache invalidation

do you have any ideas on how to make body always serializable?

And how does deduplication work if you now have multiple queries with the same key? Is the expectation that they'd override each other?

deduplication is still there, queryCache.ensure() returns the existing UseQueryEntry when the keyHash matches, so parallel requests still collapse

[mrlubos]

My naive assumption would be we want our own serializer for query keys which would handle headers and body. After all, we already do something similar for Fetch requests as an example

[mrlubos]

I believe you're familiar with this code https://github.com/hey-api/openapi-ts/blob/main/packages/openapi-ts/src/plugins/@hey-api/client-core/bundle/bodySerializer.ts

[mrlubos]

I'm also happy to merge and release an incomplete version of that would help you move faster

[brolnickij]

I'm also happy to merge and release an incomplete version of that would help you move faster

i suggest finishing this task completely within this PR, without merging it into the main branch, so that the feature is "production ready"

[mrlubos]

While you're at it, add yourself as a collaborator to the relevant pages in the documentation please

[brolnickij]

@mrlubos whenever you got a moment, could you take a look at my fix?

P.S. CI is still red even though everything passes locally (looks like the new snapshot didnt stick on the runner)

[mrlubos]

@brolnickij can you try git add the snapshots folder? Sometimes you need to do it instead of git add . because of the ignore rules in openapi-ts, I never get around to fixing it. That would explain why it's passing locally

[brolnickij]

@mrlubos hmm, i checked, and all the changes were already pushed there are no unstaged or unpushed snapshots left in the local repository

[mrlubos]

I can have a look later!

[brolnickij]

can you try git add the snapshots folder? Sometimes you need to do it instead of git add . because of the ignore rules in openapi-ts, I never get around to fixing it. That would explain why it's passing locally

u were right